Living Specs
By the Syncfusion DevTutorials team · Last updated
Keep the spec true after it ships: change the spec and its check together, find drift between spec and code, and judge the outcome by its own measure, turning a miss into a new intent.md.
The Spec Went Stale
The feature shipped.
The tests passed. The team moved on.
Then things changed:
- The stakeholder raised the row limit, but only said it in a chat.
- A later update changed the date format.
- Weeks later, the reports still took too long.
The spec still described release day.
It no longer described what the code does today.
Simple lesson: a spec is only useful while it is still true.
A Real-World Example
A kitchen keeps a recipe card for its soup.
The chef uses less salt now, but nobody updates the card.
A new cook follows the card. The salty soup is back.
A spec is the recipe card. If you change the soup, change the card too.
A change request mid-build
Click the button and open the change request.
- The change: the row limit goes from 100,000 to 250,000.
- Before you edit: press Check my spec. One line still says 100,000.
If the agent runs now, it builds the old limit again.
Simple lesson: when the plan changes, change the spec. Otherwise the agent keeps building the old plan.
TL;DR
- Living spec = a spec you keep up to date after the feature ships.
Change request = the stakeholder asks for something different.
- Update the requirement.
- Update its acceptance criterion in the same edit.
Drift = the spec and the code no longer agree.
- If the change was agreed → update the spec.
- If it was an accident → fix the code.
- Outcome = the result the user really needed.
- Passing tests show the code matches the spec. They do not show the outcome happened.
- Measure the outcome after release.
- If the outcome was missed, write a new
intent.mdwith the numbers you measured.
What You Will Learn
In this lesson, you will learn:
- What a living spec is.
- How to handle a change request.
- How to find drift and fix the right side.
- How to check the outcome after release.
- How a missed outcome becomes a new
intent.md.
About the examples in this lesson
- The change requests, drift reports and numbers are fixed examples.
- Simple rules check your work. No AI model grades it.
Change Requests
When behavior changes, update the specification first so future work starts from the latest truth.
Change the Spec, Not Just the Chat
Stakeholders change their minds. That is normal.
When they do, write the change in spec.md.
A chat message lives in one conversation only.
The spec is what every future run, developer and reviewer reads.
If the spec does not change, the old behaviour still looks correct.
Change the Check Too
A requirement and its acceptance criterion are a pair.
If one changes, the other must change too.
Example:
- REQ-2 now says the limit is 250,000 rows.
- AC-4 still checks for 100,000 rows.
Now the spec and its check disagree.
The new code fails the old check. Or the old code passes it, and nobody notices.
Important: the check must also reach the new limit. A test with 120,000 rows never gets near 250,000.
Watch the change request, one edit at a time:
The requirement and the check changed together. Now the next run builds and tests the new limit.
When a limit goes up, move the test up too.
- Give the check more rows than the new limit.
- If you do not, the check passes for every build and checks nothing.
Simple lesson: change the requirement and its check in the same edit.
Drift
When the Spec and the Code Disagree
Drift = the spec says one thing, but the code does another.
Drift happens slowly:
- Features grow.
- Code gets cleaned up.
- Quick fixes go in.
For each drift, ask one question:
Did the team agree to this change?- Yes → the spec is out of date. Update the spec.
- No → the code is wrong. Fix the code.
Example:
- The stakeholder agreed to a bigger limit → update the spec.
- A clean-up started exporting hidden columns by accident → fix the code.
Watch a drift review, one requirement at a time:
Each requirement got one of three answers: OK, update the spec, or fix the code.
Simple lesson: do not always trust the code. Ask if the change was agreed.
Lab Exercise: Find the Drift
Read the drift report.
For each requirement, choose one answer:
- OK
- Update the spec
- Fix the code
Find the drift
Press Check my spec when you are done.
Did the Outcome Happen?
Green Tests Are Not the Goal
Earlier, you wrote an outcome like this:
The Monday report takes under 10 minutes with zero manual fixes.Passing tests prove the code matches the spec.
They do not prove the user's problem is solved.
To know that, you measure after release.
Example, four weeks later:
- The report still takes 35 minutes.
- 9 of 12 reports still need manual fixes.
The code works. The outcome was missed.
Watch what happens after release:
All the tests passed, but the outcome was missed. The numbers became the start of a new intent.md.
A Miss Becomes a New intent.md
A missed outcome is not the end.
It is new information.
The numbers show the next problem to solve.
Example:
9 of 12 reports still require manual fixes.That line becomes evidence in a new intent.md.
The user is the same. The problem is new.
In simple words: intent leads to a spec. The spec leads to code. The code gets measured. The numbers lead to the next intent.
Lab Exercise: Did the Outcome Happen?
Read the target and the numbers.
Then write two things:
- a verdict: was the outcome met or missed?
- a follow-up
intent.md
Did the outcome happen?
Press Check my spec when you are done.
Your answer needs:
- a verdict;
- a Problem line that quotes the numbers;
- a new Outcome with a number.
Quote a number in the new Problem line.
For example: "9 of 12 reports still needed manual fixes." The number proves the problem is still real.
What Changes per Tool
| Tool | How to keep the spec up to date |
|---|---|
| Claude Code, Codex, Cursor | Update docs/specs/<feature>/spec.md in the same pull request as the code |
| Spec Kit | Update spec.md, then make the plan again |
| Kiro | Update requirements.md, then refresh the files that depend on it |
The rule is the same in every tool:
When the behaviour changes, update the spec in the same change.
Common Mistakes
| Mistake | Wrong idea | Correct idea | What goes wrong |
|---|---|---|---|
| Changing it only in chat | "Everyone saw the message." | Update spec.md. | The next run builds the old limit. |
| Changing the REQ but not the AC | "The check is close enough." | Change both in the same edit. | The check tests the old behaviour. |
| A test below the new limit | "It still passes." | Test with more rows than the limit. | It passes for every build. |
| Always updating the spec | "The code is the truth." | Ask if the change was agreed. | Accidents become the spec. |
| Thinking green means done | "Tests pass, so we are done." | Measure the outcome. | The real problem stays. |
| Stopping after a miss | "It did not work. Move on." | Write a follow-up intent.md. | Nobody learns why it failed. |
Exercises
These exercises help you practise keeping a spec up to date.
Press Check when you are ready. Use Show Hint if you get stuck.
What to Remember
- A spec is only useful while it is still true.
- Agreed changes go into the spec.
- Change a requirement and its check together.
- Drift means the spec and the code disagree.
- Agreed drift → update the spec.
- Accidental drift → fix the code.
- Passing tests do not prove the outcome happened.
- Measure the outcome after release.
- A missed outcome starts a new
intent.md.
Further Reading
- Anthropic Academy: courses on Claude Code, including the AI-native SDLC playbook this course builds on.
- Understanding Spec-Driven Development, by Birgitta Böckeler: spec-first, spec-anchored and spec-as-source.
- Kiro specs: updating requirements and refreshing tasks.
Next: Team Templates. You will learn how to turn your spec habits into templates the whole team can use.