A case for specs as the real interface between people, AI agents, and large codebases — built from what's actually running in production, not from theory.
a working method, not a pitch
Every AI session starts cold. It doesn't have the six months of hallway conversations, the incident that produced a rule, the reason a "wrong" pattern is actually deliberate. Code tells it what the system does. Nothing tells it why, or what not to touch, unless that gets written down somewhere durable.
So I build that layer: a small set of versioned specs, kept separate from the code, each one naming what it's derived from and when it was last checked against reality. A cold start — human or model — then starts from evidence instead of a guess.
It isn't a framework, and it doesn't depend on any particular AI tool. Think of it as the other half of AI memory: features like Claude's CLAUDE.md and session memory hold what the assistant has learned about you — this layer holds what the project knows. One is personal and fuzzy; the other is shared, versioned, and auditable. A team needs both.
I've been running this method on live systems for a while now — including the 18,000-file school platform I maintain. The specs are plain files, but they also render as a visual map a person can browse: one source of intent, two ways to read it — models read the text, people get the graph. The specifics of how it works, and what it caught, belong on their own pages.
what this actually fixes
Plain text, nothing tool-specific. Any AI can read it, and so can a person with no AI at all — if it only makes sense to one tool, it never encoded the intent in the first place.
A fixed reading order replaces reverse-engineering intent from thousands of files — for a new engineer and a fresh session alike.
One logged session reached an architecture decision on roughly a fifth of the context that reading raw source would have cost — including facts the code alone would have answered wrongly.
Nobody — person or context window — holds 150+ modules at once. A bigger project means more files, not a harder start.
CI catches what's written. A per-module checklist catches what's missing — the rate limit that isn't there, the branch nobody guarded.
where this is going
None of this is presented as finished. The same discipline it asks of a spec — write the claim, name the source, date it, delete it when it's wrong — applies to this page too. What's here is what's actually running; what isn't built yet is marked as such, not implied.