Run legacy change cycle

老项目改造验收闭环

把一句话需求转成有证据、有门禁、有测试、可验收、可复盘的一次完整改造。核心原则是：先确认现状，再定需求和方案；产品决策归用户，证据充分的执行工作自主推进。

第一次创建文档前，以及生成最终复盘前，完整读取 references/full-cycle-template.md。

执行契约

• 只在 G0–G4、破坏性操作、新依赖、范围扩大、Characterization Test 失败或同一错误连续三次失败时暂停。
• 不因普通技术细节逐步询问用户。优先从项目证据、现有模式和已批准方案中得出答案。
• 不替用户决定产品政策、范围、权限语义、数据可恢复性、部分成功策略或破坏性兼容方案。
• 不做与需求无关的重构。优先复用和调用现有方法；无法完成需求时，只做方案已覆盖的最小必要修改。
• 不新增依赖、不执行破坏性数据操作、不扩大范围，除非用户明确批准。
• 测试断言来自实际行为、已批准合同和可复现证据，不能来自“应该如此”的猜测。
• 不把基线失败、未执行测试、自动浏览器检查或文档更新描述成已经通过人工验收。
• 每个阶段完成后自行检查完整性和一致性；不合格则自行修订，不触发额外问答。

入口与恢复

接受一句话需求、内联规格，或本 Skill 之前生成的需求目录。先定位项目根目录并读取实际存在的项目说明、文档、构建清单、配置和相关代码，不要求项目必须同时拥有 AGENTS.md 和 CLAUDE.md。

为功能生成稳定的 kebab-case <feature>，默认使用：

docs/requirements/<feature>/
├── requirement.md
├── solution.md
└── summary.md

三个文档不竞争同一个全局状态，状态归属固定如下：

• requirement.md 只维护 需求状态、G0/G1 记录和产品决策；在 solution.md 创建前，它是恢复入口。
• solution.md 从方案起草开始维护唯一的 当前阶段、最近完成门禁、下一动作 和逐批实施记录；G2 到 G4 以及文档同步期间，以它为流程状态权威。
• summary.md 只在收尾时维护 最终状态，不反向覆盖前两份文档的历史状态。

恢复时按 solution.md（若已存在）→ requirement.md → 门禁原话、决策表、测试证据和实施记录的顺序核对，从第一个未完成阶段继续。若文字状态与证据冲突，以门禁记录和可复现证据为准，先修正文档状态再执行；不得凭冲突状态继续，也不得重复已确认的门禁。只有需求身份、范围或证据已经变化时，才说明原因并重新打开相关门禁。旧的平铺需求文档可以作为输入，但新产出仍进入功能目录。

门禁表

门禁	必须等待的输入	通过后动作
G0 现状确认	用户确认功能不存在；若已存在，用户选择新增、重构或优化	起草需求
G1 需求决策	用户统一决定业务目标修正、Bxx 边界政策和范围	需求定稿
G2 方案决策	用户审核 solution.md 第 7 节的阻塞 Dxx	方案定稿并开始实施
G3 改造前留档	用户确认已保存或提供改造前截图	开始前端改造
G4 浏览器验收	用户按验收场景确认结果，或提供缺陷反馈	同步文档并复盘

自动化截图、接口探测和页面检查只能提供证据，不能代替 G0、G3 或 G4 的用户确认。如果项目没有 Web UI，明确记录该事实，并把 G0/G4 改为用户通过实际 API、CLI 或客户端确认；不得虚构浏览器入口。

第零步：确认现状（G0）

1. 先读取并核对实际存在的项目说明、架构、接口、数据模型、运行方式和相关代码。人已评审过的文档优先；文档与代码冲突时同时保留冲突证据，不把旧文档当事实。
2. 只读追踪入口：菜单、路由、页面、API 或等价客户端路径。
3. 搜索同名、同义和相邻能力，判断功能是不存在、部分存在还是已经存在。
4. 告诉用户最短可复现路径，提醒其打开产品检查。
5. 暂停并记录用户原话：
   • 确认不存在：进入需求拆解。
   • 已存在或部分存在：要求用户选择新增、重构或优化，并据此重新界定目标。

如果 G0 发现的是改造前已经存在的项目文档漂移，先在 requirement.md 记录差异，再用代码、配置和用户确认纠正对应的当前事实文档，并记录修改证据。此时只能回填“当前真实行为”，不能提前写入尚未实施的目标行为；涉及产品政策、架构方向或范围选择时仍须等待相应门禁。

不得因为期限紧、用户要求“直接编码”或代码搜索没有命中而跳过 G0。

第一步：六维需求拆解（G1）

读取最小但充分的证据集：项目说明、docs/、README、相关前后端代码、接口、模型、迁移、权限、错误处理和测试。先写一句话摘要，再严格按文章的六维顺序生成 requirement.md：

