Zum Inhalt springen

Schichten und Overrides

Schicht Inhalt Geändert von
.act/ Regeln, Coding-Regelsätze, Arbeitsmethoden, Formate, Skills, Agent-Rollen, Hooks, Scripts, Tier-Tabelle Ein Update ersetzt sie als Ganzes. Du bearbeitest sie nie.
docs/ ai/ (Config, Regeln, Board, Inbox, Aufgaben, Journal) und project/ (deine Dokumentation) Dir und dem Assistenten. Ein Update überschreibt deine Inhalte nie; es frischt unbearbeitete erzeugte Dateien auf, legt Befunde in der Inbox ab und führt Migrationen aus.

.act-local/ bleibt auf deinem Rechner: lokaler Zustand und Caches (der Cache der kompilierten Hook-Module liegt in .act-local/pyc/, Wegwerfmaterial in .act-local/tmp/). Die Prüfung act-local-tidy beim Sitzungsstart räumt altes Wegwerfmaterial daraus weg (siehe Konfiguration); init und update halten außerdem JetBrains und VS Code davon ab, den Ordner zu indizieren. Das erzeugte Board ist docs/ai/board.md (per gitignore ausgeschlossen) im Standardmodus board: docs und liegt nur im Modus local in .act-local/. In Claude Code blockiert ein Hook Schreibzugriffe nach .act/.

Ein Override ist eine eigene Fassung, die die des Templates ersetzt. Eine projektspezifische Fassung von allem unter .act/ kommt nach docs/ai/local/<gleicher Pfad>. Derselbe relative Pfad wird dort vor .act/ gesucht, sodass eine Regeldatei, ein Skill-Ordner (docs/ai/local/skills/<name>/) oder ein Agent (docs/ai/local/agents/<name>.md) den des Templates überdeckt. docs/ai/local/ gehört dir: Der Assistent schreibt dort nur auf deine ausdrückliche Anweisung. Ein Skill oder Agent, den du mit act-load-settings hinzufügst, landet ebenfalls dort; einer, den du dort von Hand anlegst, bekommt seine Werkzeugkopien beim nächsten Sitzungsstart (Standard session-start-refresh: block) oder Update. Arbeitsmethoden gehen denselben Weg (docs/ai/local/methods/<name>.md). Die Formate für Commit-Nachricht, Changelog, Release Notes und README sind die eine Ausnahme: Eine Datei docs/project/formats/<name>.md ersetzt die gleichnamige Datei des Templates vollständig (act-export-settings --with-formats trägt sie in ein anderes Projekt, act-load-settings schreibt sie zurück), siehe Konfiguration.

Ein Override, dessen Gegenstück unter .act/ das Template umbenannt oder entfernt hat, wirkt stillschweigend nicht mehr. act-doctor meldet eine solche Datei unter docs/ai/local/ mit dem ähnlichsten Namen unter .act/ (Regel-Overrides, Rollen und eigene Skills bleiben außen vor); ein lokaler Skill mit dem Namen eines Template-Skills ist ebenfalls ein Befund, bis du ihn mit python .act/scripts/doctor.py --accept skill:<name> behältst (own-rules-review); update.py zeigt die Zeile im Bericht seines Doctor-Laufs.

Ein Package bringt Regeln, Coding-Sätze, Skills, Rollen, Topics, Scripts und Prüfmodule in ein Projekt, ohne .act/ zu ändern (siehe Skill act-packages). Seine Regeln laden in dieser Reihenfolge: die Dateien aus pre-template/ des Packages, dann .act/, dann die Dateien aus post-template/ des Packages, dann docs/ai/local/. Die Import-Zeilen eines Packages stehen in markierten Blöcken von docs/ai/rules.md; python .act/scripts/rules.py --imports zeigt die sich ergebende Reihenfolge. Ein Package wirkt ab der nächsten Sitzung.

docs/ai/rules.md importiert die Regeldateien und listet jede Regel mit einem Kontrollkästchen. Eine angekreuzte Regel gilt; eine nicht angekreuzte ist aus, obwohl ihr Text geladen wird. Streiche eine Import-Zeile, um einen ganzen Bereich abzuschalten. Eine Regeldatei, die über exclude in docs/ai/config.md ausgeschlossen ist (Scope), behält ihre Zeile, aber der Sitzungsstart macht den Import zu einem bloßen Pfad, sodass Claude Code sie nicht mehr lädt. Dein eigener Text kommt in die Abschnitte am Ende der Datei:

  • ## Overrides: - replaces `R-id`: <dein Wortlaut>. Die Zeile ersetzt den ganzen Text dieser Regel, angekreuzt oder nicht.
  • ## Own rules: - `R-your-id`: text oder ein bloßer Aufzählungspunkt, zusätzlich zu den Regeln des Templates. Halte sie kurz: act-doctor warnt, wenn die eigenen Regeln von docs/ai/rules.md und docs/project/coding_rules.md zusammen die Prüfung own-rules-budget überschreiten (Standard 6000 Zeichen).

python .act/scripts/rules.py --list --area core zeigt jede Regel mit ihrem Zustand, Overrides als [~] und eigene Regeln als [+] (ohne --area core listet es die Coding-Sätze); --validate meldet Text, den es nicht lesen konnte. Pfadgebundene Regeln von Claude Code unter .claude/rules/**/*.md erscheinen in --list mit ihren paths:-Mustern; --validate warnt vor einem Muster, das auf keine Projektdatei passt, und vor einer Datei ohne paths:.

