# Technik: Dateien, Optionen, Aufbau Diese Seite ist für Entwickler. Sie zeigt alle Dateien, alle Optionen und den Aufbau des Projekts. Die kurze Anleitung steht in der [README](README.md). ## Alle Optionen des Installers Optionen gibst du hinter `bash -s --` mit: ```sh # alles installieren, nie fragen curl -fsSL https://deltatree.github.io/BestAiConfig/bootstrap.sh | bash -s -- --yes # nur Cursor, plus die Pflicht-Dateien curl -fsSL https://deltatree.github.io/BestAiConfig/bootstrap.sh | bash -s -- --components cursor # mehrere Assistenten curl -fsSL https://deltatree.github.io/BestAiConfig/bootstrap.sh | bash -s -- --components cursor,cline # Sprache festlegen curl -fsSL https://deltatree.github.io/BestAiConfig/bootstrap.sh | bash -s -- --language French ``` | Option | Wirkung | |---|---| | `--components ` | Nur diese Assistenten. Die Pflicht-Dateien kommen immer. | | `--all` | Alle Assistenten. | | `--yes`, `--non-interactive` | Keine Fragen. | | `--language ` | Sprache des Assistenten. `ask` legt keine fest. | | `--version ` | Eine archivierte Version aus `versions//`. | | `--uninstall` | Entfernt alles, was die Registry installiert hat. | | `--skip-tools` | Keine BMAD-Skills aus dem Paket, keine Hinweise zu `uv` und `rtk`. | | `--base-url ` | Andere Registry, zum Beispiel ein Fork. | | `--help` | Alle Optionen. | Dieselben Einstellungen gehen über Umgebungsvariablen: `RULES_COMPONENTS`, `RULES_NONINTERACTIVE=1`, `RULES_LANGUAGE`, `RULES_VERSION`, `RULES_UNINSTALL=1`, `RULES_SKIP_TOOLS=1`, `RULES_ALLOW_HTTP=1`, `RULES_REQUIRE_DIGEST=1`, `RULES_BUNDLE_URL`. Optionen gewinnen. ## Der Webdienst Der Installer holt alles in einem Download: `bundle.tar.gz` vom Webdienst auf dtadmin. Die Adresse steht im Manifest (`install.bundle`). Das Paket enthält alle Dateien der Registry und die fertigen BMAD-Skills. Auf deinem Rechner läuft dafür kein Paketmanager. | Adresse | Inhalt | |---|---| | `https://bestaiconfig.apps.dtcloud.de/bundle.tar.gz` | Das Paket, etwa 4 MB. | | `https://bestaiconfig.apps.dtcloud.de/bootstrap.sh` | Derselbe Installer wie auf GitHub Pages. | | `https://bestaiconfig.apps.dtcloud.de/healthz` | `ok`, wenn der Dienst läuft. | Messung vom 2026-09-28 in einem leeren Repo: vorher 25 bis 46 Sekunden für 204 Einzel-Downloads, dazu `npm` und `brew`. Mit Paket 7 Sekunden. | Fall | Was passiert | |---|---| | Dienst erreichbar | Ein Download. BMAD kommt aus dem Paket. | | Dienst nicht erreichbar | Warnung, dann Datei für Datei von GitHub Pages. BMAD fehlt bis zum nächsten Lauf. | | `RULES_BUNDLE_URL=off` | Kein Paket, Datei für Datei. | | `RULES_BUNDLE_URL=` | Paket von dieser Adresse, etwa von einem eigenen Dienst. | | `--version ` | Kein Paket, denn das Paket trägt immer den neuesten Stand. | Jeder Eintrag im Paket muss eine Datei oder ein Ordner unter `registry/` oder `tools/` sein. Links, `..`, `.git` und absolute Pfade lehnt der Installer ab. Danach gelten dieselben Prüfungen wie beim Einzel-Download, auch die SHA-256-Werte. ## Alle Dateien, die der Installer anlegt Der Installer schreibt nur diese Pfade. Er fasst `.git` und deinen Code nie an. | Pfad | Komponente | Was es ist | |---|---|---| | `AGENTS.md` | `agents-md` (immer) | Die Regeldatei im offenen Standard AGENTS.md. Jeder Assistent, der den Standard liest, folgt ihr. | | `.claude/skills/*/SKILL.md` | `skills` (immer) | Ein Skill je Thema im Standard [Agent Skills](https://agentskills.io/specification). Claude Code, Cursor und Copilot lesen den Ordner. Eigene Skills bleiben. | | `.agents/skills` | `skills` (immer) | Link auf `.claude/skills`. Codex, Antigravity, Junie, Amp, OpenCode, Roo, Devin und Replit lesen ihn. | | `.claude/skills/skill-router/*` | `skills` (immer) | Die Skripte des Routers, der Meldungskatalog, die Evals. Werden bei jedem Install ersetzt. | | `.mcp.json` | `skills` (immer) | Der MCP-Server context7 für aktuelle Bibliotheks-Doku. Nur geschrieben, wenn die Datei fehlt. Schlüssel in `CONTEXT7_API_KEY`. | | `CLAUDE.md` | `claude-code` | Link auf `AGENTS.md`. | | `.claude/rules/*.md` | `claude-code` | Regeln mit engen Pfadmustern, mit `paths:`-Liste. Eigene `*.local.*` bleiben. | | `.claude/settings.json` | `claude-code` | Ein Hook, der den Router bei jeder Anfrage erzwingt, das Lese-Tor, plus `skillListingBudgetFraction` 0.03. Nur geschrieben, wenn die Datei fehlt oder unverändert ist. | | `.cursor/rules/*.mdc` | `cursor` | Eine Regel je Thema. Entfernt die alte `.cursorrules`. Eigene `*.local.*` bleiben. | | `.clinerules/*.md` | `cline` | Eine Regel je Thema. Eigene `*.local.*` bleiben. | | `memory-bank/` | `cline` | Sechs Notiz-Dateien für die Cline-Methode "Memory Bank". Nur geschrieben, wenn eine fehlt oder leer ist. | | `.github/copilot-instructions.md` | `github-copilot` | Link auf `AGENTS.md`. | | `.github/instructions/*.instructions.md` | `github-copilot` | Regeln mit engen Pfadmustern, mit `applyTo`. | | `.github/hooks/bestaiconfig.json` | `github-copilot` | Ein `sessionStart`-Hook mit der Router-Erinnerung. Nur wenn die Datei fehlt. | | `.codex/hooks.json` | `codex` | Ein `UserPromptSubmit`-Hook. Codex lädt ihn in vertrauten Projekten. | | `GEMINI.md`, `.gemini/settings.json` | `gemini` | Link auf `AGENTS.md`; ein `BeforeAgent`-Hook. | | `QWEN.md` | `qwen` | Link auf `AGENTS.md`. | | `.rules` | `zed` | Link auf `AGENTS.md`. | | `.kiro/steering/*.md`, `.kiro/hooks/bestaiconfig.json` | `kiro` | Regeln mit `inclusion: fileMatch`; ein `PromptSubmit`-Hook. | | `.devin/rules/*.md` | `devin` | Regeln mit `trigger: glob`. Entfernt die alte `.windsurfrules`. | | `.github/agents/` | `agents-md` | Ein leerer Standard-Ordner. | | `.bestaiconfig.lock` | immer | Version, Adresse der Registry, Prüfsumme, gewählte Komponenten. | | `_bmad/`, `.claude/skills/bmad-*` | Hilfsprogramm | Die [BMAD-Methode](https://github.com/bmad-code-org/BMAD-METHOD) mit den Modulen `cis` und `tea`. Kommt fertig aus dem Paket des Webdienstes. Wird bei jedem Lauf auf die gepinnte Version gebracht. `_bmad/custom/` gehört dir: der Installer schreibt es nur, wenn es fehlt. Dort setzt du zum Beispiel deinen Namen (`user_name`). | | `uv`, `rtk` | Hilfsprogramme | `uv` führt die Python-Skripte von BMAD aus. `rtk` kürzt Befehlsausgaben. Der Installer installiert sie nie. Fehlen sie, nennt er den Befehl zum Selbst-Installieren. | Der Installer lädt zuerst alles herunter. Dann sichert er deine Dateien. Dann schreibt er. Scheitert ein Schritt, stellt er die Sicherung wieder her. Ein fehlendes Hilfsprogramm gibt nur einen Hinweis. ## Eigene Regeln, die jede Installation überleben | Ebene | Wo | Wirkung | |---|---|---| | Diese Registry | `sources/custom/*.md` | Deine Regeln gewinnen gegen jede andere Quelle. Sie gehen in alle Projekte. | | Ein Projekt, alle Assistenten | `AGENTS.local.md` | Die Regeln sagen jedem Assistenten, diese Datei zu lesen. Der Installer fasst sie nur zwischen seinen zwei Markern an. | | Ein Projekt, ein Assistent | `.cursor/rules/x.local.mdc`, `.clinerules/x.local.md` | Dateien mit `.local.` im Namen bleiben. | | Eigene Skills | `.claude/skills//` | Bleiben bei jedem Install. | | Projektwissen | `memory-bank/*.md` | Gehört dir. Der Installer legt nur fehlende Dateien an. | ## Wie die Skills wirken 1. Beim Start liest der Assistent nur Name und Beschreibung jedes Skills. 2. Jede Beschreibung sagt, wann der Skill gilt. 3. Passt die Aufgabe, liest der Assistent den ganzen Skill und folgt ihm. Der Skill `skill-router` ist der Einstieg. Eine Regel in `AGENTS.md` schickt jeden Assistenten zuerst dorthin. Der Router wählt die Phase (zum Beispiel Anforderungen, Bauen, Prüfen) und die Disziplinen (zum Beispiel Tests, Sicherheit, einfache Sprache). Wie stark ein Assistent den Router erzwingt, ist verschieden: | Assistent | Router-Einstieg | Schreib-Sperre | |---|---|---| | Claude Code | Hook bei jeder Anfrage | Hook vor der ersten Dateiänderung | | GitHub Copilot | Hook beim Sitzungsstart | nur die Regel | | Codex, Kiro, Gemini, Antigravity | Hook bei jeder Anfrage | nur die Regel | | Cursor, Cline, Devin, Qwen, Zed | nur die Regel | nur die Regel | Ein Hook beweist, dass der Router aufgerufen wurde. Er beweist nicht, dass der Assistent ihm gefolgt ist. Miss es selbst: `sh .claude/skills/skill-router/measure-discipline.sh`. ## Kontext-Budget Jede Skill-Beschreibung sitzt bei jeder Anfrage im Kontext. Darum gibt es ein Budget: höchstens 25 Wörter je Beschreibung, höchstens 1000 Wörter für eigene Skills, 1600 für die BMAD-Skills. Der Installer meldet den Stand. Claude Code kürzt die Liste ab 1 Prozent des Kontextfensters; der Seed setzt 3 Prozent. Details in [skill-gate-kosten.md](skill-gate-kosten.md). ## Token sparen Ein Coding-Assistent verbraucht die meisten Tokens beim Lesen, nicht beim Denken. Spotify hat das im September 2026 gemessen. Große Reads gehen an einen Helfer. Der Hauptkontext spart dann 82 bis 94 Prozent. Ein Token ist ein Wortstück; nach Tokens rechnet der Anbieter ab. Der Skill `context-budget` gilt für jeden Assistenten. Er sagt: - Erst suchen, dann nur den nötigen Ausschnitt lesen. - Lange Dateien und Fragen über drei oder mehr Dateien an einen Subagenten geben. Ein Subagent ist ein Helfer mit eigenem Kontext. Er liefert nur Befunde zurück. - Fehlersuche, Architektur und Sicherheit nie abgeben. - Vor jeder Änderung den Originaltext lesen, nie nur die Zusammenfassung. - Vorhersehbaren Code (zum Beispiel Tests nach Vorlage) direkt in die Datei schreiben lassen. Zurück kommen nur Pfad und Prüfergebnis. Claude Code bekommt zusätzlich das **Lese-Tor**. Es ist ein Hook vor jedem Read. Liest der Hauptagent eine Textdatei mit mehr als 350 Zeilen ganz, lehnt das Tor ab. Der Agent liest dann einen Ausschnitt oder fragt einen Subagenten. Subagenten, Ausschnitte, kleine Dateien und Bilder laufen immer durch. | Du willst | So geht es | |---|---| | Eine andere Schwelle | `BESTAICONFIG_READ_GATE_LINES=800` setzen, zum Beispiel unter `env` in `.claude/settings.json`. | | Das Tor abschalten | `BESTAICONFIG_READ_GATE_LINES=0` setzen. | | Das Tor behalten, aber eine Datei ganz lesen | Den Assistenten bitten, sie in Abschnitten zu lesen. | Die Schwelle 350 stammt von Spotify. Sie ist ein Startwert, keine Messung für dein Projekt. Shell-Befehle wie `cat` prüft das Tor nicht; der Skill verbietet diesen Umweg. ## Als Plugin installieren Dieselben Skills gibt es als Plugin-Paket: ```sh claude plugin marketplace add https://deltatree.github.io/BestAiConfig/marketplace.json claude plugin install bestaiconfig@bestaiconfig claude plugin update bestaiconfig ``` Das Paket `plugin.zip` trägt auch eine `plugin.json` im Standard [Agent Plugins 1.0](https://agent-plugins.org/specification). Cursor, Copilot CLI, Codex und Kiro können den entpackten Ordner installieren. ## Download prüfen Neben jeder Datei liegt eine Prüfsumme und eine Stückliste (`sbom.cdx.json`): ```sh curl -fsSL https://deltatree.github.io/BestAiConfig/bootstrap.sh -o bootstrap.sh curl -fsSL https://deltatree.github.io/BestAiConfig/bootstrap.sh.sha256 | shasum -a 256 -c - ``` Die Prüfsummen kommen vom selben Server wie die Dateien. Sie erkennen kaputte Downloads, nicht einen gekaperten Server. Mehr in [SECURITY.md](../SECURITY.md). ## Wie es innen funktioniert 1. Der Compiler `src/compile_rules.py` liest alle Quellen. Er braucht nur Python. 2. Er entfernt Doppelungen. Die Quelle mit höherer Priorität gewinnt ganz. 3. Er prüft die Größen-Budgets. 4. Er schreibt jedes Format, das Inventar `manifest.json`, den Installer und die Startseite nach `public/`. Dazu die Doku nach `public/docs/`. 5. Ein GitHub-Workflow veröffentlicht `public/` nach jedem grünen Merge und jede Nacht auf GitHub Pages. Der Code kennt kein Assistenten-Format. Jedes Format ist Daten in [`targets.json`](../targets.json): Ordner, Endung, Kopfzeilen, Links, Aufräumen, Seed-Dateien. Ein neuer Assistent ist ein JSON-Eintrag, keine Code-Änderung. Ein Test bricht den Build, wenn ein Formatname im Code auftaucht. Das Schema steht in [registry-schema.md](registry-schema.md). ## Aufbau des Repos | Pfad | Zweck | |---|---| | `src/` | Compiler-Module und `bootstrap.sh` | | `sources.json`, `targets.json` | Woher die Regeln kommen, wohin sie gehen | | `sources/custom/` | Eigene Regeln, höchste Priorität | | `sources/vendored/` | Zusammenfassungen fremder Quellen | | `templates/` | Seeds, Router-Skripte, Meldungskatalog, Initializer `AGENTS.md` | | `tests/` | Testsuite, nur Python-Standardbibliothek | | `.github/workflows/` | `ci.yml`, `deploy.yml`, `bump-bmad.yml` | | `docs/` | Diese Seiten und die Release-Records | | `public/` | Erzeugte Ausgabe, nie eingecheckt | ## Für einen Fork 1. Workflow einmal von Hand starten: Actions, "Nightly Build & Deploy", "Run workflow". Das legt den Branch `gh-pages` an. 2. Settings, Pages: "Deploy from a branch", Branch `gh-pages`, Ordner root. Der Installer trägt die Adresse des Forks automatisch. GitHub schaltet Zeitpläne nach 60 Tagen ohne Commit ab; ein Commit schaltet sie wieder ein. ## Initializer für neue Projekte Kopiere [`templates/AGENTS.md`](../templates/AGENTS.md) in ein neues Projekt. Die Datei sagt dem Assistenten, zuerst den Installer zu starten. Der erste Lauf ersetzt die Datei durch die echte `AGENTS.md`. ## Commits Conventional Commits: `feat:`, `fix:`, `chore:`, `docs:`, `test:`. Ein Commit mit KI-Hilfe trägt am Ende einen `Co-Authored-By`-Trailer. ## Architektur Die Grundsätze stehen in `_bmad-output/planning-artifacts/architecture/architecture-BestAiConfig-2026-08-06/ARCHITECTURE-SPINE.md`, die Anforderungen unter `_bmad-output/planning-artifacts/prds/`.