AGENTS.md und CLAUDE.md für eine Wissensdatenbank

AGENTS.md und CLAUDE.md sind einfache Markdown-Dateien, die Coding-Agenten lesen, bevor sie in einem Ordner arbeiten. In einer Wissensdatenbank sagst du Agenten dort, wie deine Notizen aufgebaut sind und welchen Regeln jedes Dokument folgen muss. Keine der beiden Dateien hat Pflichtfelder oder ein Schema: Du schreibst Anweisungen in ganz normalem Markdown.

Diese Anleitung zeigt zuerst das Setup von Hand. Neben jedem Teil siehst du, was sich mit Knowtarium ändert, unserer Ende-zu-Ende-verschlüsselten Wissensdatenbank, die Menschen und Agenten gemeinsam schreiben, und welche Konventionen es jedem Agenten mitgibt, den du verbindest.

AGENTS.md

AGENTS.md ist ein offenes Format, um Coding-Agenten anzuleiten, betreut von der Agentic AI Foundation unter dem Dach der Linux Foundation. Viele Coding-Agenten lesen es, darunter OpenAI Codex und Cursor. Du legst es ins Root deines Ordners und kannst in Unterordnern weitere anlegen: Es gilt die AGENTS.md, die der bearbeiteten Datei am nächsten liegt, und was du im Chat tippst, hat Vorrang vor allen.

CLAUDE.md

CLAUDE.md ist die Version von Claude Code. Laut der Doku von Anthropic liest Claude Code sie von mehreren Orten, den allgemeinsten zuerst:

Organisationen können außerdem eine zentral verwaltete CLAUDE.md ausrollen. Die Dateien überschreiben sich nicht gegenseitig: Claude Code hängt sie aneinander, vom Root des Dateisystems bis zu dem Ort, an dem du es gestartet hast, also stehen die spezifischsten Anweisungen am Ende. Dateien in Unterordnern werden geladen, wenn Claude eine Datei in diesem Unterordner liest. Eine CLAUDE.md kann mit @path/to/file andere Dateien einbinden, bis zu vier Ebenen tief. Anthropic empfiehlt, jede Datei unter 200 Zeilen zu halten.

In Knowtarium

Knowtarium ergänzt Prüfungen, die eine Datei mit Anweisungen nicht leisten kann. Egal, was ein Agent mit deinen Regeln macht: Jede seiner Änderungen ist signiert und lässt sich mit einem Klick rückgängig machen, er löscht Dokumente nur, wenn du ihm das erlaubt hast, und er kann nichts als von einem Menschen geprüft markieren. In Ordnern, in denen du Review einschaltest, warten seine Änderungen als Diffs, bis du sie freigibst.

(öffnet in voller Größe in einem neuen Tab) (öffnet in voller Größe in einem neuen Tab)

Wenn du mehr als einen Agenten nutzt, schreib deine Regeln einmal in AGENTS.md. Neuere Versionen von Claude Code lesen AGENTS.md von selbst, wenn es im Ordner oder darüber keine CLAUDE.md oder CLAUDE.local.md gibt (ab v2.1.277). Wenn du zusätzlich Anweisungen nur für Claude willst oder eine ältere Version nutzt, leg daneben eine CLAUDE.md an, die sie importiert:

@AGENTS.md
 
## Claude Code
 
- Arbeite im Plan Mode bei jeder Änderung, die mehr als drei Dokumente betrifft.

Claude liest zuerst die importierte AGENTS.md, dann die Zeilen darunter. Jeder andere Agent liest AGENTS.md direkt, also laufen die Regeln nie auseinander.

Die meisten Beispiele für AGENTS.md sind für Code geschrieben: Build-Befehle, Tests, Stil. Eine Wissensdatenbank braucht andere Regeln. Das hier sind die wichtigsten, wenn Agenten einen großen Teil deiner Notizen schreiben.

Ordnerstruktur

Sag, wofür jeder Ordner auf oberster Ebene da ist und wo neue Dokumente hinkommen. Ohne das erfinden Agenten Ordner, und zwei Agenten legen dieselbe Art von Notiz an zwei Orten ab.

