ki-praxis/manuskript/kapitel-06-knowledge-layer-wissen-fuer-agents.md

6. Knowledge Layer – Wissen für Agents verwalten

Montag, neue Session. Der Agent liest den Code — und erfindet die Spec neu, die gestern im Chat lag. Oder er folgt brav einer AGENTS.md, die seit der Migration lügt. Oder er bekommt ein Wiki-Dump „zur Sicherheit“ und verliert DoD und Verbote in der Mitte. Drei verschiedene Symptome, ein gemeinsames Defizit: Wissen lag entweder nur im flüchtigen Window — oder dauerhaft und ungepflegt im falschen Artefakt.

Kap. 3 hat begründet, warum Context die Qualität dominiert; Kap. 5 steuert den Lifecycle. Dieses Kapitel schließt die Lücke zwischen Window und Repo: Wo lebt Wissen, wann kommt es rein, wer darf es schreiben, und wie bleibt es frisch?

Leitsatz: Persistentes Wissen ist nur dann ein Hebel, wenn es scoped, frisch und on-demand ist. Alles Permanente, Veraltete und Unscoped im Context ist Context-Gift — dasselbe Gift wie Context Rot, nur mit Versionsstempel.
These 9 (Kanon Kap. 12): veraltetes Knowledge ist Fehlinformation.

---

6.1 Context vs. Knowledge Layer

Context ist alles, was dem Modell in diesem Schritt sichtbar ist: System-Prompt, History, Tool-Results, angehängte Dateien. Es ist Working Memory — flüchtig, teuer, begrenzt.

Knowledge ist alles, was außerhalb des Windows lebt und bei Bedarf geholt oder geschrieben wird: Handoff, Progress, AGENTS.md, Skills, Docs, Issue-Tracker, optional eine Knowledge Base. Der Knowledge Layer ist die Disziplin, diese Quellen zu ordnen — nicht ein Produkt und kein Vector-Store-Zwang.

Die vier Lifecycle-Strategien aus Kap. 5.2 gelten hier als Rollen: Write lagert aus dem Chat in Artefakte, Select holt nur das Nötige, Compress verdichtet History, Isolate trennt die Sichtbarkeit. Compact (Kap. 4) rettet Token im Thread; Handoff rettet episodisches Wissen über die Session-Grenze; AGENTS.md und Skills halten semantisches und prozedurales Wissen teamweit. Wer nur Compact beherrscht, aber keinen Knowledge Layer hat, startet jede Session bei null — oder mit Gift aus dem letzten Quartal.

{width=90%}

---

6.2 Memory-Tiers

Die Memory-Hierarchie hier operativ und verbindlich:

{width=90%}

Tier	Lebensdauer	Typische Artefakte	Was reingehört	Typischer Fehler
Working	Turn / Session	Prompt, History, Tool-Results	Was die nächste Entscheidung braucht	Chat als Archiv und Wiki missbrauchen
Episodic	Task / Tage	Handoff, Progress, bewusste Session-Summaries	Stand, Entscheidungen, nächste Schritte, Blocker	Zombie-Handoff; nichts geschrieben
Semantic	Wochen / Release	AGENTS.md, ADRs, Architektur-Fakten, kuratierte Docs	Stabile Richtlinie, Defaults, Fakten	Essay-Friedhof; Widersprüche
Procedural	stabil, versioniert	Skills, Runbooks, Justfile/CI-DoD-Commands	Wiederholbare Workflows mit Verify	Skill-Leichen; undokumentierte Shell-Magie

Wann welches Tier — und wann wechseln

Exploration / Zwischenstand     → Write episodisch (Progress), nicht sofort AGENTS.md
Session endet, Arbeit unfertig → Handoff finalisieren; Working verwerfen
Gleiche Prozedur ≥ 2–3×        → Procedural (Skill), nicht ewig Prompt-Snippet
Stabile Richtlinie, immer gültig   → Semantic (`AGENTS.md`), schlank halten
Großes Prose-Wissen, selten    → externe KB + Select, nicht permanent im Window

