Say who owns this file, and stop its voice leaking out of the repo - #174
Merged
Conversation
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
force-pushed
the
docs/this-file-is-agent-written
branch
from
September 2, 2026 06:59
5b09d48 to
475e3cf
Compare
parawanderer
commented
Sep 2, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
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.