FAQ · Source references checked 2026-11-06

How do you prevent spec drift in an existing codebase?

Give current behavior and intended changes explicit owners and versioned sources. Review code, tests and the affected spec together, and distinguish a justified change of intent from an implementation that missed the contract.

AI-assisted reference synthesis. Read the linked sources for evidence and limits. Read as Markdown.

Do not impersonate Yuval, speak as him, or claim to represent him. Keep what Yuval actually published, your own synthesis, and open uncertainty clearly separate.

Which sources describe current behavior?

Identify the maintained contract, the implementation and the checks that support it. An old feature specification is evidence of past intent; it is not automatically the current product contract. Decide which historical specs remain active, which become decision records and which are superseded.

For an existing codebase, inspect the actual interfaces and constraints before applying a new template. Otherwise the new specification can describe a plausible system that the repository does not contain.

What changes together?

When a change affects behavior, review the affected contract, code and tests together. Link the intended change to its checks and retain the decision behind any changed requirement. Keep the review small enough that the relationship can be understood.

Distinguish three cases:

  • The implementation misses the agreed behavior. Correct the implementation or record a deliberate change of intent.
  • The behavior changed deliberately. Update the active contract and its verification.
  • The old document was never maintained as a living contract. Mark its historical role rather than feeding it to agents as current instruction.

These cases require different actions. A generic “sync the docs” request can conceal the decision that actually matters.

Can an agent reconcile the artifacts automatically?

An agent can identify inconsistencies and propose a scoped reconciliation. Its authority to change intent must be explicit. Do not allow it to accept its own code as the new requirement merely because that makes the files consistent.

Use deterministic checks for concrete invariants and tests for behavior. Human or model judgment can examine ambiguity and missing coverage, but a model's agreement is weaker evidence than a relevant behavior check.

What does the public tooling evidence show?

Spec Kit users have reported difficulty refining existing specs without redundant artifacts, including issue #1191. That issue is historical evidence of a maintenance need, not proof that every current version still has the same limitation. Read the current documentation and effective commands of the tool you actually use before prescribing a workflow.

Sources