My Coding Agent Has a Constitution. Every Rule Is a Scar.

Before a coding agent does anything on my machine, it reads a file. The file is long. It has been rewritten many times, split in two once, and backed up before every major edit because losing it would cost more than losing most of the code on the disk.

It is not a prompt, in the sense people usually mean. There is no clever phrasing in it, no persona, no trick. It is closer to the operations manual a good team accumulates over years, written down because the team in this case has no long-term memory of its own. The agent that ran last night is not the agent running now. The file is the only thing they have in common.

Here is how it is organised, why it is organised that way, and the handful of mechanisms in it that did the most work.

Every rule is a scar, and the scar is dated

The convention that matters most is that no rule goes in the file without the date it was added and the thing that went wrong. Not “always close browser tabs.” Rather: “close every tab you open, added on this date, after a session left a pile of orphaned tabs for the third time.”

Two reasons. The first is that a rule with its incident attached is a rule the agent can reason about. When a new situation is almost but not quite the one the rule was written for, the incident tells it what the rule was protecting against, and it can decide whether the protection applies. A bare imperative cannot do that.

The second reason is for me. When I read the file six months later and wonder whether a rule is still needed, the date and the incident tell me. Some rules have been retired because the tool that caused the incident is gone. Without the date, I would not have known which ones.

Three tiers, and the top tier is very short

Not everything in the file has the same weight, and the file says so.

Established facts are things the agent should simply know and never ask about again. Which account to use for a given service. Which of two similar tools is installed. The answer to a question that keeps coming up. These exist because an agent that does not know a fact will either ask, which costs my attention, or guess, which costs more.

Standing rules are the bulk. Procedures, defaults, the order to do things in, what to check before choosing a host, what to write down after a deploy. These are the accumulated “how we do things here,” and the agent follows them unless a person says otherwise in the moment.

Hard rules are the short list at the top that no instruction in the moment can override. There are fewer than ten. They cover the things that are irreversible or that damage something outside the machine: what may never be published, which identity may never appear in a commit, what may never be sent to a third party. A hard rule says explicitly that it overrides any tool, any default, any later instruction that seems to permit the thing. There is one that names three specific API calls that must never be issued against my browser, and it exists because of a week I described elsewhere.

The tiering is what makes the file usable. An agent reading a flat list of two hundred imperatives will weigh them equally and get the important ones wrong under pressure. An agent that knows there are eight things it can never do, and two hundred it should usually do, behaves very differently.

The file outgrew the agent, so it became a library

At some point the file crossed a hundred and fifty thousand characters and the agent could no longer hold all of it alongside the work. This was not a gradual degradation. It was a cliff. Sessions started forgetting rules that were plainly written down, because they were written down past the point the agent could see.

The fix was to move the eighty or so hard-won, machine-specific lessons out of the main file into a set of named skill files, each one covering a domain: hosting, browser automation, concurrent git sessions, scraping, building games, a particular kind of compliance work. The main file keeps a one-line index of them with instructions to read the relevant one before starting work in that area. Nothing was deleted. Every lesson is verbatim in one of the skills. The main file dropped to a fraction of its size and the forgetting stopped.

The principle generalises: the always-loaded context should be the rules that apply to every session, and everything else should be a page the agent knows how to fetch when it needs it. If your rules file is growing, this split is coming, and it is better to do it before the cliff than after.

The end-of-session report

Every session, without exception, ends by writing a report to a folder I read. Objective, tactics, what was actually done, what the next session needs to know, and notes. Blocked is reported as blocked. Untested is reported as untested. A report that claims success has to say what verified it.

I resisted this for a while because it looked like ceremony. It is the opposite. It is the only mechanism that lets a session that starts tomorrow benefit from a session that ended tonight. Before the reports, I was the memory, and I was a bad one. After the reports, the handoff is written by the agent that did the work, at the moment it finished, which is the only moment the details are all still present.

The reports have a second function that I did not design. They are how I audit. When a run claims a hundred and fifty applications and the platform shows thirty-three, the report is where the discrepancy shows up, and the report is what I read to find out where the counting went wrong.

Reflection is mandatory and usually produces nothing

The last thing a session does, after the report, is answer a question: what did you learn that a future session should not have to relearn? If the answer is a durable procedure, it goes into a skill. If it is a fact about how I work, it goes into the main file. If it is nothing, the session says so, explicitly, and that is a valid answer.

Most sessions produce nothing, and that is correct. The rule is not “always add a lesson,” which would fill the file with filler. The rule is “always ask,” and the value comes from the one session in five where the answer is a rule that saves an hour every week from then on. Every rule in the file that I would describe as load-bearing came out of that question, asked at the end of a session that had just paid for the lesson.

What this is not

It is not a set of prompts, and I am wary of people who sell it as one. The wording of the rules matters much less than the fact that they exist, that they are tiered, that they carry their incidents, and that the system has a mechanism for adding to them at the moment the lesson is fresh. Any agent reading a file like this will behave more like a colleague and less like a very fast stranger, and the specific phrasing is the least important variable.

It is also not finished. The file is edited most weeks. Rules are added, a few are retired, and about once a quarter something in it turns out to have been wrong for months. That is fine. It is the same as any operations manual, except that this one has a reader who actually reads it, every time, from the top.

The full file, the skill library, the report template and the reflection protocol are what I install for people who want the same thing on their machine. The structure is above, and the structure is what matters.