paceflow

PACEflow

PACEflow 是一套 Claude Code hook，用工具层的确定性门，让 AI 在长任务里不忘走流程——先规划获批再动手、改完验证再收尾；过程记账卸给一次性子代理，并跨 session 恢复。

它做什么

PACEflow 在工具调用边界加两个确定性 hook 门，外加一套跨 session 的记录：

• 没有获批的活跃变更（CHG），写代码被拒（PreToolUse）。逼出「先建变更记录、获批，再动手」。
• 没验证 / 没审计就想结束会话，被 Stop 拦下。逼出「改完先验证、审计，再收尾归档」。
• 过程记账由 artifact-writer 子代理写，不占用主 session 上下文。
• 跨 session 恢复：CHG / finding / correction / walkthrough 索引在 SessionStart 自动重注入，新 session（或 compact 后）接上「上次做到哪、为什么这么改」。

门只确认步骤发生过、顺序对、留了记录：VERIFIED 表示验证这一步被记录了，REVIEWED 表示审计这一步被记录了。内容对错由测试、CI、review 和模型能力决定，门不裁决。

它不做什么

• 不让模型更聪明，不改模型能力。
• 不抓 bug、不判断代码质量。
• 不替你写 spec 或做设计；spec.md 是你的项目事实文件，不是「真相源」。
• 不防刻意绕过——你随时能 /paceflow:pause、/paceflow:disable 主动退出。

PACE 六阶段

阶段	含义	Hook 保障
Plan	规划任务	PreToolUse deny 未规划的代码修改
Artifact	派 agent 创建/更新索引与 changes/ 详情	模板自动注入 + 格式守门
Check	用户审批	PreToolUse 检查详情文件 <!-- APPROVED -->
Execute	执行	PostToolUse 归档提醒
Verify	验证	Stop 完成度检查 + verified-date / <!-- VERIFIED -->
Review	审计	收口前对本 CHG diff 做对抗审计并记录；Stop 检查 + reviewed-date / <!-- REVIEWED -->

CHG 是最小变更单元

CHG/HOTFIX 是连续执行、可验证、可关闭的最小变更单元，不是大计划容器。大计划拆成多个可独立完成和验证的 CHG（如数据结构/迁移、后端接口、前端调用、文档/配置分别记录）。

合适的 CHG 粒度：

• ✅ 「给 golden 快照测试加 Windows 路径归一化」
• ✅ 「让 artifact-writer 按 CHG 复用」
• ❌ 太宽：「改进 PACEflow」
• ❌ 太小：「重命名一个局部变量」

项目记忆

文件	用途
spec.md	项目元数据、技术栈
task.md	CHG/HOTFIX 唯一索引
findings.md	finding 摘要索引
corrections.md	correction 摘要索引
walkthrough.md	工作总结索引
changes/	CHG/HOTFIX/finding/correction 详情文件

---

安装

当前版本的 hook 注册使用 Claude Code 2.1.139 新增的 hooks[].args exec form。请使用 Claude Code 2.1.139 或更高版本；2.1.138 及更早版本不支持该字段，可能只执行 command: "node" 而不传脚本路径，导致 hook 没有实际运行。

# 在 Claude Code 中执行（2 条命令）
/plugin marketplace add paceaitian/paceflow
/plugin install paceflow@paceaitian-paceflow

安装后 9 类 hook 事件、配套 helper 脚本、4 个用户 skill、5 个用户命令和 artifact-writer agent 自动注册，零配置。重启 Claude Code 生效。

可选：设置环境变量 PACE_VAULT_PATH 指向你的 Obsidian Vault。新项目首次写代码或派 artifact-writer 时，PACEflow 会要求主 session 询问 artifact 存放在 $PACE_VAULT_PATH/projects/<项目名>/ 还是本地项目目录，并把选择持久化到 Project Root 的 .pace/artifact-root；local 表示 Project Root 本地目录，不是当前子目录，也不是 .pace/。已有 changes/ 的项目沿用现有位置。真实 Git worktree 和 .claude/worktrees/<name> 会自动归一到宿主项目名；也可用 PACE_PROJECT_NAME 显式指定项目名。自动化/headless 环境可设置 PACE_ARTIFACT_ROOT=local|vault|/abs/path 跳过询问。

