docs(projects): update claude-in-a-box project text and diagram

The box now runs an agent pipeline, assist mode and evals.
The old card and diagram only described rule loading and the commit hook.
This commit is contained in:
lobo committed 2026-10-21 08:27:27 +02:00
1 parent 910822028b
commit 82228e9141
4 files changed
+139 -89

No files matched your search

+18 -14
View File
@@ -197,12 +197,12 @@
},
"CLAUDE_BOX": {
"TITLE": "Claude-in-a-Box",
"DESCRIPTION": "Eine Entwicklungsumgebung im Container, in der ein KI-Coding-Agent nach einem festen Regelsatz arbeitet und nicht nach dem, was ich gerade eintippe. Er zieht sich die Regeln für den Stack, den er im Repository vorfindet, und ein Git-Hook stoppt den Commit, wenn Build oder Tests rot sind.",
"DESCRIPTION": "Eine Entwicklungsumgebung im Container, in der KI-Agenten Code nach festen Regeln schreiben. Eine Pipeline aus kleinen Agenten klärt, plant, implementiert, vereinfacht und reviewt, und ich sage Ja zum Plan und zu jedem Commit. Hooks außerhalb der Agenten blockieren rote Builds und Zugriffe auf Secrets.",
"LINK_INTERNAL": "Projektdetails",
"HIGHLIGHTS": {
"P1": "Der Agent lädt die Regeln für den Stack, den er im Repo vorfindet. Ein Java-Service bekommt also andere als ein Frontend.",
"P2": "Ein Commit-Hook führt Build und Tests aus und blockiert den Commit, wenn sie fehlschlagen.",
"P3": "MCP-Server für Codesuche und lesenden Jira-Zugriff, dazu eigene Review-Agenten, die den Diff durchgehen."
"P1": "Ein Agent pro Aufgabe, jeder mit frischem Kontext und passendem Modell. Die Übergabe läuft über Dateien, nicht über den Chat.",
"P2": "Ein Commit-Hook führt Build, Tests und einen Secret-Scan aus und blockiert den Commit, wenn etwas rot ist.",
"P3": "Eine Eval-Suite misst jede Änderung an Regeln oder Agenten an festen Aufgaben mit versteckten Prüfungen."
}
},
"P2": {
@@ -383,17 +383,21 @@
},
"CLAUDE_BOX": {
"TITLE": "Claude-in-a-Box",
"SHORT_DESCRIPTION": "Ein Container-Setup, um mit einem KI-Coding-Agenten nach einem festen Regelsatz zu arbeiten.",
"INTRODUCTION": "Ein KI-Coding-Agent produziert den ganzen Tag Code, ohne sich zu beschweren. Das Problem ist, dass das Ergebnis meistens vernünftig aussieht, auch wenn es falsch ist, und die ganzen Kosten damit im Review landen. Also habe ich ein Docker-Setup gebaut, das den Agenten denselben Regeln unterwirft wie alle anderen, die am Repository arbeiten. Er liest die Architekturregeln des Projekts, in dem er gerade steckt, und der Build muss durchlaufen, bevor ein Commit möglich ist. Auf den Hook, der genau das durchsetzt, komme ich immer wieder zurück, weil er das Einzige ist, woran der Agent nicht vorbeikommt.",
"BULLET_1": "Container mit festen Toolchains: JDKs und Maven über SDKMAN, Node und ein Home-Volume, das einen Rebuild übersteht.",
"BULLET_2": "Die Regeln werden per Erkennung geladen. Ein Repo mit pom.xml bekommt die Java- und Spring-Regeln, eines mit package.json die TypeScript-Regeln, und Repos mit eigenen Architekturnotizen bekommen diese zusätzlich.",
"BULLET_3": "Ein Commit-Hook ermittelt den Stack, führt den passenden Build und die Tests aus und verweigert den Commit, wenn sie fehlschlagen.",
"BULLET_4": "MCP-Server für Code-Graph-Abfragen und lesende Jira-Zugriffe, dazu Review-Agenten, die einen fertigen Diff prüfen, bevor er als erledigt gilt.",
"CHALLENGE_1": "Die Regeln kurz genug zu halten, dass sie noch etwas bringen. Lange allgemeine Richtlinien werden einfach ignoriert, also sind sie in Dateien pro Stack und pro Repo aufgeteilt, die nur bei Bedarf geladen werden.",
"CHALLENGE_2": "Das Quality Gate so zu bauen, dass der Agent sich nicht daran vorbeireden kann. Die Prüfung läuft als Git-Hook außerhalb des Agenten, ein fehlgeschlagener Build blockiert den Commit also unabhängig davon, was der Agent über seine eigene Arbeit denkt.",
"CHALLENGE_3": "Die Toolchains in einem Container ohne Root zum Laufen zu bringen. Builds, Browser und Sprach-Runtimes mussten alle in Volumes landen, die dem Entwickler-User gehören.",
"SHORT_DESCRIPTION": "Ein Container-Setup für einen KI-Coding-Agenten: eine Pipeline aus kleinen Agenten mit je einer Aufgabe und Hooks, an denen keiner von ihnen vorbeikommt.",
"INTRODUCTION": "Ein KI-Coding-Agent produziert den ganzen Tag Code, ohne sich zu beschweren. Das Problem ist, dass das Ergebnis meistens vernünftig aussieht, auch wenn es falsch ist, und die ganzen Kosten damit im Review landen. Also habe ich ein Docker-Setup gebaut, das den Agenten denselben Regeln unterwirft wie alle anderen, die am Repository arbeiten: Er liest die Architekturregeln des Projekts, in dem er gerade steckt, und der Build muss durchlaufen, bevor ein Commit möglich ist. Inzwischen ist aus der Box eine Pipeline geworden. Das Klären passiert im Chat, danach gibt es einen kleinen Agenten pro Aufgabe, jeder mit frischem Kontext: Einer plant, einer implementiert, einer vereinfacht, einer reviewt. Die Übergabe läuft über Dateien, nicht über den Chat, und ich sage an zwei Stellen Ja: zum Plan und zu jedem Commit. Die Hooks um das Ganze herum sind immer noch der Teil, auf den ich am häufigsten zurückkomme, weil sie das Einzige sind, woran sich kein Agent vorbeireden kann.",
"BULLET_1": "Agenten-Pipeline: Klären (die Hauptsession stellt gezielte Fragen und schreibt eine Spec), Planen, Implementieren, Vereinfachen, ein Security-Check, wenn die Änderung etwas Sicherheitsrelevantes berührt, Review, Commit-Message. Jeder Schritt nach dem Klären ist ein eigener Agent mit frischem Kontext und einem Modell, das zur Aufgabe passt: Fable für Klären, Planen und Review, Sonnet fürs Implementieren, Opus für Vereinfachen und Security, Haiku für die Commit-Message. Sind weniger als 20 % des wöchentlichen Fable-Budgets übrig, wechseln diese Schritte von selbst auf Opus, und die Statusleiste zeigt es an.",
"BULLET_2": "Ich bleibe an zwei Stellen im Spiel: Der Plan braucht mein OK, bevor jemand Code schreibt, und jeder Commit braucht mein Ja. Der Reviewer ist kritisch und kennt den Chat nicht: Er lässt das Gate laufen, schreibt für jeden Fund einen fehlschlagenden Test und prüft, ob das Feature funktioniert, wenn nötig im Browser. Funde gehen zurück an den Implementierer, höchstens zwei Runden. Ein Agent, der denselben Fehler zweimal nicht beheben kann, hört auf und meldet RED, und ich entscheide. Kleine Änderungen überspringen Plan und Review.",
"BULLET_3": "Die Regeln werden per Erkennung geladen. Ein Repo mit pom.xml bekommt die Java- und Spring-Regeln, eines mit package.json die TypeScript-Regeln, ein Unity-Projekt die datenorientierten Regeln, und Repos mit eigenen Architekturnotizen bekommen diese zusätzlich. Jeder Agent liest nur die Dokumente, die seine Aufgabe braucht, damit der Kontext klein bleibt.",
"BULLET_4": "Hooks außerhalb der Agenten: ein Compile- oder Type-Check am Ende jedes Turns, ein Commit-Gate, das den vollen Build, die Tests und einen Secret-Scan ausführt und einen roten Commit verweigert, ein Guard, der das Lesen von .env-Dateien und Keys blockiert, und ein Work-Mode-Guard. Drumherum ein Container ohne Root mit festen Toolchains und MCP-Servern für Code-Graph-Abfragen, Gitea und lesendes Jira.",
"BULLET_5": "Work-Mode assist, pro Chat: Ich schreibe den Kern (Domain, Services, Persistenz), die Agenten schreiben Gerüst, Boilerplate und Tests und reviewen meinen Code. Ein Hook verweigert den Agenten das Schreiben auf die Kernpfade, die Trennung wird also erzwungen und nicht nur erbeten.",
"BULLET_6": "Eine Eval-Suite lässt die ganze Pipeline headless gegen feste Aufgaben laufen, Fallen eingeschlossen, jede mit versteckten Prüfungen. Die Ergebnisse werden pro Commit der Box protokolliert, eine Änderung an einer Regel oder einem Agenten wird also gemessen statt geraten.",
"CHALLENGE_1": "Die Regeln kurz genug zu halten, dass sie noch etwas bringen. Lange allgemeine Richtlinien werden einfach ignoriert, also sind sie in Dateien pro Stack, pro Repo und pro Aufgabe aufgeteilt, und jeder Agent lädt nur die, die für ihn gelten.",
"CHALLENGE_2": "Die Gates so zu bauen, dass kein Agent sich daran vorbeireden kann. Jede Prüfung läuft als Hook außerhalb des Agenten: Ein fehlgeschlagener Build blockiert den Commit, ein Lesezugriff auf Secrets wird verweigert, ein Schreibzugriff auf einen Kernpfad im Assist-Modus abgelehnt, unabhängig davon, was der Agent über seine eigene Arbeit denkt.",
"CHALLENGE_3": "Ein Reviewer, der zugesehen hat, wie der Code entstanden ist, winkt ihn durch. Also startet jeder Agent mit leerem Kontext und bekommt nur die Dateien, die seine Aufgabe braucht: Der Reviewer sieht Spec, Plan und Diff, nie den Chat. Der Preis ist, dass jeder Agent den Code neu liest, die Pipeline ist also langsamer als ein langer Chat.",
"CHALLENGE_4": "Zu wissen, ob eine Änderung an der Box etwas bringt. Jede angepasste Regel fühlte sich wie eine Verbesserung an, also habe ich die Eval-Suite gebaut: feste Aufgaben mit versteckten Prüfungen, vor und nach einer Änderung mit denselben Modellen ausgeführt. Die Suite prüft auch sich selbst: Die unveränderte Vorlage muss an jeder Aufgabe scheitern und die Referenzlösung muss bestehen, sonst sagt ein grüner Lauf nichts aus.",
"LEARNING_1": "Die Formulierung der Prompts war deutlich weniger wichtig, als ich dachte. Fast der ganze Unterschied kam vom Drumherum.",
"LEARNING_2": "Den Output des Agenten genauso zu reviewen und durch dieselben Gates zu schicken wie den Pull Request eines neuen Teammitglieds hat sich als die nützlichste Regel überhaupt herausgestellt."
"LEARNING_2": "Den Output des Agenten genauso zu reviewen und durch dieselben Gates zu schicken wie den Pull Request eines neuen Teammitglieds hat sich als die nützlichste Regel überhaupt herausgestellt.",
"LEARNING_3": "Kleine Agenten mit jeweils frischem Kontext schlagen einen langen Chat. Nicht weil das Modell klüger wird, sondern weil niemand frühere Fehler mitschleppt und jede Übergabe eine Datei ist, die ich lesen und korrigieren kann."
},
"TBP": {
"TITLE": "To Be Played",