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
the introduction to the book AI-Assisted Software
Engineering (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 the plan, which goes into every
request it makes, with a person checking each feature against its scenarios.
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 the approved documents it
builds on.
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 maps the real code and ties
every claim it writes to evidence — or says 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 Anthropic, OpenAI and Google, a different one for
each role if you like, and the scan can summarise code with a model on your own
hardware. It refuses to let the model that writes a document be the one that
reviews it. 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
was 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, Go 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.
Evidence by a recipe for each document. Gathered by text search
and by walking the map, the same way every time for a given document. 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: symbolic links that lead outside
the repository are not followed, and secrets are redacted. Treating comment and
README text as data rather than instructions is designed but not built yet.
Built for large systems: before spending anything it estimates how many model calls
and tokens the scan will take, it resumes where it stopped after a crash, and it stops
cleanly at a limit on calls or tokens, if one is set.
Where this stands: the rebuilt scan is what
SpecForge runs today. It has been run end to end on a real codebase never used to
tune it, with every claim tied to a line of source. Still to do: a run on a much
larger codebase, and a side-by-side comparison with the older, simpler scan. 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.
