The rules we give our AI coder

Groundwork — the site you're reading — is built by one founder with Claude Code. The rules file our AI reads at the start of every session is about five thousand words long, and almost every line is there because something went wrong once and we decided it would never go wrong the same way twice.

Most of those rules are specific to this app. But a core of them transfers to anyone building with an AI coder — especially someone who will never read the code, because the rules are what stand in for the review you can't do. This article is that core, with the incidents that earned each rule, and a paste-ready block at the end.

Why a rules file works

An AI coding agent is capable and agreeable in equal measure. Left to defaults, it does what you asked in the most direct way available, tells you things are done, and moves on. Correct it in conversation and the correction lasts exactly one session.

A rules file it re-reads every session turns one-time corrections into permanent behavior. That's the whole mechanism — and it means the file's real job is to be the place where incidents become prevention. When something goes wrong, the response isn't just "fix it"; it's "fix it, and add the rule."

The rules, and what earned them

Run every check before saving any work — and treat a warning as a failure. Software projects accumulate automated checks: tests (does the app still do what it did yesterday?), plus style and consistency checkers. Think of them as smoke alarms you didn't have to install. The rule has two teeth: the AI runs all of them before declaring anything done, and "mostly passing" counts as failing. We learned the second part when a check that tolerated warnings let exactly the kind of problem it existed for sail through.

Save work in small, named steps. Version control — the save-point system every project has — means any change can be undone individually. But only if saves are small and described honestly. One giant "made changes" save is an undo button that undoes a week.

One door for anything that leaves the app. Email, payments, posts to other services: each goes through a single shared piece of code with an off-switch for testing. We learned this when a spending-alert feature quietly built its own private email connection instead of using the shared one — and sent real email, to real addresses, every time the tests ran. Nobody noticed for weeks, because everything worked. When there's one door, you can guard it; when every feature cuts its own, you can't even count them.

Data lives with the account, not in the browser. Our app once remembered that a user dismissed a welcome card by noting it in the browser instead of in their account. Result: the first person to dismiss it on a given computer silently hid it for every account that logged in on that computer afterwards. No error, no complaint — just a feature that vanished for some users and nobody could say why. The rule: anything a user would expect to follow them to another device belongs in the database.

Start every session in sync. Before anything else, the AI pulls the latest version of the project from GitHub and refreshes the installed third-party pieces so this computer matches what the project actually expects. It feels like ceremony until the day it isn't. Ours once ran every check against a stale set of installed pieces: everything passed, the "fix" the checks had approved shipped, and it was wrong — the checks weren't lying, they were honestly reporting on an outdated copy. A session that starts out of sync spends the whole day being confidently wrong.

A feature isn't done until a test proves it. Tests are the most important of those every-save checks — and they only exist if someone writes them. The rule pairs building with proving: every feature arrives with the automated test that shows it works, and no test ever gets deleted or loosened to make a red check turn green. Our project's configuration literally forbids tested code from losing its tests, and the bar only ever moves up.

When you fix a bug, prove the alarm rings. After a real bug, the AI should add a check that would have caught it — and then demonstrate the check works, by briefly putting the bug back and confirming the check goes red before fixing it again. We do this on every guard we add. It sounds paranoid until you learn the alternative: a test that has never failed proves nothing, and an AI is perfectly capable of writing one that passes for the wrong reason.

Never touch the live app's data by hand. The database serving real users is not a place to experiment, test, or "quickly fix" anything. Changes to real users' data go through the app's own code, deliberately, after the AI has told you what could go wrong.

Ask before deleting. Files, data, history — even things that look unused. "Looks unused" is a guess, and deletion is the one operation where a wrong guess has no undo.

Every incident becomes a rule. The meta-rule that makes the file grow instead of you repeating yourself. Ours ends with exactly this instruction, and it's why the file is five thousand words.

Paste this into your project

Save this as a file called AGENTS.md at the top level of your project (Claude Code also reads CLAUDE.md; having the rules in one and a pointer in the other is fine — ask your AI to set that up):

# Standing rules for working on this app

Read these at the start of every session. They override your defaults.

I am not an engineer and I will not read the code. Explain what you do and
what you find in plain language, always.

1. Start every session by pulling the latest version of the project from
   GitHub and syncing the installed third-party pieces to match it. Tell me
   in one line whether anything changed.

2. Before saving any batch of work, run every check this project has (tests,
   style checks, type checks, the scan of our dependencies for known
   vulnerabilities). If anything fails — including warnings — stop and fix
   it first. Never tell me something is done while a check is red.

3. When you build a feature, build the automated tests that prove it works,
   in the same batch. Never delete or weaken a test to get a red check to
   pass — tell me instead.

4. Save work in small, clearly described steps, so any single change can be
   undone on its own. Before each save, tell me in one sentence what changed.

5. Never delete files, data, or history without asking me first, even things
   that look unused.

6. Never put passwords, API keys, or other secrets into the code. They go in
   the environment files that stay out of version control. If you ever find
   one in the code, tell me immediately.

7. Never change the live app's data by hand, and never test against it.
   Anything touching real users' data goes through the app's own code, after
   you've told me the risk.

8. Anything that sends email, moves money, or posts to another service goes
   through one shared place in the code, with a switch that disables it
   during tests.

9. Keep PROJECT.md up to date as part of every change. When I make a decision
   in our conversation, record it in DECISION_LOG.md with the reason — even
   if no code changed. When work comes up that we're not doing now, add it
   to OPEN_WORK.md instead of starting it.

10. When you fix a real bug, add a check that would have caught it — then
    prove the check works: briefly put the bug back, confirm the check goes
    red and nothing else does, and fix it again.

11. When something goes wrong, propose a new rule for this file so it can't
    happen the same way twice.

Two notes on living with it. First, the file only works if it stays honest — when a rule stops matching how you actually work, change the rule, don't ignore it. Second, expect it to grow. A rules file that looks the same after three months means either your app has had no incidents, or — more likely — the incidents aren't being converted into rules.

The rules cover how the AI works day to day. What they can't cover is the slow problems — the security hole, the creeping bill — which is what the monthly check-up is for.