Test driven development with AI: set the rule once, keep it for the whole project

TL;DR

Difficulty: Intermediate

An AI assistant writes code first because that is what you asked for, and it forgets your rules every new session.

  • Write the TDD rule once in AGENTS.md (or CLAUDE.md, Cursor rules, Copilot instructions): test first, show the failing run, wait for approval, never touch existing tests, done means the full suite passes.
  • Approve every test yourself before code is written. The test is where the business meaning lives.
  • Run the tests yourself and let machines check: a pre commit hook, hooks in the assistant, CI on every push and branch protection that blocks a red merge.

You describe a feature and the assistant hands you finished code, with a test written afterwards if at all, and tomorrow it has forgotten how you work. This chapter shows how to make test first the default for the whole project: one rules file, one human checkpoint, and checks that do not depend on what the AI says.

The question this article answers

You have read about test driven development. You know the loop: write a test that fails, write just enough code to make it pass, tidy up, repeat. If not, test driven development explained starts from zero and is worth ten minutes first.

Now you open an AI coding assistant, describe a feature, and it hands you two hundred lines of finished code. No test came first. Perhaps a test arrived afterwards, written to agree with whatever the code already does. The next morning you start a new session and have to explain your way of working all over again.

So the question is simple: how do I make an AI coding assistant work test first, every time, for the whole life of the project, without repeating myself and without simply trusting it?

The short answer has three parts. Write the rule down once, in the file every assistant reads at the start of every session. Keep a person in the loop at the one moment that matters, when the test is approved. And make the machine check the result, so that "the tests pass" is something you see, not something you are told.

This chapter goes through each part with the same invented business used across the series: Corrib Tea, an online tea shop in Galway that sells loose tea and subscriptions at corribtea.example, with card payments through a payment provider, discount codes, stock and order emails. Its developer is Priya. By the end she has a repository where the assistant works test first by default, and where it cannot quietly stop doing so.

Why AI assistants reach for the code first

An assistant does what the prompt asks. "Add free delivery over €40" asks for a feature, so it writes the feature. A test is a second request that nobody made.

There is a second reason, and Anthropic says it plainly in the documentation for its own tool, Claude Code. An assistant stops when the work looks done. If it has nothing to run that tells it whether the work really is done, "looks done" is all it has, and the documentation adds: "In practice that makes you the test suite."1 In other words, without a test, you become the person who finds every mistake by hand.

The reverse is also measured. Two researchers gave language models programming problems with and without the matching tests, and found that "including test cases leads to higher success in solving programming challenges"2. A test is not only a safety net for the human. It is the clearest description of the goal the assistant can get.

And there is a third reason, which every experienced developer who works with these tools learns sooner or later. When a test fails, the quickest way to make it pass is not always to fix the code. Kent Beck, who wrote Test Driven Development: By Example, kept a list of warning signs while building software with an AI agent in 2025. One of them: "Any indication that the genie was cheating, for example by disabling or deleting tests."3 Why that happens, and how to catch it, is the whole of when AI changes the test instead of the code. Here it is enough to know it happens, so the rule has to forbid it.

Example: one request, two answers

Priya types the same request into a fresh session twice.

The first time, the repository has no instructions for the assistant. The request is "Free delivery on orders over €40, otherwise €3.95." The assistant adds a method to the order model, changes the basket page, and writes "Done. Delivery is now free over €40." There is no test. Priya has to open the shop, add tea worth €39.99, check the fee, add tea worth €40, check again. She is the test suite.

The second time, the repository has a rules file (the next section shows it). Same request. The assistant replies with a test file of 12 lines, runs it, shows that it fails, and stops with a question: "Here is the failing test. Does it describe the rule correctly before I write the code?" Priya reads 12 lines instead of checking a basket by hand, and she notices something the assistant could not know. More on that in the worked example further down.

Same tool, same model, same request. The difference is one file.

A rules file is the project's memory

Every session with an assistant starts with a blank memory. The Claude Code documentation puts it in one sentence: "Each Claude Code session begins with a fresh context window."4 Whatever you told it yesterday in the chat is gone today.

