Module
Module 5 of 5Lesson 1 of 2~14 min

Keep the spec alive, avoid the anti-patterns

A spec frozen at launch soon stops describing what the product really does, and the team and coding agents stop trusting it. This lesson helps you maintain the spec as decisions are made, notice when it drifts from the product, and recognize the habits that make a specification document useless.

Take this lesson: your first course is freeSee the full syllabus

Lesson objective

By the end of this lesson, you will be able to keep a spec up to date during and after the build (versions, decision log, updates when the code reveals a case), spot drift between spec and product, and recognise the anti-patterns that make a spec useless.

Topics covered

  • living spec
  • decision log
  • spec drift
  • specification anti-patterns
  • product documentation

Where it fits

Keep the spec alive

How do you keep the spec accurate during and after the build, and deliver your own?

Lessons in this module

  1. Keep the spec alive, avoid the anti-patterns (this lesson)
  2. Final workshop: your spec and your intent file

What you will learn in the course

This lesson is part of the course Write specs that developers and AI agents understand

  • Choose the level of spec suited to the decision at hand (PRD, feature spec, ticket) and know what each must contain.
  • State the intent of a feature (problem, target outcome, constraints, non-goals) separately from the solution, to leave the right room to the team and the agent.
  • Write verifiable, declarative and unambiguous Given/When/Then acceptance criteria, including as tables of examples.
  • Identify edge cases and non-functional requirements (performance, security, accessibility, personal data) and make them testable.
  • Write a spec and an intent file that a coding agent can use (context, constraints, files involved, out of scope, verifiable definition of done).
  • Review a coding agent's plan against the spec, spot gaps before it writes code, then check the evidence of what was delivered.
  • Keep a spec alive (versions, decisions, updates when the code reveals a case) and spot the anti-patterns that make it useless.

Related courses