Benennung

Ein Konzept pro Datei, ein Namensmuster. Namen mit Datum für Entscheidungen und Meetings sorgen dafür, dass sich der Ordner von selbst sortiert.

Verlinkung

Entscheide dich für einen Link-Stil und schreib ihn auf. Normale Markdown-Links funktionieren in jedem Tool, [[wikilinks]] nur in manchen. Sag Agenten, dass sie Links anpassen, wenn sie eine Datei verschieben, und dass ein Link auf ein Dokument, das noch niemand geschrieben hat, erlaubt ist.

Frontmatter für Herkunft und Aktualität

Diese Regel fehlt in den meisten Vorlagen, und sie macht eine von Agenten geschriebene Wissensdatenbank später überprüfbar. Verlange, dass jedes Dokument sagt, wer es geschrieben hat und wann es veraltet. Das Open Knowledge Format, eine offene Spezifikation von Google Cloud, liefert dir die Feldnamen: type (das einzige Pflichtfeld), generated, verified, status, stale_after und sources. Mit einem veröffentlichten Format versteht jedes Tool, das OKF liest, deine Notizen.

Quellenangaben

Verlange eine Quelle für jede Zahl, jedes Datum, jeden Namen und jedes Zitat, direkt neben der Aussage. Die Anleitung dazu, wie Agenten Quellen nennen, geht tiefer.

Was Agenten nie tun dürfen

Schreib die harten Grenzen als „Niemals“-Regeln: nie etwas als von einem Menschen geprüft markieren, nie löschen, nie die Änderung einer Person überschreiben. Die Doku von Anthropic merkt an, dass konkrete, knappe Anweisungen zuverlässiger befolgt werden als allgemeine.

Wie eine Prüfung festgehalten wird

Wenn ein Agent ein Dokument bestätigt, sollte er das auf eine feste Art tun: mit einem eigenen Eintrag in verified, samt Zeitstempel. Dann kann jeder die Prüfung eines Agenten von der eines Menschen unterscheiden.

In Knowtarium

In Ordnern mit Review macht Knowtarium aus diesen Einträgen eine Vertrauensstufe. Der Eintrag eines Agenten macht ein Dokument machine-confirmed, deiner macht es human-reviewed, und beide nach der letzten Änderung machen es vollständig verifiziert. Wenn du dort die Änderung eines Agenten freigibst, schreibt die App deinen Eintrag für dich.

(öffnet in voller Größe in einem neuen Tab) (öffnet in voller Größe in einem neuen Tab)

Kopier das in eine AGENTS.md im Root deines Notizordners und pass die Ordnerliste an deine an. Sie bleibt mit reichlich Luft unter der Empfehlung von Anthropic von 200 Zeilen.

---
type: Instructions
title: Regeln für Agenten
---
 
# Wissensdatenbank: Regeln für Agenten
 
Dieser Ordner ist eine Wissensdatenbank, die Menschen und Agenten gemeinsam schreiben.
Jede Datei ist einfaches Markdown mit YAML-Frontmatter (OKF v0.2).
Lies diese ganze Datei, bevor du irgendetwas änderst.
 
## Aufbau
 
- index.md in jedem Ordner listet, was der Ordner enthält. Lies sie zuerst.
- log.md hält fest, was sich geändert hat, Neuestes zuerst. Schreib für jede Sitzung eine Zeile.
- company/     Mission, Glossar, wie wir arbeiten
- customers/   Segmente, interviews/ (eine Datei pro Interview)
- metrics/     eine Datei pro Kennzahl; computations/ für freigegebene Abfragen
- decisions/   eine Datei pro Entscheidung, benannt YYYY-MM-DD-short-title.md
- references/  Kopien von Quellmaterial, das du zitierst (PDF, CSV, gespeicherte Seiten)
- Leg nie einen neuen Ordner auf oberster Ebene an. Frag vorher.
 
## Dinge finden
 
- Fang bei der index.md im Root an und folge den Links. Lies nicht jede Datei.
- Such, bevor du schreibst. Gibt es schon ein Dokument zum Thema, aktualisiere es.
 
