docs: link the guides instead of importing them - #482
Merged
Conversation
`@CONTRIBUTING.md` in an agents file is an import: the whole file is pulled into context at the start of every session, whether the task touches it or not. CONTRIBUTING.md is 595 lines here, which is around six thousand tokens spent before anyone has said anything. A markdown link is the lazy form — the agent opens it when the work calls for it, and can be pointed at one section rather than the lot. README.md already referred to it this way, so the two files disagreed about how to cite the same document. AGENTS.md disagreed with itself as well, naming docs/methodology.md as an import in one paragraph and as plain text three sections later. CLAUDE.md keeps its trailing @AGENTS.md. That one is deliberate: the file exists so Claude Code finds AGENTS.md, and importing it is the whole job. The prose mention above it no longer imports a second time. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c
Codecov Report✅ All modified and coverable lines are covered by tests. @@ Coverage Diff @@
## main #482 +/- ##
=======================================
Coverage 99.94% 99.94%
=======================================
Files 484 484
Lines 22877 22877
=======================================
Hits 22865 22865
Misses 12 12 Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
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.
What
Replaces
@CONTRIBUTING.mdin the agent files with[CONTRIBUTING.md](CONTRIBUTING.md).Why
@filein an agents file is an import, not a reference. golangci-lint aside, Claude Code pulls the whole file into context at session start whether or not the task goes near it.That is roughly six thousand tokens spent in gohai before the first instruction is read.
A markdown link is the lazy form: the agent opens it when the work calls for it, and the link can point at one section —
CONTRIBUTING.md#before-you-start— instead of the whole document.Two inconsistencies this also settles
README.mdalready used[CONTRIBUTING.md](CONTRIBUTING.md), so the two files disagreed about how to cite the same document.AGENTS.mddisagreed with itself:docs/methodology.mdwas an import in the opening paragraph and plain backticks three sections later.What is deliberately unchanged
CLAUDE.mdkeeps its trailing bare@AGENTS.md. That import is the file's entire purpose — it exists so Claude Code finds AGENTS.md, which is 55 lines and always relevant. Only the prose mention above it, which imported the same file a second time, became a link.🤖 Generated with Claude Code
https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c