What carries over is a file in the repository that the tool reads automatically at the start of every session. Each tool has its own name for it, and they are converging:

  • AGENTS.md is an open format, "a README for agents", now looked after by the Agentic AI Foundation under the Linux Foundation. Its site lists more than 20 tools that read it, among them OpenAI Codex, Cursor, Gemini CLI, Windsurf and GitHub Copilot's coding agent. When there are several, "the closest AGENTS.md to the edited file wins"5.
  • Claude Code reads CLAUDE.md (in the project root or in .claude/CLAUDE.md) at the start of every session. In current versions it reads AGENTS.md instead when there is no CLAUDE.md, and a CLAUDE.md can pull in another file with a line such as @AGENTS.md4.
  • Cursor keeps project rules as .mdc files in .cursor/rules. A rule with alwaysApply: true applies to every chat session, and Cursor also supports AGENTS.md in the project root and in subfolders6.
  • GitHub Copilot reads repository wide instructions from .github/copilot-instructions.md, instructions for certain paths from files in .github/instructions/ with an applyTo pattern, and AGENTS.md files for its agents7.

There is one sentence in the Claude Code documentation that every team should read before relying on any of these files: the instructions are treated "as context, not enforced configuration"4. A rules file is a very good briefing. It is not a lock. That is why this article does not stop here.

Example: one file for every tool at Corrib Tea

Priya uses Claude Code most days and Cursor now and then, and she wants a contractor who prefers Copilot to get the same rules. So she writes the rules once, in AGENTS.md at the root of the repository, and points the other tools at it:

corribtea/
├── AGENTS.md                      # the one rules file, read by most tools
├── CLAUDE.md                      # one line: @AGENTS.md
├── .github/
│   └── copilot-instructions.md    # one line: "Follow AGENTS.md in the repository root."
└── docs/
    └── critical-path.md           # the shop's critical path, see chapter 4

Line by line:

  1. AGENTS.md holds the real rules. Every tool that supports the format reads it directly.
  2. CLAUDE.md contains a single import line, @AGENTS.md. Claude Code expands it, so the same text loads even in setups where it would otherwise read only CLAUDE.md.
  3. .github/copilot-instructions.md contains one sentence pointing to the same file, for the Copilot chat in the editor.
  4. docs/critical-path.md is the list of steps that must never break, from checkout to the order email. How to find and write that list is in the critical path in software. The rules file refers to it, so the assistant knows which parts need the most care.

One source of truth, three ways in. When Priya changes a rule, she changes it in one place.

Writing the rule so it cannot be misread

A vague rule gets a vague result. "Please use TDD" is a wish. The assistant may agree, write the code, and add a test afterwards, honestly believing it did what you asked.

A rule that works has four properties.

  1. It says what to do, in order. Test first, then show the failure, then wait, then code. A sequence is harder to misread than a value.
  2. It says what "done" means, as a command. "Done means bin/rails test exits with no failures, and you show me the output." The Claude Code documentation recommends exactly this: ask for evidence, "the command it ran and its output", because "'All tests pass' on its own tells you very little"1.
  3. It forbids the shortcut by name. "Never edit, skip or delete an existing test without asking me first." A general rule about quality does not cover this. A named ban does.
  4. It is short. Anthropic's guidance is to keep each CLAUDE.md under 200 lines, because "longer files consume more context and reduce adherence"4. A TDD contract fits in 20.

Example: the TDD contract in Corrib Tea's AGENTS.md

This is the section Priya puts at the top of her AGENTS.md:

## How we work: tests first, always

1. Before writing any production code, write ONE failing test for the behaviour I describe.
   Unit tests: Minitest in test/models or test/services. Browser flows: Capybara system tests.
2. Run only that test and paste the failing output. It must fail on the assertion,
   not on a typo or a missing file. If it fails for the wrong reason, fix the test setup first.
3. STOP and wait for me to approve the test. Do not write production code until I say "approved".
4. Write the least code that makes the test pass. No extra features, no "while I'm here".
5. Never edit, skip, delete or weaken an existing test. If you think a test is wrong, say why and ask.
6. Done means: `bin/rails test:all` passes. Paste the last lines of the output as proof.
7. Refactor only when everything is green, and in a separate commit from behaviour changes.
8. Anything listed in docs/critical-path.md (checkout, payment, order email): propose, never decide.

