paceflow

PACEflow

一套 Claude Code Hook 系统，通过确定性拦截（而非提示词建议）强制码前先规划、获批、再执行，解决 AI 编程"一上来就写代码、改着改着迷路"的问题。

核心理念

AI 编程最大的问题不是代码质量，而是过程控制——AI 会跳过规划直接写代码，写到一半迷路，改完不验证就收工。

PACEflow 不是靠 system prompt 去"建议"AI 做这些事（AI 可以无视建议），而是在 Claude Code 的 Hook 层物理拦截：

设计哲学：Hooks 提供 100% 确定性保障，CLAUDE.md 提供 ~70-85% 建议性约束，两者互补。

• 没有 task.md？写代码的工具调用直接 deny，AI 被迫先创建任务
• implementation_plan.md 里没标 [/] 进行中？还是 deny
• 用 Write 覆盖已有的 artifact 文件？直接 deny，必须用 Edit
• 任务完成了但 walkthrough 没写？Stop hook 给 warning，exit 2 阻止退出

PACE 五阶段

5 个 Artifact 文件 = 项目记忆

所有文件使用 <!-- ARCHIVE --> 分隔：活跃区保持精简，归档区保留历史。

安装

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

安装后 9 个 hook + 5 个 skill 自动注册，零配置。重启 Claude Code 生效。

可选：设置环境变量 PACE_VAULT_PATH 指向你的 Obsidian Vault，artifact 将自动存储到 $PACE_VAULT_PATH/projects/<项目名>/，实现跨项目知识沉淀。

node paceflow/install.js           # 安装缺失文件
node paceflow/install.js --force   # 强制覆盖
node paceflow/install.js --dry-run # 预览模式

node paceflow/install.js --migrate
/plugin marketplace add paceaitian/paceflow
/plugin install paceflow@paceaitian-paceflow

特色功能

Superpowers 全流程集成

无缝对接 Superpowers，从需求探索到代码交付的全链路自动化：

brainstorming（需求探索 + 方案设计）
  → writing-plans（生成实施计划）
    → pace-bridge（自动桥接到 PACE artifacts）
      → auto-APPROVED（设计阶段已参与决策，跳过重复审批）
        → 选择执行策略（串行 / 并行 agent / TDD）

用户只需参与设计决策，后续 artifact 创建、任务编号、变更 ID 全部自动生成。不使用 Superpowers 时回退 PACE 原生规划。

Claude Code /plan 桥接

原生支持 Claude Code 的 /plan 模式——计划文件自动检测，pace-bridge skill 一键转换为 PACE 标准 artifacts（task.md + implementation_plan.md）。Compact 后计划丢失？自动恢复提醒。

智能上下文管理

5 个 artifact 文件的活跃内容每次会话自动注入，按相关性智能截断：

• 已完成的变更/调研/工作记录自动省略
• walkthrough 只保留最近记录，findings 只注入未解决项
• token 消耗降低 57%，大幅减少 Compact 频率

Obsidian 知识中枢

设置 PACE_VAULT_PATH 后解锁跨项目知识管理：

• Artifact 自动存储到 projects/<项目名>/
• knowledge/ + thoughts/ 沉淀可复用经验
• 会话启动自动注入关联笔记摘要
• 兼容 Obsidian Tasks / Dataview 跨项目查询

Agent Teams 兼容性

Teammate 身份自动检测（CLAUDE_CODE_TEAM_NAME 环境变量），阻止性 hook 降级为提示性建议，信息性 hook 保持生效，多 agent 协作不中断。

工作原理

8 个 Hook 覆盖完整生命周期

多信号自动激活

PACEflow 自动检测项目是否需要 PACE 流程，无需手动配置：

防无限循环

Stop hook 连续阻止 3 次后自动降级为放行，防止 AI 陷入死循环。SessionStart 重置计数器。

项目结构

paceflow/
├── .claude-plugin/plugin.json        # Plugin 元数据
├── hooks/                            # 8 个 Hook 脚本
│   ├── hooks.json                    #   自动注册配置
│   ├── pace-utils.js                 #   公共工具库
│   ├── pre-tool-use.js               #   写代码前：任务检查 + 审批检查
│   ├── post-tool-use.js              #   写代码后：归档提醒 + 格式检查
│   ├── session-start.js              #   会话启动：上下文注入
│   ├── stop.js                       #   会话结束：完成度检查
│   ├── stop-failure.js               #   API 错误中断：事件日志
│   ├── todowrite-sync.js             #   任务列表：一致性校验
│   ├── config-guard.js               #   配置保护
│   ├── pre-compact.js                #   Compact 前快照
│   └── templates/                    #   5 个 Artifact 模板
├── skills/                           # 5 个 Skill
│   ├── pace-workflow/                #   PACE 核心流程
│   ├── pace-bridge/                  #   Superpowers 桥接
│   ├── artifact-management/          #   Artifact + 变更管理规则
│   ├── pace-knowledge/               #   Obsidian 知识库管理
│   └── paceflow-audit/               #   5-Agent 并行审查
└── tests/                            # 测试（77 单元 + 69 E2E + 21 安装）