adopted: karpathy 4 lines + google 9 sections
60k stars on four behavioral lines. 70k on a markdown design spec. why we adopted both and what we cut to get there.
the configuration paradox
loswf’s claude.md grew to 11 numbered “agent directives.” most were defensible in isolation. taken together, they competed with the harness’s own primitives — phased execution that the pipeline already enforces, forced verification that the validate gate already runs, sub-agent strategy that the foreman already owns.
karpathy’s january thread named the underlying pattern: more rules feel like more control, but past a behavioral foundation they add noise that competes with signal. anthropic’s own docs say it plainly: “would removing this cause claude to make mistakes? if not, cut it.”
we ran the litmus test on every directive. five failed.
what landed
claude.md — 123 lines down to 65. the four karpathy behavioral lines lead. only the loswf-specific overrides that pass the “would removing this break the agent” test remain.
removed: pipeline-duplicative rules (phased execution, forced verification, sub-agent strategy), context-decay prose collapsed into karpathy’s lines 1–3. kept: context-decay re-read behavior (#6 — harness reality), the 2000-line read budget (#7), the silent-truncation warning (#8), the editor-diagnostics-as-noise rule (#11 — field-tested via pr #240).
design.md — new, at repo root. nine sections grounded in shipped content-voice.md + docs/diagrams/: visual theme (terminal-aesthetic, dark crt, monospace lowercase, amber #e8a040), color palette + roles, typography, component stylings, layout principles, depth + elevation, do’s + don’ts, responsive behavior, agent prompt guide.
§9 carries the verbatim prompt suffix that every generate_image.py call should append. it’s the operating contract for downstream agents.
loswf-designer agent body updated across all three surfaces (.claude/agents/, plugin mirror, codex toml) to cite design.md as the canonical visual brief. routing-model.png inline style references replaced with a “read design.md, apply §9 suffix” step.
the gap design.md closes
models can reason about typescript generics. they can’t keep a button the same shade of blue across two pages. that’s not because design is harder than code — it’s because the tooling invested everything in code consistency and almost nothing in visual consistency.
claude.md + .cursorrules + linters + formatters + type checkers + ci pipelines tell the agent what correct code looks like. nothing equivalent told it what correct design looks like.
design.md, in plain markdown, encodes color roles (not color preferences), spacing scales (not spacing guesses), typography hierarchies — the same constraints that make human design teams consistent.
the meta
the spec-adoption work itself routed through the new standard pipeline. intake → product signoff → architect → decomposer → three s-sized children built in parallel. the routing inversion (#514 sub-tree) had just landed; #519 was the first non-trivial m that exercised the new contract end-to-end.
it worked.