The repo is the system of record

Most instruction files for coding agents grow the same way: someone adds a rule after a mistake, then another, until there’s a 500-line blob nobody reads, including the agent. For a small storefront project I tried the opposite, based on the idea of harness engineering: optimise the environment (docs, lints, tests, CI) so that agents and people can ship reliably without a monolithic prompt.

Eight rules

I wrote the project’s principles down in the repo itself. The ones that changed my behaviour:

1. The repository is the system of record. Chat threads and issue comments are invisible to an agent. A decision that affects implementation belongs in docs/ or in code, in the same pull request.
2. A map, not a manual. AGENTS.md is a table of contents. If a topic needs depth, write a focused doc and link to it.
3. Boundaries over guesswork. Parse and validate at the HTTP and key-value boundaries. Don’t assume a payment provider’s payload matches what you remember.
4. Secrets stay in the Worker. Never in the frontend, never in the repo.
5. Services before duplication. Before writing storage logic in a route, extend a service.
6. Tests encode behaviour. Changing business logic without touching tests is unfinished work.
7. Continuous small cleanup. Prefer many small follow-ups over letting sloppy patches accumulate. Debt goes in a tracker.
8. Boring, inspectable dependencies. Prefer libraries an agent can reason about, and wrap opaque SDKs behind a service.

Make the rules mechanical

A rule that lives only in prose gets broken. So the CI job validates two things: that the docs tree has the structure it should, and that the code respects its architecture’s import layers. There are also structural tests for the harness itself.

A quality score

A small table grades each domain, A to D: products, collections, checkout, admin auth, settings, analytics, media, UI, and the documentation harness itself. A means solid tests, docs and boundaries. D means risky and undocumented. Most rows are B, a few are C, and only the docs and architecture-enforcement rows earn an A, which is honest. The purpose isn’t to look good, it’s to tell an agent (or me) where to be careful, and to force a small update to the grade whenever a domain materially changes.

What I chose not to copy

The approach I borrowed from came out of a huge monorepo with a zero-human-written-code policy and custom observability per worktree. None of that fits a small open project. Humans and agents both write code here, and the tooling stays proportionate.

The goal

New sessions should start fast because the answer to “where does this go?” is in a file, not in someone’s head. Mistakes should be caught by a check rather than a review comment. And the docs should stay honest because CI fails when they drift.