## Commands
* One file: `bin/rails test test/models/delivery_fee_test.rb`
* Everything: `bin/rails test:all`
* Browser tests only: `bin/rails test:system`

Line by line, for anyone who has not written one before:

  • Rule 1 names the framework and the folders, so the assistant does not invent a new test style. Minitest is the testing library that ships with Ruby on Rails. A system test drives a real browser through the shop, using a library called Capybara.
  • Rule 2 is the one people forget. A test that fails because a class does not exist yet proves nothing about the behaviour. A test that fails because it expected €0 and got €3.95 proves the test is actually checking something. That is what "fails for the right reason" means.
  • Rule 3 creates the human checkpoint. The word "approved" is a clear signal that cannot be mistaken for small talk.
  • Rule 4 keeps changes small, which keeps them readable.
  • Rule 5 forbids the shortcut by name, and gives the assistant a legitimate way out: say so and ask.
  • Rule 6 defines done as a command plus its output. bin/rails test:all runs every test, including the browser tests, which plain bin/rails test skips by default8.
  • Rule 7 comes straight from Kent Beck's own instructions to his agent, which tell it never to mix structural changes and changes in behaviour in the same commit3. A tidy up and a change in behaviour are easier to review apart.
  • Rule 8 ties the contract to the critical path. On those steps the assistant may draft, and Priya decides.

The commands section matters more than it looks. An assistant that has to guess how to run the tests will sometimes guess wrong and then report that it "could not run the suite". Giving it the exact commands removes the guess.

The test first loop with an assistant

With the rule in place, a feature runs through the same loop every time. There are two people in it, so to speak: you and the assistant. Each has a job.

  1. You describe one behaviour, in plain words, with the business rule and an example or two.
  2. The assistant writes one failing test and shows you the red run.
  3. You read and approve the test. This is the decision that matters most. The test is the specification. If it says the wrong thing, the code will faithfully do the wrong thing.
  4. The assistant writes the least code that passes.
  5. You run the whole suite yourself, and only a green result counts.
  6. Refactor if needed, run again, commit.

Why put the human at step 3 and not only at the end? Because reading a test is far quicker than reading code, and it is where the business meaning lives. Twelve lines of test say exactly what the shop promises its customers. The 40 lines of code that follow are just the means.

Tap or click to open full screen and move around

Example: free delivery from €40, built test first with the assistant

Here is the whole loop at Corrib Tea, every prompt included.

Step 1, Priya describes the behaviour.

New behaviour: delivery fee.
Orders over €40 get free delivery. Below that, delivery is €3.95.
Amounts are stored in cent. Put the rule in a small class, DeliveryFee.
Follow the TDD contract in AGENTS.md.

Step 2, the assistant writes the test and runs it. It creates test/models/delivery_fee_test.rb:

require "test_helper"

class DeliveryFeeTest < ActiveSupport::TestCase
  test "delivery is free over 40 euro" do
    assert_equal 0, DeliveryFee.for(4_001)
  end

  test "delivery costs 3.95 at 40 euro and below" do
    assert_equal 395, DeliveryFee.for(4_000)
  end
end

Reading it from the top: require "test_helper" loads the Rails test setup. The class groups the tests about one subject. Each test "..." do block is one example, named as a sentence about behaviour. assert_equal 0, DeliveryFee.for(4_001) means "I expect the fee for a basket of 4,001 cent (€40.01) to be 0". The second test pins the fee at exactly €40.00.

Following rule 2, the assistant first creates an empty DeliveryFee class with a for method that returns nil, so the test fails on the assertion and not on a missing class. Then it runs the file and pastes the output:

$ bin/rails test test/models/delivery_fee_test.rb
Failure:
DeliveryFeeTest#test_delivery_is_free_over_40_euro [test/models/delivery_fee_test.rb:5]:
Expected: 0
  Actual: nil

2 runs, 2 assertions, 2 failures, 0 errors, 0 skips

Red, and red for the right reason: the test expected a number and got nothing. The assistant stops and asks for approval.

