architectural-refactor

架构重构

将架构建议付诸实践，同时不破坏任何内容。

编码 Agent 擅长局部修改，却不擅长在漫长的会话、上下文压缩和多会话工作中维持架构一致性。这项技能通过将计划外化到磁盘、在清单中跟踪进度，并在每个工作块之间设置验证关卡来解决这个问题。即使 Agent 完全丢失上下文，也能从中断处准确继续。

核心机制

整个方法依赖于存储在磁盘上（而非上下文中）的三个文件：

1. refactor-plan.md — 根据评估结果制定的具体、有序计划。每个工作块都有明确的进入条件、步骤和退出条件。
2. refactor-manifest.json — 机器可读的进度跟踪文件。记录已完成的工作、接下来的工作、失败项和验证结果。
3. refactor-log.md — 仅追加的可读日志，记录发生了什么以及原因，让任何 Agent（或人）都能了解历史。

这些文件才是事实依据。不是你的记忆，也不是对话，而是这些文件。

阶段 1：接收评估结果

阅读用户提供的评估文档。这些文档可能是 Markdown 文件、seam-ripper 输出、简化性审计结果，或任何包含建议的结构化分析。

从评估中提取：

• 需要更改的内容 — 确认的具体问题
• 目标架构的样貌 — 期望的最终状态
• 任何排序约束 — 更改之间的依赖关系（例如，“先提取模块 X，才能将 Y 与 Z 解耦”）

如果评估含糊不清或缺少关键信息，请停下来询问。基于模糊建议制定的重构计划会偏离方向，而这正是我们要避免的。

阶段 2：制定计划

将评估结果转化为具体、有序的工作块序列。每个工作块都是一个独立的重构单元，可将代码库从一种有效状态推进到另一种有效状态。

如何确定工作块的边界

工作块应当：

• 可独立验证 — 完成后，可以运行测试、类型检查和 lint，确认没有破坏任何内容
• 可独立提交 — 适合作为一条有明确提交说明的提交
• 规模足够小，便于掌握 — 如果一个工作块需要同时理解 15 个文件，就应进一步拆分
• 规模足够大，具有实际意义 — 移动单个导入不算一个工作块；提取一个模块才算

好的工作块通常包括：

• 将一组相关函数或类型提取到新模块中
• 将职责从模块 A 移到模块 B（并更新所有引用）
• 用更简单的替代方案取代某种抽象
• 反转依赖方向
• 将多个文件或抽象合并为一个
• 删除评估中确认的死代码

不好的工作块：

• “重构身份验证系统”（太模糊——具体要做什么？）
• “重命名第 42 行的变量”（太细碎——应将相关重命名归为一组）
• “重组所有内容”（无法独立验证）

依赖关系分析

为工作块排序前，先梳理它们之间的依赖关系：

• 工作块 B 是否会将代码移入工作块 A 创建的模块？→ A 排在 B 前面
• 工作块 C 是否会删除某种抽象，而工作块 D 的更改假设该抽象已不存在？→ C 排在 D 前面
• 工作块 E 和 F 是否相互独立？→ 顺序无关（但为保持一致，请选定一个顺序）

如果发现工作块之间存在循环依赖，说明工作块的边界划分有误。请重新拆分，直到依赖图成为 DAG（有向无环图，即不存在循环依赖）。

编写计划

在项目根目录（或用户指定的位置）创建 refactor-plan.md：

# Refactoring Plan

**Source:** [link/path to assessment document]
**Created:** [date]
**Target:** [one-sentence description of desired end state]

## Pre-flight Checks
- [ ] All tests pass before starting
- [ ] No uncommitted changes
- [ ] Working branch created

