Related reading: Agents Should Do TDD argued that agents should run the loop. Your Test Suite Is Your API for Agents named the surface this post argues is the actual discipline.

Every major coding tool now ships with an instruction file.

The name changes across vendors. The role does not. It is a markdown document, checked into the root of the repository, addressed to the agent, listing the practices the team wants followed. Write tests first. Run the suite before committing. Refactor after green. Never delete a test. Prefer small commits. The bullet points differ across teams. The shape does not. Somewhere in the past two years, the industry decided that the way to make a coding agent behave like a disciplined engineer is to write down what a disciplined engineer would do, put it in a file, and let the agent read it.

The pattern exists because it feels like the answer. If the agent is skipping tests, tell it not to skip tests. If it is deleting failing tests, tell it not to delete failing tests. The intuition is that the agent is a smart intern, the instruction file is the onboarding document, and after reading the document the intern will behave.

A published measurement says the intuition is backwards.

The Measurement That Should Have Ended the Conversation

The TDAD paper (Test-Driven Agentic Development, Reducing Code Regressions in AI Coding Agents via Graph-Based Impact Analysis) ran a straightforward experiment. Baseline: an agent given a coding task, no TDD instruction, no special test-discovery context. Regression rate on the test suite: 6.08%. Treatment one: the same agent, same task, plus a “do TDD” instruction in the prompt telling it to write tests first, iterate red-green-refactor, and be ambitious about tests. Regression rate: 9.94%. Treatment two: no TDD instruction, but the relevant existing tests for the function under change pulled into the agent’s view at the moment it decided to change the function. Regression rate: 1.82%.

The instruction raised regressions by nearly two-thirds. Contextual discovery cut them by roughly seventy percent from baseline, and by over eighty percent from the instructed condition. The intervention that was supposed to install discipline installed the opposite. The intervention that worked never mentioned TDD.

It is one paper, one benchmark, one agent configuration, and the decimals will move in other settings. The mechanisms behind the result are not tied to the setting, though. They are structural properties of how coding agents work, not quirks of one vendor’s implementation, and they are worth taking apart.

Note the shape of the treatment that worked. It put the relevant tests in front of the agent at the point of decision. The agent, given tests, ran the tests. The tests were the discipline. The instruction was noise occupying the space where tests could have been.

Why Telling the Agent to “Do TDD” Made Things Worse

Context tokens are a fixed budget. The agent has a finite window for the code, the tests, the intent, and the constraints. Every token spent on procedural instructions is a token not spent on repository navigation. A twelve-bullet TDD instruction is a claim on the same budget the agent needs for finding the actual tests the actual code has, and in a real codebase that budget is already tight.

Ambitious framing broadens the surface. “Be thorough about tests” is not neutral prose. It nudges the agent to touch more files, add more tests, extend more helpers. Each additional touch is an additional chance to regress a behavior the agent had no context on. The instruction that sounds like it should raise the quality bar raises the change surface instead. It produced quantity where the codebase needed precision.

The instruction is decoupled from the code. This is the sharpest of the three. The agent knows it should “do TDD.” It does not know which of the four hundred tests in the suite specify the function it is about to change. Nothing connects the words “do TDD” to the specific tests to run before touching this specific function. The agent guesses, runs whatever tests are within reach, and reports success. The tests it did not run were the ones that would have caught the regression.

The three compound: fewer tokens for navigation, a broader change surface, no coupling from instruction to relevant tests. Under any two of them the instruction is unhelpful. Under all three, it actively harms the outcome. And underneath them sits a quieter fact. The agent’s behavior is not decided by policy documents. It is decided by whatever is loudest in the context window at the point of decision, and the code is almost always louder. If the code shows undisciplined tests, the code wins. If the code shows disciplined tests, the code wins. The instruction file, either way, is largely furniture.

A team relying on the instruction file to install a discipline is relying on a lever the measurement ranks below doing nothing.

Discipline Is a Property of the Test Surface, Not the Directive

Consider a codebase where the tests are named in the domain’s language and located next to the code they specify. An agent asked to change OrderService.ApplyDiscount navigates to OrderServiceTests.cs, finds Loyalty_members_get_a_ten_percent_discount_on_orders_over_fifty_dollars, reads it, and modifies the code with the test in view. No instruction file was consulted. The discipline was in the codebase.

Now consider a codebase where the tests are named Test_ApplyDiscount_Case3, live in a directory called LegacyUnit, and are structurally disconnected from the production code they specify. The same agent, asked to change the same function, sees the function, sees no tests, and sees the instruction file at the top of the context saying “do TDD.” It generates a change, generates a plausible-looking test alongside it, and reports success. The test it did not find is the test that would have caught the regression. The instruction did not save it, because the instruction could not make the relevant test visible.

