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 series Part 1: Token Efficiency in Claude Code (start here). Part 3: Picking Models and Tools — the MCPs we tried, refused, and why.

The append loop

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.

The structure

CLAUDE.md stops being the rulebook and becomes a table of contents. The actual rules move into separate files under .claude/.

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.

What goes where

core.md — the constitution

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:

• Facts we've verified — model IDs we've confirmed work, endpoint shapes, cache key names, exact token limits per endpoint.
• Hard constraints — rules you don't break without a deliberate, written-down decision (where the API key goes, no swapping models, TTL values).

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.

design.md — the visual contract

Every hex value, every chart-type assignment, every loading-state pattern goes in design.md. Three reasons it pays off:

• A new engineer, or a fresh Claude session, doesn't have to reverse-engineer the visual conventions out of the component code.
• When we changed the color logic on the 52-week range bar, we edited one table in design.md. No component files had to change just to record the rule.
• We can reject a PR where Claude hardcoded a hex instead of using the documented token, because the rule is written down.

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.

workflow.md — who does what

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:

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.md — decisions and why

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.

The rule that keeps it from rotting

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.

What changed after

• Startup token cost down about 60% on a typical task.
• Contradictions are findable now — the same topic in two files gets flagged.
• New rules have an obvious home, and figuring out the home forces you to be clear about what kind of rule it even is.
• You can review the files on their own — a frontend change goes up against 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.

Continue reading

• Part 3: Picking Models and Tools — the MCPs we tried, refused, and why.