## Chunk 1: [Descriptive Name]
**Why:** [Which assessment finding this addresses]
**Entry criteria:** All tests pass, no prior chunks pending
**Steps:**
1. [Concrete action — e.g., "Create `src/auth/tokens.ts` with the TokenService class"]
2. [Next action — e.g., "Move `generateToken()` and `validateToken()` from `src/core/utils.ts`"]
3. [Continue — e.g., "Update imports in `src/api/middleware.ts` and `src/api/routes/login.ts`"]
4. [e.g., "Remove the now-empty token section from `src/core/utils.ts`"]
**Exit criteria:** All tests pass, types check, lint clean
**Commit message:** `refactor: extract token management into dedicated auth module`

## Chunk 2: [Descriptive Name]
**Depends on:** Chunk 1
**Why:** [...]
**Entry criteria:** Chunk 1 complete and verified
**Steps:**
1. [...]
**Exit criteria:** All tests pass, types check, lint clean
**Commit message:** `refactor: ...`

[...continue for all chunks...]

## Post-flight Checks
- [ ] Full test suite passes
- [ ] No TODO/FIXME markers left from refactoring
- [ ] Assessment findings are resolved

每个工作块中的步骤都应足够具体，让一个完全没有先前上下文的 Agent 也能按步骤执行。写明文件路径、函数名称和具体移动内容，而不是“按需重组”。

初始化清单

创建 refactor-manifest.json：

{
  "plan_file": "refactor-plan.md",
  "assessment_source": "[path to assessment]",
  "created": "[ISO date]",
  "total_chunks": 5,
  "current_chunk": 0,
  "status": "ready",
  "preflight_passed": false,
  "chunks": [
    {
      "id": 1,
      "name": "Extract token management",
      "status": "pending",
      "depends_on": [],
      "verification": null,
      "commit_sha": null,
      "started_at": null,
      "completed_at": null
    },
    {
      "id": 2,
      "name": "Decouple auth from core",
      "status": "pending",
      "depends_on": [1],
      "verification": null,
      "commit_sha": null,
      "started_at": null,
      "completed_at": null
    }
  ]
}

获取用户签字确认

执行任何操作前，先向用户展示计划。用户应确认：

• 各分块合理，并涵盖评估建议
• 排序正确
• 没有遗漏任何关键内容
• 分块粒度合适

如果用户希望修改，请先更新计划和清单，再继续。

第 3 阶段：执行

这是主要工作循环。它刻意设置得很严格，因为严格可以防止偏离。

开始会话（或压缩后恢复）

每次开始工作时——无论是首次开始，还是在上下文压缩或开启新会话后恢复——都要执行以下操作：

1. 读取 refactor-manifest.json — 确认当前进度
2. 读取 refactor-plan.md — 了解当前分块
3. 读取 refactor-log.md — 了解近期发生的情况
4. 验证当前状态 — 运行验证套件，确认代码库状态良好

这只需 30 秒，却能避免 Agent 偏离的头号原因：基于过时或臆测的上下文开始工作。

分块执行循环

FOR each chunk (in order):

  1. READ the chunk from refactor-plan.md
  2. CHECK entry criteria
     - Dependencies met? (check manifest)
     - Tests passing? (run them)
     - If not: STOP. Fix or escalate to user.

  3. UPDATE manifest: chunk status → "in_progress"
  4. LOG: "Starting chunk N: [name]"

  5. EXECUTE each step in the chunk sequentially
     - Follow the plan literally
     - If a step can't be done as written: STOP
       → Log what went wrong
       → Update manifest with the blocker
       → Ask the user how to proceed
       → Do NOT improvise a workaround

  6. VERIFY (the gate)
     - Run the full test suite
     - Run type checking
     - Run linter
     - If ANY verification fails:
       → Fix the issue (if it's clearly caused by this chunk's changes)
       → Re-verify
       → If you can't fix it in 2 attempts: STOP
         → Revert the chunk (git checkout/restore)
         → Log the failure
         → Update manifest: chunk status → "failed"
         → Ask the user

  7. COMMIT
     - Stage only the files changed in this chunk
     - Use the commit message from the plan
     - Record the commit SHA in the manifest

  8. UPDATE manifest: chunk status → "completed"
  9. LOG: "Completed chunk N. Verification: [pass/fail details]"

  10. Proceed to next chunk