Neither codebase mentioned TDD in prose. The first codebase had TDD. The second had a document.

Discipline is not a directive that gets installed. Discipline is a property of the test surface. If the test for the function is one search away, named in the domain’s language, reading like a sentence in the business’s vocabulary, the agent runs it. If it is not, no amount of “do TDD” in the prompt makes it visible. Teams reaching for the instruction file are reaching for the wrong lever. The right lever is naming, structure, discoverability, vocabulary: the properties that make tests visible at the point of decision. They are also the properties that make the codebase readable to humans. The instruction file cannot substitute for them.

Discipline lives in the shape of the code, not in the words about it.

The Instruction File Is the Prose-Spec Drift Trap, Shrunk

The instruction file is a specification. It specifies how the team wants the code written. It is prose, it is not executable, and it has no mechanism for staying in sync with the running system. It sits in the repository, believed to describe the team’s discipline, and drifts from whatever the code actually shows.

A team writes “always use builders for test setup.” Six months later, half the tests use raw setup, because the agent samples the surrounding tests, not the instruction file, and produces more of whatever the surrounding tests already show. The instruction file still says “always use builders.” It is now a lie, and nothing forces anyone to compare the document to the code. The drift compounds on every task: where the surrounding tests violate the instruction, the agent produces more violations. The instruction file is a lever with no fulcrum.

The prose-spec drift trap, named in the SDD post, is this failure at the scale of the whole system. The instruction file is the same trap at the scale of a document, and it fails the same way: a specification separated from what it specifies drifts, and when the document and the code disagree, the agent’s behavior follows the code. It happens whether the specification is a hundred-page requirements document or a twelve-bullet file at the root of the repository.

The instruction file is a claim about the team. The suite is the receipt. The agent behaves according to the receipt.

Structure Replaces the Instruction File

The answer is not “delete the instruction file and hope.” The answer is structural, and it is closer to work the team should already have been doing than to a new practice.

Test discoverability. The test file sits next to the code it specifies, named the same, and each test names a behavior in the domain’s language. OrderService.ApplyDiscount has tests in OrderServiceTests.cs, one of which is Loyalty_members_get_a_ten_percent_discount_on_orders_over_fifty_dollars. The agent asked to change discount behavior finds it by searching “loyalty” or “discount.” No instruction file is needed. The path is walked.

Vocabulary density. The tests use domain nouns: aLoyaltyMember(), anOrderContaining(...), Money, Address. When the agent generates a new test, the surrounding tests show it how to name things. The codebase teaches its vocabulary by demonstration.

Builders that make the right call shorter than the wrong one. If setting up a valid customer takes fifteen lines of manual field assignment, the agent will produce fifteen lines of manual field assignment. If aLoyaltyMember() returns a valid customer in one line, the agent will use it. The right thing has to be the shortest thing. That is not a discipline. That is design.

Naming that works as an index. The test the agent needs is the test it finds first when searching for the domain concept. Name tests by behavior, colocate them with the code they specify, refuse the case-number convention, and the suite becomes an index of the system’s behaviors. The agent uses the index. The tests get run. The regression is caught before it lands.

None of these look like a rule the agent follows. All of them are rules the agent inherits by reading the codebase. The document can drift from the code; the code cannot drift from itself. That is why the environment wins and the directive loses.

The codebase reads the agent into the loop.

The Agent Does TDD When the Codebase Already Does

The instruction file is what teams reach for when the codebase does not exhibit the discipline they want. The reach is understandable. Writing a file is faster than restructuring a codebase. Announcing “we do TDD now” is easier than making the tests actually discoverable. The instruction file is a way to feel that something has been done without doing the harder thing, and the measurement says the reach lands below doing nothing.

Two honest uses remain. The first is scaffolding. A team shifting its discipline can put a short document in the repository, name it as scaffolding, and use it as a reminder while the codebase is restructured: “we are moving toward tests discoverable by domain term; here are the terms and the naming conventions.” That is fine. It is also a document to delete once the codebase demonstrates the discipline it describes. Scaffolding that stays after the building is complete is furniture, and furniture that pretends to be structural is what drifts.

The second is guardrails. Some rules belong in an instruction file because they are policy, not discipline: do not run destructive shell commands without confirmation, do not check credentials into the repository, do not talk to external services from the test suite. Those protect the team regardless of the surrounding code, and they form a small, stable set. They are not what teams add when they add “do TDD.”

Anything beyond scaffolding and guardrails is asking the instruction file to do the codebase’s work.

Every major coding tool now ships with an instruction file. The instruction file is not the discipline. The codebase is. The agent reads what is there. Make what is there the discipline the team wants inherited, and no directive is needed. Fail to make it so, and no directive compensates.

The measurement is public. The lever is structural. The instruction file was doing less than the team believed, and in the one condition where it has been measured, it did less than nothing.