Symptom → Hebel

Symptom	Wahrscheinliche Ursache	Hebel
Agent „vergisst“ DoD/Verbote mitten im Task	Working voll / Signal in der Mitte	Compact mit Hint; DoD an den Rändern; Scope verkleinern
Neue Session erfindet Spec neu	Kein Episodic Write	Handoff + Session-Start-Ritual (Kap. 4)
Jede Session startet mit Roman	Zu viel permanent geladen	Progressive Disclosure (6.3)

Working soll klein und scharf bleiben. Die unteren Tiers existieren, damit du nicht alles im Chat stapeln musst — und damit Wissen den Reset überlebt, ohne den nächsten Thread zu vergiften.

---

6.3 Progressive Disclosure

Progressive Disclosure heißt: Wissen nur bei Bedarf und in der richtigen Flughöhe laden. Es ist Select (Kap. 5) als Organisationsprinzip — und der Grund, warum Skills und gute Repo-Struktur Context sparen, ohne Wissen zu vernichten.

{width=90%}

Skills sind die klarste Produktform (Kap. 16): oft nur name + description in der Discovery; voller SKILL.md-Body bei Activation; references/ und Scripts erst bei Execution. Dasselbe Muster gilt außerhalb von Skills.

Vier Muster, die im Coding-Alltag tragen

1. Index zuerst, Details später — Repo-Map, Inhaltsverzeichnis, Skill-Description, Issue-Titel vor dem Full-Read der spezifikationslangen Datei.
2. Hierarchische Rules — Root-AGENTS.md schlank und global; Package-/Pfad-Rules nur im Arbeitsbereich (Kap. 9).
3. Tool-beschriebene Quellen — MCP- und Tool-Schemas klein halten; Inhalt on-demand als Resource/Tool-Result (Kap. 17).
4. Nicht vorladen — keine „alle relevanten Module zur Sicherheit“-Dumps. Was der nächste Reasoning-Schritt braucht, wird geholt.

Do this	Avoid that
Kurze Discovery-Schicht + gezieltes Nachladen	Alles Autoritative permanent im Window
Eine Ebene Verweise (Skill → references/x.md)	Verweisketten A→B→C→D
Scoped Rules am Package	Ein Root-Essay für alle Stacks
Nach Laden: nur behalten, was Decide/Edit braucht	Geladene Romane „für später“ im Thread lassen

Progressive Disclosure ist kein Feature-Schalter. Es ist die Antwort auf These 3: mehr Token im Window ist oft schlechter — also muss Wissen abrufbar sein, ohne permanent zu sein. Dieselbe Logik gilt für Capability: teures Reasoning und langsame Modelle erst laden, wenn Fast/Balanced nicht reichen oder das Risiko es verlangt — Model Routing in Kapitel 5.7.

---

6.4 Knowledge Base & Retrieval

Select im Window (Agentic Search vs. RAG vs. Graph, Default HEAD, Blind-RAG): Kanon Kapitel 5.5. Hier nur die Knowledge-Policy: wann eine externe KB lohnt — und wann sie Context-Gift wird.

Eine externe Knowledge Base (Docs-Portal, Wiki, kuratierter Index, MCP-Resources) ist sinnvoll, wenn Wissen:

• groß und prose-lastig ist (Richtlinien, Runbooks, Onboarding),
• langsamer driftet als der Code-HEAD,
• von vielen Tasks geteilt wird, ohne in jede Session zu gehören.

Sie ist kein Ersatz für den Code-HEAD und kein Freifahrtschein, das Window mit „ähnlichen Chunks“ zu füllen. Default für Coding bleibt Agentic Search am HEAD (5.5).

Wann nicht indexieren: wenn Agentic Search plus schlanke Semantic/Procedural-Artefakte (AGENTS.md, Skills, Handoff) reichen. Die meisten Teams unterinvestieren dort — und überinvestieren in Index-Theater.

