88 行
2.9 KiB
Markdown
88 行
2.9 KiB
Markdown
# Playbook: Existing Project Spec Backfill And Refactor
|
||
|
||
## Purpose
|
||
为已有代码库补齐 `SPECS/`、重新建立规则层，并把缺失的结构化重构纳入正式流程。
|
||
|
||
## When to Use
|
||
- 老项目没有完整 Spec
|
||
- 代码能跑，但规则、边界和设计意图不清
|
||
- 团队准备把维护项目迁入标准 AI Agent 流程
|
||
|
||
## Inputs
|
||
- 现有代码库
|
||
- 历史文档和会议纪要
|
||
- 测试现状
|
||
- 当前问题清单
|
||
|
||
## Outputs
|
||
- 补齐后的 `CLAUDE.md`
|
||
- `.research/*.md`
|
||
- `SPECS/*.md`
|
||
- 重构和补齐计划
|
||
|
||
## Primary Agent/Model
|
||
计划 agent + `GPT-5.4 Pro xhigh`
|
||
|
||
## Secondary Agent/Model
|
||
审查 agent + `Claude Opus 4.6`
|
||
|
||
## Required Skills
|
||
- `spec-tasking`
|
||
- `spec-reviewing`
|
||
- `code-refactoring`
|
||
- `architecture-audit`
|
||
|
||
## Steps
|
||
1. 先做 `Setup`，补 `CLAUDE.md` 和技术轨道。
|
||
2. 从现有代码与历史文档反推 Research 结论。
|
||
3. 编写并审核 `SPECS/*.md`。
|
||
4. 对照 Spec 跑 `Alignment`，把现状和规则重新对齐。
|
||
5. 跑 `Refinement`，收掉结构债和命名债。
|
||
|
||
## Exit Criteria
|
||
- 老项目已经具备规范层、任务层和审查门禁
|
||
- 后续新需求可以按标准 7 阶段继续推进
|
||
|
||
## Failure Recovery
|
||
- 如果代码库过于混乱无法直接写 Spec，先用 Research 做领域切片
|
||
- 如果团队试图直接大改代码而不补 Spec，回到本 playbook 的 Spec 阶段
|
||
|
||
## Related Templates
|
||
- [`../templates/claude-md-template.md`](../templates/claude-md-template.md)
|
||
- [`../templates/spec-template.md`](../templates/spec-template.md)
|
||
- [`../templates/acceptance-checklist-template.md`](../templates/acceptance-checklist-template.md)
|
||
|
||
## Stable Knowledge Vs Runtime Context
|
||
- 稳定知识：规范结构、重构节奏、架构审计方式
|
||
- 运行时上下文：当前代码病灶、当前历史文档、当前遗留约束
|
||
|
||
## First-Round Prompt Kit
|
||
|
||
### Prompt 1: Baseline
|
||
```text
|
||
读取当前代码库和现有文档，识别主要模块、边界问题、技术债和缺失的项目执行说明。输出 Setup/Research 的基线评估，不做代码修改。
|
||
```
|
||
|
||
### Prompt 2: Spec Backfill
|
||
```text
|
||
基于代码现状、历史文档和基线评估，产出 ANALYSIS.md、TODO.yaml 和 SPECS/*.md。Spec 只定义系统契约，不复制实现细节；产出后执行 spec-reviewing，并列出人工审核项。
|
||
```
|
||
|
||
### Prompt 3: Refactor Roadmap
|
||
```text
|
||
基于已审核通过的 SPECS/*.md 和现有代码，生成 Alignment 与 Refinement 的任务序列。优先补齐缺口，再收敛结构问题，不做无依据的大改。
|
||
```
|
||
|
||
## Stage Deliverables
|
||
- Setup：补写 `CLAUDE.md`、确认轨道与边界
|
||
- Research：反向整理 `.research/*.md`
|
||
- Spec：形成 `SPECS/*.md` 并完成人工审核
|
||
- Alignment：对齐现有实现与 Spec
|
||
- Refinement：全局简化、重构、架构审计
|
||
|
||
## Acceptance Checklist
|
||
- 老项目已有清晰的 `CLAUDE.md`
|
||
- `SPECS/*.md` 不是代码镜像，而是系统契约
|
||
- Alignment 后没有高优先级缺口残留
|
||
- Refinement 后的结构与命名更清晰，不是更复杂
|