Add CLAUDE.md as a symlink to AGENTS.md - #2963
Merged
Merged
Conversation
Claude Code automatically loads `CLAUDE.md` from the repository root into an agent's context at session start. It does not load `AGENTS.md`. This repository has only `AGENTS.md`, so its conventions were never in context automatically: an agent working here reconstructed them from memory of past review comments, or simply did not know them. That is not hypothetical. It produced review churn on a recent PR over the import rules in the "Imports" section, and those rules are exactly the ones tooling cannot catch: `imports_granularity` is nightly-only and unstable, and rustfmt deliberately leaves `#[cfg]`-gated imports untouched, so `cargo fmt`, clippy and the test suite all pass green on non-compliant imports. Human review was the only detector. The same omission meant the contribution gate at the top of this file was never run. A symlink keeps `AGENTS.md` the single source of truth, so the two files cannot drift, and every other agent tool that reads `AGENTS.md` by name is unaffected. The repository already tracks symlinks (`zcash_client_backend/proto/*.proto`), so this needs no new tooling support. One caveat: a checkout without symlink support, which on Windows requires `core.symlinks` and developer mode, materializes `CLAUDE.md` as a plain file whose contents are the string `AGENTS.md`. That degrades gracefully, since the file still names the document to read. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
dannywillems
commented
Aug 12, 2026
dannywillems
left a comment
dannywillems
left a comment
Contributor
Author
There was a problem hiding this comment.
self-ACK 6ee02e4
There are conventions that we should introduce over time. It seems that we don't use the full power of AI agents/skills/rules. Also, the AGENTS.md seems to be too large according to conventions suggested by Anthropic.
pacu
self-requested a review
August 12, 2026 17:42
pacu
approved these changes
Aug 12, 2026
pacu
left a comment
pacu
left a comment
Collaborator
There was a problem hiding this comment.
My Agents.md PR originally had this but for some reason I don't recall it was removed.
thanks Danny
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
2 participants
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
Adds
CLAUDE.mdat the repository root as a symlink toAGENTS.md.Why
Claude Code automatically loads
CLAUDE.mdfrom the repository root into an agent'scontext at session start. It does not load
AGENTS.md. Since this repository has onlyAGENTS.md, its conventions were never in context automatically: an agent working herereconstructed them from memory of past review comments, or simply did not know them.
That is not hypothetical. It produced avoidable review churn on #2962 over the rules in
the "Imports" section, and those are precisely the rules tooling cannot catch:
imports_granularityis nightly-only and unstable, and rustfmt deliberately leaves#[cfg]-gated imports untouched, socargo fmt, clippy and the test suite all pass greenon non-compliant imports. Human review was the only detector. The same omission meant the
contribution gate at the top of
AGENTS.mdwas never run.The effect reaches subagents too, which matters here because much agent work is delegated:
per the Claude Code documentation, every subagent except the built-in Explore and Plan
loads the project
CLAUDE.md. Today they inherit nothing fromAGENTS.md.Why a symlink
It keeps
AGENTS.mdthe single source of truth, so the two cannot drift, and every otheragent tool that reads
AGENTS.mdby name is unaffected. This repository already trackssymlinks (
zcash_client_backend/proto/*.proto), so it needs no new tooling support.Caveat
A checkout without symlink support, which on Windows requires
core.symlinksanddeveloper mode, materializes
CLAUDE.mdas a plain file whose contents are the stringAGENTS.md. That degrades gracefully, since the file still names the document to read.Worth noting for a follow-up: the Claude Code documentation suggests keeping
CLAUDE.mdunder about 200 lines, and warns that longer files still load in full but may reduce
adherence.
AGENTS.mdis 667 lines. If that proves to be a problem in practice, thedocumented alternative is
.claude/rules/withpaths:frontmatter, which loadsconventions only when matching files enter context. This PR deliberately does not do that,
since it would split the source of truth.
🤖 Generated with Claude Code