The most important file in our repository is the one written for AI agents

We run a network of Finnish-language guide sites from a single GitHub repository. Most of the day-to-day work is done by AI coding agents: content updates, new pages, fixes and deployments. I have written about the setup elsewhere. This post is about one file in it, the instruction file at the root of the repository, and what ended up in it after two months of real use.

Why a file and not a prompt

An agent starts every task from zero. It does not remember yesterday's mistake or last week's decision. Anything that should carry over has to be in the repository, where the next session will read it.

We also use two different agents on the same repository. A shared file is the only place where both get the same rules.

So the file is short, checked in, and reviewed like code. Almost every line in it is there because something went wrong once.

The rules, and where they came from

Read the status page first, not the history. Early on, agents would read weeks of old task notes before touching anything. Now there is one short status page and a handoff note per site. The history exists, but nobody reads it for a routine change.

An instruction to act covers the whole route to live. If I ask for an update, the agent builds, checks, merges and deploys without asking again at each step. If I say "show me first", it stops there. Asking for the same permission twice is listed as an error.

Make the smallest change in the permanent source. No rebuilding a site from scratch, no new import, no redesign on the side. This rule exists because agents are very willing to improve things nobody asked about.

Check what changed, not everything. A one-line text edit used to trigger browser tests on every page and a fresh backup. The file now says that verification follows the size of the change, and that a result already produced for the same version is not repeated by hand.

Dates are facts. A page keeps its verified first publication date. Only a page whose content really changed gets a new updated date. Build times and site-wide stamps are forbidden, because they make old content look new.

Partner placements are an agreement, not a layout. The order of partners on a page and the offers shown come from a monthly register. A redesign may not move them, and last month's agreements are not carried over by default.

Do not rerun a failing job blindly. When a deployment fails, the agent has to find the actual cause first. There is exactly one documented exception, for a known transient error from the hosting provider's API.

One record per change. The deployment run and its summary are the record. No separate documentation pull request, no status line for a routine edit, no copying the same report into three files.

Leave the other agent's work alone. Whoever gets the task finishes it. Unfinished branches belonging to the other agent are not touched.

A rule that was missing

Rules also have to be removed. We had a check that pinned certain files by checksum so that imports could be verified. One of the pinned files was the status page, which changes all the time. The pin went stale and started failing unrelated pull requests. The fix was not a better pin but taking the living document out of the list.

The lesson I took from it: a guardrail on a file that is supposed to change is a bug, and the agents will dutifully work around it until someone deletes it.

What I would copy

• Keep the file short enough that it is read in full every time.
• Write the reason next to the rule when the reason is not obvious.
• When an agent does something wrong twice, change the file, not the prompt.
• Review instruction changes in pull requests like any other code.

The agents are capable. What they lack is the context of last week, and this file is where that context lives.