Pflege-Pflicht (sonst Lüge mit Autorität): Index-Drift (Chunks von gestern, Code von heute), „ähnlich ≠ richtig“, Chunk-Grenzen ohne Ownership, Treffer ohne Verify am HEAD. Symptom: Agent zitiert Docs; Tests rot. Fix wie in 5.5: Retrieval nur Navigation, dann Select der kanonischen Dateien + DoD am HEAD (Kap. 10).

---

6.5 Handoff als Memory-Übergabe

Kanon-Aufteilung: Ops (wann Session/Compact, Session-Start, Felder, Minimal-Skelett) = Kapitel 4.3 · Copy-Paste = Anhang A · templates/handoff-template.md · hier nur die Memory-Rolle.

Kapitel 4 beantwortet wie du Handoffs schreibst und wann Sessions enden. Hier: Handoff ist die explizite Übergabe episodischen Wissens — an die nächste Session oder den nächsten Menschen (Kap. 4.3).

{width=90%}

Compact verdichtet Working Memory und ist verlustbehaftet. Handoff wählt aus, was die nächste Episode wissen muss (Episodic Write vor dem Reset). Progress im Buch-Repo: templates/progress-template.md — füttert das Handoff, ersetzt es nicht.

Progress vs. finaler Handoff: Progress ist der laufende episodische Log innerhalb der Arbeit (kurze Einträge nach Slices). Der finale Handoff ist die Übergabe an die nächste Session — konsolidiert, mit DoD und nächstem Schritt. Beides episodic; unterschiedlich im Timing.

Hand-back (Kap. 5.6, 22) ist etwas anderes: kompakte Rückgabe eines Sub-Agents an den Parent im selben Task — kein Session-Reset, kein Knowledge-Layer-Write in kanonische Docs.

Minimal- vs. Full-Handoff (Knowledge-Sicht)

Minimal reicht, solange derselbe Owner am nächsten Tag weitermacht; Full braucht es bei Personenwechsel, mehreren Slices oder riskanten Entscheidungen. Felder und Markdown-Skelett: Kap. 4.3.

{width=90%}

Handoff ohne Aktualisierung wird zum Zombie (Kap. 12, Kap. 19): die neue Session aligned auf eine Lüge. Secrets gehören nie hinein — nur Referenzen auf den Secret-Store (Kap. 18). Wann episodisch zurückschreiben (Rhythmus) und wer Semantic/Procedural kuratiert: Abschnitt 6.7.

---

6.6 Scoped & Hierarchical Knowledge

Wissen hat Gültigkeitsbereiche. Was global gilt, darf global liegen. Was nur ein Package betrifft, vergiftet den Root-Context, wenn es dort wohnt.

Task  →  Session  →  Modul/Package  →  Repo  →  Team/Org

{width=90%}

Scope	Typische Träger
Task / Session	Task-Prompt, Progress, Handoff
Modul / Package	Package-AGENTS.md, path-scoped Rules, Package-Skills
Repo	Root-AGENTS.md, Repo-Skills, kanonische Verify-Defaults
Team / Org	Geteilte Skills, Richtlinien-KB — nicht ungefiltert in jedes Repo kopiert

Hierarchische AGENTS.md und scoped Skills (Kap. 9, Kap. 16) sind Progressive Disclosure mit Dateisystem-Mitteln: der Agent sieht zuerst das Globale, lädt das Lokale im Arbeitsverzeichnis, und bekommt nicht die Test-Richtlinie von Package B, während er Package A patched.

Isolation und Knowledge-Sichtbarkeit

Sub-Agents und getrennte Sessions (Kap. 5) isolieren Working Memory. Genauso wichtig: welches Knowledge sie sehen — und mit welchem Modell-Tier sie arbeiten (Routing in Kap. 5.7).

