getpaidskills/agents-md-starter

Was macht agents-md-starter?

Ausgabe: AGENTS.md im Repository-Stamm als einzige Quelle der Wahrheit, plus CLAUDE.md mit @AGENTS.md (Claude Code liest CLAUDE.md und unterstützt @path-Importe). Jeder Befehl in der Datei muss erfolgreich ausgeführt oder klar als unverifiziert markiert sein.

Schritt 1 — Scan

python3 scripts/scan_repo.py /pfad/zum/repo            # menschliche Zusammenfassung
python3 scripts/scan_repo.py /pfad/zum/repo --json     # Fakten als JSON
python3 scripts/scan_repo.py /pfad/zum/repo --draft > AGENTS.draft.md   # ausgefüllte Vorlage

Es erkennt: Sprachen nach Dateianzahl, Paketmanager aus Lockdateien, Skripte in package.json, Makefile-Ziele, pyproject.toml-Tools (pytest, ruff, mypy, uv/poetry), Go/Rust/Java-Builddateien, Frameworks (Next.js, Astro, Vite, Django, FastAPI, Rails…), Monorepo-Workspaces, CI-Workflows, Env-Beispiel- dateien und vorhandene Agenten-Regeldateien. Es führt niemals Repository-Code aus.

Schritt 2 — Lesen vor dem Schreiben

• Jede vorhandene Regeldatei lesen, die es gefunden hat (CLAUDE.md, .cursorrules, .cursor/rules/*.mdc, .github/copilot-instructions.md, GEMINI.md, CONTRIBUTING.md). Ihre echten Regeln behalten; zusammenführen, doppelt entfernen, generische Regeln („schreibe sauberen Code“) verwerfen.
• Den CI-Workflow lesen: Die Befehle, die CI ausführt, sind die zuverlässigste Definition von „Tests bestehen“.
• 2–3 repräsentative Quelldateien überfliegen, um die tatsächlichen Konventionen zu erfassen (Benennung, Fehlerbehandlung, Import-Stil) — keine Konventionen erfinden, die der Code nicht befolgt.

Schritt 3 — Befehle verifizieren

Install-/Build-/Test-/Lint-Befehle aus dem Entwurf ausführen (sicher: kein Deployment, keine Migrationen gegen echte Datenbanken, kein Publizieren). Für jeden: Behalten, wenn er funktioniert; korrigieren, wenn die richtige Variante offensichtlich ist; sonst mit (unverifiziert) markieren und dem Benutzer mitteilen. Notieren, wie lange die Testsuite dauert, falls sie langsam ist.

Schritt 4 — AGENTS.md schreiben

Beginne mit assets/AGENTS.template.md. Regeln für guten Inhalt:

• Kurz. Auf unter ~150 Zeilen abzielen. Agents lesen dies bei jeder Aufgabe; jede Zeile kostet Kontext.
• Spezifisch und überprüfbar: „Führe pnpm test --filter web vor dem Commit aus“ ist besser als „Teste deinen Code“.
• Die Befehle zuerst setzen. Dann Layout, Konventionen, Fallstricke und „nicht tun“-Regeln.
• Das Nicht-Offensichtliche festhalten: generierte Dateien, die nicht bearbeitet werden dürfen, Umgebungsvariablen, die für Tests benötigt werden, den einen langsamen Test, der lokal übersprungen werden kann, wo Geheimnisse niemals landen dürfen.
• Monorepos: Root-AGENTS.md für gemeinsame Regeln + verschachtelte packages/x/AGENTS.md für paketspezifische Befehle (Agents, die dies unterstützen, lesen die nächstgelegene Datei).

Schritt 5 — Die anderen Tools anbinden

• Claude Code: CLAUDE.md aus assets/CLAUDE.template.md erstellen (sie enthält @AGENTS.md). Wenn bereits eine CLAUDE.md existiert, ihre Regeln in AGENTS.md verschieben und Claude-spezifische Notizen unter dem Import belassen.
• Codex: Liest AGENTS.md nativ — nichts weiter nötig.
• Cursor: Liest AGENTS.md im Stammverzeichnis; .cursorrules-Inhalt in AGENTS.md migrieren und, nach Zustimmung des Benutzers, .cursorrules löschen (veraltet). .cursor/rules/*.mdc nur für glob-begrenzte Regeln behalten.
• Gemini CLI: Liest standardmäßig GEMINI.md; "context": {"fileName": ["AGENTS.md", "GEMINI.md"]} in .gemini/settings.json setzen oder eine einzeilige GEMINI.md erstellen, die auf AGENTS.md verweist. Die Dokumentation der installierten Version prüfen, ob dieser Schlüssel verschoben wurde.
• Symlinks (ln -s AGENTS.md CLAUDE.md) funktionieren ebenfalls, brechen aber bei Windows-Checkouts ohne core.symlinks; der Import-Ansatz ist sicherer.

Siehe references/tool-support.md für die Datei, die jedes Tool liest.

Schritt 6 — Bericht

Auflisten: erstellte/geänderte Dateien, verifizierte Befehle (mit Ergebnis), als unverifiziert markierte Befehle, als doppelt oder generisch verworfene Regeln und alles, bei dem der Benutzer entscheiden muss (z. B. .cursorrules löschen?). Nicht committen, es sei denn, der Benutzer hat darum gebeten.