Like many other developers and architects, I currently work in a large number of repositories, and by now I work AI-first: almost every change starts with a coding agent. That's fast. But it has a side effect that annoyed me more and more: I kept repeating myself. In every project, often in every session, the same instructions. Don't write a claim you haven't checked. Don't build an abstraction nobody needs. Keep the docs up to date. Write tests that actually test something.
At some point I moved these rules out of my head and into a tool, my own harness for coding agents. In this three-part series I show what's in it, why, and what I threw out along the way. This part covers the ground rules. Part 2 is about architecture documentation and ADRs, part 3 about the workflow.
Three problems that drove me
Sascha explained what an agentic harness is in his series, starting with What Is an Agentic Harness?. In short: everything around the model that isn't the model itself. This post is the practical side of that.
1. Repetition. General rules don't belong in a prompt. They belong in a fixed place that every agent reads in every project. When I improve a rule, the improvement should reach every project, not just the repository I happen to be working in.
2. The distance to the project. I know this problem from almost every project, long before AI: new developers, or experienced ones who only touch a project now and then, feel cut off from where the project stands. What is the goal? What was decided, and why? The result is hesitation. Nobody dares to touch code they don't understand. Coding agents make this worse, because the code changes faster than anyone can update the docs. So the agent has to do it itself.
3. Decisions that hold. Documented architecture decisions build acceptance, especially when something goes wrong. At a higher level that management can follow too, the Architecture Communication Canvas does the same. More on that in part 2.
My first answers are four ground rules that every agent follows.
Rule 1: Know, don't assume
The most important rule is called Know, do not assume: an agent writes only what it can prove, with a file it read, a test it ran, a statement from me or a linked source. "Should work" or "probably" are forbidden as results, and no task counts as done before its verification passes.
You see the difference right away in daily work. Without the rule, a task typically ends like this:
I extended the check. Commits on the main branch should now be checked correctly.
With the rule, the same result shows up in the QA report like this, a real row from my harness:
| Scenario | Result | Evidence |
|---|---|---|
| Conventional commit messages: Trunk commit header is not conventional | passed | Test "Conventional commit messages: Trunk commit header is not conventional". node --test 'scripts/*.test.mjs': passed. |
I don't have to believe that it works. I can see how it was checked and repeat it myself. Whatever an agent can't prove ends up as an open item in the docs instead of being covered by a plausible assumption. Sascha described why agents shouldn't grade their own work in Verification & Control.
Rule 2: Simplicity over elegance
Coding agents tend to overengineer. They like to build an interface for a single implementation, a factory for a new, or pull in a package for a task that needs ten lines. At the same time, simplicity has always been my own stance as a developer. The rule just makes it explicit:
- Use the simplest solution that meets the spec.
- Add an abstraction only when two or more real uses need it.
- Do not add a dependency if 20 lines of clear code do the same work.
Two classics come on top: DRY (every piece of information in exactly one place, for code, configuration and documents) and the SOLID principles. They too apply only where they make sense. That's why the rule says explicitly: Use SOLID to make code easy to change. Do not use it to add layers without need. SOLID and DRY are tools for changeable code, not a license for layers and abstractions. When in doubt, simplicity wins.
Every task ends with a short refactoring step, but only with green tests before and after. If the refactoring grows large, the agent doesn't do it but adds it to the backlog. That keeps changes small and reviewable.
Rule 3: Tests that test something
In Code Reviews in the Age of Coding Agents I told the story of tests that implement Assert.True(true), just so there are "more tests". Against that stands a short list: a good test checks behavior through a public interface, has exactly one clear reason to fail and maps to a spec scenario. A bad test mocks the unit it should test, checks private state or stays green while the feature is broken.
The agent works test-first and sees every test fail for the right reason first. And no test gets disabled or weakened just to make it pass.
Rule 4: Simplified Technical English
That instructions for agents and documents for humans should be short and unambiguous is common sense in the developer community by now. I turn that into a fixed rule with an established standard: all English text, meaning documents, specs, ADRs, comments, commit messages and reports, follows ASD-STE100 Simplified Technical English. It's a controlled English from aviation, originally made for maintenance manuals that non-native speakers must read without misunderstanding.
A fixed standard instead of "please keep it short" solves two problems at once:
- LLMs like to write at length and "poetically". A lot of prose increases the risk of contradictions and ambiguity, especially in documents that an agent later reads again as instructions.
- Humans quickly get overwhelmed and frustrated by too much text. Documentation that nobody reads isn't documentation.
The rules are simple enough for an agent to follow reliably: one word for one meaning, no phrasal verbs or contractions, at most 20 words per sentence in procedures and 25 in descriptions, active instead of passive voice. A script finds sentences that are too long. It can't check the vocabulary, because the full STE dictionary isn't in the repository. That's why an agent may not claim a text "complies with STE", only that it "follows the STE rules". That's the evidence rule, applied to itself.
By the way, all English excerpts in this post are written in this style.
What came out of it: sparc
These rules became sparc. The name comes from spec, from arc (architecture) and from the spark of an idea that should end up as working software. sparc is a plugin for Claude Code and builds on OpenSpec, which I came across through a podcast. Its plain approach convinced me: every change is a small folder with a proposal, specs, a design and tasks. As so often: simplicity is key.
Besides the rules, sparc contains fixed roles (product owner, architect, UX designer, software engineer, QA engineer), a fixed set of documents and a script that checks after every agent run whether the docs still match the code. Every rule exists exactly once. Roles and skills refer to it instead of copying it, and a project has only one AGENTS.md, not a second CLAUDE.md with slightly different content.
sparc is itself a sparc project and collected twelve architecture decisions in two days. Two of them removed something that looked like good architecture at first. I tell that story in part 3.
Takeaway: three rules for your AGENTS.md
You don't need your own harness to get started. These three lines are in almost every one of my projects nearly word for word and work in any AGENTS.md or CLAUDE.md:
- Write only what you know. Get evidence from files, tests or the user.
Do not write "should work" or "probably" as a result.
- Keep it simple. Add an abstraction only when two or more real uses need it.
Keep each fact in one place and link to it from other places.
- Write a test that fails for the right reason before you write the code.
Do not disable, skip or weaken a test to make it pass.
Conclusion
Your own harness is less work than it sounds if it sticks to what you demand in every project anyway. For me, that's four ground rules: prove claims, build simply, write real tests, write clearly. What's new isn't the content of these rules. What's new is that I don't have to repeat them anymore.
The second part covers my favorite topic: architecture documentation that keeps pace with the code, and ADRs that stay honest after the decision.