---
id: "action-write-specs-first"
type: "action-item"
source_timestamps: ["00:08:50", "00:09:48"]
tags: ["engineering-process"]
related: ["concept-spec-driven-development", "quote-spec-becomes-eval", "framework-dark-code-solution", "entity-amazon"]
speakers: ["Nate B. Jones"]
action: "Force human understanding by writing detailed specifications before allowing AI to generate any code."
outcome: "Creates a clear evaluation criteria for the AI and ensures human architectural comprehension."
sources: ["s23-amazon-16k-engineers"]
sourceVaultSlug: "s23-amazon-16k-engineers"
originDay: 23
---
# Write Specs Before Generating Code

## Action

Before allowing an AI agent to generate code, **write out a detailed specification, requirement list, or task list.**

## Outcome

- Forces the human to architecturally understand the goal
- Produces a tangible artifact that doubles as the evaluation criteria for the AI's output (see [[quote-spec-becomes-eval]])
- Closes the upstream side of the [[concept-comprehension-gap]]

## How To

1. Refuse to start an AI prompt with vague intent.
2. Write a spec containing: purpose, inputs, outputs, edge cases, success criteria, failure modes.
3. Convert the success criteria into executable test cases (the eval).
4. Run the AI against the eval; iterate until passing.
5. Review the resulting code through the [[concept-comprehension-gate]] before merge.

## Concrete Example

[[entity-amazon]]'s post-December outage rebuild of their AI coding tool is the canonical large-organization implementation of this action.

## Connects To Concept

[[concept-spec-driven-development]] — Layer 1 of [[framework-dark-code-solution]].