Skip to content

Say who owns this file, and stop its voice leaking out of the repo - #174

Merged
parawanderer merged 2 commits into
mainfrom
docs/this-file-is-agent-written
Sep 2, 2026
Merged

Say who owns this file, and stop its voice leaking out of the repo#174
parawanderer merged 2 commits into
mainfrom
docs/this-file-is-agent-written

Conversation

@parawanderer

@parawanderer parawanderer commented Sep 2, 2026

Copy link
Copy Markdown
Owner

Two gaps in AGENTS.md, both invisible from inside it.

1. Nothing said the file is agent-owned

The header names its audience ("Rules for agents working on OpenTagViewer"). Rule 10 has one table row obliging you to add a rule when a constraint would cost somebody an afternoon. Neither says the file is maintained by agents, that no human reviews it, or that keeping it current is part of the work rather than a favour to whoever comes next.

An agent picking up work here had to infer that, and both halves are load-bearing:

  • if nobody is filtering, the agent writing a change is the only check on it
  • if the next agent starts from this file, anything omitted is an afternoon they pay for

That now sits directly under the title, where it is read before anything it governs, rather than in a rule two hundred lines down.

2. Nothing warned that the register does not travel

@parawanderer has not read this file, nor most of docs/, most docstrings, or most commit messages. Agents wrote them. So an agent reading them cannot tell the maintainer's house style from its own predecessors' output, and by default assumes the former.

That showed up this week. A review of #173 was drafted in this file's voice, argued at length with the reasoning as the payload, and its reader was a first-time contributor who wanted three line numbers and a fix. Right register, wrong reader.

The loop has nobody in it: agents write the docs, a later agent reads them as evidence of what the maintainer wants, and writes more of the same. Nothing in the repository contradicts that, because nothing in the repository is written by the maintainer.

Rule 16 states the boundary. The reason it argues at length is the same reason it says not to: the length is for an agent about to undo a constraint, and a person reading a review is not that.

Docs only, so no checks will run.

Two gaps, both invisible from inside.

**Nothing said the file is agent-owned.** The header names its audience -
"rules for agents working on OpenTagViewer" - and rule 10 has one table
row obliging you to add a rule when a constraint would cost somebody an
afternoon. Neither says the file is maintained by agents, that no human
reviews it, or that keeping it current is part of the work rather than a
favour. An agent picking up work here had to infer all of that, and both
inferences are load-bearing: if nobody is filtering, the agent writing is
the only check, and if the next agent starts from this file then anything
omitted is an afternoon they pay for.

That now sits directly under the title, where it is read before anything
it governs, rather than in a rule two hundred lines down.

**And nothing warned that the register does not travel.** @parawanderer
has not read this file, nor most of docs/, most docstrings, or most
commit messages. Agents wrote them. So an agent reading them cannot tell
house style from its own predecessors' output, and assumes the former.

That showed up this week. A review of #173 was drafted in this file's
voice - argued, at length, with the reasoning as the payload - and its
reader was a first-time contributor who wanted three line numbers and a
fix. Right register, wrong reader.

The loop has nobody in it: agents write the docs, a later agent reads
them as evidence of what the maintainer wants, and writes more of the
same. Nothing in the repository contradicts that, because nothing in the
repository is written by the maintainer.

Rule 16 states the boundary. The reason it argues at length is the same
reason it says not to: the length is for an agent about to undo a
constraint, and a person reading a review is not that.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@parawanderer
parawanderer force-pushed the docs/this-file-is-agent-written branch from 5b09d48 to 475e3cf Compare September 2, 2026 06:59
@parawanderer parawanderer changed the title Say that this file is agent-written, so it stops being copied Say who owns this file, and stop its voice leaking out of the repo Sep 2, 2026
Comment thread AGENTS.md Outdated
@parawanderer
parawanderer merged commit 76f7a05 into main Sep 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant