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": "A development setup in a container where an AI coding agent works under a fixed set of rules rather than whatever I happen to type that day. It picks up the rules for whatever stack it finds in the repository, and a git hook stops the commit if the build or the tests are red.",
"DESCRIPTION": "A development setup in a container where AI agents write code under fixed rules. A pipeline of small agents clarifies, plans, implements, simplifies and reviews, and I say yes to the plan and to every commit. Hooks outside the agents block red builds and reads of secrets.",
"LINK_INTERNAL": "Project details",
"HIGHLIGHTS": {
"P1": "The agent loads the rules for the stack it finds in the repo, so a Java service and a frontend get different ones.",
"P2": "A commit hook runs the build and the tests and blocks the commit when they fail.",
"P3": "MCP servers for code search and read-only Jira access, plus separate review agents that go over the diff."
"P1": "One agent per job, each with a fresh context and a model that fits the job. Hand-over runs through files, not through the chat.",
"P2": "A commit hook runs the build, the tests and a secret scan and blocks the commit when anything is red.",
"P3": "An eval suite measures every change to rules or agents against fixed tasks with hidden checks."
}
},
"P2": {
@@ -383,17 +383,21 @@
},
"CLAUDE_BOX": {
"TITLE": "Claude-in-a-Box",
"SHORT_DESCRIPTION": "A container setup for working with an AI coding agent under a fixed set of rules.",
"INTRODUCTION": "An AI coding agent will produce code all day without complaining. The trouble is that what comes out usually looks reasonable even when it is wrong, so all the cost lands in review. I built a Docker setup that puts the agent under the same constraints as anyone else working on the repo. It reads the architecture rules of whatever project it is in, and the build has to pass before a commit goes through. The hook that enforces that last part is the piece I keep coming back to, because it is the one thing the agent has no way around.",
"BULLET_1": "Container with fixed toolchains: JDKs and Maven through SDKMAN, Node, and a home volume that survives a rebuild.",
"BULLET_2": "Rules are loaded by detection. A repo with a pom.xml gets the Java and Spring rules, one with a package.json gets the TypeScript rules, and repos with their own architecture notes get those on top.",
"BULLET_3": "A commit hook works out the stack, runs the matching build and tests, and refuses the commit if they fail.",
"BULLET_4": "MCP servers for code graph queries and read-only Jira lookups, plus review agents that check a finished diff before it counts as done.",
"CHALLENGE_1": "Keeping the rules short enough to stay useful. Long general guidelines just get ignored, so they are split into per-stack and per-repo files that only load when they apply.",
"CHALLENGE_2": "Making the quality gate something the agent cannot talk its way past. The check runs as a git hook outside the agent, so a failing build blocks the commit no matter what the agent believes about its own work.",
"CHALLENGE_3": "Getting the toolchains installed in a container that has no root. Builds, browsers and language runtimes all had to go into volumes owned by the development user.",
"SHORT_DESCRIPTION": "A container setup for an AI coding agent: a pipeline of small agents, one job each, and hooks none of them can get past.",
"INTRODUCTION": "An AI coding agent will produce code all day without complaining. The trouble is that what comes out usually looks reasonable even when it is wrong, so all the cost lands in review. I built a Docker setup that puts the agent under the same constraints as anyone else working on the repo: it reads the architecture rules of whatever project it is in, and the build has to pass before a commit goes through. Since then the box has grown into a pipeline. The chat clarifies the task; after that it is one small agent per job, each with a fresh context: one plans, one implements, one simplifies, one reviews. They hand over through files, not through chat, and I say yes at two points, to the plan and to every commit. The hooks around all of this are still the part I keep coming back to, because they are the one thing no agent can talk its way past.",
"BULLET_1": "Agent pipeline: clarify (the main session asks sharp questions and writes a spec), plan, implement, simplify, a security check when the change touches something security relevant, review, commit message. Every step after clarify is its own agent with a fresh context and a model that fits the job: Fable for clarify, plan and review, Sonnet for implementing, Opus for simplify and security, Haiku for the commit message. When less than 20% of the weekly Fable budget is left, those steps fall back to Opus on their own, and the statusline shows it.",
"BULLET_2": "I stay in the loop at two points: the plan needs my OK before anyone writes code, and every commit needs my yes. The reviewer is critical and has never seen the chat: it runs the gate, writes a failing test for each finding and checks that the feature works, in the browser if needed. Findings go back to the implementer, at most two rounds. An agent that fails to fix the same failure twice stops and returns RED, and I decide. Small changes skip plan and review.",
"BULLET_3": "Rules are loaded by detection. A repo with a pom.xml gets the Java and Spring rules, one with a package.json gets the TypeScript rules, a Unity project gets the data-oriented rules, and repos with their own architecture notes get those on top. Each agent reads only the documents its job needs, so the context stays small.",
"BULLET_4": "Hooks outside the agents: a compile or type check at the end of every turn, a commit gate that runs the full build, the tests and a secret scan and refuses a red commit, a guard that blocks reads of .env files and keys, and a work-mode guard. Around it a rootless container with pinned toolchains and MCP servers for code graph queries, Gitea and read-only Jira.",
"BULLET_5": "Work mode assist, per chat: I write the core code (domain, services, persistence), the agents write scaffolding, boilerplate and tests and review my code. A hook denies agent writes to the core paths, so the split is enforced, not just requested.",
"BULLET_6": "An eval suite runs the whole pipeline headless against fixed tasks, trap tasks included, each with hidden checks. The results are logged per commit of the box, so a change to a rule or an agent is measured instead of guessed.",
"CHALLENGE_1": "Keeping the rules short enough to stay useful. Long general guidelines just get ignored, so they are split into files per stack, per repo and per job, and each agent loads only the ones that apply to it.",
"CHALLENGE_2": "Making the gates something an agent cannot talk its way past. Every check runs as a hook outside the agent: a failing build blocks the commit, a read of a secret is refused, a write to a core path in assist mode is denied, no matter what the agent believes about its own work.",
"CHALLENGE_3": "A reviewer that has watched the code being written approves it. So every agent starts with an empty context and gets only the files its job needs: the reviewer sees spec, plan and diff, never the chat. The price is that each agent reads the code again, so the pipeline is slower than one long chat.",
"CHALLENGE_4": "Knowing whether a change to the box helps. Every edit to a rule felt like an improvement, so I built the eval suite: fixed tasks with hidden checks, run before and after a change with the same models. The suite checks itself too: the untouched fixture must fail every task and the reference solution must pass, otherwise a green run means nothing.",
"LEARNING_1": "Prompt wording mattered far less than I expected. Almost all of the difference came from the scaffolding.",
"LEARNING_2": "Reviewing and gating the agent's output the same way you would a new colleague's pull request turned out to be the most useful rule of the lot."
"LEARNING_2": "Reviewing and gating the agent's output the same way you would a new colleague's pull request turned out to be the most useful rule of the lot.",
"LEARNING_3": "Small agents with a fresh context each beat one long chat. Not because the model gets smarter, but because nobody carries earlier mistakes forward, and every hand-over is a file I can read and correct."
},
"TBP": {
"TITLE": "To Be Played",