aitormf/agent-skills

Projektkontext

Hilf der Person, die stabilen Regeln des Projekts zu entscheiden und aufzuschreiben – jede Regel in der Datei, in die sie gehört. Die Person trifft die Entscheidungen: du liest, schlägst konkrete Optionen vor und erstellst Entwürfe.

Es ersetzt Spec Kits constitution.md. Alle Inhalte haben einen besseren Platz:

Inhalt	Datei	Gelesen von
Stack, Schichten, Abhängigkeitsregeln, nicht verhandelbare Prinzipien, Glossar	docs/ARCHITECTURE.md	Menschen und Agenten; spec-to-plan und review-spec prüfen die Prinzipien
Qualität, Branches, Commits, PRs, Review, AI-Nutzung	CONTRIBUTING.md	Menschen (und Agenten per Link)
Das Warum jeder strukturellen Entscheidung und die verworfenen Alternativen	docs/adr/NNNN-*.md	Beide, bei Bedarf
Befehle, Grenzen, nicht offensichtliche Konventionen, Dokumentationskarte	AGENTS.md (+ CLAUDE.md mit @AGENTS.md)	Agenten, in jeder Sitzung
Wie man Schwachstellen meldet, Agentenrichtlinie	SECURITY.md	Menschen

Vorlagen in assets/en/ (Englisch) und assets/es/ (Spanisch). Verwende die Sprache, in der das Projekt dokumentiert ist; frage nach, falls unklar. Jede Vorlage erklärt im Eröffnungskommentar, wie sie auszufüllen ist.

Regeln

• Keine Duplikate. Wenn etwas bereits in pyproject.toml, in CI oder in einem Linter steht, verweise darauf; kopiere es nicht. Wenn ein Prinzip in zwei Dateien erscheint, widersprechen sie sich irgendwann: Prinzipien leben nur in ARCHITECTURE.md.
• Kurzes AGENTS.md: unter 150 Zeilen. Es ist eine Karte, die verlinkt; sie enthält nicht. Für jede Zeile: „Wenn ich sie entferne, würde der Agent einen Fehler machen?“. Wenn nein, raus.
• Was mit einem Werkzeug geprüft werden kann, wird mit einem Werkzeug geprüft. Frage bei jedem Prinzip, wie es verifiziert wird (Lint, import-linter, Test, CI, Review) und notiere es in der entsprechenden Spalte.
• Nichts Volatiles: kein Sprint-Status oder TODOs. Diese gehören in den Tracker oder in docs/plans/.
• Zeige jede Datei vollständig (oder den Diff, falls sie bereits existiert) und schreibe erst nach Zustimmung der Person.

Prozess

1. Projekt lesen

Bevor du etwas fragst, lies: Manifeste (pyproject.toml, package.json, go.mod…), README.md, bestehende Kontextdateien, .github/workflows/, Linter-Konfiguration und die Ordnerstruktur. Nutze das Gefundene, um Antworten vorzuschlagen, anstatt offene Fragen zu stellen.

Bestimme den Modus und teile ihn der Person mit:

• Greenfield (kein oder fast kein Code): ARCHITECTURE.md ist vorschreibend, wie es sein wird.
• Brownfield: ARCHITECTURE.md ist beschreibend, wie es heute ist. Das Ideal gehört in ADRs und die Sperren der Werkzeuge. Falls Kontextdateien bereits existieren, frage nur nach den Lücken und schlage Diffs vor.
• Migration von einer constitution.md: Verteile die Inhalte gemäß der obigen Tabelle und schlage vor, sie zu löschen oder auf einen Link zu reduzieren.

2. Interview in Runden

Eine Kategorie nach der anderen. Biete zu jeder Frage konkrete Optionen an (A, B, „offen lassen“, „anderes“). Wenn die Dateien die Frage bereits beantworten, frage nach Bestätigung, anstatt zu fragen. Wenn eine Kategorie nicht zutrifft (z. B. gibt es keine Datenbank), überspringe sie und sage dies. Am Ende jeder Runde fasse zusammen, was entschieden wurde.