1. 业务目标：谁受益、解决什么问题、可观察的结果。
2. 用户场景：角色、触发条件、当前痛点、期望体验和主流程。
3. 可观察契约：适用的 UI 行为，以及 API 的方法、路径、输入、成功输出、错误码/错误行为、权限或事件合同。
4. 边界场景：空值、非法值、重复、未找到、越权、上限、并发、陈旧数据、部分失败、重试/幂等、兼容和删除语义等。非平凡需求至少列 8 项；每项必须有明确期望或 [待产品决策]。若证据表明不足 8 项，写明为何该需求简单及已穷尽的检查类别。
5. 老项目约束：架构、接口、数据、安全、迁移、依赖、历史行为和兼容约束；每项都给 path:symbol、path:line 或权威文档来源，并说明对本需求的影响。
6. 范围边界：分成“本次包含”“本次明确排除”“后续候选”和“尚未解决”。尚未解决且会改变交付结果的事项必须进入 G1，不能藏进后续候选。

在六维之后补充可测试的验收标准。把事实标成 已确认 或 代码推断；把需要产品判断的事项编号为 B01、B02。禁止把权限、删除语义、部分成功、上限、兼容策略等高影响选择伪装成技术默认值。

一次性整理全部业务目标修正、边界政策和范围问题后触发 G1；只让用户拍板这三类产品判断。收到反馈后统一回填六维、契约、边界、验收与范围章节，清除已解决标记并保留决策记录；所有阻塞 Bxx 和“尚未解决”范围项解决后，才把状态改为 需求定稿。

第二步：拆解方案（G2）

只有需求定稿后才能设计方案。追踪用户入口到前端、API、认证、校验、Service、数据访问、缓存、队列、外部服务和存储的完整往返，同时检查事务、并发、幂等、多租户、配置、日志、监控、发布和回滚。

按模板生成固定七节的 solution.md：

1. 需求与方案概要。
2. 现状链路和代码证据。
3. 目标链路及 Mermaid 流程图。
4. P01、P02 改造点清单。
5. 影响和风险。
6. 实施批次、测试、文档与回滚计划。
7. 待审核的关键决策点。

每个 Pxx 必须包含范围、文件或符号、复用依据、依赖、验证和风险。没有数据变化时明确写“不改表、不迁移”。只有真实取舍才创建 Dxx，并把所有未决项集中到第 7 节。

触发 G2 等待审核。用户反馈后必须同步修订链路、改造点、风险、批次、验证和回滚，不能只改第 7 节；若决策改变了可观察契约、验收或范围，还要同步回填 requirement.md。此阶段只把目标行为写入需求和方案，项目级 API、模型、架构、配置等“已实现文档”仍保持当前事实，不得把计划伪装成已发布行为。阻塞决策全部解决且章节一致后，把状态改为 方案定稿，待实施。

第三步：后端小步改造

先检查 solution.md 的 Pxx。若有后端、数据、服务端配置、迁移或后端测试改造点，执行本节全部规则；若经链路证据确认完全不涉及这些区域，在 solution.md 记录“后端阶段不适用”、依据和跳过的验证，不创建虚假的后端基线或 Characterization Test，直接进入下一适用阶段。

识别真实命令

从仓库证据选择命令，禁止根据模板猜技术栈：

证据示例	候选命令
pom.xml / Maven Wrapper	./mvnw test 或项目约定的 mvn test
build.gradle* / Gradle Wrapper	./gradlew test
pyproject.toml、pytest.ini、测试目录	项目环境中的 python -m pytest
package.json + lockfile	对应 npm、pnpm、yarn 或 bun 脚本
go.mod	go test ./...

优先使用 README、CI、Wrapper 和包脚本中的项目标准入口。安装清单中已有的依赖不算新增依赖，但修改依赖清单仍需用户批准。

建立基线和 Characterization Test

1. 改业务代码前运行可识别的后端全量测试，记录命令、环境、收集数、通过、失败、跳过、错误和耗时。
2. 实际探测受影响的现有行为，再编写最小 Characterization Test 锁定它。
3. 先让 Characterization Test 在未改业务代码时通过。任一 Characterization Test 在改造前或任一批次后失败，都立即停止业务改造；只允许做只读诊断并报告实际输出、与基线的差异和可能原因，然后等待用户决定。不得套用“同一错误连续三次”的普通失败重试规则。
4. 不为让测试变绿而改业务行为、放宽断言或把真实依赖全部 mock 掉。

全量基线可以存在与本需求无关的历史失败，但必须明确隔离；只有受影响链路的 Characterization Test 可运行且为绿时才可继续。最终不得引入新的失败。

按改造点分批

• 按真实依赖把 Pxx 分为每批 1–3 项。
• 恰好存在 P01–P06 时，默认使用 P01–P03、P04–P05、P06；依赖冲突时以方案中的依赖顺序为准并记录原因。
• 每批执行：实现最小改动 → 运行 Characterization Test → 运行相关单元/集成测试 → 自查差异 → 记录结果。
• 当前批未通过，不得进入下一批。
• 除 Characterization Test 外的普通实现、单元/集成测试、构建或类型检查失败，先定位再做方案范围内的最小修复；同一错误连续三次仍失败，暂停并列出三次尝试、证据和需要用户决定的最小事项。
• 每批通过后立即在 solution.md 回填 Pxx 状态、实际改动、测试结果和方案偏差；不能等最终复盘才补实施记录。