## Benennung
 
- Ein Konzept pro Datei. Dateinamen sind lowercase-with-hyphens.md.
- index.md und log.md sind reserviert. Nutz sie nie für ein Dokument.
 
## Links
 
- Nutz normale Markdown-Links, nie [[wikilinks]].
- Verlinke ab dem Bundle-Root: [Churn](/metrics/churn.md).
- Ein Link auf ein Dokument, das es noch nicht gibt, ist in Ordnung. Leg keine
  leere Datei an, nur um den Link zu reparieren.
- Wenn du eine Datei umbenennst oder verschiebst, aktualisiere jeden Link darauf.
 
## Frontmatter
 
Jedes Dokument beginnt mit Frontmatter. Behalte Schlüssel, die du nicht kennst,
genau so, wie sie sind.
 
```yaml
---
type: Metric                # Pflicht: Metric, Decision, Interview, ...
title: Churn
description: Ein Satz, genutzt in index.md und in der Suche.
status: stable              # draft | stable | deprecated
generated: { by: <your-name>/<version>, at: <UTC-Zeit, ISO 8601> }
stale_after: <UTC-Zeit>     # ab wann man das nicht mehr bedenkenlos zitieren kann
sources:
  - id: billing-export
    resource: /references/billing-2026-09.csv
    title: Billing-Export, September 2026
---
```
 
- Signiere jedes Dokument, das du schreibst oder änderst, in `generated`.
  Aktualisiere `generated.at` bei jeder wesentlichen Änderung.
- Setz `stale_after`: 90 Tage für Kennzahlen, 1 Jahr für Entscheidungen.
- Neue Dokumente beginnen als `status: draft`.
 
## Quellen
 
- Jede Zahl, jedes Datum, jeder Name und jedes Zitat braucht eine Quelle.
- Trag die Quelle mit einer kurzen, stabilen `id` in `sources` ein und zitiere sie
  nach der Aussage mit einer Fußnote: Churn sank auf 2,4 %.[^billing-export]
- Zitiere nur Quellen, die du in dieser Sitzung geöffnet hast. Erfinde nie eine URL.
- Findest du keine Quelle, schreib die Aussage unter
  "## Offene Fragen", statt sie als Fakt hinzustellen.
 
## Die Änderung einer Person prüfen
 
- Lies die Änderung, dann jedes Dokument, das darauf verlinkt oder eine
  Quelle mit ihr teilt.
- Wenn alles noch zusammenpasst, trag dich in `verified` ein:
  - { by: <your-name>/<version>, at: <UTC-Zeit> }
- Wenn etwas nicht mehr passt, schlag die Korrektur vor. Setz sie nicht still um.
 
## Niemals
 
- Füg nie einen `human:`-Eintrag zu `verified` hinzu. Das macht nur ein Mensch.
- Entferne oder sortiere nie die `verified`-Einträge von jemand anderem um.
- Lösch nie ein Dokument. Setz `status: deprecated` und sag, warum.
- Überschreib nie die Änderung einer Person. Wenn du anderer Meinung bist, sag es und hör auf.
- Bearbeite nie Dateien in references/. Sie sind die Belege.
 
## Wenn du fertig bist
 
- Schreib einen Eintrag mit Datum in log.md.
- Liste jede Datei auf, die du angelegt, geändert, verschoben oder als deprecated markiert hast.

Ersetz die Fristen unter Frontmatter durch deine eigenen. OKF zählt jede .md-Datei außer index.md und log.md als Dokument, deshalb beginnt die Vorlage mit eigener Frontmatter und einem type, damit das Bundle gültig bleibt. Der Beispielblock mit Frontmatter darin ist für die Agenten zum Abschauen da.

Manche Regeln zählen nur an einer Stelle. Mit AGENTS.md legst du eine zweite Datei in diesen Ordner, etwa metrics/AGENTS.md; Agenten nutzen die nächstgelegene. Claude Code hat außerdem Regeln für bestimmte Pfade: Markdown-Dateien in .claude/rules/ mit einem Feld paths, die nur geladen werden, wenn Claude eine passende Datei liest.

