AI-Assisted Development Methodology

Context

I build software and structured content as a solo developer, with AI agents doing much of the producing, primarily Claude in chat as the planning layer and Claude Code as the builder. Across two projects (StoryBuilder, an application with an LLM evaluation pipeline, and Content Garden, a content pipeline), I turned the way I work into a written method with its own decision log, versioning, and maturity grades. Its next application is a project whose infrastructure will act as the builder, which is expected to change the briefing form while leaving the lifecycle intact.

The problem

I started experimenting with vibe coding and agentic coding in early 2025, but I quickly ran into limits. The results were fast but unsatisfying, especially an early, loose build of the StoryBuilder project. The agent did excellent infrastructure work and, elsewhere, quietly shipped functionality that didn’t match what I intended. Nothing was wrong with the agent. The specification left room, and the agent filled it with its own choices: some fine, some wrong, and some silently broken. I couldn’t tell which was which until later. Under-specified briefings produced both defects and unintended features that were indistinguishable from the intended functionality until they surfaced downstream. That’s when I took a step back and developed a formal framework and methodology to produce more robust, predictable results with agentic coding tools.

What I did

I made specification quality the primary defect-prevention mechanism and treated everything else as backstop, then cut any ceremony that served neither.

The methodology defines three strictly separated roles. The product owner (me) is the sole decision authority: approving every batch, ruling on every fork, and applying every governance record. The architect (Claude in chat) produces specifications, options papers, briefings, and reviews, and never decides or builds. The builder (Claude Code or similar) executes against specification in PR-per-branch increments, escalates ambiguity, and never touches governance. The builder is an abstraction chosen per project; the seam (specification, execution, then review) is consistent. Deciding and executing never share a context.

Work runs in single-job threads: discussion threads scope and decide and close with a handoff and a thread-start prompt; production threads execute, batch-gated, with my approval before each batch; companion, rework, and review threads propagate and verify. Every thread opens by reconciling state (what has actually run, which document versions are authoritative, whether a handoff has gone stale) and closes by verifying every promised file exists on disk, because the transcript is never the record.

The rules carry evidence grades: settled, provisional, in trial. A rule is promoted when it demonstrably catches something or holds across a second project, not by fiat. Each rule is indexed to an observed failure, and every deviation found in review is sorted into one of three classes (the briefing was silent; the builder guessed instead of escalating; the builder ignored the spec) so the method learns the right lesson.

What was built

The methodology is defined in an approximately 180-page document, developed in conjunction with the architect. The document can be referenced as project knowledge, and the operating rules are also packaged as a skill so a new assistant can act as the architect without loading the full document. A governance layer lives in the repository beside the code: an append-only decision log with errata-only corrections (150+ entries on StoryBuilder, 36+ on Content Garden, 68 on the method itself), a deferred-items register, per-thread dispositions and priming prompts, build-review dispositions per pull request, briefings with acceptance criteria, and archived run evidence.

From the decision log

DL-149 — Analysis-method errata 001: the age-authenticity cap is two to three times more punitive than §2.2 stated

Date: 2026-09-04 · Thread: Piece 3 · D3-F · run preparation

Decision: An errata addendum is issued to the locked analysis method, correcting four sections and closing one open question. The locked method is not edited in place; the addendum is the instrument the pre-registration provided for. Seven items are corrected, including the cap arithmetic and the aligned-arm age range.

Rationale: The error was found by a zero-spend verification that derived the arithmetic from source and then executed it, the two agreeing cell for cell. It entered because the prior source read paraphrased a code comment rather than the code. The project's own unit-test output had printed the true value on every run since it was written. Standing lesson recorded: any arithmetic a pre-registration depends on is verified by executing the code, and the project's existing test output is the first place to look.

Evidence, supersedes/relates, and type fields omitted here; the full entry is in the repository.

Outcome

The evidence is the failures caught before they cost anything.

• A zero-spend source read before a $30 measurement run found that the locked analysis method had paraphrased a code comment instead of executing the code, and had the age-authenticity cap two to three times less punitive than the implementation. The method was corrected by a formal errata addendum, the run plan stayed pre-registered, and the run went ahead clean. The standing lesson was written down: any arithmetic a pre-registration depends on is verified by executing the code.
• A rework thread’s opening reconciliation found two companion threads that had never run, and stopped the work from integrating against a stale baseline.
• An urgent discussion inserted mid-sequence had silently touched a written handoff’s scope; input reconciliation caught it before the handoff was consumed.
• A git governance-boundary violation was traced, then codified into a standing rule.

Recent builds have gone right because the briefings were detailed enough that the builder had nothing to guess.

What it shows

Governance design for AI-agent delivery · Specification and briefing standards · Failure-mode analysis and continuous method revision · Evidence and measurement discipline · Right-sizing process for a solo owner

Six of the fifteen failure modes the method defends against

Known limits, stated plainly

The method assumes one human reads everything and rules on every fork. It does not scale to a team without redesigning the gates, and that redesign is deliberately out of scope. Three copies of the governance documents are synchronized by hand. Whether the cross-model review protocol pays for itself is the open empirical question its pilot is meant to answer. The custom-system builder pattern is untested until the next project.