pdlc-refactor
代码重构(保持外部行为不变,改善内部结构)
SKILL.mdskills/pdlc-refactor/SKILL.md
GitHub代码重构
<!-- @include templates/prompts/iron-law.md(已内联于下方,无需另读) -->⛔ IRON LAW · 不可违反的硬门禁
以下规则为不可协商的执行约束:
- 文件必须落盘:所有带编号(功能ID / 缺陷ID)的文档,必须作为实际文件写入磁盘,不可仅在对话中输出。
- 阶段必须落章:每个阶段完成后必须在状态机
docs/.pdlc-state/<feature-id>.json追加 history,不可跳过。 - 测试必须存在:进入
/pdlc-implement前,对应测试必须存在且处于红灯状态。违反则中止。 - 自检必须执行:段二自检为强制步骤,不得以"已经很好了"为由跳过。
- 防循环:段三修复为单次,不递归。无法自动修复的问题记录到报告,继续往下走。
- 状态必推进:成功执行某 phase 后
current_stage必须变更。收尾时若发现current_stage未推进,视为失败并报错,不得静默返回(防止外层循环拿滞后的状态空转烧额度)。唯一例外:命中人工点主动 block 时,current_stage保持不变但必须写last_phase_result.ok=false+blocked_reason。
违反任一条 = 立即中止当前命令,输出违规详情,等待人工介入。
<!-- @include-end templates/prompts/iron-law.md -->对指定服务或模块进行安全重构,保证行为不变。
工作流程
- 确认测试覆盖: 先检查现有测试是否充分,不充分则先补测试
- 阅读设计文档: 阅读
docs/02_design/对应子目录下的相关设计文档 - 识别坏味道: 分析代码中的坏味道(Code Smell)
- 制定重构计划: 列出重构项,按风险排序
- 逐步重构: 每次只做一个小的重构,确保测试通过
- 运行完整测试: 确认没有破坏现有功能
常见重构场景
- 提取方法/类: 过长的方法、过大的类
- 消除重复: DRY 原则,提取公共逻辑
- 简化条件: 复杂的 if-else 链、嵌套条件
- 改善命名: 不清晰的变量名、方法名
- 解耦依赖: 降低模块间耦合度
- 统一风格: 对齐项目编码规范
要求
<!-- @include templates/prompts/output-language.md(已内联于下方,无需另读) -->🌐 Output language for generated artifacts
All generated artifacts (PRDs, design docs, code comments, review reports, test plans, deployment manuals, changelog entries, etc.) follow this policy:
Default — match the conversation language exactly:
- 用户用中文与 Claude 对话 → 产中文文档、中文代码注释、中文报告
- User talks to Claude in English → produce English artifacts
- User talks in another language → produce artifacts in that language
- Never silently default to a fixed language regardless of the user's input.
Explicit override always wins: when the user specifies a language for an artifact (e.g. "write the PRD in English", "用英文写 API 设计文档", "output the deploy doc in Japanese"), use that language for that artifact, regardless of conversation language.
Mixed-language requirements: if the user wants some artifacts in one language and others in a different language (common: Chinese PRD + English API docs for partners), honour each per-artifact instruction.
Uncertain: if you cannot reliably detect the conversation language, ask once before producing the first artifact.
This policy applies to content (prose, comments, headings). It does not override technical conventions like English variable names, English git commit subjects, or English error codes when the project's conventions require them.
<!-- @include-end templates/prompts/output-language.md -->- 重构提交信息格式:
refactor: <简要描述> - 严禁在重构中混入新功能
- 每个重构步骤都要保证测试通过
- 更新 CHANGELOG.md:条目格式
- <简要描述>(<功能ID 或缺陷ID>);[未发布]里已有同一 ID 的条目就不再追加(/pdlc-ship按 ID 去重)
重构目标: $ARGUMENTS
<!-- pdlc:meta 由 frontmatter 生成(adapters/sync_skills.py),勿手改 --><!-- pdlc:meta-end --> <!-- @include templates/prompts/state-update.md(已内联于下方,无需另读) -->本命令的状态机取值:阶段短名
refactor(写进history[].stage与last_phase_result.stage);下一跳pdlc-review(写进next_step,交接时提示)。
状态机更新(段四必须执行)
本命令完成主产出后,必须推进状态机文件 docs/.pdlc-state/<feature-id>.json。
用脚本推进,不要手写状态 JSON
bash scripts/pdlc-advance.sh <功能ID> --stage <本阶段短名> --next <下一跳命令名|null> \
[--produced <产物路径,逗号分隔>] [--autonomous] [--decision "<确认点>=<所选默认>"]... \
[--name <kebab-case>(状态文件还不存在时)] <项目根>
- 脚本是本 skill 自带的
scripts/pdlc-advance.sh。阶段短名与下一跳就是本命令正文里「本命令的状态机取值」那两个值;带了--autonomous就照传 - 检查由脚本自己跑:它按阶段调用同目录的
scripts/pdlc-checks.sh(tdd 验红灯;impl / fix / refactor 跑 unit、coverage、lint; review 再加 e2e;e2e 只跑 e2e;文档类阶段不跑),据此判ok、整段写入 history 与last_phase_result, 写完调用scripts/pdlc-state-lint.sh体检。不要自己先写checks,也不要挑检查项 - tdd 阶段的
--produced必须列出写的测试文件:脚本记下它们的指纹,之后 impl / refactor / review 推进时比对 - 主动交还人类(命中人工点、评审有阻塞项、测试本身有矛盾等)→ 加
--blocked "<原因>":脚本照跑检查、如实记录,但不推进,原因写进blocked_reason /pdlc-ship写ship_done、/pdlc-deploy写deploy_done→ 加--done(只有这两个命令能用)
脚本的退出码决定怎么收尾:
| 退出码 | 含义 | 你要做的 |
|---|---|---|
0 |
已推进 | 交接里引用 stdout 那行 JSON(checks、current_stage、next_step) |
3 |
未推进:检查没过 / 红灯没验证 / 主动 block / tdd 写的测试被改 | 把 stdout 里的 blocked_reason 原样写进报告,按阻塞收尾。不要为了让它推进去改测试或改检查命令 |
2 |
脚本跑不了(参数错、缺 jq、状态文件损坏) | 参数错就改正重跑;缺 jq 才按下面的格式手写,并在报告里写明「状态机未经脚本写入」 |
退出码
3且原因是「tdd 阶段写的测试被改动」:实现阶段不改测试。测试是否真的写错了(与设计 / PRD 矛盾),只有人能判断:
- 交互模式:先把矛盾讲清楚、问人;人同意后再带
--tests-changed "<理由>"重跑,理由记进auto_decisions--autonomous:没有人可问,不要改测试,带--blocked "<矛盾在哪>"收尾。自主模式下带--tests-changed脚本也不推进项目开了 PDLC 护栏(
docs/00_standards/pdlc-hooks.yml)时,用 Write / Edit 直接写状态文件会被拦下。
状态文件格式(读状态时参考;只有脚本跑不了时才照它手写)
{
"feature_id": "<F/B ID>",
"feature_name": "<kebab-case>",
"created_at": "<首次创建时间 ISO 8601>",
"current_stage": "<当前阶段名>",
"run_mode": "interactive | autonomous",
"history": [
{
"stage": "<阶段名>",
"done_at": "<ISO 8601>",
"produced": ["<相对路径 1>", "<相对路径 2>"],
"self_audit": { "passed": <N>, "failed": <N>, "manual": <N> },
"auto_decisions": [
{ "point": "<autonomous 下自动前进的确认点>", "chose": "<所选默认>", "at": "<ISO 8601>" }
]
}
],
"last_phase_result": {
"stage": "<本次阶段名>",
"ok": true,
"advanced_to": "<推进到的下一阶段 | null>",
"checks": {},
"self_audit": { "failed": 0 },
"blocked_reason": null,
"run_mode": "interactive | autonomous",
"at": "<ISO 8601>"
},
"relations": {
"extends": [],
"depends_on": [],
"supersedes": [],
"resolves": [],
"conflicts_with": [],
"relates_to": [],
"_updated_at": "<ISO 8601 | 省略>"
},
"next_step": "<下一跳命令名,如 pdlc-design;若流程结束则为 null>"
}
⛔ 示例里的
"checks": {}是「本阶段没有命令可跑」的样子,不是键名示范——键名与取值见下方 §1。
relations块(RFC#6,Phase 1 可选,Phase 2 推荐):6 个 key 对应 6 种关系类型,各为 ID 数组,存出边。其中conflicts_with/relates_to是对称类型,两端都要写;其余四种有向,只写在源 feature 上。拿不准时用/pdlc-relate set写入,它会按规则校验。旧状态文件无此块时视为全空,向后兼容。入边由/pdlc-relate rebuild派生到_relations.json,不在此块手维护。
⛔ 写状态机的四条硬约束——读侧(
/pdlc-status、/pdlc-retro、/pdlc-relate)会逐条体检, 违反的每一处都会出现在它们输出的最前面:
- 实例里不写
terminal_state。skill frontmatter 的terminal_state:是「这个命令走完后应到达的终态名」, 不是状态字段。判终态只看current_stage是否以_done结尾。history[].stage写本命令的阶段短名(见本命令正文里「本命令的状态机取值」)——pdlc-implement写impl, 不写implement/implementation;pdlc-prd写requirements,不写prd。- 时间戳必须带时刻:
created_at/done_at/at一律写完整 ISO 8601(如2026-07-28T10:40:00+08:00)。 只写日期,同一天内的阶段耗时就全部算成 0——读侧只能记「不可测」。next_step只写命令名或null,不附说明文字(如「pdlc-ship(等评审通过)」)。 要说明原因,阻塞时写进last_phase_result.blocked_reason。
⛔
_done的含义是「已发布」,只由/pdlc-ship(写ship_done)与/pdlc-deploy(写deploy_done)写入。 其它命令的current_stage一律写本命令的阶段短名,走完整条链路的编排命令(/pdlc-feature)也一样—— 它收尾时current_stage是最后一个阶段的短名,next_step是pdlc-ship。
- 「评审通过、等待发布」就是
current_stage为review且next_step为pdlc-ship(/pdlc-e2e在评审之前,它的下一跳是pdlc-review)。 循环相关文档里说的review_done指的就是这个状态,不是要写进current_stage的值。- 为什么:读侧判「已抵达终态」只看
current_stage是否以_done结尾。评审通过就写_done,/pdlc-ship就分不清哪些功能已经发布过,发布说明会重复或漏收。- 旧版本写入的
feature_done/fix_done/review_done分不清是否已发布,/pdlc-ship会列出来请人确认。
手写回退(仅脚本退出码 2 且无法修正时)
- 文件不存在 → 创建文件,写入初始结构(
history为含当前阶段的数组) - 文件存在 → 读取 JSON,追加当前阶段到
history,更新current_stage和next_step - 写回文件:用
jq或等效工具保持格式化 - 写完体检:运行
bash scripts/pdlc-state-lint.sh <项目根>,属于本功能状态文件的偏差当场改正。退出码2(缺 jq 等)= 没体检,报告里写明「未体检」,不得当作通过。
⚠️ 若更新失败(文件损坏/权限问题),必须中止命令并在最终报告中报错。状态机不可跳过。
last_phase_result(机器可读阶段结果;脚本按下面的规则写,手写回退时照做)
顶层 last_phase_result 是循环判停的唯一真源,外层只需 jq '.last_phase_result.ok' 即可决定 继续 / 停止 / 交还人类。规则:
checks只放真跑命令的退出码结果(scripts/pdlc-checks.sh的 stdout 原样),键名只能是tests_pass/coverage_pass/lint_clean/e2e_pass(tdd 段red_verified),值只能是布尔或null(无法判定)。不照抄test-commands.yml的unit/lint, 不写"4 passed, 1 failed"这类摘要。没有检查可跑的阶段(文档类阶段、项目无test-commands.yml)→checks: {}, 绝不因为「本阶段成功」就填true——schema 示例里checks是空的,正是这个意思。self_audit单列:只放自检未通过数,仅供参考,不作循环判停依据。ok的定义:没有命中blocked_reason,且 tdd 段red_verified为true、其它阶段没有任何检查为false(null不拦)→true;否则false。命名空间:
advanced_to= 下一阶段的短名,不是命令名、也不是本阶段的current_stage。三者关系:stage=本阶段短名、current_stage=本阶段完成后的当前短名、advanced_to=下一阶段短名、next_step=下一跳命令名。⛔ 短名不是「命令名去掉
pdlc-前缀」——pdlc-implement的短名是impl,不是implement。别推导,查下表:
next_step(下一跳命令名) |
advanced_to(下一阶段短名) |
|---|---|
pdlc-tdd |
tdd |
pdlc-implement |
impl |
pdlc-review |
review |
pdlc-design |
design |
pdlc-ship |
ship |
pdlc-deploy |
deploy |
next_step 为 null(终态或无后续)时 advanced_to 也是 null。
<!-- @include-end templates/prompts/state-update.md --> <!-- @include templates/prompts/handoff.md(已内联于下方,无需另读) -->📌 本表是唯一真源,且是被断言钉住的:每行的短名必须等于该 skill 自己 frontmatter 里声明的
stage:,且任何 skill 的非nullnext_step都必须在表里有行——两个方向 都由tests/frontmatter-check.sh检查,所以表不会和实现各自漂移。写错短名的后果与键名写错同类:消费方按契约名匹配,认不出就当没这个阶段。 5. 推进一致:
ok=true时本阶段必须真的推进了current_stage(与第 6 条 IRON LAW 呼应);到达终态或无后续时advanced_to=null。ok=false(含 blocked)时current_stage不变、advanced_to=null、blocked_reason写明原因。 6.run_mode:镜像本次调用是否带--autonomous(带了写autonomous,没带写interactive)。
段四:交接(Handoff)
命令完成后必须输出以下格式的最终消息:
✅ <阶段名> 完成:<主要产出物路径>
📊 自检:<通过数>/<总数> 通过(若有未通过,附要点)
📦 状态快照:docs/.pdlc-state/<feature-id>.json
👉 下一步:/pdlc-<next_step>
(如果有分叉)或 /pdlc-<alt>(条件:<选择依据>)
规则:
- 主流程命令(写状态机的命令;下一跳见正文里「本命令的状态机取值」)必须显式输出"下一步",不可省略
- 工具型命令(Layer 3)可以没有
next_step,此时输出👉 下一步:(本次流程结束,无后续) - 分叉场景必须说明选择条件,例如"若需补充测试用例 →
/pdlc-tdd;若测试已齐 →/pdlc-review"<!-- @include-end templates/prompts/handoff.md -->