Step 3, Priya reads the test, and finds the real question. "Over €40" in her own prompt was loose. Does a basket of exactly €40.00 ship free? The test says no. She checks with the owner of Corrib Tea, who has the answer at once: the banner on the site says "free delivery from €40", so €40.00 must ship free. A customer with exactly €40 in the basket who is charged €3.95 would rightly feel cheated, and would be giving out about it by email before the tea arrived.

Priya replies:

Not approved yet. The rule is "€40 or more is free". Change the tests:
4_000 cent is free, 3_999 cent costs 395. Then run them again.

The assistant changes the two tests to DeliveryFee.for(4_000) returning 0 and DeliveryFee.for(3_999) returning 395, runs them, shows two failures again, and waits. Priya replies "approved". Note who changed the test: the assistant did, because a person asked it to, before any code existed. That is the only time a test should change in this loop.

Step 4, the assistant writes the least code that passes.

class DeliveryFee
  FREE_FROM_CENTS = 4_000
  STANDARD_CENTS = 395

  def self.for(subtotal_cents)
    subtotal_cents >= FREE_FROM_CENTS ? 0 : STANDARD_CENTS
  end
end

Two named numbers, so nobody has to guess what 4,000 means in a year. One method: if the subtotal is 4,000 cent or more, the fee is 0, otherwise 395. The >= is the whole point of step 3. With > the shop would have broken its own banner.

Step 5, Priya runs the suite herself. Not the assistant: Priya, in her own terminal.

$ bin/rails test:all
...
214 runs, 389 assertions, 0 failures, 0 errors, 0 skips

Step 6, commit. No refactoring is needed this time, so that part is grand. Priya commits the test and the class together, with the message "Free delivery from €40 (DeliveryFee)".

Count the time. Writing the prompt, reading 12 lines of test, one question to the owner, reading eight lines of code. A few minutes. What it caught was a rule that would have charged customers €3.95 against the shop's own promise, on every order of exactly €40, until someone complained.

Run the tests yourself, never take the assistant's word

An assistant that writes "all tests pass" may be right. It may also have run one file instead of all of them, read an old result, or summarised optimistically. The only result that counts is one you can see.

There are five ways for a developer to start the tests without depending on the assistant at all. Use as many as fit.

  1. By hand, in your own terminal. In Rails, bin/rails test runs the unit and integration tests, bin/rails test path/to/file_test.rb:6 runs the single test on line 6, and bin/rails test:all adds the browser tests8. For a JavaScript front end with Playwright, npx playwright test runs every browser test9.
  2. In watch mode. Vitest, a test runner for JavaScript and TypeScript, enters watch mode in development when you simply run vitest, and runs the affected tests again on every save10. You see red and green while the assistant works.
  3. Before every commit. Git can run a script, called a hook, at fixed moments. The pre commit hook runs before a commit is created, and if it exits with a non zero status, "the git commit command" aborts "before creating a commit"11.
  4. In the assistant's own hooks, covered in the next section.
  5. In CI on every push, also covered in the next section. CI (continuous integration) is a server that runs the full suite on every change, in a clean environment that nobody's laptop can influence.

A pre commit hook can be skipped with git commit --no-verify, as the Git documentation states11. That is fine for an emergency and also the reason why the server, not the laptop, has the last word.

Example: Priya's pre commit hook

Priya keeps her Git hooks in the repository, so the contractor gets them too. She creates .githooks/pre-commit:

#!/bin/sh
# Runs the fast tests before every commit. The full suite runs in CI.
echo "Running unit tests before commit..."
if ! bin/rails test test/models test/services; then
  echo "Tests failed. Commit stopped. Fix the code, then commit again." >&2
  exit 1
fi

And activates it once per machine:

chmod +x .githooks/pre-commit
git config core.hooksPath .githooks

Line by line: the first line says the script runs with the standard shell. The if ! line runs the model and service tests, the fast ones that finish in seconds, and checks whether they failed. If they did, the script prints a plain message to the error output and exits with 1, which stops the commit. core.hooksPath tells Git to look for hooks in the .githooks folder instead of the hidden default one11, so the hooks live in version control like everything else.

Now, when the assistant commits on Priya's behalf (many assistants can run Git), the same hook runs. A red suite stops the commit whether a person or an assistant typed the command.

Enforce it mechanically, not by trust

