Zum Inhalt springen

Eigene Regeln, Skills und Rollen

Das Projekt überschreibt immer das Template. Du bearbeitest nie etwas unter .act/; ein Wächter (template-write-guard) verweigert dort Schreibzugriffe. Alles, was dir gehört, kommt nach docs/ai/ und docs/project/ und übersteht jedes Update.

docs/ai/rules.md listet die Regeldateien auf, die der Assistent lädt, jeder Import gefolgt von seinen Regeln als Kontrollkästchen:

@../../.act/rules/shared/20-code.md
- [x] `R-code-language`
- [ ] `R-code-encoding`
  • Eine Regel abschalten: Entferne ihr Kreuz. Die Datei wird weiterhin ganz geladen, aber eine nicht angekreuzte Regel gilt als aus. Verschiebt ein Update der Vorlage eine Regel in eine andere Regeldatei, verschiebt act-update ihre Kästchenzeile in einer bearbeiteten docs/ai/rules.md mit, Kreuz und Begründung unverändert, sodass eine ausgeschaltete Regel ausgeschaltet bleibt. Importierst du die neue Datei nicht, wird die Verschiebung nur gemeldet; rules.py meldet außerdem eine verschobene Regel, deren neue Datei du mit einer eigenen Kopie unter docs/ai/local/rules/ überdeckst, in der sie fehlt (die Regel wird dann nicht geladen), und eine ID, die in einem Block zweimal steht (nur die letzte Zeile zählt).
  • Neue Regeln der Vorlage: act-update und der Sitzungsstart tragen von der Vorlage neu hinzugefügte Regeln auch in eine bearbeitete docs/ai/rules.md ein, als Kästchenzeile je Regel, und eine neue Regeldatei als Import-Block am Ende ihres Abschnitts. Dein eigener Text, nicht angekreuzte Kästchen und von dir entfernte Imports bleiben unverändert, und eine entfernte Zeile kommt nicht zurück (.act-lock.json merkt sich, was angeboten wurde); ihre Regel gilt trotzdem als eingeschaltet, ausgeschaltet wird sie über das Kreuz. Was sich nicht sicher eintragen lässt, nennt python .act/scripts/rules.py --add-missing.
  • Einen ganzen Bereich abschalten: Lösche seine @-Importzeile.
  • Das Template je Projekt beschneiden: Die Schlüssel profile (minimal, standard oder full, der Standard) und exclude im Abschnitt Scope von docs/ai/config.md lassen Skills, Rollen, Regeldateien (nicht shared/10-safety.md) und Topics des Templates weg. Der Sitzungsstart entfernt die Kopien, stellt die Importzeile einer ausgeschlossenen Regeldatei in docs/ai/rules.md auf einen bloßen Pfad um und nennt den Schnitt in einer Zeile; wirksam wird er ab der nächsten Sitzung, die Checks bleiben an. Siehe Scope.
  • Den Wortlaut einer Regel ersetzen: Füge unter ## Overrides einen Listenpunkt der Form - replaces `R-...`: <your version> hinzu, der die Regel und deine Fassung nennt (Zeilen, die mit <!-- beginnen, werden übersprungen). Eine replaces-Zeile gewinnt gegenüber dem Text des Templates, egal ob die Regel angekreuzt ist oder nicht.
  • Eigene Regeln hinzufügen: Lege unter ## Own rules einen Punkt pro Regel an, die im Template keine Entsprechung hat. Eine eingerückte Liste direkt unter einer eigenen Regel (oder einer replaces-Zeile) gehört zu ihr und wird als Teil ihres Textes gelesen. Jede eigene Regel bleibt bei einer Zeile: Vorfall, Beleg und Kennungen gehören in die Projektdoku, die nicht in jeder Sitzung geladen wird. Der Abschnitt „Own rules“ im Gerüst von coding_rules.md enthält eine Tabelle, wohin welche Art Regel gehört (eigene Regel, pfadgebundene Regeldatei unter .claude/rules/, eigener Regelsatz, Projektdoku oder nirgends). act-doctor warnt, wenn die Abschnitte „Own rules“ von docs/ai/rules.md und docs/project/coding_rules.md zusammen own-rules-budget überschreiten (Standard 6000 Zeichen, off oder 0 schaltet es ab), und nennt bis zu fünf Zeilen, die wie Verlauf aussehen; es blockiert nie. Siehe Checks.

