Three documents that keep my AI coding agent honest (free templates + Claude Code skill)

onepersonrd — Wed, 28 Oct 2026 06:06:29 +0000

I run a one-person R&D operation that ships small hardware products — boards, 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 coding standard 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.