The Claude Code documentation draws a line that applies to every tool. There are instructions the model reads and then decides about, such as a prompt or a CLAUDE.md, and there are instructions the tool itself executes every time, "no matter what the model decided to do", such as hooks and deny rules1. The rules file belongs to the first kind. Everything in this section belongs to the second.

Hooks inside the assistant

Claude Code can run your own shell commands at fixed points: after a tool call succeeds (PostToolUse), before one (PreToolUse), and when Claude finishes responding (Stop)12. The hook receives details as JSON on its standard input, including the path of the file that was just edited12. Two exit codes matter. Exit 0 means no objection. Exit 2 means: for PostToolUse, the message on the error output is shown to Claude as feedback, since the edit already happened, and for Stop, Claude is prevented from stopping and continues working13.

That gives two useful hooks: run the matching test after every edit, and refuse to finish while the suite is red. Other assistants offer similar mechanisms under other names, so check your own tool's documentation for the equivalent.

Example: two hooks in Corrib Tea's repository

Priya adds .claude/settings.json to the repository, so the hooks apply to anyone who opens the project in Claude Code:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-matching-test.sh" }]
      }
    ],
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/suite-must-pass.sh" }]
      }
    ]
  }
}

The first block says: after every Edit or Write, run run-matching-test.sh. The second says: whenever Claude is about to finish, run suite-must-pass.sh. $CLAUDE_PROJECT_DIR is the project folder, so the paths work from anywhere12.

The first script finds the test that belongs to the edited model and runs it:

#!/bin/bash
# After each edit: run the test that belongs to the changed model file.
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

