Writing code for agents

Several of the conventions on this site look eccentric in isolation and obvious together, once you accept one thing: a language model is a primary reader and writer of this code. This page is the argument that they are not stylistic preferences that happen to suit agents, but a coherent design for a codebase whose main author is a model and whose main reviewer is a human.

The evidence, such as it is

61% of one repository's 2,777 commits were authored by Claude, and 30% by a human. The code was largely written by a model, under the rules published on this site. That is the fact the rest of this page is trying to explain.

There is a smaller piece of direct evidence in a filename. One of the estate's guidance documents is called …/type_safe/v3.1.1__for_llms__type_safe__testing_guidance.md. Documentation written explicitly for a model reader, named as such, already exists — which means the idea was not reverse-engineered onto the code after the fact.

Six conventions, read as one design

1. Runtime validation is a better fit for generated code than static typing

Type_Safe validates at construction. A model that produces a wrong-shaped object gets an error at the point of the mistake, not three layers away and not in a separate checking pass the generator may never run.

That last clause is the whole argument. A type-checker helps a human who runs it. A constructor that refuses invalid input helps whoever runs the code, including a generation loop that is going to execute a test in four seconds and read the traceback. How Type_Safe works →

It is also the weakest link in the chain, and this site says so: runtime validation catches shape errors and catches nothing else. Unreachable code, unused imports, shadowed names and a typo in a branch that never executes are all invisible to it, and there is no linter anywhere in the estate to catch them either. Q5 →

2. Constrained primitives encode the domain in the type name

Safe_Str__SSM__Path tells a model what the value is without a comment, a docstring or a lookup. The name is the documentation, it travels with the value, and it cannot drift from the validation because it is the validation. The pattern →

3. One class per file, filename = class name

A model can locate any symbol by path construction alone — no index, no grep, no embedding search. If it knows the class is called Schema__Caller__IP, it knows the file. That is a property you only get by giving it up everywhere else: no multi-class modules, no convenience groupings, more files than a human would naturally create.

4. Fully-qualified imports and no re-exports

Empty __init__.py means there is exactly one import path to anything. A model cannot invent a plausible-but-wrong one, because the plausible-but-wrong ones do not exist. Re-export layers are a convenience for humans who type imports and a trap for anything generating them.

5. Banners instead of docstrings

A banner at the top of a one-class file is a fixed, findable location for the purpose. Docstrings scatter the same information across a file at unpredictable depths. Rule 8 — inline comments only, no docstrings, ever — reads as an odd aesthetic preference and works as an indexing decision. The four banner forms →

6. Explicit single-owner responsibility rules

Step__Executor is the ONLY class that calls page.* Playwright methods.

This is how you stop a generator putting a call in a reasonable-looking wrong place. A model asked to add a click will put it wherever the surrounding code makes plausible — and plausible is a large set. A rule that names one owner shrinks it to one, and a CI guard behind that rule makes the constraint real rather than advisory. Rules 16 to 19 →

Of the four boundary rules, one is described as having a guard. That is the pattern to copy and the ratio to fix. What the other three would cost →

And one convention that is purely for machines

Every page is available as markdown at the same path with the extension swapped, and links inside the markdown point at markdown, so a traversing agent never has to parse HTML.

The markdown twin is an HTML convention with no human beneficiary at all. It exists so that a reader that does not want a DOM does not have to build one. How it works →

This site keeps a smaller version of the same promise: the front page has a markdown twin, every source document is fetchable as raw markdown at a constructed URL under /briefs/, and /llms-full.txt is the entire site in one request, generated from those sources so it cannot say anything the site does not.

The alignment argument belongs here too

Aligned columns turn a class body into a table. A reader — human or model — scanning a five-attribute primitive sees two columns rather than five sentences. It is the same claim as the rest of this page, and it carries the same caveat: it is asserted from design intent, and nobody has measured whether it helps. The measurements, and the honest version →

The thesis

These conventions trade a little human convenience — no docstrings, more files, more typing — for a lot of machine predictability. That is a defensible trade to make deliberately and a strange one to make by accident.

The corollary is the part that gets skipped. A codebase optimised for a generator still has to be reviewable by a person, and every convention above is doing double duty: the properties that make a symbol locatable by path construction also make it locatable by a human with a file tree, and a constructor that rejects invalid input helps whoever is reading the traceback. The design only works if both readers are served, and the one place it currently is not is enforcement — there is no linter, and the four structural guards are the whole automated surface. What is not enforced →