docs(claude): move ADR index and apply loop to lazy skills - #108
Merged
Conversation
Trim the always-loaded root CLAUDE.md from 36,175 to 11,380 chars
(~9,000 to ~2,800 est. tokens per session) by moving reference
material behind lazy loading and deleting dead guidance.
- ADR summary table -> .claude/skills/adr-index. The binding rule
("ADRs are binding; supersede via a new ADR") and the "new ADRs go
in docs/adrs/ADR-NNN-<slug>.md" convention stay resident.
- OpenSpec apply-loop mechanics (DEVLOG conventions, pre-flight,
block carving, worker/reviewer loop, gates, supervisor review,
done criteria) -> .claude/skills/openspec-apply. The Roles section
including "the main thread never writes feature code", the full
"Stop and ask" list, and the standing Rules stay resident and take
precedence over the skill.
- Pi-specific instructions -> .pi/AGENT.md, next to the .pi/skills
and .pi/prompts they govern; CLAUDE.md keeps a pointer.
- Drop the "## serena" section: serena is not a configured MCP
server for this repo (it is registered only under the daemon
workspace), so those were dead instructions.
- Trim Build and test / Code style down to the non-derivable parts:
keep the env -u MEKO_API_KEY test gotcha, openspec validate
--strict, the TreatWarningsAsErrors prohibition, and the C#
conventions that differ from language defaults; drop the standard
dotnet invocations and the defaults an analyzer already enforces.
No behavioural rules were removed - only relocated or deleted where
the target no longer exists.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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
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.
Why
The root
CLAUDE.mdloads into every session. At 36,175 chars it was costing ~9,000 tokens per session, and a large share of it was reference material only needed occasionally — plus one section pointing at tooling this repo doesn't have.This trims it to 11,380 chars (~2,800 est. tokens, a ~6,200-token saving per session) without dropping any behavioural rule.
What moved
.claude/skills/adr-index/docs/adrs/; only the one-line skill description stays resident.claude/skills/openspec-apply//opsx:apply.pi/AGENT.md.pi/skillsand.pi/promptsit governsWhat stays resident (deliberately)
Nothing safety-critical was moved behind lazy loading:
docs/adrs/ADR-NNN-<slug>.mdconvention.TreatWarningsAsErrorsprohibition.CLAUDE.mdstates that the resident roles and prohibitions take precedence over theopenspec-applyskill, preserving the original "this subsection is authoritative" intent.What was deleted
## serena— serena is not a configured MCP server for this repo (it's registered only under thedaemonworkspace), so those were dead instructions that no session could act on.## Build and testand## Code style: the standarddotnet build/dotnet testinvocations, and the C# conventions an analyzer already enforces (PascalCase/camelCase, theIprefix, file-scoped namespaces). Kept the non-obvious ones — theenv -u MEKO_API_KEY make testgotcha,openspec validate <slug> --strict,cancellationTokenlast-and-named,recordvsclass, and "novarwhen the type isn't obvious".Notes
chore/rather thanchange/.🤖 Generated with Claude Code