Die Regeldateien, die der Abschnitt „Orchestrator only“ in docs/ai/rules.md importiert (.act/rules/orchestrator/ oder ihre Overrides unter docs/ai/local/rules/orchestrator/), erreichen Worker nicht; anderer Text in diesem Abschnitt schon. Die Rollen des Templates laden kein CLAUDE.md, ein Hook gibt ihnen stattdessen die geteilten Regeln, die Coding-Regeln, deine eigenen Regeln aus docs/ai/rules.md, CLAUDE.local.md und ~/.claude/CLAUDE.md, ohne .act/rules/orchestrator/. Eine Regel für Worker gehört daher in die geteilten oder die Coding-Abschnitte oder unter ## Own rules. python .act/scripts/rules.py --worker zeigt, was ein Worker bekommt.

Lass die Marken (<!-- act:overrides -->, <!-- act:own-rules -->) stehen, wo sie sind; die Mechanik findet die Abschnitte über sie. python .act/scripts/rules.py --imports zeigt, was tatsächlich geladen wird. Jede Datei endet mit ihrer Größe in Zeichen (ein CRLF-Zeilenende zählt als eins), und eine letzte Zeile gibt die Summe an, getrennt in den Anteil des Templates unter .act/ und den des Projekts. Coding-Regelsätze funktionieren genauso in docs/project/coding_rules.md; eine Satzzeile nimmt hinter dem Pfad optional einen Grund (- [ ] use: <path> — <reason>) wie eine Gruppenzeile, um festzuhalten, warum ein Satz aus ist; ein eigener Satz oder eine lokale Überschreibung eines Template-Satzes liegt unter docs/ai/local/coding/<set>.md und wird ebenfalls in docs/project/coding_rules.md eingeschaltet (nur die lokale Datei wird geladen, statt der des Templates). act-update führt neue Sätze und Gruppen des Templates in docs/project/coding_rules.md auf: ein neuer Satz nicht angekreuzt, eine neue Gruppe eines angekreuzten Satzes angekreuzt; deine Zeilen, Kästchen und Begründungen bleiben. update.py --plan zeigt genau diese Liste vorab und schreibt nichts. Solange docs/project/coding_rules.md nicht committete Änderungen hat, trägt das Update nichts ein (sie gingen sonst in den Update-Commit) und sagt das mit dem Befehl, der nach deinem Commit zu starten ist: python .act/scripts/rules.py --add-new-coding. rules.py --list und --validate zeigen außerdem die pfadgebundenen Regeln von Claude Code unter .claude/rules/ mit ihren paths:-Mustern, warnen vor einem Muster ohne passende Datei und vermerken eine Datei ohne paths: (sie wird bei jedem Start geladen); eine solche Regel wird erst geladen, wenn eine passende Datei gelesen oder geschrieben wird, und act-adopt bietet an, diese Dateien unverändert zu behalten. Die Regel-IDs stehen in der Regelreferenz und der Coding-Regelreferenz.

docs/ai/local/ spiegelt .act/: Eine Datei mit demselben relativen Pfad gewinnt gegenüber der Fassung des Templates. docs/ai/local/<path> wird vor .act/<path> gesucht. Um eine Skill-Datei des Templates zu ändern, kopiere sie nach docs/ai/local/skills/<name>/<file> und bearbeite die Kopie; die Projektkopie wird dann aus deinem Override erzeugt. Der Ordner gehört dir, und der Assistent schreibt dort nur, wenn du es ihm sagst.

Benennt oder entfernt das Template eine Datei, die du überschreibst, hat die Überschreibung stillschweigend keine Wirkung; act-doctor meldet eine solche Datei mit dem ähnlichsten Namen unter .act/. Regel-Overrides, Rollen und eigene Skills bleiben außen vor, ebenso ein eigenes Script oder ein eigener Coding-Satz, es sei denn, ein Name ist der Anfang des anderen oder unterscheidet sich nur in der Endung.

