Writing a Build Spec

All the work of the previous lessons — requirements, scope, components, data model, planning, task decomposition, tool decisions — converges into a single artifact: the build specification, or build spec. A build spec is a complete, self-contained document that describes what a project must do, how it is structured, and what each implementation task requires. It is the difference between a project that drifts and one that ships.

What a Build Spec Contains

A build spec is not a design document, a project proposal, or a vision statement. It is a working document with a specific purpose: to give any implementer — you on a different day, a collaborator who just joined, or an AI assistant — enough context to build any part of the project correctly without asking basic questions. A complete build spec has six sections: Section 1 — Project Overview: Two to four sentences describing what the project does, who uses it, and what the core value is. This is not marketing copy; it is the anchor every subsequent decision traces back to. Section 2 — Requirements List: The numbered requirements from lesson 1, with functional and non-functional categories and acceptance criteria. This section establishes the standard for "done." Section 3 — Scope: The explicit in-scope feature list and the explicit out-of-scope list. References the MoSCoW prioritization. This section answers "what are we building now" and "what are we deliberately not building." Section 4 — Architecture: The component diagram (or list) from lesson 3, the data model from lesson 4, and the technology decisions from lesson 7. This section answers how the system is structured and what each part is responsible for. Section 5 — Task List: The ordered task list from lesson 6, with each task's title, output description, dependencies, and estimate. This section answers what to build and in what order. Section 6 — Constraints: The explicit rules from lesson 7 — naming conventions, permitted libraries, architectural rules. This section prevents drift. Together these six sections contain every decision that matters. Omitting a section means an implementer must make that decision themselves — and they may make it differently than you intended.

Writing a build spec for AI-assisted building has a specific technique: the spec doubles as a prompt template. The architecture section — particularly the component list and data model — is copied verbatim as the context header for every implementation prompt. The task entry from the task list is the body of the prompt. The constraints section becomes the closing rules of the prompt. This structure means every prompt is grounded in the same shared context, which is the primary reason well-planned AI-assisted projects produce coherent codebases. Here is an example of how a task entry from a build spec maps to an AI prompt: Spec Task Entry: Task 4: Implement the createTask API endpoint. Output: POST /api/tasks accepts a JSON body with fields title (string, required), description (string, optional), dueDate (ISO 8601 string, optional), and projectId (UUID, required). Validates all inputs. Inserts a new task record. Returns the created task with its generated ID. Returns 400 on validation failure, 403 if the calling user does not own the specified project, 201 on success. Depends on: Task 1 (tasks table schema), Task 2 (projects table schema), Task 3 (auth middleware). Derived AI prompt: [Architecture context header: component list, data model, technology stack] Implement Task 4: the createTask endpoint. POST /api/tasks. Accepts title (string, required), description (string, optional), dueDate (ISO 8601 string, optional), projectId (UUID, required). Validate all inputs — return HTTP 400 with an error message on validation failure. Check that the authenticated user owns the project with the given projectId — return HTTP 403 if not. Insert the task and return HTTP 201 with the full task record including its generated ID. Use the existing database client from db.js. Follow the project naming conventions. Do not introduce new dependencies. Notice that the AI prompt is almost a direct expansion of the spec task entry, with the architecture context prepended and the constraint rules appended. Writing the spec and writing the prompts are essentially the same work.

Common Spec Failures and How to Avoid Them

Three failure modes appear consistently in student build specs. The vague requirement: "Users should be able to manage their tasks" is not a requirement. How many tasks? What does 'manage' include — create, edit, delete, reorder, archive? What happens if a task has subtasks? Every vague requirement will force a decision later, made under pressure and without deliberation. The fix: make every requirement testable. If you cannot write an automated test for it, it is not specific enough. The missing failure case: Requirements often specify the happy path — what happens when everything works — and say nothing about errors. What happens when a user submits a form with missing fields? When an API call times out? When a user tries to access a resource they do not own? AI-generated code, prompted without failure-case specifications, tends to handle only the happy path. The fix: for every functional requirement, write at least one failure-case requirement alongside it. The implicit dependency: A task description assumes context that is not stated. "Implement the comment feature" assumes the reader knows what a comment is, what data it stores, how it relates to posts, and who can create or delete one. When an AI receives an implicitly dependent prompt, it guesses — and guesses wrong in proportion to what you left out. The fix: every task description must state its inputs, outputs, and any predecessor tasks, explicitly. A spec that avoids these three failures will produce AI outputs that require substantially less revision. The revision time you save far exceeds the time spent writing a precise spec.