| name | project-evolution |
| description | Manage project evolution over time: feature lifecycle, ADR decisions, roadmap, technical debt, known issues, refactor candidates, release notes, upgrade history, and durable development process records. Use when adding features, planning upgrades, changing architecture, stabilizing a project, or keeping long-term project knowledge current. |
Project Evolution
Purpose
Turn project work into durable, searchable development history.
Maintenance keeps current references accurate. Evolution records why the project changed, what risks remain, and what should happen next.
Use with project-assistant so evolution records are triggered automatically after meaningful implementation, not only during planning.
Read Before Work
Read evolution docs before:
- Planning a feature or upgrade.
- Changing architecture, module boundaries, API contracts, database schema, auth, deployment, or release flow.
- Fixing recurring bugs.
- Refactoring code with known debt.
- Deciding what to implement next.
Minimum read set when present:
.ai_project.mddocs/roadmap/roadmap.mddocs/changelog/development-log.mddocs/maintenance/technical-debt.mddocs/maintenance/known-issues.mddocs/maintenance/refactor-candidates.md- Relevant
docs/decisions/ADR-*.md
Recommended Docs
docs/
roadmap/
roadmap.md
maintenance/
technical-debt.md
known-issues.md
refactor-candidates.md
decisions/
ADR-0001-title.md
changelog/
development-log.md
Feature Lifecycle
Track meaningful features with:
planned: agreed direction, not started.in-progress: implementation started.implemented: code exists.verified: tested or manually verified.released: shipped or ready for distribution.deprecated: replaced or intentionally retired.
Record feature name, status, owner/module, key files, related docs, verification, open risks, and next step.
ADR Triggers
Create or update an ADR when:
- Introducing a new framework, database, major library, runtime, or deployment path.
- Changing module boundaries or architecture style.
- Changing auth, security model, packaging, or release strategy.
- Choosing between meaningful alternatives.
- Accepting notable tradeoff or technical debt.
ADR shape:
# ADR-0001: Title
## Status
Proposed | Accepted | Superseded
## Context
## Decision
## Consequences
## Alternatives Considered
Technical Debt
Record debt when:
- A shortcut is accepted.
- A file is too large.
- Coupling is known.
- Tests are missing.
- A migration or rollout is incomplete.
Each entry should include area, debt, reason accepted, risk, suggested cleanup, and trigger for cleanup.
Known Issues
Record recurring or unresolved issues with symptom, affected module, reproduction/evidence, current hypothesis, workaround, and next diagnostic step.
Refactor Candidates
Record candidates when:
- A file approaches or exceeds 1000 lines.
- A module owns too many responsibilities.
- Logic is duplicated across features.
- Tests are hard to write because boundaries are unclear.
- API DTOs, UI models, and domain models are mixed.
Development Log
Append only useful milestones:
- Date.
- Change summary.
- Files/modules touched.
- Verification.
- Docs updated.
- Next step.
Avoid noisy command logs and generic summaries.
Project Assistant Handoff
After meaningful work, decide whether to update:
- Feature lifecycle status in
.ai_project.md or docs/roadmap/roadmap.md.
- ADR for important decisions.
- Technical debt, known issues, or refactor candidates.
- Development log for durable milestones.
Do not record routine tiny edits unless they affect future planning, debugging, release, or ownership.
Final Answer Requirements
When evolution docs changed, include:
演进记录：
- 更新 `docs/roadmap/roadmap.md`
- 新增 `docs/decisions/ADR-0002-api-client-boundary.md`
If evolution docs should have changed but did not, state why.
Output Contract
- State the selected workflow, assumptions, and concrete deliverable.
- Include verification, limitations, or next-step handoff when relevant.
- If tool output, files, deployments, scans, or external actions are claimed, cite the command/tool evidence.
