I run a one-person R&D operation that ships industrial sensing products — analogue boards, microcontroller firmware, PC tools. Most of the typing is done by AI coding agents (mainly Claude Code). They are fast, and for a year they failed in the same four ways:
- They extended the scope without asking.
- They reported "done" without running the test.
- They stated facts they had not checked ("the sibling project uses the same part").
- They repeated the same mistake in the next session.
None of this was fixed by a better model. It was fixed by a process the agent cannot skip. I've generalized it into a small kit and put it on GitHub under MIT: ai-rd-process-kit.
The idea
Before any implementation, the agent writes three documents, and I accept them:
- Plan — scope decided in seven lines (constraints, vision, first release, one-sentence core concept, out of scope, MVP, deferred), completion criteria before the task list, and a progress scale where 100% means reviewed and tested, nothing else.
- Design document — every chapter created on day one. A chapter that doesn't apply says "N/A (reason)". Rejected options are kept with the reason. Design order is data → functions → UI, because starting from the screen is how you find the missing data at the end.
- Requirements ↔ test matrix — every requirement has at least one test, every pass criterion is a number, and "not run" is a status that is never reported as "pass".
Then the agent works in small checked pieces, updates the documents in the same change that alters the design, and when it fails, it writes the lesson itself: situation, cause, prevention. It reads that file at the start of every session.
The progress scale (the part people copy first)
| % | Means |
|---|---|
| 0 | Not started |
| 25 | Started |
| 50 | Draft complete, not self-checked |
| 75 | Waiting for review, or under test |
| 100 | Accepted in review and tests passed |
Unverified work stays at 75. Where things can be counted, they are counted: tests passed 38/52 → 73%.
Two real lessons from the file
"Not found" is not "does not exist." The agent searched a rulebook for two keywords, found nothing, and reported that no rule applied. The rule existed under different wording. Prevention: questions of the form "is there a rule about X" are answered by reading the relevant chapters, and the report says what was searched and what was not read.
ERC passed, the netlist had three shorts. An auto-generated schematic passed the electrical rules check. The netlist showed a rotated protection diode shorting two supply rails, a pull-up routed onto a data line, and a duplicated reference designator. Prevention: after generating a schematic, export the netlist and script-check supply/ground separation, polarity of oriented parts and duplicate designators before layout.
What's in the kit
-
templates/— plan, design doc, requirements↔test matrix, lessons-learned (with four real, anonymized examples) -
rules/CLAUDE.md.example— 13 promises for the root of your project -
skills/rd-process/SKILL.md— a Claude Code skill: session start, create the docs, work, test, log, session end
Five-minute setup: copy the templates into docs/, put the rules in CLAUDE.md, install the skill, and say "plan this". If the agent starts coding before showing you the scope table, the rules aren't loaded.
What it is not
Not a methodology, not a tool, not a prompt pack. Four Markdown files and a habit. It works with any agent that reads an instruction file; the skill is for Claude Code.
If you try it, I'd like to know which rule your agent broke first. Mine was #4.
Disclosure: this post and the templates were drafted with an AI assistant and rewritten by me from first-hand use.
Top comments (1)
The hard part with agents is not making them act, it is making them stop and ask.