Using AIDLC to Build Documents (Not Just Code)

I was answering requirements questions for a knowledge-transfer package when the AI stopped me cold.

I had picked "slide deck" as the output format. Two questions later, I picked "native web rendering" for the diagrams. Instead of guessing which one I meant, the workflow halted:

"These conflict: a slide deck is not a website, and native web rendering does not live inside a deck. Which do you actually want?"

It was right. I had contradicted myself without noticing, and if the AI had quietly picked one interpretation, I would have found out a full build later. That one catch is why I keep using this process for documents, and it's a good place to start explaining what the process is.

What I Was Building

I needed a knowledge-transfer (KT) package for an internal service: a presentation for about 30 engineers, delivered remotely over Zoom, built from a pile of existing design docs. You don't need to know anything about that service to follow along. This is about the process, not the subject.

The process is AIDLC, the AI-Driven Development Lifecycle, an open workflow from AWS Labs. The rules and setup instructions live at github.com/awslabs/aidlc-workflows, and the thinking behind it is in the AI-DLC blog post. You install it as a set of steering rules for your coding agent (Kiro, Q Developer, Cursor, Cline, Claude Code, or Copilot), and from then on the agent follows the workflow. Nothing in this article depends on which agent you use.

AIDLC moves through three phases. Inception is where you work out what you're making and why. Construction is where you work out how, then actually make it. Operations is where you run and maintain it, and for now that phase is mostly a placeholder. Inside those phases are stages: workspace detection, requirements, planning, design, generation, build-and-test. Two ideas make the whole thing work. First, it's adaptive, so not every stage runs every time. Second, it has gates. After most stages, the AI stops and waits for you to approve before it moves on. The contradiction catch above happened at a gate. The gates are where you stay in control.

Why This Works For a Document

A document project has the same shape as a software project if you squint. Requirements become "who is the audience and what must this cover." Design becomes your outline. Writing code becomes writing the content and assembling the artifact. Build-and-test becomes "does it render, does it open, is it accurate." The stages that only make sense for running software, like user stories and infrastructure design, get skipped on purpose, with the reason written down. The mental adjustment is small: your design is the outline, and your code is the content.

The Walkthrough

Kicking Off and Workspace Detection

I opened with a plain request that said what I wanted, who it was for, and what source material I had. Mine was roughly: "Using AIDLC, create a knowledge-transfer artifact. The audience is 30 engineers, delivered remotely over Zoom. Here are the source docs. Should it be a website or a slide deck? Evaluate and recommend."

The AI then scanned the workspace to see what it was working with. A greenfield workspace is empty, and you're starting fresh. A brownfield workspace already has material. For documents, brownfield usually means the source of truth already exists somewhere, like a codebase, old design docs, or a wiki, and that material is what you synthesize from. Mine was brownfield: a folder of design docs.

Reverse Engineering, When the Source Already Exists

Because I was documenting something that already existed, AIDLC ran a reverse-engineering pass first. It read the source material and produced grounding notes (overview, structure, inventory) so that later stages work from facts instead of inventing them.

This was also my first taste of the gate-and-correct rhythm. The first pass got the annotation (Spring AOP) semantics wrong, describing only what a setting disabled and not what it did. I pushed back, the AI fixed it and presented again, and I approved. All of that landed in the audit log at aidlc-docs/audit.md, verbatim:

## Reverse Engineering - User Correction
**Timestamp**: 2025-11-04T16:42:19Z
**User Input**: "Annotation semantics -> include what it does also. Not just the negation. If you are not able to interpret, ask for this information."
**AI Response**: Re-read the source design doc, expanded the annotation semantics section to cover positive behavior, presented revised notes.
**Context**: Reverse Engineering, revision 2

---

## Reverse Engineering - Approval
**Timestamp**: 2025-11-04T16:51:03Z
**User Input**: "No more changes. next step."
**AI Response**: Marked reverse engineering complete. Proceeding to
Requirements Analysis.
**Context**: Stage approval

Two things worth noticing. You can demand precision, and approval is a deliberate "next step" rather than the AI moving on by itself.

Requirements Analysis, and Why the Questions Matter

