skills/cc-switch-dev-workflow/references/knowledge-base/playbooks/existing-project-spec-backfill-and-refactor.md

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/spec-template.md
• ../templates/acceptance-checklist-template.md

Stable Knowledge Vs Runtime Context

• 稳定知识：规范结构、重构节奏、架构审计方式
• 运行时上下文：当前代码病灶、当前历史文档、当前遗留约束

First-Round Prompt Kit

Prompt 1: Baseline

读取当前代码库和现有文档，识别主要模块、边界问题、技术债和缺失的项目执行说明。输出 Setup/Research 的基线评估，不做代码修改。

Prompt 2: Spec Backfill

基于代码现状、历史文档和基线评估，产出 ANALYSIS.md、TODO.yaml 和 SPECS/*.md。Spec 只定义系统契约，不复制实现细节；产出后执行 spec-reviewing，并列出人工审核项。

Prompt 3: Refactor Roadmap

基于已审核通过的 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 后的结构与命名更清晰，不是更复杂