bc-rules-organizer

Caution

One giant CLAUDE.md loaded for every file is expensive. Rules for React components load even when Claude is editing SQL migrations. Claude Code supports paths: frontmatter in .claude/rules/*.md to scope rules to file patterns — but setting it up correctly requires knowing the right fields, quoting conventions, and dedup logic. Bug #16299: all rules still load at session start regardless of paths:, so keep files lean.

Tip

Invoke bc-rules-organizer to extract, split, and optimize rules files. The agent reads any source (CLAUDE.md, docs, code comments), distributes rules by path pattern, runs the 3-Check Dedup Protocol, and finishes with brewtools:text-optimize on every created file. See the rules skill for KNOWLEDGE-to-rules conversion.

Quick reference

FieldValue
Modelsonnet
ToolsRead, Write, Edit, Glob, Grep, Bash, Skill
Skills usedbrewtools:text-optimize
Permission modeacceptEdits
Triggers”organize rules”, “path-specific rules”, “extract rules”, “split CLAUDE.md”

When to use

  • Split a bloated CLAUDE.md — extract sections into path-scoped rule files and replace with @path/to/rule.md references
  • Scope rules to file types — React rules only for src/components/**/*.tsx, SQL rules only for **/*Repository*
  • Deduplicate across files — merge semantically similar entries, eliminate cross-file antonym pairs
  • Refactor existing rules — add missing paths: frontmatter, fix unquoted globs, enforce table format standards
  • Consolidate code comments — extract actionable rules scattered in source files into .claude/rules/

Examples

# Extract rules from CLAUDE.md and distribute by path pattern
"organize rules from CLAUDE.md"
"extract rules from CLAUDE.md"
# Create path-specific rules for a module
"path-specific rules for src/components"
"create rules file for bq-core module"
# Refactor and deduplicate existing rules
"split CLAUDE.md into rule files"
"optimize .claude/rules/ — merge duplicates, add paths frontmatter"

Flow

  1. Analysis — ask at most 2 questions

    Identifies the source file (CLAUDE.md, docs, code) and any explicit path patterns. If not provided, auto-detects from project structure. Reads existing .claude/rules/ files to map what’s already covered.

  2. Extraction — group by scope

    Classifies every rule as anti-pattern (avoid) or best practice. Groups rules into logical scopes: component rules, API rules, test rules, build config, module-level. Each group maps to a target file and a paths: pattern.

  3. 3-Check Dedup Protocol

    Before writing any entry: (1) within-file similarity — skip if >70% overlap, merge if 40–70%; (2) cross-file antonym — “don’t do X” in avoid + “do not-X” in best-practice = keep avoid entry only; (3) CLAUDE.md duplicate — concept already in CLAUDE.md → skip entirely. Source column value “CLAUDE.md” is forbidden.

  4. File creation — standard structure

    Creates avoid.md / best-practice.md for global rules (no paths:) and {‘{prefix}’}-avoid.md / domain files with quoted glob patterns. Max 20 rows per table — splits into specialized files if exceeded. All entries numbered sequentially.

  5. Optimization — brewtools:text-optimize on every file

    Applies token-efficiency transforms: tables over prose, abbreviations, lazy documentation links (> Details: file.md) instead of inline content, remove filler. Final files are dense and LLM-efficient.

Frontmatter reference, file naming, and output report

Supported fields: only paths: — globs, alwaysApply, description are not valid Claude Code fields.

---
paths:
  - "src/components/**/*.tsx"
  - "src/components/**/*.ts"
  - "!src/components/**/*.test.tsx"
---

Quoting rules — patterns must be quoted strings, array format required, brace expansion needs quotes: "{src,lib}/**".

File naming:

ConventionExamplesUse for
avoid.md, best-practice.mdGlobal, no paths:Pure anti-pattern or practice collections
{prefix}-avoid.md, {prefix}-best-practice.mdtest-avoid.md, sql-best-practice.mdPath-scoped by tech or type
Descriptive domain filereact-components.md, bq-core.mdMixed rules for a specific module/stack

Common prefixes: test, sql, api, security, performance, kotlin, java, react.

Table formats (authoritative):

Avoid table: | # | Avoid | Instead | Why | Best practice table: | # | Practice | Context | Source |

Both require sequential # column, max 20 rows, “CLAUDE.md” forbidden as Source value.

Pattern examples:

PatternMatches
"**/*.kt"All Kotlin files
"src/main/**/*.java"Java in src/main
"bq-core/**/*"All files in bq-core
"!**/*.test.ts"Exclude test files
"*.md"Root markdown files only

Example transformation:

Input CLAUDE.md prose section → Output .claude/rules/react-components.md:

---
paths:
  - "src/components/**/*.tsx"
  - "src/components/**/*.ts"
---

# React Component Rules

| # | Avoid | Instead | Why |
|---|-------|---------|-----|
| 1 | `export default` | `export function Name()` | Explicit imports, easier tracking |
| 2 | Inline styles | Separate `*.styles.ts` | Separation of concerns |

Output report format — always returned as final response:

## Rules Organization Complete

### Created/Updated Files
| File | Paths | Change |
|------|-------|--------|
| `react-components.md` | `src/components/**/*` | New |
| `test-avoid.md` | `**/*.test.*` | Updated |

### Stats
| Metric | Value |
|--------|-------|
| Files created | 2 |
| Files updated | 1 |
| Total rules | 18 |
📄

Rules skill

Convert KNOWLEDGE.jsonl entries into structured rules files — complementary to bc-rules-organizer.

🔗

GitHub source

Agent definition, capabilities, and workflow phases.

🚀

Brewcode overview

All brewcode agents, skills, and hooks in one place.

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.