Model-Driven Harness
The AI writes the model, a deterministic generator writes the code, the tests decide.
Burgr is useful without any AI. This page is for the case where an AI coding agent does the work: what Burgr adds to the harness around it, the harness to copy, how it compares with other approaches, and what it saves, measured.
The idea
Harness engineering frames an AI agent with everything around it: its context (rules, CLAUDE.md, skills), its tools and permissions, and deterministic feedback loops (compiler, tests). A document alone stays advisory. The harness gets solid when a rule is enforced instead of asked.
A Model-Driven Harness puts a deterministic code generator at the center:
- the agent writes a small, structured, validatable YAML model, and the code of the extension points the templates provide;
- Burgr hydrates the templates: same model and same templates give the same output, with no tokens and no review;
- the harness shipped with the template set tells the agent where it may write, what it must neither edit nor read (the generated files), and how to test.
The expected gain is fewer tokens on structural code (CRUD, API, persistence), and fewer iterations to get code that compiles and passes its tests. The gain depends on the share of generable code: hand-written business logic costs the same as in any approach.
The language of the generated code does not matter. Templates are text: the existing sets produce C#, TypeScript, SQL and PlantUML, and a set can target Java, Python or Go. The concept is the separation of model, deterministic generation and harness, not a stack.
What is generated, what is framework
A criterion decides where behavior goes: the generated code carries what varies from one model to the next (names, properties, types, relations, routes, columns, an entity's own validations), and the framework carries what is identical for every entity (unit of work, rights, events, pagination, errors, serialization).
Two signs of a bad split: a template with large blocks that use no variable of the model (that logic belongs in the framework), and a framework that uses reflection or a switch on the entity type (that logic belongs in the generated code). The target is a large generated codebase that is never read, and a small, stable framework that is documented for the agent. A set without framework of its own, like Mini, relies only on the language's.
The harness to copy
Each template set ships its harness. dotnet burgr specs/ /harness:. copies it into your repository and never overwrites an existing file:
| File | Role |
|---|---|
AGENTS.md | The workflow, what is allowed and forbidden, the model syntax the set supports, what is generated, the extension points, how to test. For a set with a framework, the contracts of that framework too, so the agent never has to read generated code to understand a behavior. |
CLAUDE.md | Points Claude Code at AGENTS.md (@AGENTS.md). |
.claude/hooks/block-generated-files.sh and .claude/settings.json | A PreToolUse hook that refuses Read, Edit and Write on a generated file. |
The workflow it gives the agent:
1. Change the model: the *.yaml files next to burgr.json.
2. Regenerate: dotnet burgr <directory of burgr.json>.
3. Build: the compiler lists the extension points the model now requires.
4. Write the hand-written code and its tests, then dotnet build and dotnet test.
Allowed: edit the model and regenerate; write the extension points, the tests and any hand-written file; search a generated file with Grep to find a signature. Forbidden: edit, create or delete a generated file; read a generated file in full; write by hand what the generator produces.
Why a hook and not a permission rule
A permissions.deny rule on Read(**/*.g.*) is also applied to Grep and Glob by Claude Code. The agent then no longer sees the generated files at all, without being told: it cannot find the signature of a partial method and concludes it does not exist. The hook refuses only Read, Edit and Write, so Grep and Glob still find what the agent needs, for a fraction of the tokens of reading the file.
The hook does not hard-code the pattern of generated files: it reads GeneratedFilePrefix and GeneratedFileSuffix from every burgr.json of the repository, the same source Burgr uses to write and clean its files. A framework file (suffix .f by default) may be read but not edited. A refusal tells the agent what to do instead. One limit: reading through a shell (cat, Get-Content) is only forbidden by the written rule, not by the hook.
The harness files are in the template sets: Mini, Onion. The hook and AGENTS.md are plain files: copy them, or write the equivalent for your own template set.
How it compares
| Approach | What differs |
|---|---|
| Spec-driven development | The specification is prose that the agent turns into code each time, and is checked only by review and tests. Here the specification is a validated model, and the code is produced by a generator rather than re-derived: the output is the same every run, and a model using an unsupported feature is refused with its name. |
| Model-driven engineering | The same idea, with a deliberately small plain-text model and plain-text templates, and a harness that decides what the agent may touch. |
| OpenAPI generators | They start from an API contract and stop at the client or the server stub. Burgr starts from the domain and can also produce persistence, schema and diagrams. |
| JHipster, Rails scaffolding | One fixed stack, generated once and then edited by hand. Here the generated files are never edited, so the model stays the source of truth, and the template set is yours to choose or write. |
| An agent with no generator | The agent writes every line, and pays for the same structural code on every entity. See the figures below. |
If you use an AI to write code you do not read, the same discipline applies: it writes the model, the generated code is not reviewed, and the tests are what decides.
Benchmarks
Same tasks and prompts with and without Burgr, Claude Sonnet 5.5 (claude-sonnet-5-5) through headless Claude Code 2.1.327, run of November 19, 2026, 5 runs per case, in a fresh container each time. A hidden acceptance suite, run against the started API as a black box, judges every run. The without-Burgr baseline is C# written by hand with the same architecture as the template set compared.
| Case | Project |
|---|---|
| simple-create | Warehouse (Mini): 2 aggregates, an enum, a reference, a calculated property, validations |
| complex-create | Ticketing (Onion): 3 aggregates, a synchronized entity, a value object, rules, a service, rights, JWT |
| complex-evolve | An existing user-management API, plus teams with synchronized members, two rules and a right |
| simple-fix | Unfavorable: a one-character bug in a calculated property |
| entry | Unfavorable: one question about the code, no change (entry cost of the harness) |
Ratios Burgr / hand, on the medians of 5 runs per case:
| Case | Cost | Output tokens | Duration | Input tokens |
|---|---|---|---|---|
| complex-create | −37% | −63% | −52% | +105% |
| complex-evolve | −47% | −54% | −30% | −30% |
| simple-create | −31% | −51% | −34% | +36% |
| simple-fix | +12% | 0% | −4% | +8% |
| entry | +18% | −9% | −15% | +15% |
Median cost of one run, in dollars:
| Case | Burgr | Hand |
|---|---|---|
| complex-create | $0.43 | $0.69 |
| complex-evolve | $0.25 | $0.47 |
| simple-create | $0.12 | $0.18 |
| simple-fix | $0.07 | $0.06 |
| entry | $0.06 | $0.05 |
Every measure (tokens, turns, builds, lines written, minimums and maximums) is in the report of the run.
All 40 judged runs pass the acceptance suite, with and without Burgr. On the complex creation, Burgr runs wrote about a third of the code (493 lines against 1435), and the cost ranges of the two variants do not overlap.
Read these figures with their caveats.
- Input tokens go up when creating: more turns, almost all of them cached. Do not quote a saving in tokens without separating input from output.
- The first build of the complex creation is never green with Burgr (0 of 5, against 1 of 5 by hand): the gain there does not come from fewer build iterations. On the simple creation it is the other way round: 5 of 5 with Burgr, against 3 of 5 by hand.
- Small tasks cost a little more, about one cent per run: the harness has an entry cost.
- The share of generable code decides the gain. Hand-written business logic costs the same either way.
- The costs are the estimates Claude Code reports with a subscription token, and the results are for one model.
Redo them
The protocol, the cases, the hidden suites and the runner are public in SolidOps/burgr-benchmarks. dotnet run bench.cs -- verify judges the references and the starting states without calling any model, and costs nothing. run --yes calls the Anthropic API with your own key and is billed.