Mark HollandSenior AI Solutions Engineer

How I spec a build

Twelve steps, in order, from the materials a team already has to a build that is checked against what was agreed. Each step leaves a file behind.

  1. 1Intake of existing materialsdocs/reference/
  2. 2Interview for gaps onlydocs/PRD.md
  3. 3Expected results and definition of donedocs/PRD.md
  4. 4Product requirementsdocs/PRD.md
  5. 5Technical specdocs/TECHNICAL-SPEC.md
  6. 6Design doc, for anything with a screendocs/DESIGN.md
  7. 7Guardrailsdocs/GUARDRAILS.md
  8. 8Project rules for the AICLAUDE.md
  9. 9Project skeletonREADME.md
  10. 10Ordered build promptsdocs/DEVELOPMENT-PROMPTS.md
  11. 11QA checklistdocs/QA-CHECKLIST.md
  12. 12Verify the build against the specBUILD_STATUS.md

Step 1: Intake of existing materials

Read everything the team already has before asking a single question.

What it produces

  • docs/reference/, kept read-only
  • A short "here's what I learned" summary the team can correct

Step 2: Interview for gaps only

Ask only about what the materials leave open.

What it produces

  • Answers captured directly into PRD.md (no separate answers file)

Step 3: Expected results and definition of done

Agree what done looks like, in results someone can check.

What it produces

  • Expected Results section of PRD.md

Step 4: Product requirements

What the product does, for whom, and what each feature must do to count as done.

What it produces

  • docs/PRD.md

Step 5: Technical spec

How it is built: architecture, data, interfaces, and how it is tested.

What it produces

  • docs/TECHNICAL-SPEC.md

Step 6: Design doc, for anything with a screen

Screens, components, states, and accessibility, agreed before anyone builds them.

What it produces

  • docs/DESIGN.md

Step 7: Guardrails

What the AI may and may not do, where plain code decides instead of the model, and the eval gate a change must pass.

What it produces

  • docs/GUARDRAILS.md
  • A tested safety-hook kit that blocks risky actions during the build

Step 8: Project rules for the AI

The rules every coding agent follows on this project.

What it produces

  • CLAUDE.md

Step 9: Project skeleton

Folders, starter settings, and a README in place before the first feature.

What it produces

  • Folder structure
  • .env.example
  • .gitignore
  • README.md

Step 10: Ordered build prompts

One prompt per milestone, run in order, each naming the checks that must pass.

What it produces

  • docs/DEVELOPMENT-PROMPTS.md

Step 11: QA checklist

The checks a release must pass, written before the build starts, each tied to an acceptance criterion.

What it produces

  • docs/QA-CHECKLIST.md

Step 12: Verify the build against the spec

Every acceptance criterion maps to a test, and someone other than the builder checks the result. Gaps are recorded, not ignored.

What it produces

  • BUILD_STATUS.md

When something changes, the spec changes first, then the code.

AI Spec KitA blank spec template, a complete sample spec with notes on why each part matters, and an editable Markdown copy.