Engineering discipline for AI coding agents.
SpecForge plans the software before an agent writes a line of it — the domain, the
architecture, the specification — so what the agent builds holds together after
the demo.
AI proposes. Human approves. Harness enforces.
The problem
The vibe-coding trap
Describe an idea to an AI coding agent and it starts writing at once. It does not
ask where one part of the business ends and another begins, or how the pieces
should talk to each other. Three days later the code passes its tests and the
demo runs.
A week after that, adding a feature shows the logic scattered across services and
one class doing four jobs. The code is not wrong, exactly. It is just not
engineered — because the decisions that matter most were never made. Why that is
not the agent's fault is argued in
Your AI Coding Agent Is Not the Problem (Medium).
The answer
A specification, not a prompt
SpecForge does the engineering work that has to come before the first line:
a domain model, clear boundaries, an architecture, and a feature-by-feature
specification. Each piece is written by AI, reviewed independently by a
separate check, and approved by a person before the
next one builds on it.
Only then does a coding agent start — working from a plan it is held to.
Scope — classifies the project by size and complexity, so a small
app is not buried under enterprise ceremony.
Decide — picks the single most valuable next document from a
catalogue of planning artifacts, respecting what each one depends on.
Synthesize — writes that document from everything already approved.
Verify — an independent, adversarial review of the document, listing
the assumptions a person needs to confirm.
Gate — you approve, give feedback, or resolve the open assumptions.
Nothing moves on without you. Then the loop picks the next document, until the
catalogue is complete and the build can begin.
The planning loop, from a product description to the build.
Each step, and why the loop is built this way, is explained in
The SDD Planning Loop (Medium).
Right-sized
A catalogue of planning artifacts in three tiers — domain design, architecture,
and specification. A lightweight project takes only the essentials; a complex one
takes the full path.
Existing code, too
For a system that already exists, SpecForge's scan is being rebuilt to map the
real code and tie every claim it writes to evidence — or say plainly that it does
not know. How the scan works.
Proven on a real case
The method has been worked through end to end on a case study — a community
equipment library built with .NET 9 and C#, using clean architecture, a modular
monolith and CQRS. The whole case study, with every prompt, is in the book
AI-Assisted
Software Engineering (Gumroad, $19).
You choose the AI
SpecForge works with models from several AI companies, or one running on your own
hardware. The discipline is in the loop — the independent review and your
approval — so it holds whichever model writes the documents.
Existing code, too
A scan that knows what it doesn't know
Point a quick AI scan at a fifteen-year-old codebase and it writes
documents that read well — filling the gaps with what systems of that shape usually
look like. A wrong guess and a real observation come out in the same confident tone,
and everything planned afterwards is built on both. SpecForge's scan of existing code
is being rebuilt so that every sentence it writes can say how it knows.
Four layers between reading the code and writing a claim
A map of the code, built without AI. Every file, type and
function, what calls what and what inherits from what, and which project file owns
which code — parsed directly from the source in C#, Java, Python and
TypeScript/JavaScript. No model call, so it can be tested exhaustively and rebuilt
whenever the code changes.
Summaries from the bottom up. Functions first, then types, files,
modules and the whole system, each level built on context already checked below it.
Module summaries say what the code does for the business before how it is built. A
small edit re-summarises only what it actually changes.
The right search for each question. Text search, walking the map,
or looking up a summary — whichever answers the question. Every piece of evidence
carries a receipt: which lines, of which snapshot of the code.
Claims first, prose second. Each document is drafted as a list of
claims, each pointing at its evidence and checked against it before a word of it
reaches the page.
Three kinds of claim, never blurred
A fact must cite evidence that genuinely supports it. If it
cannot, it is removed or marked unverified.
An inference is shown as an inference, not dressed up as an
observation.
An intent — the “why”, which code rarely proves — is marked as
unknown when nothing shows it, rather than invented.
Every claim also carries a confidence — high, medium or low — worked out by fixed
rules rather than the model's opinion of itself, and always with its reason stated.
Honest about gaps
Where no evidence exists — code wired up at runtime by dependency injection or
reflection, which no reading of the source can resolve — the gap becomes a
specific entry in a list of what the scan could not determine, marked as either
something a deeper analysis could close or something it never will.
“Our tools couldn't check this” and “this is genuinely
dynamic” are kept apart, because they mean different things to the person
reading.
What stays the same, and what it guards against
The same four documents — a product description, an architecture overview, a
shared-infrastructure guide and an AGENTS.md for the coding agent —
reviewed one at a time at the same gate, approved or corrected by a person.
The code being scanned is treated as untrusted: text in a comment or README is
quoted as data, never followed as an instruction, and symbolic links that lead
outside the repository are not followed.
Built for large systems: it estimates the work and cost before spending anything,
resumes where it stopped after a crash, and halts cleanly at a set cost ceiling.
Where this stands: this is the design the scan is
being rebuilt to, not a finished feature. Before it counts as done, it has to beat the current,
simpler scan side by side, on a codebase that was never used to tune it. The full
design is set out in
The Scan That Knows What It Doesn't Know (Medium).
SpecForge is in development
If you lead a team that builds software with AI coding agents and would
like to hear when it is ready — or to shape it — get in touch.
