From Writing the Spec to Approving It: What AI-DLC Looks Like on a Real Build

Most AI-assisted development still follows the old split. A human writes the spec, a human writes the code, and the AI helps with autocomplete or generates tests at the end. AI-DLC (the AI-Driven Development Life Cycle) reverses that. The AI drafts the requirements, the design, and the code. The human answers short questions and approves each stage before the next one starts.

To see what that looks like in practice, I built a small command-line tool with it and then read the record the workflow left behind. This post walks through that record, folder by folder.

TL;DR

• AI-DLC is public and open source: awslabs/aidlc-workflows. The method comes from this AWS DevOps blog post.
• My only written input was one sentence. Everything else I did was pick options and approve gates.
• The run produced requirements, four architecture decisions, a unit plan, a traceability file, and 12 tests that passed when I ran them, in about 44 minutes from start to the code approval.
• The human role moves from author to decision-maker. The decisions are still yours, and the record shows where they changed the outcome.

The app

The tool is a Spooky Date Fact Generator. It picks one of 10 spooky dates (or takes --date MM-DD) and prints a spooky event for that day from Wikipedia's "On this day" feed. It is small on purpose.

The whole request was this sentence:

/aidlc build random date generator with fact around that number

The flip, in one table

	Traditional with AI help	AI-DLC
Requirements	Human writes them	AI drafts them from multiple-choice answers
Design	Human sketches it	AI proposes, human picks between options
Code	Human writes, AI assists	AI writes against an approved plan
Tests	Human or AI at the end	AI writes them to the stated requirements
Human job	Author	Decide, validate, approve
Evidence	Pull request diff	Audit log, decisions, traceability file

Where everything was written

Two locations matter. The generated app sits in its own folder, and the workflow record sits in an aidlc/ folder.

app/                                  <- the generated tool
  src/spooky-facts.ts      core: dates, fetch, keyword filter, nearest-date search
  src/cli.ts               command line: options, output, exit codes
  test/                    12 tests, offline, with a fake fetch
  package.json, biome.json, tsconfig.json, README.md

aidlc/
  codekb/                             <- 9 docs about the existing repo
  intents/<date>-date-fact-generator/ <- the record for this build
    aidlc-state.md                    stage checklist and settings
    audit/                            every event, decision, and approval
    inception/
      reverse-engineering/            scan of the existing repo
      requirements-analysis/          questions + requirements.md
      domain-design/                  questions + components.md + decisions.md
      units-generation/               unit-of-work files
    construction/u1-spooky-date-cli/code-generation/
      code-generation-plan.md, code-summary.md,
      unit-test-instructions.md, traceability.json

Each stage writes a -questions.md file, and your answers sit in the same file as the AI's questions. That makes the decision trail readable without any tooling.

Stage by stage: what it did and why it helps

Initialization. The workflow scaffolded the record folder, scanned the workspace, and classified it as brownfield TypeScript on Bun. This is automatic. It helps because every later stage starts from facts about the repo instead of guesses.

Reverse Engineering. A developer agent scanned the existing repo and wrote nine knowledge-base documents (architecture, technology stack, code structure and others). This matters most in a brownfield repo. The later code followed the repo's Bun, TypeScript, and Biome conventions because the AI had read them first.

Requirements Analysis. The AI asked six questions, such as where facts come from, what to do when a date has no spooky event, and whether this should be a web page or a command line. Each had lettered options. I answered, and one answer included a free-text note: generate dates that have spooky facts, from 10 such scenarios. The result is requirements.md with 15 functional and 5 non-functional requirements, each with acceptance criteria and a tag pointing back to the answer that produced it, such as [Q5]. This stage turns one vague sentence into testable statements before any code exists.

Domain Design. Four more questions produced components.md and four architecture decision records. The AI recommended splitting the tool into four parts. I chose two. The decision record states that the four-part split was rejected as more structure than needed. This is the clearest example of the validator role, because the human overrode the AI's recommendation and the reason is recorded.

Units Generation. One question: build as one unit or two. I chose one, approved the plan, and got unit-of-work.md with boundaries, responsibilities, and constraints. It fixes the blast radius. The unit is limited to apps/date-fact-generator/, and nothing in the framework folders may change.

Code Generation. The AI wrote a plan, then the code, then the tests. It asked one thing here: Bun was not installed, so should it install Bun or switch to Node. I chose Bun. The code-summary.md lists files created, decisions made, and deviations from the plan. One deviation worth noting: the AI added word forms such as "dies" and "sank" to the keyword list, because whole-word matching would otherwise miss "Houdini dies". The summary also states that some planned checks were grouped into fewer tests to match the 12-test count.

Build and Test. In the record I read, this stage was still marked in progress, so its summary was not written yet. I ran the checks myself from the app folder: 12 tests passed with 93 assertions, and lint and typecheck were clean.

What the human actually did

Reading the audit log, the human work was this:

• Typed one sentence to start.
• Approved a recomposed plan. The workflow's planner found the default express plan was missing inputs for later stages, and proposed adding Domain Design and Units Generation while dropping deployment and monitoring.
• Answered 11 multiple-choice questions across three stages, plus two more decisions: build inside the existing repo, and install Bun.
• Approved 5 stage gates: reverse engineering, requirements, domain design, units, and code generation.

That is the flip. Nothing in that list is writing a spec or writing code. All of it is deciding and checking.

Why this holds up better than a prompt

Two details make the validation real instead of a rubber stamp.

First, traceability. traceability.json maps every requirement ID (FR1.1 through NFR5, 20 in total) to the file that satisfies it. If a requirement has no target, it shows up.

Second, the record is complete. The audit log holds the timestamp of each question, answer, and approval. A reviewer six months later can see why the design has two components and not four.

What this run does not show

This was an express-scope build of a 658-line app, with plan approval, sensors, and learnings switched off by the scope. It shows the shape of the method, not how it behaves on a large system with many units and teams. The Build and Test stage had not completed in the record, and the tests are offline, so only one manual live smoke run, recorded in the code summary, exercised the real Wikipedia feed.

The questions are only as good as the options offered. A weak option list can steer a hurried approver, so reading the alternatives still matters.

Takeaway

The useful change is not that the AI writes more code. It is that the human's time moves to the points where judgment counts: what the tool should do, which design to accept, and whether the result meets the requirements. If you want to try it, start with a small brownfield repo and read the -questions.md files first. They show the method faster than any description.