docs: compact CLAUDE.md by offloading restated detail to ADRs / docs/ci.md #151

New issue

Closed

opened 2026-06-19 22:10:09 +00:00 by james · 0 comments

james commented

2026-06-19 22:10:09 +00:00

Owner

Problem

CLAUDE.md had grown to 199 lines, several of which restated detail that
already lives canonically in linked ADRs or docs/ci.md. Because Claude
reads CLAUDE.md on every turn, every restated paragraph is paid for
again and again in context budget — and is a second source of truth that
can drift from the canonical one.

What to change

Compact the following passages to "rule + pointer" form. Every detail
dropped is one click away in an already-linked ADR or docs/ci.md — no
information is lost.

Section	Issue	Action
Auth public-routes enumeration	Lists routes that `lib/auth/public-routes.ts` already enumerates and will drift	Keep the rule, drop the enumeration
Themes bullet	Enumerates the full DS token alias list — ADR-0023 + the CSS files are canonical	Keep the rule + pointer; drop the token list
Test coverage bullet	Restates targets that ADR-0019 owns	Keep "soft signal, not a gate" + pointer
Package-age bullet	Restates mechanics ADR-0022 + `docs/ci.md` own	Keep the rule + accept-via-`.dep-policy.json` + pointer
Pin actions by SHA	YAML example is illustrative, not load-bearing	One-sentence rule + reason
Install scripts	Restates mechanics `docs/ci.md` owns	Keep the rule + pointer
Releases bullet	Mechanics already in `docs/ci.md` + ADR-0014	Keep the trigger + signing facts; drop URL / Cloudflare / pre-release minutiae
Conventional Commits	Type list + pre-#16 history is in `docs/ci.md`	Keep the format + enforcement points + pointer

Out of scope

Collapsing the whole "Working in this repo" CI-policy block to a
single pointer was considered but rejected — the headline rules are
load-bearing enough that surfacing them in CLAUDE.md is worth the
lines.
No content changes to ADRs or docs/ci.md are needed; they already
own the detail being dropped.

Acceptance

CLAUDE.md is shorter (~165 lines vs. 199).
All hard rules, stack defaults, orientation pointers, and
out-of-scope items remain.
Every section that was compacted still links to its canonical
source.

## Problem `CLAUDE.md` had grown to 199 lines, several of which restated detail that already lives canonically in linked ADRs or `docs/ci.md`. Because Claude reads `CLAUDE.md` on every turn, every restated paragraph is paid for again and again in context budget — and is a second source of truth that can drift from the canonical one. ## What to change Compact the following passages to "rule + pointer" form. Every detail dropped is one click away in an already-linked ADR or `docs/ci.md` — no information is lost. | Section | Issue | Action | | --- | --- | --- | | Auth public-routes enumeration | Lists routes that `lib/auth/public-routes.ts` already enumerates and will drift | Keep the rule, drop the enumeration | | Themes bullet | Enumerates the full DS token alias list — ADR-0023 + the CSS files are canonical | Keep the rule + pointer; drop the token list | | Test coverage bullet | Restates targets that ADR-0019 owns | Keep "soft signal, not a gate" + pointer | | Package-age bullet | Restates mechanics ADR-0022 + `docs/ci.md` own | Keep the rule + accept-via-`.dep-policy.json` + pointer | | Pin actions by SHA | YAML example is illustrative, not load-bearing | One-sentence rule + reason | | Install scripts | Restates mechanics `docs/ci.md` owns | Keep the rule + pointer | | Releases bullet | Mechanics already in `docs/ci.md` + ADR-0014 | Keep the trigger + signing facts; drop URL / Cloudflare / pre-release minutiae | | Conventional Commits | Type list + pre-#16 history is in `docs/ci.md` | Keep the format + enforcement points + pointer | ## Out of scope - Collapsing the whole "Working in this repo" CI-policy block to a single pointer was considered but rejected — the headline rules are load-bearing enough that surfacing them in `CLAUDE.md` is worth the lines. - No content changes to ADRs or `docs/ci.md` are needed; they already own the detail being dropped. ## Acceptance - `CLAUDE.md` is shorter (~165 lines vs. 199). - All hard rules, stack defaults, orientation pointers, and out-of-scope items remain. - Every section that was compacted still links to its canonical source.

james referenced this issue from a commit

2026-06-19 22:12:29 +00:00

docs: compact CLAUDE.md by offloading restated detail (#151)

james referenced this issue from a pull request that will close it,

2026-06-19 22:16:11 +00:00

docs: compact CLAUDE.md by offloading restated detail (#151) #152

james closed this issue

2026-06-19 22:19:05 +00:00

james referenced this issue from a commit

2026-06-19 22:19:06 +00:00

Merge pull request 'docs: compact CLAUDE.md by offloading restated detail (#151)' (#152) from 151-compact-claudemd into main