case "$FILE" in
  */app/models/*.rb)
    TEST="${FILE/\/app\/models\//\/test\/models\/}"
    TEST="${TEST%.rb}_test.rb"
    ;;
  *) exit 0 ;;
esac

if [ ! -f "$TEST" ]; then
  echo "No test found for $FILE. Write the failing test first (AGENTS.md rule 1)." >&2
  exit 2
fi
bin/rails test "$TEST" >&2 || exit 2

In plain words: read the JSON the hook receives, take out the edited file's path with jq, a small tool for reading JSON. If the file is a model in app/models, work out where its test should be, for example test/models/delivery_fee_test.rb for app/models/delivery_fee.rb. Anything else, leave alone. If no test exists, tell the assistant to write one first and exit with 2, so the message reaches it. Otherwise run the test, and exit with 2 if it fails, so the failure output goes straight back to the assistant.

The second script is the gate at the end:

#!/bin/bash
# Before Claude finishes: the whole suite must be green.
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # already sent back once: let it stop, CI is the next gate
fi

if ! OUTPUT=$(bin/rails test 2>&1); then
  echo "The suite is red. Fix the code, not the tests. Last lines:" >&2
  echo "$OUTPUT" | tail -n 30 >&2
  exit 2
fi

The stop_hook_active check comes from the documentation: it prevents an endless back and forth, and Claude Code itself overrides a Stop hook that blocks eight times in a row12. If the suite fails, the last 30 lines of output go back to the assistant with a plain instruction, and exit 2 keeps it working. If it fails a second time, the assistant may stop, and it reports a red suite. That is honest, and the next gate is waiting.

CI and branch protection

The last gate does not run on anyone's machine. A CI workflow runs the whole suite on a server for every push. Branch protection on GitHub then refuses to merge a change into the main branch until the checks you mark as required have passed: "all required status checks must pass before collaborators can merge changes into the protected branch"14. With required reviews switched on as well, changes reach the protected branch only through a pull request14.

This gate does not care who wrote the code, which tool was used, or whether a hook was skipped. That is exactly what makes it the backstop.

Example: the CI workflow and the branch rule at Corrib Tea

Priya adds .github/workflows/ci.yml, using GitHub Actions, the CI service built into GitHub15. It looks like this:

name: CI
on:
  push:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:17
        env:
          POSTGRES_PASSWORD: postgres
        ports: ["5432:5432"]
    env:
      RAILS_ENV: test
      DATABASE_URL: postgres://postgres:postgres@localhost:5432/corribtea_test
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          bundler-cache: true
      - run: bin/rails db:prepare
      - run: bin/rails test:all

Line by line: on: push and pull_request mean the workflow runs for every push and every pull request. The test job runs on a fresh Linux machine, with a PostgreSQL database started next to it as a service. The env block tells Rails to use the test environment and where the database is. The steps fetch the code, install Ruby and the project's gems (with a cache, so later runs are quicker), create the test database, and run every test, browser tests included.

Then, once, in the repository settings on GitHub, she adds a protection rule for main: require a pull request before merging, and require the status check test to pass. From now on, nothing reaches main with a red suite. Not her own late evening fix, not the contractor's change, not the assistant's.

Why the layers multiply

Each layer misses some problems. The useful question is how often a slip gets past all of them. If the layers are roughly independent, the chance that one slip gets through every layer is the product of the chances that each layer misses it:

Pthrough=q1⋅q2⋅q3P_{\text{through}} = q_1 \cdot q_2 \cdot q_3

Here PthroughP_{\text{through}} is the probability that a slip passes every layer, q1q_1 is the probability that the first layer misses it, q2q_2 the probability that the second misses it, and q3q_3 the same for the third. Multiplying chances like this is explained from scratch in Foundations: probability.

Real layers are never fully independent: a test that does not exist is missed by every layer at once. That is why the test itself, approved by a person, comes first. But the formula shows why three imperfect checks beat one good one.

Example: three layers at Corrib Tea, with invented numbers

The numbers here are invented to show the arithmetic, not measured. Say the rules file alone gets ignored in 1 slip out of 5, so q1=0.2q_1 = 0.2. The Stop hook misses 1 in 10, for instance when it gives up after its second try, so q2=0.1q_2 = 0.1. CI with branch protection misses 1 in 20, mostly through slow browser tests someone switched off, so q3=0.05q_3 = 0.05.

Pthrough=0.2×0.1×0.05=0.001P_{\text{through}} = 0.2 \times 0.1 \times 0.05 = 0.001

So Pthrough=0.001P_{\text{through}} = 0.001, which is 1 slip in 1,000. With the rules file alone it would have been 1 in 5. Each layer on its own is far from perfect. Together they turn a weekly annoyance into a rare event.

Tap or click to open full screen and move around

What changes over a long project

On day one, everything fits in the assistant's head. By month four the project has hundreds of files, dozens of decisions, and a conversation history no tool can hold in full.

Two things happen. Long sessions get compacted: the tool summarises the conversation to make room, and details given only in the chat can disappear. And new sessions start blank, every morning. The Claude Code documentation is specific about what survives: the project root CLAUDE.md "survives compaction", because the tool reads it again from disk, and an instruction that vanished after compaction "was given only in conversation"4. Its advice is just as specific: add instructions that matter to the file, so they persist4.

So the rules file is not set and forget. It is the project's long term memory, and it deserves the same care as code:

  • Keep it in version control and review changes to it like any other change. A line removed from the rules file changes how every future session behaves.
  • When you correct the assistant twice for the same thing, write it down. The second correction is the signal.
  • Keep it short. Move rules that only apply to part of the code into rules for that part (.claude/rules/ with paths, Cursor rules with globs, Copilot files with applyTo), so they load only when relevant467.
  • Point to living documents instead of copying them. The critical path list lives in docs/critical-path.md, and the rules file only says where it is.

Example: month four at Corrib Tea

In month four, Priya notices that in two separate sessions the assistant made an integration test for the subscription renewal pass by replacing the whole payment service with a stand in object (a "mock") that always says yes. The test was green and proved nothing about renewals.

She does not explain it again in the chat, where it would be forgotten by tomorrow. She adds two lines to AGENTS.md:

9. Integration tests for checkout and renewals use FakePaymentProvider (test/support).
   Never replace the payment service itself with a mock or stub in those tests.

She commits the change with the message "Rules: integration tests use FakePaymentProvider". The next morning a fresh session opens, reads the file, and writes the next renewal test against the fake provider without being told. The contractor's sessions in Cursor get the same rule from the same file. The correction was made once, and it now holds for everyone and every session after.

What a business owner should ask

If you commission software rather than write it, you do not need to read hooks or YAML. You need to know the safeguards exist. Five questions are enough, and a good developer answers each in a sentence and can show it on screen.

  1. Is there a rules file for the AI tools, in the repository, and does it say tests come first? Ask to see it. It is plain text.
  2. Who approves a test before the code is written? The answer should be a named person, not "the AI checks itself".
  3. Do the tests run automatically on every change, on a server? Ask what happens to a change with a failing test. The right answer is "it cannot be merged".
  4. Which parts are the critical path, and who decides changes there? The right answer names checkout, payment and the like, and a person, not a tool. The critical path in software explains what to expect.
  5. Can you show me the last release and the tests that ran for it? This is where release registers and security testing per release come in.

For what it is worth, this is how I work myself. I build in Ruby on Rails and Solidus, test first with BDD scenarios, every release passes a test gate, and I use AI every working day by risk tier: on low risk work AI builds, on medium risk work AI drafts and I edit, and on high risk work I decide and AI only advises. Why that split matters, and who carries the responsibility for AI written code, is set out in AI writes the code, who is responsible for it.

Example: the owner of Corrib Tea asks the five questions

The owner of Corrib Tea asks Priya the five questions over coffee. She opens AGENTS.md and shows rules 1 to 3: tests first, and she approves each test. She opens the last pull request on GitHub, where a green tick next to "test" shows CI passed, and the settings page where main requires that check. She opens docs/critical-path.md, where checkout, payment, the order email and subscription renewals are listed, and rule 8, which says the assistant proposes and she decides there. The free delivery change is in the history, with its test. Ten minutes, and the owner knows how a change gets into the shop, and who answers for it.

Set the rule once, check it every time

An AI assistant will work test first if you tell it to, in a file it reads every session, in words it cannot misread. That part takes an hour, once.

It will keep working test first only if something checks. A person approves each test, because the test is where the business meaning lives. Hooks run the tests while the assistant works. A pre commit hook stops a red commit. CI and branch protection stop a red merge, whoever wrote the code.

Set the rule once. Check it every time. The next chapter, when AI changes the test instead of the code, deals with the one way an assistant can make a red suite green without fixing anything, and how to catch it.

If you want your project set up so that AI works test first and nothing red reaches production, book the free workshop: we map your critical path and your safeguards together, and the first two weeks of work are on me.

Sources

  1. 1.

    Anthropic, Best practices for Claude Code, Claude Code documentation, 2026, https://code.claude.com/docs/en/best-practices

  2. 2.

    Noble Saji Mathews and Meiyappan Nagappan, Test-Driven Development for Code Generation, arXiv 2402.13521, 2024, https://arxiv.org/abs/2402.13521

  3. 3.

    Kent Beck, Augmented Coding: Beyond the Vibes, newsletter, 25 June 2025, https://newsletter.kentbeck.com/p/augmented-coding-beyond-the-vibes

  4. 4.

    Anthropic, How Claude remembers your project, Claude Code documentation, 2026, https://code.claude.com/docs/en/memory

  5. 5.

    Agentic AI Foundation (Linux Foundation), AGENTS.md, 2026, https://agents.md/

  6. 6.

    Cursor (Anysphere), Rules, Cursor documentation, 2026, https://cursor.com/docs/context/rules

  7. 7.

    GitHub, Adding repository custom instructions for GitHub Copilot, GitHub Docs, 2026, https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions

  8. 8.

    Rails Core Team, Testing Rails Applications, Ruby on Rails Guides, 2026, https://guides.rubyonrails.org/testing.html

  9. 9.

    Microsoft, Running and debugging tests, Playwright documentation, 2026, https://playwright.dev/docs/running-tests

  10. 10.

    Vitest, Command Line Interface, Vitest documentation, 2026, https://vitest.dev/guide/cli

  11. 11.

    Git project, githooks: hooks used by Git, Git documentation, 2026, https://git-scm.com/docs/githooks

  12. 12.

    Anthropic, Automate actions with hooks, Claude Code documentation, 2026, https://code.claude.com/docs/en/hooks-guide

  13. 13.

    Anthropic, Hooks reference, Claude Code documentation, 2026, https://code.claude.com/docs/en/hooks

  14. 14.
  15. 15.

    GitHub, Workflow syntax for GitHub Actions, GitHub Docs, 2026, https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax