docs: add nested AGENTS.md/CLAUDE.md symlinks for AI docs - #22135
Open
claude[bot] wants to merge 2 commits into
Open
docs: add nested AGENTS.md/CLAUDE.md symlinks for AI docs#22135claude[bot] wants to merge 2 commits into
claude[bot] wants to merge 2 commits into
Conversation
Create relative AGENTS.md symlinks to the relevant docs/ai guidance in subtrees that clearly own a topic, plus CLAUDE.md -> AGENTS.md in each (mirroring the root pattern), so agents working under those directories automatically load the guidance: - rust/ -> docs/ai/rust-dev.md - packages/contracts-bedrock/ -> docs/ai/contract-dev.md - op-acceptance-tests/ -> docs/ai/acceptance-tests.md - .circleci/ -> docs/ai/ci-config-review.md - .github/ -> docs/ai/ci-config-review.md Also list the new nested files in the root AGENTS.md Subdirectory Instructions section. Co-Authored-By: Claude <noreply@anthropic.com> Co-authored-by: Sebastian Stammler <seb@oplabs.co>
sebastianst
approved these changes
Jul 30, 2026
Co-Authored-By: Claude <noreply@anthropic.com> Co-authored-by: Sebastian Stammler <seb@oplabs.co>
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.
Requested by Sebastian Stammler · Slack thread
Before / After
Before: an agent editing files under e.g.
rust/op-revmnever seesdocs/ai/rust-dev.mdunless it happens to follow a link from the doc list in the rootAGENTS.md. That's how we got a recent change torust/op-revmmade without knowing the crate is first-party (migrated, not vendored).After: touching any file under a mapped directory auto-loads the relevant
docs/aidoc via a nestedCLAUDE.mdsymlink — the same mechanism the repo root already uses (CLAUDE.md→AGENTS.md). Non-Claude agents that look forAGENTS.mdin the working directory get the same content.How
For each mapped directory, a pair of relative symlinks:
<dir>/AGENTS.md→ the relevantdocs/ai/*.md<dir>/CLAUDE.md→AGENTS.md(mirrors the root pattern)Nested
CLAUDE.mdfiles stack, sorust/kona/CLAUDE.md(a real file) continues to apply on top of the newrust/link.Mapped
rust/docs/ai/rust-dev.mdpackages/contracts-bedrock/docs/ai/contract-dev.mdop-acceptance-tests/docs/ai/acceptance-tests.md.circleci/docs/ai/ci-config-review.md.github/docs/ai/ci-config-review.mdThe root
AGENTS.md"Subdirectory Instructions" section now lists these nested files.Deliberately left unmapped
writing-acceptance-tests.md— a directory can only symlink one doc;op-acceptance-tests/points atacceptance-tests.md, which links to the writing guide in its first paragraph (and it stays in the root doc list).ci-ops.md— about operating CI (diagnosing failures, reruns), not editing config in.circleci//.github/;ci-config-review.mdis the one aimed at edits to those directories.docker.md— Dockerfiles are scattered across the repo (cannon/,op-alt-da/,ops/docker/,rust/kona/docker/, ...), no single owning directory.dev-workflow.md,flake-prevention.md— cross-cutting; already linked from the root doc list and from the mapped docs.go-dev.md— Go services live in many top-level directories; no single subtree owns Go.derivation.md,execution-layer.md,fault-proofs.md— each spans Go + Rust + contracts across multiple subtrees.opgeth-decoupling.md,devfeatures.md,reth-update-review.md,dispute-game-investigation.md— task-specific playbooks/reference docs, not "you are editing files here" guidance.Note on Windows
On checkouts without
core.symlinksenabled, git degrades symlinks to one-line text files containing the target path — still readable as pointers, nothing breaks.Generated by Claude Code