docs: point agents at the files humans already read - #64
Open
rickstaa wants to merge 1 commit into
Open
Conversation
rickstaa
force-pushed
the
rs/readme-coverage
branch
from
August 10, 2026 10:51
899dfcc to
6eefbd1
Compare
Nothing auto-loads README or CONTRIBUTING, so an agent works from the code and misses conventions that are written down. AGENTS.md is a pointer to both, and CLAUDE.md points at AGENTS.md so Claude Code's auto-load reaches the same file other tools read. It holds no rules of its own, which is what stops it becoming a second README that drifts. The two conventions the tooling cannot enforce move into CONTRIBUTING, where human contributors see them too: keeping the `# Livepeer:` markers accurate, and never committing media or weights. CONTRIBUTING also stops restating the axis list and links the table instead. It already disagreed with the README, which had gained a fifth axis, and a rule stated in two places is a rule that will disagree again. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
rickstaa
force-pushed
the
rs/agent-pointers
branch
from
August 10, 2026 10:51
53c97ba to
40439a8
Compare
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
1 participant
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.
An agent working in this repo reads the code and nothing else.
README.mdandCONTRIBUTING.mdare not auto-loaded by any tool, so conventions that are written down get missed — I skippedCONTRIBUTING.mdentirely across seven PRs in this repo and only opened it when challenged, after recommending a file containing rules it already had.AGENTS.mdis the vendor-neutral file Codex and Cursor look for;CLAUDE.mdis what Claude Code auto-loads. So the content lives inAGENTS.mdandCLAUDE.mdis one line pointing at it.AGENTS.mdholds no rules of its own, on purpose. It says these are teaching examples, then sends you to CONTRIBUTING for how to work here and README for the axis table that decides whether a new example belongs. The moment it starts holding facts it becomes a second README that drifts, and the pointer stops being trusted.The two conventions the tooling can't enforce move into CONTRIBUTING
Not into the agent file — human contributors need them equally:
# Livepeer:markers accurate. They are a user-facing device: the README tells readers to grep them to see an example's whole Livepeer surface. A change that adds or removes a call has to renumber them and update the docstring, or the thing the README promises stops being true. feat(vllm): register single-shot so the call pays as it runs #59 is the live case, wherevllmwent from three calls to two.CONTRIBUTING stops restating the axis list
It said the repo "covers each value of the example axes (registration, mode, transport, pricing) once" while the README's table is the actual source of truth. #63 added a fifth axis to the README and the two immediately disagreed — with the stale copy sitting in the file contributors are pointed at. It now links the table instead.
Also sharpens one README line: the
# Livepeer:markers are numbered in the order they happen, which is what makes them readable as a sequence rather than scattered labels.Stacked on #63.
🤖 Generated with Claude Code