---
paths:
  - "metrics/**/*.md"
---
 
# Kennzahlen
 
- Jede Kennzahl verlinkt die Abfrage, die sie berechnet, in metrics/computations/.
- Ändere nie eine Zahl ohne einen neuen Eintrag in den Quellen.

So bleibt die Datei im Root kurz. Die Doku von Anthropic warnt, dass längere Dateien mit Anweisungen mehr Kontext verbrauchen und schlechter befolgt werden.

Führ in Claude Code /context aus und schau unter Memory files nach, ob deine Datei geladen wurde. Bei jedem Agenten kannst du eine Sitzung damit beginnen, dass du ihn bittest, die Regeln für ein neues Dokument wiederzugeben. Kann er das nicht, wird die Datei nicht gelesen oder ist zu lang.

Dann prüf das Ergebnis, nicht das Versprechen. Zwei greps finden die häufigsten Ausrutscher:

# Dokumente ohne type: das einzige Pflichtfeld in OKF
$ grep -rL "^type:" --include="*.md" . | grep -v -e "/index.md$" -e "/log.md$"
 
# Wikilinks, die sich eingeschlichen haben
$ grep -rn "\[\[" --include="*.md" .

Wenn derselbe Fehler zweimal auftaucht, schreib eine Regel dafür. Das rät Anthropic auch für die CLAUDE.md: Schreib auf, was du sonst noch einmal erklären würdest.

Knowtarium bringt einen Skill mit Konventionen mit, den jeder Agent, den du verbindest, zusammen mit seinen Tools bekommt (Claude Code, Codex, Cursor, Claude Desktop und andere). Du musst die Konventionen einer Knowtarium-Wissensdatenbank also nicht in jede Datei mit Anweisungen schreiben.

Was er beibringt

• Zuerst den eigenen Index des Workspace lesen. Wo es eine index.md gibt, sie lesen und ihren Links folgen, statt jedes Dokument zu laden.
• Lesen, bevor du schreibst. Titel und Beschreibungen vor ganzen Dokumenten, und jede Änderung nennt die Version, auf der sie beruht. So kann ein Agent keine Änderung überschreiben, die er nicht gelesen hat.
• Wissen, wie eine Änderung landet. In den meisten Ordnern wird eine Änderung sofort gespeichert und lässt sich rückgängig machen, also zurückhaltend sein; in Ordnern mit Review wartet sie auf Freigabe. So oder so der Person sagen, was davon zutrifft.
• Nach der Änderung einer Person prüfen. In Ordnern mit Review die verbundenen Dokumente lesen, die Prüfung erfassen, wenn alles noch zusammenpasst, und einen Konflikt melden, wenn nicht.

Wie er mit deiner AGENTS.md zusammenspielt

In Knowtarium ist deine AGENTS.md die Anweisung des Ordners: Schreib sie in der App, und Agenten bekommen sie bei jeder Notiz, die sie dort schreiben.

Manche Regeln hängen nicht davon ab, dass jemand eine Datei liest. In Knowtarium ist jede Änderung eines Agenten mit seinem eigenen Schlüssel signiert, Agenten löschen Dokumente nur, wenn du ihnen das erlaubt hast, sie können nichts als von einem Menschen geprüft markieren, und in Ordnern mit Review können sie deine Prüfung nicht überspringen. Ein Agent erreicht nur den Workspace und die Ordner, mit denen du ihn verbunden hast. Die App ruft selbst keine KI auf: Wenn du deine Änderungen prüfen lassen willst, bittest du deinen Agenten, und er folgt dem Skill.

Agenten verbinden sich über MCP mit npx knowtarium connect, mit dem Knowtarium-Plugin in Claude Code und Codex (es enthält den Skill), mit der Erweiterung in Claude Desktop oder mit einem Klick in Cursor und VS Code. Konnektoren für Chat-Apps wie claude.ai und ChatGPT kommen später. Siehe Wie Agenten mit Knowtarium arbeiten.