Auch die Texte, die der Assistent schreibt, haben Formate: Eine Datei docs/project/formats/<name>.md (commit.md, changelog.md, release-notes.md, project-readme.md) ersetzt das Format des Templates für dieses Thema vollständig; die Schlüssel, die ein Preset wählen, stehen unter Formats.

Optionale Arbeitsmethoden (test-first, spec-first, simple-changes) sind Regelsätze, die die Zeile methods im Abschnitt Scope von docs/ai/config.md einschaltet. Sie werden als Importe in docs/project/coding_rules.md geschrieben, sodass Orchestrator und jeder Worker sie laden, und eine Gruppe lässt sich dort wie in jedem Regelsatz abwählen. Eine eigene Methode liegt unter docs/ai/local/methods/<name>.md. Siehe Scope.

Der Ordner enthält auch optionale eigene Dateien, zum Beispiel reminders.md (eine Zeile „erinnere mich“ pro Zeile, mit optionalem Takt) und security-accepted.md (siehe Sicherheitsprüfung).

Ein Skill ist ein Verzeichnis mit einer SKILL.md, die mit YAML-Frontmatter (name, description) beginnt und werkzeugneutrale Anweisungen enthält. Lege deinen eigenen unter docs/ai/local/skills/<name>/SKILL.md ab; seine Werkzeugkopien (.claude/skills/<name>/, und .agents/skills/<name>/ nur, wenn codex, copilot, gemini oder cursor eingerichtet ist) schreibt act-load-settings beim Import. Ein von Hand platzierter Skill bekommt sie beim nächsten Sitzungsstart (mit session-start-refresh auf dem Standard block) oder update.py-Lauf, oder mit python .act/scripts/unit_copies.py. Eine Kopie folgt ihrer Quelle: Eine unveränderte Kopie wird beim Sitzungsstart aufgefrischt, wenn sich die Quelle ändert, und act-doctor meldet eine von Hand geänderte Kopie, die erhalten bleibt; ändere die Quelle in docs/ai/local/skills/, nicht die Kopie. Eine gelöschte bleibt gelöscht. Bis dahin ist der Skill über /act <name> erreichbar. Ein Skill-Name, den das Template schon mitliefert, ist ein Override dieses Skills, kein neuer; act-doctor meldet ihn, bis du ihn mit python .act/scripts/doctor.py --accept skill:<name> behältst oder löschst (own-rules-review). Schreibe die description mit dem Auslöser zuerst („Use when …“, 15 bis 55 Wörter, keine Aufzählung von Schritten), denn sie ist alles, was ein Agent sieht, bevor er den Skill lädt; python .act/scripts/skills.py --check prüft sie, und doctor meldet bei deinen eigenen Skills eine fehlende oder zu lange Beschreibung. doctor prüft außerdem das Frontmatter deiner eigenen Skills und Rollen: gültiges YAML, ein name gleich dem Ordner- oder Dateinamen, keine unbekannten oder ungültigen Felder. Ein langer Skill hält den Kernablauf in SKILL.md und legt Details in references/<topic>.md ab, die nur bei Bedarf geladen werden. Die mitgelieferten Skills stehen in der Skill-Referenz.

Eine eigene Rolle ist eine Datei docs/ai/local/agents/<name>.md mit ihren Regeln. Eine neue Rolle ist ihre eigene Brückenquelle und braucht Frontmatter (name, description, Tier/Reasoning, tools); nur ein Override einer Rolle des Templates ist reiner Text ohne Frontmatter. Tier und Reasoning (bei einem Skill: reasoning im Frontmatter, überschreibbar durch eine Zeile mit dem Namen des Skills) lassen sich auch in der Tabelle Roles von docs/ai/config.md setzen (siehe Tiers und Reasoning); die werkzeugspezifische Datei unter .claude/agents/ wird von init und update erzeugt; eine eigene Rolle bekommt sie unter dem Standard session-start-refresh auch beim Sitzungsstart. Sobald eine solche Datei existiert, gehört ihr Text dir: Updates frischen nur ihre Zeilen model und effort auf. Die Rollen des Templates tragen omitClaudeMd: true; eine eigene Rolle ohne das Feld lädt CLAUDE.md wie bisher, auch die Orchestrator-Regeln. Setze das Feld, wenn sie nur die Worker-Regeln bekommen soll (siehe Update). Die eingebauten Rollen sind unter Rollen beschrieben.

