Document hygiene and an agentic setup for working with AI

Most of what goes wrong when I build with an AI assistant has nothing to do with how clever the model is. It comes from what the model was told, and from what it was never told. A session starts knowing nothing about my project. Whatever it needs has to be written down somewhere it will read. So I treat that writing as part of the work, with the same care as the code.

This is the setup I have settled on after a lot of long projects with Claude Code. None of it is specific to one tool. It is mostly about keeping documents honest.

Instructions in layers

The first mistake I made was one huge instruction file per project, copied and tweaked each time. The copies drifted apart, and every new rule had to be added in five places. Now the instructions come in layers. Each layer only says what the one above it cannot know.

• Shared rules. How I want work done anywhere: judge the size of a change before choosing how much process it needs, plan big changes before touching files, never weaken security to make something pass, and never claim something is done without checking.
• This machine. Where the local server lives, which browser I use, how hosting deploys. This is the only part that differs between people who share the setup.
• This project. One file, AGENTS.md, that every AI tool reads. It says what lives where, what must never be edited by hand, and how the project ships. Tool-specific files just point to it, so nothing is written twice.
• Skills. Longer procedures for planning, releasing, auditing and house style. They are read only when the work calls for them, so they cost nothing the rest of the time.

The rule that keeps this working: when the same fact appears in two places, one of them will be wrong soon. Write it once, and point to it from everywhere else.

The documents are the memory

A chat is a poor place to keep decisions. It scrolls away, it gets summarised, and the next session never sees it. So every project has a small .docs/ folder, and the AI keeps it current as part of the job.

• roadmap.md always exists. It holds everything planned or decided, in order. If I approve a list in the chat, it goes into the roadmap in the same turn, not "later".
• implementation_plan.md holds exactly one phase: what changes, why, how it will be checked, and who does what. The AI writes it and then stops until I approve it.
• task.md holds that phase's tasks, each ticked off with the commit that did it.
• When a phase is complete, the lasting facts move out: the changelog says what shipped, a walkthrough shows how to use it, and reference notes change only when something durable did.

Then comes the step that is easy to skip: trimming. Finished detail leaves the plan and the task list, so the next session reads only what is still true. A working document that only grows turns into a history book, and the AI will happily act on a decision that was reversed three weeks ago.

Small changes do not touch any of this. A typo fix gets a clear commit message, and that is the record. Paperwork has to earn its place, or nobody keeps it up.

Long sessions without starting over

I used to start a fresh chat whenever a session got long, and lose half a day re-explaining the project. Now I let the conversation be summarised when the context fills up. A small hook then sends the AI back to .docs/ before it does anything else. Where the summary and the files disagree, the files win.

That only works because of the document habits above. If a decision lives only in the chat, the summary may drop it. If it is in the roadmap, it survives anything.

Process in proportion

Not every change deserves the full routine. A few CSS lines get done directly, with one quick check. A new feature follows the patterns already in the code and gets its affected pages checked once. Anything large or risky, such as sign-in, payments, data changes or deployment, gets a written plan, my approval, and a review by a second agent that tries to break it.

Size is about what could break, not how many lines move. A two-line change to who can see what is a bigger deal than a hundred lines of styling.

Checks the AI cannot talk its way past

An AI is very good at sounding finished. So the checks that matter are scripts, not opinions. One audit suite scans for security issues, broken links and assets, accessibility problems and style drift. It reports only what the current change introduced, kept apart from the debt that was already there, so a real new problem never hides in old noise.

For the tests that guard important behaviour, there is one more step: deliberately break the thing the test protects, and make sure the test notices. A test that stays green when its feature is removed was never testing anything.

Helpers, but sparingly

Splitting work across several agents is tempting, and sometimes right. But every hand-off loses detail, and each agent reports with the same confidence whether it was right or not. So the default is one session working directly. Helpers come in only when pieces are truly independent, and whatever they report gets checked against the actual diff before I believe it.

What it adds up to

None of this is clever. It is the same discipline a good team uses: write decisions down, keep one source of truth, plan the risky parts, and check the work instead of trusting it. The difference is that an AI forgets everything between sessions, so the habits stop being nice to have. They are the only thing that carries a project from one day to the next.