Runde	Was wird entschieden	Ziel
1. Zweck	Was das Projekt ist und was nicht; Typ (App, Service, Bibliothek, CLI)	ARCHITECTURE.md §1, README.md
2. Stack und Architektur	Sprache, Framework, Persistenz, Infrastruktur; Schichten oder Module und was was importieren darf	ARCHITECTURE.md §2–4, ein ADR pro struktureller Entscheidung
3. Nicht verhandelbare Prinzipien	5–10 stabile, verifizierbare Regeln: warum und wie jede geprüft wird	ARCHITECTURE.md §5
4. Qualität	Test zuerst oder danach, Mindestabdeckung, Typisierung, was niemals gemockt wird	CONTRIBUTING.md §5; falls nicht verhandelbar, auch ein Prinzip
5. Sicherheit	Authentifizierung, sensible Daten, Eingabevalidierung, regulatorische Compliance	ARCHITECTURE.md §10, SECURITY.md
6. Prozess	Branches, Conventional Commits, Merge oder Squash, Freigaben, PR-Größe, erlaubte AI-Tools	CONTRIBUTING.md §4, §6–7
7. Abhängigkeiten	Richtlinie zum Hinzufügen, verbotene Bibliotheken, Bauen oder Kaufen	Prinzip (falls nicht verhandelbar) oder CONTRIBUTING.md
8. Für den Agenten	Befehle (der Verifikationsbefehl ist Pflicht), nicht offensichtliche Konventionen, kritische oder fragile Bereiche (Brownfield), Grenzen (immer / fragen / nie)	AGENTS.md

In Runde 8 ist der Verifikationsbefehl der Vertrag mit den anderen Skills (plan-to-tasks, implement, Review). Falls er nicht existiert, schlage setup-guardrails-python (oder ein Äquivalent für die Sprache) vor oder lasse es als offene Frage in AGENTS.md. Wenn das Projekt review-prepush oder review-pr verwendet, biete auch den optionalen Abschnitt ## Code review an (Vorlage in review-context/assets/AGENTS-code-review.md): Basis-Branch, Hochrisikopfade, Berichtssprache…

3. Entwurf und Schreiben

Reihenfolge: ARCHITECTURE.md → ADRs → CONTRIBUTING.md → SECURITY.md → AGENTS.md. AGENTS.md kommt zuletzt, weil es auf alle anderen verlinkt.

• Beginne mit der Vorlage aus assets/. Lösche die Abschnitte, die noch nicht zutreffen; lasse sie nicht leer.
• ADRs: Kopiere ADR.md als docs/adr/0000-template.md (0000-plantilla.md auf Spanisch) und adr-README.md als docs/adr/README.md. Erstelle ein ADR pro struktureller Entscheidung aus den Runden 2–3. Brownfield: nur 3–5 rückwirkende, für das, was am meisten hinterfragt wird, mit den verworfenen Alternativen.
• AGENTS.md muss enthalten:
  • die Zeile „Planung“: überprüfe den Plan anhand der Prinzipien in docs/ARCHITECTURE.md, bevor du implementierst;
  • einen Link zu CONTRIBUTING.md für den Prozess.
• CLAUDE.md enthält nur @AGENTS.md, es sei denn, es hat bereits Inhalt. In diesem Fall schlage vor, ihn in AGENTS.md zu verschieben.
• pull_request_template.md kommt in .github/. Biete es an, erzwinge es nicht.

4. Abschluss

Liste die erstellten oder geänderten Dateien sowie die offenen Fragen auf. Erinnere die Person:

• AGENTS.md wird monatlich überprüft und gekürzt, besonders beim Wechsel der Modelle.
• ARCHITECTURE.md wird vierteljährlich mit dem Code abgeglichen.
• Jeder Fehler, den der Agent wiederholt, wird zu einer Werkzeugregel oder, als letztes Mittel, zu einer Zeile unter „Bekannte Fallstricke“.