# 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 后的结构与命名更清晰，不是更复杂