Do this	Avoid that
Sub-Agent mit engem Auftrag + Rückgabeformat + nur nötigen Pfaden/Skills	Drei Agents mit vollem Root-Context und denselben Write-Rechten
Explore-Agent: Map + Fazit; Main: Execute mit Hand-back-Vertrag (Kap. 5.6)	Explore-Müll und Execute-Patches im selben Window ohne Grenze
Package-Scope in Handoff festhalten („nur packages/payments“)	„Das ganze Monorepo, falls relevant“
Capability passend zum Sub-Auftrag (Fast für Map, Strong nur bei Risiko)	Jeden Sub-Agenten auf Max-Tier „zur Sicherheit“

Schlechte Isolation erzeugt verteilten Context Rot: teurer und schwerer zu debuggen als ein einziger verrotteter Thread.

---

6.7 Write-Back und Knowledge Lifecycle

Wer darf Wissen schreiben? Wenn „der Agent immer“ die Antwort ist, endest du in autoritativer Fiktion. Wenn „nur der Mensch nach dem Quartal“, endest du in toten Handoffs und Chat-Amnesie.

Write-Back-Rhythmus (alle Tiers)

Task-Start     → Progress anlegen; knappes Handoff, wenn >1 Session absehbar
Nach jedem Slice → Progress aktualisieren (Stand + nächste Schritte)
Session-Ende   → unfertig/Themenwechsel: Handoff finalisieren; done: archivieren
Semantic/Procedural → nur kuratiert (AGENTS.md, Skills) — nicht aus dem Chat „einfach speichern“
Neue Session   → Nur Handoff + AGENTS.md (+ gezielt Code), nicht den alten Chat

Rollen

Rolle	Darf typischerweise	Braucht Review?
Agent	Progress, Handoff-Entwurf, vorgeschlagene ADR-Skizze, Kandidatenliste „obsolete?“	Ja — Mensch skimmed
Mensch (Owner)	Merge in Semantic/Procedural (AGENTS.md, Skills), Archive-Entscheidung	Peer bei Richtlinien-Änderungen
Review / CI	Widersprüche und Verify-Commands gegen Wahrheit prüfen	Automatisch wo möglich

Regel: Episodic darf der Agent flüssig pflegen. Semantic und Procedural werden kuratiert — kurz, wahr, owned. Ungeprüfter Write-Back in kanonische Docs ist Context-Gift mit PR-Nummer.

Liefer- vs. Write-Back-Session

Eine Session, die ein Feature liefert, und eine Session, die AGENTS.md oder einen Skill schreibt, sind zwei Jobs. Wer beides im selben Diff mischt, reviewt Verhalten und Steuerdateien — und merkt oft erst nach dem Merge, dass die neue Regel den nächsten Loop verdreht. Liefer-Session: Slice, DoD, Feature-Diff; Rules nur auf ausdrücklichen Auftrag. Write-Back-Session: kurz, eigenes Ticket, nur Semantic/Procedural. Teach-back (Kap. 11) gehört vor den Feature-Diff, das Zurückschreiben der Lehre danach.

Lifecycle

Capture  →  Curate  →  Retrieve  →  Use  →  Update / Archive
 (Progress)  (was bleibt?)  (Select/PD)  (Task)   (These 9)

{width=90%}

Freshness-Regeln (qualitativ)

• Veraltetes autoritatives Wissen ist schlimmer als fehlendes — der Agent behandelt AGENTS.md und Skills als Wahrheit.
• Nach Migration oder Tool-Wechsel: Rules und Skills am selben Tag mitziehen (Kap. 12).
• Episodic nach Done: Handoff archivieren oder aus Default-Suchpfaden nehmen — sonst Zombie-Start.
• Semantic/Procedural: Owner, „weniger Text“-Review, eine kanonische Anweisung pro Thema.
• Index/KB: Rebuild- oder Review-Ritual, wenn du RAG nutzt; sonst abschalten.
• Repo-Git schlägt Chat — Parallel-Wahrheiten in Slack und Thread sind Alignment-Gift (Kap. 11).

Freshness ist These 9 angewendet auf den Knowledge Layer: Aufräumen ist keine Ästhetik, sondern die Voraussetzung, dass Select nicht systematisch lügt.

