Skip to content

Open-source maintainer

Reviews contributions from people and machines they have never met, against conventions only they know.

Open-source maintainer

Who this is

The person whose repository other people's assistants now write into. Pull requests arrive that are fluent, plausible and wrong in the specific way that comes from not knowing what this project decided two years ago.

How they work

In gaps. A maintainer's scarcest resource is the attention needed to explain the same convention for the eleventh time, and an AI-assisted contribution multiplies the number of times that explanation is needed without multiplying the maintainer.

What goes wrong

Conventions that live in the maintainer's head and in old review comments, so every contributor — human or machine — rediscovers them by being corrected. Decisions relitigated by someone who could not have known they were settled. Documentation that describes a design the code abandoned, which a contributor then faithfully implements.

13 moments

Every moment that names this one. Derived from the moments; this page keeps no list.

  1. opened CLAUDE.md and AGENTS.md and found two different rulebooks for one repositoryEach provider reads its own hand-edited file, nothing relates them, and which contract applies depends on which tool is open. cost: highcommon Why, and what to do →
  2. watched a session undo last week's decision, for the reason it was madeA decision whose reason lived in a conversation cannot be reviewed, only re-argued — by a worker with less information than the first one had. cost: highcommon Why, and what to do →
  3. found the rule for that directory in a README no session ever loadedA local rule is either in the always-loaded file, where every session pays for it, or beside the code, where nothing relates it to the path being edited. cost: highcommon Why, and what to do →
  4. read three roadmaps for one project and believed none of themA plan kept in prose is a snapshot, and every copy of it drifts on its own schedule; stored status is an assertion that stays true after the world moves. cost: mediumcommon Why, and what to do →
  5. found a rule everyone believed was enforced and nothing ever invokedEvery artefact of enforcement exists — the rule, the script, the test — and no path connects them, so the control is fiction. cost: highcommon Why, and what to do →
  6. found code that contradicted a decision the repository had written downThe decision was recorded and the implementation went the other way, because nothing relates a decision to the paths it governs. cost: highoccasional Why, and what to do →
  7. read a promise in the README that no test stood behindA sentence describing what the software does is written once and never connected to anything that would fail if it stopped being true. cost: highcommon Why, and what to do →
  8. shipped an interface change whose contract document still described the old oneA contract maintained by hand beside the code it describes goes stale on the first change that forgets it. cost: highcommon Why, and what to do →
  9. pasted a command from the documentation and watched it failExamples are written once, in prose, and nothing ever executes them again. cost: mediumcommon Why, and what to do →
  10. found the same thing explained three times, slightly differentlyEvery hand-maintained copy of a fact drifts on its own schedule, and a reader cannot tell which copy is the current one. cost: mediumconstant Why, and what to do →
  11. published a page that promised more than any test could supportPublic material is written by a different act from the code, so it drifts ahead of the behaviour and nothing brings it back. cost: highcommon Why, and what to do →
  12. spent the first hour in an unfamiliar repository working out what was normal hereWhat is conventional in a codebase is knowledge held by its regulars, so every arrival — human or machine — pays for it again. cost: mediumconstant Why, and what to do →
  13. reviewed a well-written contribution that broke a convention it had no way to discoverAssistants let anybody produce plausible contributions at volume; the conventions that make one correct are still only in the maintainers. cost: highcommon Why, and what to do →