This stage pins down what you actually want. The useful part is the structured question format: multiple choice with an [Answer]: tag you fill in.

## Clarification Question 1
Which artifact do you actually want me to produce?

A) Slide deck, diagrams rendered as images
B) Local website, native diagram rendering
C) Both, a deck for presenting plus a website reference
X) Other (describe after [Answer]:)

[Answer]: A

This format forces the fuzzy decisions into the open before anything gets built. The X) Other option means you're never stuck inside the choices offered. And the AI will catch contradictions instead of guessing. This is where the halt from the opening of this article happened: I picked "slide deck" for the format, and native web rendering for the diagrams, two answers that don't go together, and the workflow refused to proceed until I resolved it. It's cheaper to let the AI interrogate you now than to rebuild later.

Workflow Planning, Where You Skip Stages on Purpose

This is the stage that makes AIDLC practical for documents. Planning decides which stages run and which get skipped, and it records the reason for each skip. Here's the plan the AI produced for my run, as it renders in the plan file:

## Stage Execution Plan

- [x] Workspace Detection - EXECUTE (always runs)
- [x] Reverse Engineering - EXECUTE (brownfield: source docs exist)
- [x] Requirements Analysis - EXECUTE (always runs)
- [ ] User Stories - SKIP: one deliverable, no personas or interactive flows
- [ ] Application Design - SKIP: no software components or methods to design
- [ ] Units Generation - SKIP: single deliverable, nothing to decompose
- [x] Functional Design - EXECUTE: this becomes the outline
- [ ] NFR Requirements - SKIP: no performance, scalability, or security
      concerns in the software sense
- [ ] NFR Design - SKIP: depends on NFR Requirements
- [ ] Infrastructure Design - SKIP: output is local files, nothing deployed
- [x] Code Generation - EXECUTE: this is where the artifact gets built
- [x] Build and Test - EXECUTE: confirm it renders, opens, and traces to
      real sources

Writing down the reason for a skip matters. It's the difference between "we forgot the security review" and "security review does not apply to a local markdown file, and here is the line saying so." Anyone reviewing later can see the decision was made on purpose.

Functional Design, Which Is Your Outline

For a document, functional design means the outline and topic scope. This was the most important gate in my run. Get it right, and the build is easy. Get it wrong, and you're regenerating everything.

The AI proposed the full structure: sections, sub-topics, ordering, depth, which diagram goes where, and a time budget for the presentation. It attached confirmation questions to each part.

## Question 1: Section list and ordering
Does the outline cover the right topics in the right order?
A) Yes, approve as-is
B) Reorder some sections (describe)
C) Add or remove sections (describe)
[Answer]: A

## Question 2: Depth and time-box
Is the time and depth allocation right?
[Answer]: A

Spend your effort here. It's the cheapest place to change your mind.

Code Generation, Where the Thing Gets Built

Once I locked the outline, generation ran in two parts. First, the AI listed the exact build steps (scaffold files, author diagrams, build the website, render images, generate the deck) as a checklist and asked me to approve it. Then it worked through the checklist, ticking boxes as it went. The checklist isn't busywork. It's how you track progress, and it's how you can say "stop, step 3 is wrong" without losing the rest of the work.

Build and Test, Where You Confirm It Works

For a document, this part is concrete. Does the website open from local files, do the diagrams render, does the deck open with the images embedded, and does the content trace back to real sources with nothing invented? I found what was broken, had it fixed, and was done.

What the Run Leaves Behind

By the end, the deliverables themselves (the deck, the website) sit in the workspace root. Everything about how they came to be sits in aidlc-docs/. Here's the actual tree from my run:

aidlc-docs/
├── aidlc-state.md                 # where the run is, stage by stage
├── audit.md                       # every exchange, verbatim
├── inception/
│   ├── plans/
│   │   └── execution-plan.md      # the stage plan with its skip list
│   ├── requirements/
│   │   ├── requirement-clarification-questions.md
│   │   ├── requirement-verification-questions.md
│   │   └── requirements.md
│   └── reverse-engineering/       # the grounding notes
│       ├── business-overview.md
│       ├── architecture.md
│       ├── component-inventory.md
│       └── ... (six more)
└── construction/
    ├── plans/
    │   ├── kt-architecture-overview-functional-design-plan.md
    │   └── kt-architecture-overview-code-generation-plan.md
    └── kt-architecture-overview/
        ├── functional-design/
        │   ├── kt-outline.md      # the outline I guarded
        │   └── agenda-and-presenter-notes.md
        └── code/
            └── code-summary.md    # what got built, from which sources

