SectorFlow Engineering Series · Part 2 of 3 · Read Part 1 first: Token Efficiency in Claude Code
How we stopped appending to CLAUDE.md and started importing only what we need.
June 2026 · SectorFlow Engineering
In this seriesPart 1:[Token Efficiency in Claude Code](start here).[Part 3: Picking Models and Tools]— the MCPs we tried, refused, and why.
If you use Claude Code for a while you'll probably land where we did: a CLAUDE.md
that got too big and too self-contradictory to trust.
It starts fine. You write down the basics — what the app does, where the server lives, what the API looks like. Then something breaks. Claude picks the wrong model string, or makes a chart without the right color, or ignores a cache rule you mentioned in passing three weeks ago. So you write the rule down and append it. Reasonable.
And it works for a while. Then the file's big, the week-two rules are sitting on top of the week-six rules, and when two of them disagree — they will, because requirements move and old notes go stale — the model either reconciles them into mush or just picks one. You spend an hour debugging output before you realize the rule you thought was active got overridden by something you wrote months ago and forgot about.
The bigger issue: the whole file loads every session, no matter what you're doing. A color fix on the frontend doesn't need the deployment runbook. An API route change doesn't need the chart color rules. Every line that isn't relevant is costing tokens and adding noise.
We thought about how to fix this without just deleting the stuff we'd need again later, and ended up with what we call the skills file pattern. Split the context into separate files by purpose, import only what the task needs.
CLAUDE.md
stops being the rulebook and becomes a table of contents. The actual rules move into separate files under .claude/
.
| File | What it owns | When it loads |
|---|---|---|
core.md |
||
| Absolute constraints: model strings, API key rules, cache TTLs, data contracts | Every session — the foundational constraints | |
design.md |
||
| Color tokens, chart types, component patterns, -state conventions | UI and frontend tasks only | |
infrastructure.md |
||
| Hosting config, environment variables, deployment rules, automator wiring | Infrastructure and CI tasks | |
workflow.md |
||
| Ticket format, commit rules, token rules, division of labor | Every coding session | |
architecture.md |
||
| ADRs, scaling thresholds, rejected technical decisions | Architecture reviews and new integrations |
The import syntax in CLAUDE.md
is nothing special:
@sector-dashboard/.claude/core.md
@sector-dashboard/.claude/design.md
@sector-dashboard/.claude/workflow.md
(infrastructure.md and architecture.md load only when the task references them)
So a UI task loads core + design + workflow. An infra task loads core + infrastructure + workflow. architecture.md
only shows up if someone actually asks about a scaling decision or an ADR. The context stays small and stays on topic.
core.md
is the one file that loads every single session, so everything in it has to be true and currently enforced. We treat it like a constitution. Stable, authoritative, never wishful.
Two kinds of things go in:
Don't put aspirations in core.md. "We should try to…" or "ideally the model would…" — that's workflow.md material. core.md is only for things that are true right now. The moment you put a hope in there, reality eventually contradicts it and now you've got a lie sitting in your most-trusted file.
Every hex value, every chart-type assignment, every -state pattern goes in design.md
. Three reasons it pays off:
design.md
. No component files had to change just to record the rule.design.md
is also where we list what not to touch. TradingViewChart.jsx
is wrapper-only. signals.js
has its own color system and must not get the new --sf-
variables. Those "don't" rules matter as much as the conventions do.
This is the file that matters most day to day. It spells out what Claude does and what the engineer does, in enough detail that there's no room to wonder. Part 1 has the full reasoning, but the short version is: if the engineer can do it in under two minutes in a terminal, it shouldn't go to Claude through an MCP.
workflow.md
also holds the task format we make engineers use when they hand work to Claude:
| Required field | Why it exists |
|---|---|
Branch: {name} |
|
| Stops Claude asking or guessing — one less tool call | |
Files to CREATE: [list] |
|
| Scopes creation, stops new files getting added speculatively | |
Files to MODIFY: [list + one-liner] |
|
| Keeps Claude from reading unrelated files for context | |
What to build: [criteria] |
|
| The single source of truth for when it's done | |
Do NOT read: [not listed] |
|
| An explicit boundary — absence isn't permission |
If any of those fields is missing, Claude asks before it touches a file. That kills the usual failure mode where it reads three or four files "to understand the codebase" before writing a single line.
Architecture decisions go in as ADRs — the decision, what led to it, what it costs us. We record the rejected ones too, and those turn out to be the more useful part.
When some future session asks "why not GraphQL?" or "should we add WebSockets for live data?", the answer is already sitting there: considered, rejected, here's why. Claude doesn't reopen it and neither do we.
One rule keeps the split files from turning into the same contradictory mess as the old monolith:
One file owns one domain. If a rule could live in two files, it goes in the more constrained one — usually core.md. And if you can't tell which file a rule belongs in, it's probably too vague to be a rule.
In practice: color tokens go in design.md
, not core.md
. Cache TTLs go in core.md
, not architecture.md
. Division of labor is workflow.md
, not core.md
. Once the domains are clear the contradictions jump out — if the same thing shows up in two files, one of them is wrong.
design.md
and nothing else.It's not a complicated setup. Six files and a manifest. The work is in holding the one-domain line: the moment a file starts feeling like it's about two things, split it.