完成后运行后端全套测试，准确报告收集、通过、失败、跳过和启动/收集错误。无法从工具输出取得某项数字时写“未知”并保留原始证据，不估算数字。

第四步：前端改造与验收（G3、G4）

如果 Pxx 包含前端改动：

1. 根据路由和菜单代码给出准确入口，触发 G3，等待用户确认已保存或提供改造前截图。
2. 只实现方案批准的交互和合同，复用现有组件、请求封装、状态和样式。
3. 运行项目已有的相关单测、类型检查和生产构建；不要运行会自动改写文件的 lint/format 命令，除非改写范围已经确认。
4. 给出浏览器验收路径、主场景、边界场景和预期可观察结果，触发 G4。
5. 用户反馈缺陷时自主复现、修复、重跑验证，再次交回 G4；没有用户确认不得宣称验收完成。

如果方案有证据表明不涉及前端，在 solution.md 和 summary.md 记录“不适用”及依据，不制造截图门禁。

第五步：同步文档并复盘

文档回填不是只在最后发生，按事实成熟度执行：

时点	必须回填	允许写入的事实
G0 后	requirement.md；发现既有漂移时同步对应项目文档	改造前现状、入口、用户确认、经证据核实的当前事实
G1 后	requirement.md	用户确定的业务方向、边界政策、范围和验收
G2 后	solution.md；契约/范围受影响时回填 requirement.md	已批准的目标与计划；不得写成已实现
每个实施批次后	solution.md	Pxx 状态、实际差异、验证结果、风险变化
G4 通过后	所有受实际改动影响的项目文档	已实现、已测试、已由用户验收的行为
最终审计后	summary.md	全部证据、偏差、遗留风险和最终状态

G4 通过后，先从实际差异识别受影响的文档，而不是只检查固定文件名：

• API 合同变化：更新 docs/api-list.md 或项目等价 API 文档。
• 表、字段、枚举、迁移或持久化模型变化：更新 docs/data-model.md、Schema/ER 图或等价模型文档。
• 模块边界、依赖或部署拓扑变化：更新架构图、模块依赖图、部署说明或 README 中对应章节。
• Workflow、异步任务、关键调用顺序或数据流变化：更新对应流程图、时序图和运行说明。
• 配置项、环境变量、启动命令、测试入口或运维方式变化：更新配置样例、README、测试/运维文档；不得复制真实密钥。
• 权限、安全、多租户、发布、监控或回滚约束成为稳定项目规则：更新已有的 CLAUDE.md、AGENTS.md 或等价项目说明；不因文件缺失强制创建。
• requirement.md 回填最终实现偏差和 G4 验收结果；solution.md 回填最终 Pxx、测试和文档同步结论。
• 某类文档没有变化时，在 summary.md 写“不需要更新”、判断依据和检查过的文件，不做占位修改。

文档修改完成后做只读漂移审计；可使用现有的报告型文档审计 Skill，但不能让只读审计工具代替实际编辑。确保需求、方案、代码、测试和文档描述的是同一事实。

最后按模板生成 summary.md，列出所有产出、用户重点复核项、决策、批次、测试计数、构建结果、截图和浏览器确认、调试尝试、文档同步、遗留风险与回滚方式。最终状态只能是：

• 完成：所有适用门禁和验证通过，且没有新增失败。
• 带已知基线风险完成：本次验证通过，但仍有证据充分、与本改造无关的历史基线问题。
• 阻塞：任一必需门禁、Characterization Test 或验证无法完成。

关键决策与非决策

必须暂停的关键决策包括：业务政策、范围、权限语义、数据删除/恢复、部分成功、公共合同破坏、迁移与回填、不可逆操作、新依赖、重大架构取舍和发布风险接受。

不应打扰用户的事项包括：有代码证据的命名与目录、使用已有工具函数、项目标准测试命令、实现细节中的等价写法、失败诊断和方案范围内的最小修复。

完成检查

报告完成前逐项确认：

• G0–G4 中所有适用门禁都有用户确认记录。
• requirement.md、solution.md 和实际实现一致。
• 所有 Bxx、阻塞 Dxx 和 Pxx 都有闭环状态。
• 所有适用的 Characterization Test 在改造前为绿，且每个后端批次后仍为绿；后端不适用时有链路证据。
• 适用的后端全量测试和前端构建结果有新鲜证据和准确计数；不适用项有明确依据。
• 没有新增失败、无关重构、未经批准的新依赖或范围扩大。
• 条件性文档同步和只读漂移审计已完成。
• summary.md 明确用户应重点复核的位置和剩余风险。

任一项不满足时继续修复，或以 阻塞 状态暂停；不得提前宣布完成。