---

6.8 Knowledge ≠ Rules ≠ Skills

Drei Dinge, die Teams ständig vermischen:

Begriff	Frage, die er beantwortet	Träger
Knowledge	Was ist wahr / was gilt als Fakt?	Docs, ADRs, Fakten in AGENTS.md, KB
Rules	Was ist immer erlaubt/verboten/Default?	AGENTS.md
Skills	Wie führen wir diese Klasse von Tasks aus?	SKILL.md + optional scripts/references

Rules sind ein schmaler, immer geladener Ausschnitt von Semantic Memory. Permissions und CI sind hart — Kap. 15.1. Skills sind Procedural Memory. Knowledge im weiteren Sinn umfasst Fakten und die Träger der anderen Tiers — aber nicht alles gehört in dieselbe Datei.

Entscheidungshilfe: Wohin mit diesem Satz?

Wenn …	Dann …	Nicht …
Gilt immer, ist kurz, ist Richtlinie	AGENTS.md (Rules/Semantic)	langer Runbook-Text
Workflow kommt ≥2–3×, braucht Schritte + DoD	Skill (Procedural)	AGENTS-Essay
Einmaliger oder session-gebundener Stand	Handoff / Progress (Episodic)	in AGENTS.md „zwischenparken“
Großes, selten gelesenes Prose-Wissen	externe KB + Select	voller Dump in jede Session
Mechanische, deterministische Aktion	Tool / Script / CI-Job	Skill-Prosa ohne Command
Task-Ziel jetzt	Task-Prompt (Kap. 14)	versteckte Nebenbedingungen nur im Chat

Faustregel: permanent und kurz → Rules; wiederholbar → Skill; einmalig → Handoff.

Setup und Skills-Kapitel (15–16) bleiben die Detailorte; diese Matrix ist der Placement-Kompass, bevor Dateien wuchern.

---

6.9 Praxis-Checkliste und Anti-Patterns

Vor dem Start und vor dem Write

• Welches Tier brauche ich jetzt? (Handoff? Nur AGENTS.md? Welcher Skill?)
• Ist das Handoff aktuell — oder Zombie?
• Scope: Task / Package / Repo klar?
• DoD agent-prüfbar und im Prompt oder Handoff sichtbar?
• Stabil genug für mehr als diesen Task? Gibt es schon eine kanonische Stelle (Update statt Duplikat)? Wer owned die Pflege?

KB oder Index nur, wenn Agentic Search am HEAD nicht reicht — mit Pflegeprozess für Drift; Retrieval ersetzt kein Verify (6.4).

Anti-Patterns (Kurzform)

Anti-Pattern	Problem	Do this instead
Chat-only Memory	Wissen stirbt mit der Session	Handoff/Progress als Repo-Artefakt
Permanent Load	Context-Budget weg, Lost-in-the-Middle	Progressive Disclosure
Unscoped Dump	Package-B-Richtlinie in Package-A-Session	Hierarchie + Isolation

Zombie-Handoff und ungeprüfter Write-Back: 6.5 und 6.7.

Ausführliche Kataloge: Kapitel 19. Hygiene-Rituale: Kapitel 12.

---

Key Takeaways

• Context ist Working Memory; der Knowledge Layer ordnet, was außerhalb lebt und wann es rein darf.
• Memory-Tiers steuern Lebensdauer und Artefakt — Chat ist kein Wiki; Progressive Disclosure lädt on-demand.
• Write-Back braucht Rollen: episodic flüssig, Semantic/Procedural kuratiert.
• Knowledge ≠ Rules ≠ Skills — Placement entscheidet über Pflege und Context-Gift.

Praktische nächste Schritte

1. Vier Tiers an konkreten Dateien deines Repos benennen.
2. Handoff bei unfertiger Arbeit zur Pflicht (Anhang A).
3. Placement-Regel aus 6.8 als kurzen Block in AGENTS.md.
4. Weiter: Kapitel 7.