Ada
The step before building.
You describe what you want. Ada structures it into governed artifacts. Claude Code builds against those artifacts — not against a conversation.
The problem Ada solves
The intent gap
When you describe a project to Claude Code in a chat window, something happens that most people don't notice until it's too late: the description is never formalized.
Claude Code infers what you meant. It builds against that inference. The inference is usually close. Close is not the same as right.
By the time the drift becomes visible — the wrong entity model, the feature that was never meant to exist, the constraint that got dropped — rewinding is harder than starting over. And starting over means re-explaining everything. Again.
The gap between informal natural language requirements and precise program behavior is formally documented in research as the intent gap. Most tools address it after the fact. Ada addresses it before building starts.
This is not a prompt engineering problem. Better prompts produce better guesses. The issue is structural: intent was never written down in a form that persists, traces, and governs.
The mechanism
How Ada works
Ada is a command-line compiler. It runs before Claude Code starts. The interface is a session — Ada asks questions, you answer, Ada compiles. The output is files on disk.
You describe what you want to build
At whatever level you think in. You don't need technical vocabulary. Ada does not ask which framework. It asks what the system should do and be — the semantic questions that actually determine whether the right thing gets built.
Ada identifies and resolves blocking unknowns
Before compiling, Ada runs structured elicitation — a focused session that surfaces the gaps in the description that would cause the wrong system to be built. Not every unknown, just the blocking ones. You answer. The unknowns become known.
Ada compiles through 7 stages
CTX → INT → PER → ENT → PRO → SYN → GOV. Each stage reduces ambiguity in one dimension: codebase context, intent graph, persona mapping, entity extraction, process synthesis, synthesis, governance. The governor evaluates coherence and either approves or iterates.
Files land on disk. Claude Code builds against them.
CLAUDE.md, agents/, hooks/ — plain files you can read before handing to Claude Code. If they match what you meant: proceed. If not: run Ada again with the correction. The intent is yours to verify before building starts.
The compiler
7 stages. Each reduces ambiguity.
Codebase Context
Static analysis of the existing project. Package boundaries, type registry, existing conventions. Ground truth before intent is applied.
Intent Graph
Your raw description is structured into an intent graph — goals, constraints, unknowns. Blocking unknowns gate the next stage.
Persona Mapping
Who builds this, who uses it, what they know and care about. The context layer that determines how entities and processes should be named.
Entity Extraction
The canonical entities of your domain — extracted from intent, not inferred from conversation. Stored in a provenance-addressed entity map.
Process Synthesis
State machines and workflows that describe how entities move. Synthesized from intent and entity map — not designed by the AI in isolation.
Synthesis
The governed blueprint — architecture, component mapping, the CLAUDE.md and agents and hooks — assembled from all upstream stages.
Governance
The Governor evaluates coherence. Checks that the compiled output traces back to the stated intent. Outputs a score. A score below threshold triggers iteration — not a silent failure. approved 0.94
The output
What Ada produces
Three artifact types. Plain files. You read them before handing to Claude Code. Each traces back to something you said.
CLAUDE.md The primary context file. Claude Code reads this on every message turn — not just at session start. It is injected into every context window throughout your session. Whatever Ada writes here constrains how Claude Code interprets every subsequent request.
CLAUDE.md encodes: what the project is, what it is not, what architectural decisions have been made, what constraints apply, and what the bounded contexts are.
agents/ Specialized agent files, each scoped to a bounded context. An agent knows its domain, its entities, its constraints. When Claude Code works in that context, it loads the relevant agent — not a general instruction set.
hooks/ Pre-tool guard files. These run before Claude Code takes any tool action — read, write, bash. They enforce the constraints from your intent at the boundary where decisions are made. Not advisory. Structural.
A single Ada compilation produces hundreds of these. Each one corresponds to a specific invariant in your intent — an entity that must exist, a constraint that must hold, a boundary that must not be crossed.
This is not a prompt. It is a governed artifact that traces back to what you said in the elicitation session. Claude Code builds against it — on every turn.
The distinction
Ada vs the alternatives
Claude Code's auto-memory records what it observed as it worked.
Ada records what you intend before it starts.
One is retrospective. One is prospective. They are not the same thing.
MEMORY.md helps Claude Code remember. Ada tells Claude Code what it was supposed to build before it starts. These solve different parts of the problem. They can coexist — Ada governs, memory records.
Who it's for
If any of these are familiar, Ada is for you.
"I described what I wanted, Claude Code built something else."
"I re-explain the architecture at the start of every session."
"By the time I noticed the drift, rewinding was harder than starting over."
"I'm not a developer, but I know exactly what the system should do."
"I need Claude Code to stay inside the decisions I've already made."
Ada is not a tool for AI practitioners. It is a tool for people who have clear intent and a gap between that intent and what currently gets built.
Honest status
Where Ada is now
Intent elicitation
Structured session that surfaces blocking unknowns before compilation. Runs before the 7-stage pipeline.
7-stage compilation
CTX → INT → PER → ENT → PRO → SYN → GOV. Produces CLAUDE.md, agents/, and hooks/ as governed artifacts.
Governor with coherence scoring
Evaluates compilation output. Iterates if coherence falls below threshold. Approves when it passes.
Persistent world model
Navigable artifact store. CLAUDE.md becomes a 3-line pointer to the manifest. Query the compiled world model months later.
Ongoing semantic authority
Ada as the governance layer on every commit. Drift detection. Impact analysis. "Does this change align with what the system was meant to be?"
not zero distance. less.
Go deeper
Start before Claude Code does.
Ada runs in your terminal. Governed artifacts in minutes.
git clone https://github.com/alexrozex/ada Built by one person. ~400 iterations since late 2024.
Full setup guide →