How do you keep specs aligned with the code after implementation?

[chuthuyquynh38-del]

I've been thinking about what happens to specs once implementation starts moving quickly.

Small fixes, refactors, and new edge cases can easily make the code drift from the original spec. At that point, keeping specs updated manually can become another maintenance task.

How do you handle this in practice? Do you update specs with every meaningful code change, or eventually treat the code as the source of truth?

Also curious whether the agent should be responsible for flagging or updating specs when it notices that drift.

[R3Dzf]

I'd treat specs as a living description of intended behavior, rather than documentation that becomes obsolete once the code is written.

What I'd recommend is a simple rule: if a change affects observable behavior, constraints, or acceptance criteria, the spec should be reviewed alongside the code. Pure refactoring usually doesn't require a spec update.

For an AI-assisted workflow, I'd split the responsibility into three parts:

1. Detect drift: Let the agent compare the code diff against the relevant specs and flag potential mismatches.
2. Propose updates: Have it suggest a spec change when behavior has intentionally changed, ideally in the same PR.
3. Require review: Keep a human responsible for deciding whether the code or the spec represents the intended behavior.

I'd also add a lightweight PR checklist: "Does this change affect documented behavior? If yes, which spec was updated?"

One useful distinction is between implementation details and behavioral contracts. Specs shouldn't need updating every time an internal function changes, but they should stay accurate about what the system promises to do.

That keeps specs useful without turning maintenance into unnecessary overhead.