Ein Package ist ein zweiter Weg, Regeln, Coding-Sätze, Skills, Rollen, Topics, Scripts und Prüfungen in ein Projekt zu bringen, ohne .act/ zu ändern; ohne Plan, Diff und dein Ja im Chat wird nichts installiert. Packages finden, installieren, aktualisieren, entfernen, schreiben und einreichen: siehe die Anleitung Packages. Die Ladefolge der Regeln steht unter Schichten.

Zwei Skills tragen deine Abweichungen vom Template in ein anderes Projekt.

Beide Skills starten nur als eingetippter Slash-Befehl (/act-export-settings, /act-load-settings); eine Bitte in normalen Worten startet sie nicht.

act-export-settings schreibt, was du gegenüber dem Template geändert hast, in eine settings.md: deine eigenen Regeln, abgeschaltete Regeln und Gruppen, replaces-Overrides. Nichts über das Projekt selbst (Name, Arbeitsstand) kommt hinein. Optionen:

  • --all listet auch die unveränderten Regeln auf.
  • --with-scripts, --with-checklists, --with-agents, --with-skills fügen die Dateien aus docs/ai/local/ hinzu; jede davon erzeugt statt einer .md eine .zip.
  • --with-topics fügt die Topic-Regeln unter docs/ai/local/rules/topics/ hinzu: ein eigenes Topic als [+] <name>.md, ein Override eines Topics des Templates als [~] <name>.md mit einem Fingerabdruck des überschriebenen Topics. Ganze Dateien, es erzeugt also ebenfalls eine .zip.
  • --with-formats fügt deine Format-Dateien aus docs/project/formats/ hinzu (nur die vier Namen oben) und erzeugt daher eine .zip; act-load-settings schreibt sie dorthin zurück.
  • --strict bricht ab, statt einen Platzhalter einzusetzen; nutze es, wenn die Datei deine Hände verlässt.
  • --out PATH wählt den Ort; Standard ist .act-local/export/. --profile schreibt stattdessen in dein persönliches Profil. Einen Pfad außerhalb des Projekts verweigert die Prüfung outside-root: nimm den Standardordner, trag den Pfad in outside-root-allow ein (Checks) oder setze ACT_OUTSIDE_ROOT=warn für einen Lauf.

Das Script durchsucht jeden Wert nach Zugangsdaten, Mailadressen, IP-Adressen, lokalen Pfaden und internen Hosts und ersetzt einen Treffer durch einen sichtbaren Platzhalter <setup:KIND>. Es meldet die Zahl der Funde; überfliege die Datei, bevor du sie irgendwohin schickst.

act-load-settings importiert eine solche Datei. python .act/scripts/settings_load.py plan zeigt, was passieren würde, und schreibt nichts; ohne genannte Datei nimmt es alles in .act-local/import/. Eine Datei außerhalb des Projekts verweigert outside-root: leg sie nach .act-local/import/, erlaube ihren Ordner in outside-root-allow oder setze ACT_OUTSIDE_ROOT=warn für einen Lauf. apply schreibt dann, was eindeutig ist. Überschneidungen mit deinen eigenen Regeln werden beurteilt, nicht stillschweigend angewendet, und alles Ungeklärte landet in einem Inbox-Eintrag. Mitgelieferte Scripts, Skills und Rollen werden dir gezeigt, bevor sie geschrieben werden, und ein Skill oder eine Rolle, die denselben Namen wie einer des Templates trägt oder riskantes Frontmatter verlangt (Hooks, MCP-Server, Berechtigungsmodi), wird gemeldet und nie geschrieben. Eigene Topic-Regeln und Topic-Overrides gehen nach docs/ai/local/rules/topics/<name>.md: ein Topic, das dort mit anderem Inhalt schon liegt, wird als geändert gemeldet und nicht angetastet; ein Override, dessen Topic im Template nicht mehr existiert, wird als tot gemeldet und nicht geschrieben; einer, dessen Topic sich seit dem Export geändert hat, wird als „seit dem Export geändert“ gemeldet und von Hand geprüft. Bekommt die Frage „Write ?“ zu einer Settings-Datei keine Eingabe (doch kein Terminal), wird die Datei nicht geschrieben.