The layout mirrors the phases. inception/ holds the thinking: grounding notes, requirements, and the plan that recorded which stages to skip. construction/ holds the making: the locked outline, the build checklist, and a summary of what was generated. The two files at the top track state and history for the whole run. When someone asks "why does slide 14 say that?", the answer is somewhere in this folder.

The Messy Part, Which Is Normal

If you only read the finished artifacts, you'd think an AIDLC run is a clean question-and-answer session. Mine wasn't. I stepped in, changed my mind, and corrected the AI constantly, and that's how it's supposed to go. The gates exist so you can do exactly this.

I changed my mind at a gate. I settled the format, then walked it back a message later: "I chose local website + PPT in my answers." Then I refined the roles again: "I will present from website. PPT is for lasting reference." The requirements doc got updated each time. Changing your mind at a gate costs almost nothing. Changing it after the build costs a lot, which is the whole reason the gates come first.

A lot of my steering didn't fit a multiple-choice box, and that was fine. Plenty of my corrections were just typed out plainly:

"Timeline is incorrect again..."

"ignore [that part], the project was deprioritized."

"directly V3 was created. v1 and V2 were in design only. Do not mention versions."

"There are just two types of throttling... they work in parallel, not layered."

The AI took each one, rechecked the source where it needed to, and presented again. You're never limited to the menu.

I also asked a side question without derailing anything. Mid-build: "Approve. I have a tangential question before we continue. You asked to create diagrams for the web version. What were my other options?" The AI answered and then carried on with the build.

Some corrections only became obvious once the artifact existed. During review, after generation, I asked: "Give a better visual diagram for the identity format. Can you use a vector diagram here?" Review is a legitimate place to refine. And sometimes I cut scope rather than adding it. Late in the run: "Remove Section 12. I don't want to talk about it. I don't know much about it. I'll add it later if I find something." The outline shrank, the reason was logged, and the run moved on.

Why the Audit Log Is Worth Keeping

Every one of those messages, including the flip-flops, the terse corrections, and the side questions, is captured in aidlc-docs/audit.md in the format shown earlier: my input word for word, paired with what the AI did, and a timestamp. It's never summarized.

That sounds bureaucratic, but I've already gone back to it more than once. I could reconstruct why the artifact looks the way it does. A reviewer followed the decision trail without having been in the room. And when something was wrong, I traced it back to the instruction that caused it, which turned out to be mine. The workflow's rule is to log every interaction, append rather than overwrite, and keep your exact words.

Habits That Made My Run Go Well

Front-load the thinking. Requirements and the outline are where decisions are cheap, so that's where I spent my attention. I let the AI ask its questions, because a contradiction caught early is a build saved. I approved on purpose rather than on autopilot, and when the multiple-choice options didn't fit, I just typed what I meant. One more thing: the audit log keeps your exact words, so say what you mean the first time. Future-you will read it.

A Checklist to Reuse

If you want to run AIDLC for your own document:

• Open with a plain request: the deliverable, the audience, the source material, and any questions you want the AI to evaluate.
• Let it detect greenfield versus brownfield. If brownfield, let it reverse-engineer the source into grounding notes first.
• Answer the clarifying questions, use X) Other when you need to, and let it flag contradictions.
• At planning, confirm the skip list and check that each skip has a reason.
• Lock the outline. This is your most important approval, so take your time with it.
• Approve the build checklist, then let it generate.
• Review the rendered artifact and correct freely. Even large structural changes are fair game at this point.
• Skim the audit log at the end. It's your decision trail.

Keep the spine, skip the software-only stages, guard the outline, and steer out loud.

References

• AIDLC workflow rules and setup: https://github.com/awslabs/aidlc-workflows
• AI-DLC methodology blog post: https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/