mirror of
https://github.com/github/spec-kit.git
synced 2026-07-03 12:28:06 +08:00
93 lines
4.3 KiB
Markdown
93 lines
4.3 KiB
Markdown
# Evolving Specs in Existing Projects
|
|
|
|
Existing projects need two separate maintenance loops:
|
|
|
|
- **Spec Kit project-file updates** refresh managed commands, scripts,
|
|
templates, and shared memory files.
|
|
- **Feature artifact evolution** keeps repository-specific `specs/` artifacts
|
|
aligned with the code and product behavior you intend to ship.
|
|
|
|
Use the [upgrade workflow](../upgrade.md) when you need newer Spec Kit project
|
|
files. Use one of the artifact persistence models below when requirements or
|
|
implementation insights change an existing project.
|
|
|
|
For the conceptual model definitions, see
|
|
[Spec Persistence Models](../concepts/spec-persistence.md).
|
|
|
|
## Flow-Forward Spec
|
|
|
|
Use flow-forward when each feature directory should remain a historical record.
|
|
|
|
When you add another feature or make a substantial follow-up change, create a
|
|
new feature spec through your installed `/speckit.specify` command and continue
|
|
through the standard flow:
|
|
|
|
1. Run `/speckit.specify` to create a new feature directory under `specs/`.
|
|
2. Run `/speckit.plan` to define the implementation approach.
|
|
3. Run `/speckit.tasks` to derive the work breakdown.
|
|
4. Run `/speckit.implement` and review the resulting code and artifact diffs.
|
|
5. Run `/speckit.converge` to verify completeness and generate tasks for remaining gaps. If tasks are appended, repeat `/speckit.implement` and `/speckit.converge` until the feature is fully complete.
|
|
|
|
The previous feature directory remains intact for audit, comparison, or
|
|
explaining how the project reached its current state. Use clear feature names or
|
|
cross-links when a new directory supersedes or extends earlier work.
|
|
|
|
## Living Spec
|
|
|
|
Use living spec when `spec.md` is the contract and `plan.md` and `tasks.md` are
|
|
derived from it.
|
|
|
|
When intended behavior changes, revise the existing `spec.md` first. Then
|
|
regenerate or manually revise downstream artifacts so they match the updated
|
|
spec:
|
|
|
|
1. Start from a clean working tree or a dedicated branch so every generated
|
|
change is reviewable.
|
|
2. Update `spec.md` with `/speckit.clarify` or an explicit edit.
|
|
3. Rerun `/speckit.plan` or revise `plan.md` so the technical approach matches
|
|
the revised spec.
|
|
4. Rerun `/speckit.tasks` or revise `tasks.md` so implementation work matches
|
|
the revised plan.
|
|
5. Run `/speckit.analyze` before implementation resumes to catch gaps between
|
|
the spec, plan, and tasks.
|
|
6. Run `/speckit.implement`, then review the code and artifact diffs together.
|
|
7. Run `/speckit.converge` to assess completion and append any remaining work to `tasks.md`. If tasks are appended, repeat `/speckit.implement` and `/speckit.converge` until the feature is fully complete.
|
|
|
|
Preserve important implementation rationale before replacing derived artifacts.
|
|
If a plan or task list contains decisions that still matter, carry them forward
|
|
explicitly.
|
|
|
|
## Flow-Back Spec
|
|
|
|
Use flow-back when implementation discoveries are allowed to reshape the
|
|
artifact set.
|
|
|
|
In this model, the first useful edit can happen wherever the insight lands:
|
|
`spec.md`, `plan.md`, `tasks.md`, or the implementation. After the change, bring
|
|
the artifact set back into alignment:
|
|
|
|
1. Capture the discovery in the artifact closest to the work.
|
|
2. Decide whether it changes intended behavior, implementation strategy, task
|
|
breakdown, or only code.
|
|
3. Update any other artifacts that now disagree with the accepted direction.
|
|
4. Run `/speckit.analyze` to check for gaps across `spec.md`, `plan.md`, and
|
|
`tasks.md`.
|
|
5. Continue implementation only after the artifact set describes the behavior
|
|
and approach you want future contributors to trust.
|
|
|
|
Flow-back is flexible, but it requires discipline. Do not leave a lower-level
|
|
change in `tasks.md` or code if `spec.md` still says something different and the
|
|
spec is meant to remain trustworthy.
|
|
|
|
## Before Updating Spec Kit Project Files
|
|
|
|
Before refreshing Spec Kit project files with the terminal command
|
|
`specify init --here --force --integration <your-agent>`, protect any
|
|
project-specific material that lives outside `specs/`, especially
|
|
`.specify/memory/constitution.md` and customized files under
|
|
`.specify/templates/` or `.specify/scripts/`. Use `<your-agent>` for the AI
|
|
coding agent integration used by the target project.
|
|
|
|
Your `specs/` directory is not part of the template package, but shared project
|
|
files can be overwritten by a forced refresh.
|