“STOP”的含义

当技能要求 STOP 时，意思是：不要继续到下一个分块，不要尝试变通方案，也不要“修好后继续”。这项技能的全部意义在于，偏离计划会让代码库陷入最初需要重构才能解决的混乱状态。

停止时：

1. 用当前状态更新清单
2. 写一条清晰的日志，说明发生了什么
3. 明确告知用户出了什么问题，以及他们需要做出什么决定

用户可能会说“跳过这个分块”“修改计划”或“这样处理”。都可以。决定权在用户，而不在 Agent 手中。

处理偏离信号

留意以下迹象，判断自己是否偏离计划：

• 你正在编辑当前分块步骤中未提及的文件
• 你在“顺便修复”计划中没有提到的问题
• 你因为“这样更合理”而调整步骤顺序
• 你因为“现在不需要了”而跳过某个步骤

如果出现上述任何情况，立即停止并重新阅读计划。如果计划确实有误，请在获得用户批准后更新计划（以及清单）。不要悄悄偏离计划。

第 4 阶段：收尾检查

所有分块完成后：

1. 最后运行一次完整的验证套件
2. 检查重构日志，确认是否存在异常
3. 将最终状态与评估的目标架构进行比较
4. 更新清单：status → "completed"
5. 向用户总结：
   • 已成功完成的分块
   • 跳过或修改的分块
   • 评估中尚未处理的事项
   • 验证结果

验证套件

验证命令取决于项目。首次运行时检测这些命令，并记录在清单中，以确保不同会话间保持一致：

{
  "verification": {
    "test": "npm test",
    "typecheck": "npx tsc --noEmit",
    "lint": "npm run lint",
    "detected_at": "[ISO date]"
  }
}

检测顺序：

1. 检查 package.json 脚本、Makefile、Cargo.toml、pyproject.toml 等
2. 检查常用命令（npm test、pytest、cargo test、go test ./...）
3. 如果没有找到任何命令，询问用户使用哪些命令来验证代码库

每个关卡的三项检查（测试、类型检查、代码检查）都必须通过。如果项目缺少其中一项（例如，纯 JavaScript 项目没有类型检查器），请在清单中注明并跳过该检查，但绝不能跳过测试。

从失败中恢复

如果某个分块失败，需要重试：

1. 使用 git stash 或 git checkout . 撤销失败分块中未提交的更改
2. 更新清单：将分块状态设为 "pending"（从 "failed" 重置）
3. 记录重试情况
4. 重新阅读计划中的分块内容
5. 从该分块的第 1 步开始重新执行

如果同一分块失败两次，就不要再重试。更新清单、记录详细情况，并交由用户处理。同一分块失败两次，说明计划需要修订，而不是继续尝试。

会话交接

如果所有分块尚未完成就要结束会话，或要为其他 Agent/会话创建交接内容：

1. 确保清单已完全更新
2. 添加日志条目：“会话已结束。当前状态：已完成 M 个分块中的第 N 个。下一步：第 N+1 个分块。”
3. 提交清单和日志文件

下一次会话从读取清单开始——继续工作所需的所有上下文都已保存在磁盘上。

此技能不做什么

• 决定重构什么。 这是评估工作的职责（使用 /seam-ripper、/simplicity-audit，或自行分析）。
• 做出架构判断。 如果计划有歧义，就停止并询问，而不是猜测。
• “改进”计划之外的内容。 顺手清理正是偏离计划的开始。如果发现值得修复的内容，将其添加到未来分块的计划中——现在不要处理。
• 跳过验证。 绝不允许，任何理由都不行。“测试太慢”不是理由。“这显然没问题”也不是理由。