The "skills file" pattern splits CLAUDE.md into task-scoped imports

The post, part two of a three-part SectorFlow Engineering series, diagnoses a common failure mode in Claude Code projects: a `CLAUDE.md` that starts small and useful but grows into a large, self-contradictory file as rules accumulate over weeks. Because the entire file loads every session, irrelevant rules consume tokens and add noise — a frontend color fix doesn't need the deployment runbook, and an API route change doesn't need chart color rules. Stale rules also silently override newer ones, causing hard-to-debug output problems.

The proposed fix is the "skills file pattern": `CLAUDE.md` becomes a table of contents, and the actual rules move into purpose-specific files under `.claude/`.

The proposed fix is the "skills file pattern": `CLAUDE.md` becomes a table of contents, and the actual rules move into purpose-specific files under `.claude/`. Five files are described — `core.md` (absolute constraints like model strings, API key rules, and cache TTLs, loaded every session), `design.md` (color tokens, chart types, component patterns, loading-state conventions, loaded for UI/frontend tasks), `infrastructure.md` (hosting config, environment variables, deployment rules, loaded for infra/CI tasks), `workflow.md` (ticket format, commit rules, token rules, division of labor, loaded every coding session), and `architecture.md` (ADRs, scaling thresholds, rejected technical decisions, loaded only when architecture topics arise). The import syntax in `CLAUDE.md` is standard `@path` references, with conditional files omitted for irrelevant tasks.

The post goes into particular depth on `core.md`, which is treated as a "constitution" — only verified facts and hard constraints belong there, never aspirations or wishful rules. `design.md` is highlighted for its "don't touch" rules (e.g., `TradingViewChart.jsx` is wrapper-only; `signals.js` has its own color system). The source text is truncated before the full discussion of `workflow.md`.

Key facts

1. 01The pattern replaces a monolithic CLAUDE.md with purpose-specific files under `.claude/`: `core.md`, `design.md`, `infrastructure.md`, `workflow.md`, and `architecture.md`.
2. 02`core.md` loads every session and is treated as a constitution — only verified facts and hard constraints, never aspirations.
3. 03`design.md` loads only for UI and frontend tasks; `infrastructure.md` only for infra and CI tasks; `architecture.md` only when architecture topics are explicitly referenced.
4. 04A UI task loads `core` + `design` + `workflow`; an infra task loads `core` + `infrastructure` + `workflow`.
5. 05`design.md` includes explicit 'don't touch' rules, such as `TradingViewChart.jsx` being wrapper-only and `signals.js` having its own color system.
6. 06The motivation is that a large, fully-loaded CLAUDE.md wastes tokens on irrelevant rules and allows stale rules to silently override newer ones.
7. 07The source text is truncated before the full discussion of `workflow.md`.

Topics