Die Hauptsitzung lädt CLAUDE.md, das docs/ai/rules.md importiert und darüber die geteilten Regeln, die Coding-Regeln und die Orchestrator-Regeln. Ein Worker lädt CLAUDE.md nicht; ein SubagentStart-Hook gibt ihm denselben Text ohne die Orchestrator-Regeln (siehe Rollen). Die drei Git-Regeln R-safe-no-secret-diff, R-safe-git-reset und R-safe-git-discard stehen am Ende der Orchestrator-Regeln, weil nur die Hauptsitzung committet oder den Arbeitsbaum ändert; Worker laden sie nicht. Eine Regel, die das Projekt abgeschaltet hat (abgewählt oder ihr Import entfernt), bleibt auch für einen Worker aus. Hast du docs/ai/rules.md bearbeitet, verschiebt ein Update ihre Kästchenzeilen mit, Kreuz und Begründung unverändert, sodass eine ausgeschaltete Regel ausgeschaltet bleibt. Update und Sitzungsstart tragen außerdem Regeln, die das Template seither ergänzt hat (etwa R-docs-order), in eine bearbeitete docs/ai/rules.md ein: eine Kästchenzeile je neue Regel und eine neue Regeldatei als Import-Block am Ende ihres Abschnitts. Dein eigener Text, nicht angekreuzte Kästchen und entfernte Imports bleiben unberührt, und eine Schicht, aus der du nichts importierst, bleibt unverändert; .act-lock.json hält fest, was angeboten wurde, eine entfernte Zeile oder ein entfernter Import kommt also nicht zurück. Was sich nicht sicher eintragen lässt, nennt python .act/scripts/rules.py --add-missing, und rules.py --validate sowie der Doctor melden Regeldateien, die noch nicht importiert sind, und Regeln, die das Template nicht mehr hat. Ist eine Regel in eine andere Datei gewandert, meldet rules.py außerdem eine verschobene Regel, die in einer Datei landet, die dein Projekt mit einer eigenen Kopie unter docs/ai/local/rules/ überdeckt und in der die Regel fehlt (sie würde nicht geladen), sowie eine ID, die in einem Block doppelt steht (nur die letzte Zeile zählt; --validate meldet es auch). python .act/scripts/rules.py --worker zeigt, was ein Worker bekommt, --imports, was die Hauptsitzung lädt, mit der Größe jeder Datei in Zeichen und einer Summe, geteilt in den Anteil des Templates und den des Projekts. Die Regeln, die ein Hook mechanisch prüft, stehen in der Regeldatei gekürzt: Verbot oder Pflicht und der Name der Prüfung bleiben, was die Prüfung erkennt, ihre Grenzen, ihr Schalter und ihre Syntax stehen auf der Seite zu den Prüfungen.

docs/project/coding_rules.md funktioniert genauso für Coding-Regeln. Jede Zeile - [x] use: @../../.act/coding/<set>.md (angekreuzt) oder - [ ] use: .act/coding/<set>.md (nicht angekreuzt) schaltet einen Satz an oder aus, mit seinen Gruppen (CR-<set>-<group>) darunter, jede einzeln ankreuzbar. init belegt die Kästchen anhand des erkannten Stacks vor, und stack in docs/ai/config.md ist die Stelle, an der du das korrigierst. Dieselben Abschnitte für Overrides und eigene Regeln gelten auch hier. Sätze gibt es unter anderem für Python, TypeScript, Vue, Nuxt, Tailwind, PHP, Java, Go, Rust, Kotlin, C, C++, PowerShell, Docker, CI, CSS, JavaScript und React. Bringt ein Update einen neuen Satz, erscheint er nicht angekreuzt in der Datei; eine neue Gruppe eines angekreuzten Satzes erscheint angekreuzt. Vorhandene Zeilen, Kästchen und eigene Regeln bleiben, wie sie sind. update.py --plan zeigt vorab, welche Sätze und Gruppen ein Update eintragen würde; python .act/scripts/rules.py --add-new-coding trägt sie später ein. Solange docs/project/coding_rules.md nicht committete Änderungen hat, trägt das Update nichts ein (sie wären sonst in den Update-Commit geraten), sagt das in Schritt 6 und in den Schlussnotizen und nennt den Befehl für nach dem Commit. Die Arbeitsmethoden, die über methods eingeschaltet werden, stehen ebenfalls als importierte Sätze in dieser Datei.

docs/ai/config.md steuert Arbeitsablauf, Prüfungen, Rollen und Sprachen. Die Tabelle ## Roles darin überschreibt Tier, Reasoning, Modell (Claude Code) oder Copilot-Modelle einer einzelnen Rolle. Siehe die Konfigurationsreferenz, die Regelreferenz und die Referenz der Coding-Regeln.

Ein Update kann .act/ ohne Merge ersetzen, weil das Projekt es nie bearbeitet hat. Deine Entscheidungen liegen in Dateien, die dem Update nicht gehören. Findet ein Update trotzdem eine Handänderung in .act/, entscheidest du: rescue verschiebt sie nach docs/ai/local/, discard verwirft sie, abort bricht das Update ab.