Skip to content

docs(claude): move ADR index and apply loop to lazy skills - #108

Merged
ThatRendle merged 1 commit into
mainfrom
chore/claude-md-lazy-loading
Jul 31, 2026
Merged

docs(claude): move ADR index and apply loop to lazy skills#108
ThatRendle merged 1 commit into
mainfrom
chore/claude-md-lazy-loading

Conversation

@ThatRendle

Copy link
Copy Markdown
Contributor

Why

The root CLAUDE.md loads 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

Content New home Why
ADR summary table (35 rows) .claude/skills/adr-index/ Reference index over docs/adrs/; only the one-line skill description stays resident
OpenSpec apply-loop mechanics .claude/skills/openspec-apply/ DEVLOG conventions, pre-flight, block carving, worker/reviewer loop, gates, supervisor review, done criteria — only needed during /opsx:apply
Pi-specific instructions .pi/AGENT.md Addressed to a different agent; now sits next to the .pi/skills and .pi/prompts it governs

What stays resident (deliberately)

Nothing safety-critical was moved behind lazy loading:

  • The binding ADR rule — "Accepted ADRs must not be contradicted … write a superseding ADR" — and the docs/adrs/ADR-NNN-<slug>.md convention.
  • The full Roles section, including "the main thread never writes feature code" and the reviewer-vs-supervisor distinction.
  • The complete Stop and ask list.
  • The standing Rules subsection.
  • Out of scope for V1 in full.
  • The TreatWarningsAsErrors prohibition.

CLAUDE.md states that the resident roles and prohibitions take precedence over the openspec-apply skill, 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 the daemon workspace), so those were dead instructions that no session could act on.
  • Derivable lines in ## Build and test and ## Code style: the standard dotnet build / dotnet test invocations, and the C# conventions an analyzer already enforces (PascalCase/camelCase, the I prefix, file-scoped namespaces). Kept the non-obvious ones — the env -u MEKO_API_KEY make test gotcha, openspec validate <slug> --strict, cancellationToken last-and-named, record vs class, and "no var when the type isn't obvious".

Notes

  • No code changes; docs and agent-config only.
  • Not an OpenSpec change — hence chore/ rather than change/.

🤖 Generated with Claude Code

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>
@ThatRendle
ThatRendle merged commit ac23f64 into main Jul 31, 2026
5 checks passed
@ThatRendle
ThatRendle deleted the chore/claude-md-lazy-loading branch July 31, 2026 15:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant