Skip to content

docs(bc-cmrs): move CLAUDE.md's domain rules into path-scoped .claude/rules files - #472

Merged
gitrgoliveira merged 2 commits into
mainfrom
worktree-bridge-cse_01WKu23VAJUZQ91ZA9nxeWns
Oct 13, 2026
Merged

gitrgoliveira merged 2 commits into
mainfrom
worktree-bridge-cse_01WKu23VAJUZQ91ZA9nxeWns

Conversation

@gitrgoliveira

Copy link
Copy Markdown
Owner

Summary

  • CLAUDE.md drops from 240 KB to 69 KB. The detailed domain rulings move, unchanged, into seven path-scoped files under .claude/rules/. Claude Code loads each file only when a session reads or edits code in that file's area.
  • Measured saving: a fresh headless session's first call fell from 135k to 72k tokens of context. Both runs used the same prompt and the same user settings; the only difference is this CLAUDE.md. Every later call in every session and every subagent starts from the smaller base.
  • CLAUDE.md keeps a pointer table naming which file governs which area. It also notes that a Serena call does not load these files. A global guard outside this repo refuses a Serena edit in an area until that agent has read its rule file.
  • AGENTS.md and GEMINI.md point to .claude/rules/, since only Claude Code loads those files on its own.
  • "Keep the orchestrating session small" now says subagents default to Sonnet, and to pass model: "opus" for implementers and the final review round.

Why

Bead bc-cmrs: CLAUDE.md was about 60k tokens, and every model call of every session and subagent loaded it. The bead suggested docs/agents/ or .claude/rules/. The rules went to .claude/rules/, not docs/, because docs/ is the public MkDocs site and these rules are full of bead ids and internal references. A plain @import would not have helped, because Claude Code loads imports at launch.

Files changed

File What
CLAUDE.md Domain sections moved out; pointer table; subagent model line; corrected size note
.claude/rules/draw-and-seeding.md Tree, seeding, pool creation, tree-aware seeding, pool bout ids
.claude/rules/match-results-and-marks.md The whole "Match results and marks" section, plus operator labels, match colours, and clearing a mark
.claude/rules/match-writes.md "Merge changes, never drop" and "Write refusal and the clock frame"
.claude/rules/teams-and-lineups.md Team credit, bout row names, lineup vacancy, lineups and kachinuki, carried lineups, lineup saves, member stamps, migration, drafts
.claude/rules/eligibility-and-queue.md Competitor eligibility, send back to queue
.claude/rules/store.md Startup writability check, store transactions, cache invalidation, competition directory creation
.claude/rules/workbook.md Excel layout, team block bout rows, workbook owners, Representative Bouts sheet, workbook construction
AGENTS.md, GEMINI.md A "Domain rules" pointer to .claude/rules/

Test plan

  • make go/test passes (lint + security scan + tests)
  • New/updated unit tests cover the change: not applicable, no code changed. TestNoDefaultWin* passes with the new files tracked.
  • Manual browser verification: not applicable, no web-mobile/ or web/ change
  • Screenshots added above: not applicable, no UI change
  • Docs updated under docs/: not applicable, no user-facing change
  • Docs screenshots and videos recaptured: none changed
  • No new console errors or warnings: not applicable
  • Every non-blank line of the old CLAUDE.md is present in the new CLAUDE.md or one of the rule files (script check: 0 missing)
  • References that crossed the split now name the file they point to
  • The guard refuses a Serena edit on internal/engine/match_merge.go until .claude/rules/match-writes.md has been read; checked in a live session and with fake hook inputs

Closes bc-cmrs

🤖 Generated with Claude Code

…/rules files

CLAUDE.md goes from 240 KB to 69 KB; a fresh session's first call drops from
135k to 72k tokens. The rulings move verbatim into seven files that Claude Code
loads only when a matching file is read or edited, with a pointer table in
CLAUDE.md and AGENTS.md/GEMINI.md. Subagents now default to Sonnet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings October 12, 2026 22:13

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings October 12, 2026 22:16

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@gitrgoliveira
gitrgoliveira merged commit d228abe into main Oct 13, 2026
13 checks passed
@gitrgoliveira
gitrgoliveira deleted the worktree-bridge-cse_01WKu23VAJUZQ91ZA9nxeWns branch October 13, 2026 07:05
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.

2 participants