Project Root 与子目录继承

PACEflow 区分三个路径：

• Current CWD：Claude Code 当前打开的目录。
• Project Root：PACEflow 管理的项目边界，.pace 运行态、CHG owner、Stop 检查和 local artifact root 都以它为准。
• Artifact Root：spec.md / task.md / walkthrough.md / findings.md / corrections.md / changes/** 的存放目录，可等于 Project Root，也可位于 Obsidian vault。

在被 PACEflow 管理的父项目子目录中启动 Claude Code 时，子目录默认继承最近的父级 Project Root。这样在 packages/api、plugin/、嵌套 git repo 等目录里工作时，仍能看到同一个父项目的 active CHG、owner 和 Stop 状态。

如果当前子目录是一个真正独立的新项目，先运行：

node "${CLAUDE_PLUGIN_ROOT}/hooks/set-project-root.js" --mode independent

再运行 set-artifact-root.js --choice local|vault 选择它自己的 artifact root。不要手写子目录 .pace/project-root 或 .pace/artifact-root。

---

快速开始

前提：插件已安装（见上方「安装」），并在项目运行过 /paceflow:enable。

一次改动

以「加一个小功能」为例：

1. 让 Claude 写代码。没有活跃且已获批的 CHG 时，写代码的工具调用被 deny。
2. Claude 创建 CHG（标题 + 任务清单）。
3. 你批准（一句「开始」）。批准前详情无 APPROVED，写代码持续被 deny；APPROVED 只能由你触发写入，AI 不能自批。
4. 批准后写代码放行。

前四步是一次改动的最短闭环。

收尾时发生什么

5. 验证：Claude 运行验证并记录；未验证时 Stop 阻止结束会话。
6. 审计：收尾前对本次改动做一次 review 并记录。
7. 收尾：close 补全任务状态、写验证/审计标记、归档、追加一条工作记录。

命令：/paceflow:status 状态 · /paceflow:pause 本会话暂停 · /paceflow:disable 停用（不删 artifact）。

---

集成

Superpowers

接 Superpowers 的规划链：brainstorming / writing-plans 产出的 plan 经 pace-bridge 转成 CHG，设计阶段已参与决策时自动 APPROVED。

brainstorming → writing-plans → pace-bridge（plan 转 CHG）→ auto-APPROVED → 执行

不用 Superpowers 时回退 PACE 原生规划。

Claude Code /plan

/plan 计划文件自动检测，pace-bridge 转成 CHG（changes/<id>.md + task.md 索引）；compact 后计划丢失会提醒恢复。

Obsidian

设置 PACE_VAULT_PATH 后，artifact 可存到 vault 的 projects/<项目名>/：

• 首次启用选择 artifact 存 vault 还是本地项目目录
• knowledge/ + thoughts/ 笔记沉淀跨项目经验，SessionStart 自动注入关联摘要
• 兼容 Obsidian Tasks / Dataview 跨项目查询

Agent Teams

自动检测 teammate 身份（CLAUDE_CODE_TEAM_NAME）。teammate = 纯执行者：任务管理（批准 / 建 CHG / 改状态 / 归档）归主 session 单一权威源；流程引导类 deny 对 teammate 降级为提示避免死锁，批准 / 完整性类 deny 仍硬阻断。完整降级规则见 REFERENCE。

---

升级与迁移

新安装可跳过本节，仅 v6 / v5 老用户升级时需要。

v6 → v7：v7 改了 artifact 数据布局（task.md 单索引、frontmatter 9-key 封闭合同、implementation_plan.md 退役）。升级分两步、顺序不能反——先升级插件并 reload 所有 session，再迁移数据：