Instructions for a coding agent: what goes in the rules file

The rules file is where the agent learns what it can decide on its own. If the file doesn’t say what finished means, the agent stops as soon as the work looks done, and you end up checking everything. The rules below come from the Claude Code best practices documentation and from Nielsen Norman Group research on working with AI.

The definition of done comes before the request

The Claude Code best practices documentation explains the mechanism in one sentence: the agent stops when the work looks done. Without a check it can run itself, “looks done” is the only signal left, and every error sits there until you spot it.

The definition of done is a signal the agent reads on its own. It can be the test suite, the build exit code, the linter, or a script that compares the output against a reference file. The same page lists what to do with that in practice. Ask for test cases together with the function, the screenshot compared against the design, and the build error fixed at the cause instead of the error silenced.

This changes the shape of the request. A specification that works names the files and the interfaces involved, says what is out of scope and ends with an end-to-end check. What you write up front ends up worth more than any fix you make along the way.

A check that passed once isn’t an evaluation. A coding agent generates anew on every request, and Nielsen Norman Group points out that this generation varies from run to run. Run the check more than once before treating the result as a firm signal. The full method lives in AI output evaluation.

The file loaded in every session has to be short

The rules file is read at the start of every conversation, so everything in it takes up context in every task. The best practices page recommends a test per line: if removing that line doesn’t make the agent fail, cut it. The documentation points out what happens with a bloated file. The rule gets lost in the middle of the text, and the agent starts ignoring instructions that are written down.

When a rule is ignored often, the fix isn’t to rewrite the whole file. The guidance is to emphasize that line alone, because emphasis spread across several lines highlights none.

What isn’t a general rule leaves this file. Knowledge that only applies to one kind of task belongs in a file the agent loads when the task appears, not in the file that always loads.

Autonomy is written together with the stop point

Asking permission at every step looks safe and isn’t. The documentation describes the real effect of manual mode: after the tenth approval you are clicking instead of reviewing. A pause nobody planned turns into a rubber stamp.

The design that works separates three things. Read tools and commands you already trust go on a pre-approval list. What modifies the system requires a decision. What can’t be undone requires a person, and that list is short and explicit.

A rule that must not fail shouldn’t live as an instruction. The documentation is clear about the difference: instruction in text is advice, a hook, a script that runs automatically on an event, is deterministic and guarantees the action happens. Lint before commit, test before push and the secret scan are hooks, not sentences.

A new instruction goes into a queue, and research goes to a subagent

A new instruction shouldn’t cancel the run in progress. It goes into the queue and the earlier work finishes, because a task interrupted halfway leaves the repository in a state nobody can describe.

Research is the case where it pays to spend separate context. The article AI in the design workflow describes the same split between what the tool does and what stays with the person. The documentation recommends subagents for investigation, because they run with their own context and stop filling the main conversation with files that only served to find a path. Reading a large repository is the example the page gives.

Here the advice has changed from what used to be said. NN/g recommended treating AI as an intern, with a closed brief and step-by-step direction, precisely because an open brief without direction yields generic output. Current practice inverts the shape of the request and keeps the principle. You still give direction, but you write the definition of done and let the agent work until it gets there.

Review looks at the diff, not the base

Review of agent code is done by what changed. A large commit can’t be reviewed by anyone, not even by you the following week, which is why the recommendation for a small and descriptive commit counts double here.

The documentation also warns where the record isn’t reliable: the checkpoints track only the changes made by the agent’s editing tools. What went through the command line or an external process doesn’t go in. Git is still the history, and the checkpoint doesn’t replace it.

Ask for evidence instead of a claim. The page puts that as a time saving: reading the test output, the command that ran and what it returned is faster than running the check again on your own.

What ships without a source needs a mark

A language model sometimes gives an answer that sounds right, is wrong, and comes with full confidence. NN/g describes hallucination exactly like that, as data that looks true and isn’t, presented in a way that makes it hard to spot.

The catch is that checking takes effort, and that effort is what decides whether anyone checks. The NN/g review shows that people skip verification because the tool was adopted precisely for the promise of efficiency. The same article warns that checking again is mandatory after a correction, since the new version can introduce another error.

The rule that remains for the file is short, and it already applies in any AI workflow, as in synthesis work. Every factual claim carries the source or receives the unverified mark. What can’t be verified isn’t delivered, and that sentence is in the common failure list of the best practices documentation itself.

Where the NN/g articles disagree with each other

The two articles disagree about where the instruction should live. Your AI UX Intern asks for detailed instruction in the request, step by step, because the tool gets lost on an open brief. The article The 3 Roles of Context for AI Agents points the other way. Someone who uses an agent every day builds a library of context, and the lever shifts to curating that library.

They also diverge on the value of one run. One AI Output Is an Example, Not an Evaluation treats the isolated output as a sample that doesn’t support a conclusion, and asks for repeated runs with a confidence interval. The intern article treats the first pass as usable, as long as someone reviews it afterwards.

What both keep is the boundary. The agent delivers a draft and evidence, and the decision to accept is still a person’s, with a name on the commit.