ref(agents): compact AGENTS.md files and defer deep guides to skills - #121469
Merged
Conversation
Move the ~300-line React Testing Guidelines section out of the always-loaded static/AGENTS.md and into an on-demand react-testing skill. static/AGENTS.md now carries a short pointer. Frees always-on frontend context (static/AGENTS.md 592 -> 287 lines) while preserving the full guide via progressive disclosure.
…ventions skill Move the Options System, Logging, Tracing/Spans, and Metrics Tags sections (~110 lines of task-specific code walkthroughs) out of the always-loaded src/AGENTS.md into an on-demand backend-conventions skill. src/AGENTS.md 449 -> 338 lines.
…ing skill Move the ~110-line Frontend API Calls / TanStack Query type-inference / response-headers guidance out of the always-loaded static/AGENTS.md into an on-demand frontend-data-fetching skill. static/AGENTS.md 287 -> 178 lines.
Tighten always-on backend guidance: reduce IDOR, serializer N+1, composite-index, silo, and integration sections to short rules with pointers to existing skills (django-access-review, sentry-security, django-perf-review, hybrid-cloud-*, cell-architecture, generate-migration, document-api-endpoint). Drop redundant prose (e.g. 'Why detail?'). src/AGENTS.md 338 -> 170 lines.
Move the Avatars/Disclosure/Icons/Images worked examples out of static/AGENTS.md into the design-system skill; keep terse always-on bullets plus a pointer. static/AGENTS.md 178 -> 77 lines (now under the 100-line ceiling).
…o skills Move git-worktree setup and 'make reset-db' into the setup-dev skill and point DB/migration commands at the setup-dev and generate-migration skills. Compress the venv and devserver-log prose. Preserve all cross-agent guidance (Context-Aware Loading, Agent Skills conventions) since this repo supports many agents, not just Claude. Root AGENTS.md 203 -> 140 lines (now under the 200-line adherence target).
… description The skill now covers 'make reset-db' and the per-worktree devenv/.venv step; add matching triggers so they're discoverable. Scoped to environment setup — generic worktree management stays with the worktree skill.
natemoo-re
force-pushed
the
nm/agents/context-opt
branch
from
August 6, 2026 18:23
df36003 to
31bcb34
Compare
billyvg
approved these changes
Aug 6, 2026
natemoo-re
enabled auto-merge (squash)
August 6, 2026 18:57
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
natemoo-re
commented
Aug 6, 2026
github-actions
Bot
added
the
Scope: Frontend
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
3 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.
Recommend reviewing commit-by-commit to see exact path of content shifting from system prompt -> skills, see #121311 for another recent trim
Summary
Audit and refactor of the repo's
AGENTS.md/CLAUDE.mdsetup to reduce always-loaded agent context and defer task-specific procedures to on-demand skills, following current prompt-engineering guidance (progressive disclosure; "AGENTS.md = README for agents, reference don't copy"; keep always-on files short).Our own
agents-mdskill targets ≤100 lines per file and Claude's memory docs target <200 lines; the files had drifted well past both. Deep, task-specific how-to (RTL testing guide, TanStack Query essays, logging/tracing/metrics walkthroughs) was paying full context cost on every unrelated task. This moves that content into skills that load only when relevant.Result
Always-loaded AGENTS.md context reduced ~64% (1381 → 495 lines); every file now under the 200-line target:
AGENTS.md(root)src/AGENTS.mdstatic/AGENTS.mdtests/AGENTS.mdNo information lost — deep content moved into skills (progressive disclosure) with one-line pointers left behind.
New skills
react-testing— full RTL guide (extracted fromstatic/)backend-conventions— logging (LOG005/LOG011), tracing/spans, metrics tag cardinality, options system (fromsrc/)frontend-data-fetching— TanStack Query /apiOptions, type-inference rules, response headers (fromstatic/)feature-flags— FlagPole register/check/test/rollout (from root)Deferred to existing skills (pointers, no new skills)
django-access-review,sentry-securitydjango-perf-reviewhybrid-cloud-*,cell-architecturegenerate-migration,setup-devdesign-systemdocument-api-endpoint