yonlu/yellowjacket
1
1
Fork 0
Code Issues 53 Pull Requests Actions Packages Projects Releases 13 Wiki Activity

Docs: CLAUDE.md is 4,000 lines; split the architecture narrative into docs/architecture/ #256

New Issue
Closed
opened 2026-09-25 12:25:37 +00:00 by yonlu · 2 comments
yonlu commented 2026-09-25 12:25:37 +00:00
Owner
Copy Link
Copy Source

CLAUDE.md is 4,046 lines / ~39k words, and it is loaded into every agent session in full (and AGENTS.md is a symlink to it). The Architecture section alone is ~3,300 lines of per-feature "why" narrative. Most of it is relevant only when touching that one area, but every session pays for all of it, and the rules that apply to every change (tracker workflow, commit grammar, codegen, test tiers) are buried.

Direction

  • Move the per-area "why" sections verbatim into docs/architecture/<area>.md (lifecycle, database, explore catalog, frontend shell/navigation, menus/touch/a11y, layout/responsive, events/performance, CI/release/packaging). Nothing is deleted; the arguments survive where someone working in that area will look.
  • Rewrite CLAUDE.md as a short entry point: project, tracker rules, commands, test tiers, package map, the cross-cutting rules as terse bullets, and a pointer per topic into docs/architecture/.
  • Extend scripts/skill-check.sh to scan docs/architecture/*.md, so moved make-target mentions stay checked.
  • Update in-code references that cite a CLAUDE.md section by name (main.go, e2e/specs/phone-search.spec.ts, progress-line.test.ts, check-css-literals.mjs) to the new location.
CLAUDE.md is 4,046 lines / ~39k words, and it is loaded into every agent session in full (and AGENTS.md is a symlink to it). The Architecture section alone is ~3,300 lines of per-feature "why" narrative. Most of it is relevant only when touching that one area, but every session pays for all of it, and the rules that apply to *every* change (tracker workflow, commit grammar, codegen, test tiers) are buried. ## Direction - Move the per-area "why" sections **verbatim** into `docs/architecture/<area>.md` (lifecycle, database, explore catalog, frontend shell/navigation, menus/touch/a11y, layout/responsive, events/performance, CI/release/packaging). Nothing is deleted; the arguments survive where someone working in that area will look. - Rewrite CLAUDE.md as a short entry point: project, tracker rules, commands, test tiers, package map, the cross-cutting rules as terse bullets, and a pointer per topic into `docs/architecture/`. - Extend `scripts/skill-check.sh` to scan `docs/architecture/*.md`, so moved make-target mentions stay checked. - Update in-code references that cite a CLAUDE.md section by name (`main.go`, `e2e/specs/phone-search.spec.ts`, `progress-line.test.ts`, `check-css-literals.mjs`) to the new location.
yonlu added the Kind/Documentation
Priority
Medium
3
 labels 2026-09-25 12:25:37 +00:00
yonlu self-assigned this 2026-09-25 12:25:41 +00:00
yonlu added the
Status
In Progress
 label 2026-09-25 12:25:41 +00:00
yonlu commented 2026-09-25 12:25:42 +00:00
Author
Owner
Copy Link
Copy Source

Starting work on this on docs/256-claude-md-split.

Starting work on this on `docs/256-claude-md-split`.
yonlu commented 2026-09-25 13:25:25 +00:00
Author
Owner
Copy Link
Copy Source

Approach changed after triage: the per-component sections were already duplicated as comments at the code (every issue number they cite also appears in a code comment), so they are deleted rather than moved to docs/architecture/. CLAUDE.md is rewritten as ~370 lines of broad engineering rules; the three declined decisions recorded nowhere else went to NOTES.md. NOTES.md staleness found along the way is #257.

Approach changed after triage: the per-component sections were already duplicated as comments at the code (every issue number they cite also appears in a code comment), so they are deleted rather than moved to docs/architecture/. CLAUDE.md is rewritten as ~370 lines of broad engineering rules; the three declined decisions recorded nowhere else went to NOTES.md. NOTES.md staleness found along the way is #257.
yonlu closed this issue 2026-09-27 01:45:21 +00:00
gitea-actions bot removed the
Status
In Progress
 label 2026-09-27 01:46:18 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Area/Design
Area/Downloads
Area/Explore
Area/Library-UI
Area/Metadata
Area/Packaging
Area/Player
Area/Queue
Area/Settings
Area/Shell-Nav
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
 Platform/Android
Platform/Desktop
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Medium
3
The priority is medium
Priority
Low
4
The priority is low
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
In Progress
Somebody is actively working on this right now
No labels Kind/Documentation
Priority
Medium
3
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
logan yonlu
No Assignees yonlu
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: yonlu/yellowjacket#256