Add CLAUDE.md and move AGENTS.md detail into linked docs - #15222
Add CLAUDE.md and move AGENTS.md detail into linked docs#15222mattmillerai wants to merge 1 commit into
Conversation
AGENTS.md had grown to 355 lines. Move the detailed architecture, model and node sections into docs/agents/ and keep the root file to the rules that should steer every change. All existing rules are preserved. Add CLAUDE.md as a regular file containing an @AGENTS.md import so Claude Code reads the same instructions. The previous attempt used a symlink, which broke updates and was reverted in 7cf4e78.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
🔍 Cursor Review — Consolidated panel
Triggered by @mattmillerai.
✅ No high-signal findings.
Panel: 8/8 reviewers contributed findings.
|
Verified the shim actually works rather than assuming it: ran a fresh Claude Code session in a checkout of this branch and asked it to answer from loaded instructions only, without reading or searching any files. It correctly recited the mascot rule and all five no-internet-requests bullets. So the one-line Also confirmed the file is a regular blob, not a symlink:
|
|
Warning Review limit reachedYou’ve reached a temporary PR review limit under our Fair Usage Limits Policy. Next review available in: 38 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (6)
Comment |
|
@mattmillerai how can we do if we wish to add more guidelines for agents considering the length restriction? |
@alexisrolland good question. The general rule of thumb we are following is that anything beyond the AGENTS.md file has diminishing returns. You can reference other doc paths within AGENTS.md for the agents to look at when needing to add additional context but overall the AGENTS file itself shouldn't exceed the length restriction (200 lines); thus it's an exercise in deciding the most important/concise rules up front and referencing other docs for the remainder. Let me know if that helps answer? |
3 participants
ELI-5
AGENTS.mdgot long enough that the rules at the bottom stop getting read. This moves the deep detail into three linked docs and keeps the root file to the rules that should steer every change. Nothing is deleted. It also adds aCLAUDE.mdso Claude Code actually sees these rules — it does not readAGENTS.md.Opening as a draft because both calls are yours: whether core wants the split at all, and whether it wants a Claude-specific file.
Problem
AGENTS.mdis 355 lines. Rules near the end compete with everything above them for attention.CLAUDE.md, notAGENTS.md, and does not fall back. Today it gets no project instructions in this repo.Change
AGENTS.md355 -> 167 lines. The detail moves to:docs/agents/architecture.md— architecture boundaries, state ownership, interface contractsdocs/agents/models.md— dtype/device/memory, optimized ops, model detection, autograddocs/agents/nodes.md— node conventions, inputs and outputsThe root keeps the rules that apply to any change: engineering style, the no-internet-requests guardrails, Python style, commit/review habits, and the highest-signal rule from each moved section with a link to the rest. A
Commandssection is new — lint and test invocations were not written down anywhere in this file.About the previous CLAUDE.md
#14757 added
CLAUDE.mdas a symlink, which broke updates and was reverted in 7cf4e78. This adds it as a regular file (git mode100644, not120000) containing a one-line@AGENTS.mdimport. No symlink, so the packaging path that broke before is not involved.Verification
AGENTS.mdverified present verbatim in the new set — scripted check, zero missing.CLAUDE.mdconfirmed a regular file, not a symlink.CODEOWNERSextended to cover/CLAUDE.mdand/docs/agents/, matching the existing/AGENTS.mdentry.Docs only — no code paths touched.
Open question
@alexisrolland asked about adding native-node design rules (title verbs, categories, singular/plural inputs, widget naming).
docs/agents/nodes.mdis the intended home for those — it can grow without pushing the root file back over the line.