1. 项目概述：从重复纠正到智能协作的进化

如果你和我一样，每天都在用Claude Code、Cursor这类AI编程助手，那你肯定经历过这个场景：周一你告诉它“测试里别用Mock数据库”，它点头答应；周五你写新功能，它又在测试里给你塞了个Mock。你像个复读机一样，一遍遍解释着项目的命名规范、代码风格、架构偏好。每次新开一个会话，AI助手就像得了“健忘症”，之前花时间调教出来的“默契”荡然无存，你又得从头开始。这种重复劳动不仅消磨耐心，更严重的是，它打断了真正的创造性工作流。

这就是我最初开发Pro Workflow的动机。它不是一个简单的插件集合，而是一个旨在解决AI编码助手“记忆失能”核心问题的系统性工程。其核心思想很简单： 让每一次纠正都成为最后一次 。通过一个基于SQLite的持久化记忆系统，Pro Workflow将你与AI的交互从“单次会话”提升到“长期伙伴关系”。你纠正一次，它记住一条规则；50个会话后，AI助手已经深刻理解你的项目上下文、技术栈偏好和代码禁忌，纠正率趋近于零。这背后是一套完整的架构，包含24个技能、8个专职代理、21条命令和覆盖24个事件的29个钩子脚本，共同构建了一个能够自我进化、自我管理的智能工作流引擎。

2. 核心架构与设计哲学拆解

2.1 自我纠正循环：从临时记忆到持久化规则

传统AI助手的工作模式是“会话隔离”。每个会话都是一个孤岛，上下文窗口关闭，一切归零。Pro Workflow引入的“自我纠正循环”打破了这一模式。其核心是一个轻量级但功能强大的SQLite数据库，并集成了FTS5全文搜索引擎。

循环流程解析：

1. 触发与捕获 ：当你在会话中纠正Claude（例如，评论说“这里应该用集成测试，而非单元测试”），Pro Workflow的钩子脚本（如 PostToolUse 或特定的 UserPromptSubmit ）会捕获这个交互。
2. 规则提炼 ：系统不会简单存储你的原话。它会调用一个内置的“学习代理”，分析这次纠正的上下文（涉及的文件、代码模式、错误类型），并将其提炼成一个结构化的、可重用的“规则”。例如，将“别Mock数据库”转化为一条规则：“在 /tests/integration/ 目录下的 .spec.js 文件中，当测试涉及 User 模型时，应使用真实的数据库连接而非 jest.mock(‘@/models/User’) ”。
3. 存储与索引 ：这条规则会被存入SQLite数据库。FTS5引擎会为规则内容、关联的文件路径、错误类型等建立索引，支持后续的模糊搜索和语义关联。
4. 自动加载与应用 ：在下一个会话开始时， SessionStart 钩子会自动加载所有与你当前项目目录相关的历史规则，并将其作为“前置知识”注入到Claude的上下文窗口中。这意味着，AI助手从第一行代码开始，就已经在遵守你的历史约定了。
5. 效果验证与迭代 ：如果本次会话中，AI在没有被提醒的情况下正确应用了规则，系统会默默记录一次“成功应用”。如果它再次犯错，你会进行新的纠正，循环再次开始。规则本身也会根据应用频率和成功率进行权重调整。

这个循环的关键在于“化合物效应”。单个规则的影响微乎其微，但当几十条、上百条规则在几十个会话中不断累积和强化时，AI助手的行为模式会无限趋近于你的理想状态。这不再是简单的提示工程，而是构建了一个专属于你和你的项目的“领域知识图谱”。

2.2 模块化技能与代理体系：从单兵作战到团队协作

Pro Workflow没有设计成一个庞然大物般的“超级AI”，而是采用了微服务化的架构思想。24个技能是独立的、可复用的能力单元，8个代理则是这些技能的调度者和执行者。

技能（Skills） ：可以理解为封装好的“函数”或“策略”。例如：

• Self-Correction Loop 技能封装了上述的规则捕获、提炼、存储逻辑。
• Context Engineering 技能提供了一套“写-选-压-隔”方法论，用于主动管理有限的上下文令牌。
• Smart Commit 技能集成了代码质量检查、变更分段审查和生成规范提交信息。

代理（Agents） ：是拥有特定职责和上下文的“虚拟工程师”。它们被配置了不同的系统提示词、权限集和技能调用权限：

• planner 代理 ：只读权限，专注于复杂任务拆解。当你输入 /develop add user authentication 时， orchestrator 会首先调用 planner ，让它生成一份包含技术选型、API设计、数据库变更的详细计划，待你批准后才进入实施阶段。
• reviewer 代理 ：基于检查清单进行代码审查和安全审计。它在 /develop 流程的“Review”阶段被调用，确保代码符合规范且没有引入明显漏洞。
• debugger 代理 ：采用假设驱动的方法排查Bug。它会系统性地提出可能的原因，设计验证实验，并定位根因，而不是漫无目的地猜测。
• permission-analyst 与 cost-analyst 代理 ：这两个是v3.2的新特性，体现了运维思维。前者分析权限被拒绝的模式，自动优化 claude.dangerous 等配置规则，减少干扰性提示。后者监控令牌消耗，识别如“反复读取大文件”等高成本操作，提供优化建议。

这种设计的好处是 关注点分离 和 资源优化 。让专门的代理做专门的事，避免了让主AI线程负担过重导致上下文污染或性能下降。你可以通过 /doctor 命令随时检查这个“团队”的健康状况。

2.3 钩子（Hooks）驱动的事件化工作流

29个钩子脚本是Pro Workflow的“神经系统”，分布在24个关键事件上。它们使工作流从“被动响应”变为“主动感知和干预”。

关键钩子场景举例：

• PreToolUse (Bash) ：在你运行任何bash命令前触发。这里集成了 LLM Gates 功能。例如，在执行 git commit 前，钩子会将被暂存的变更发送给一个轻量级LLM进行快速审查，检查是否有明显的调试语句（ console.log ）、TODO注释或硬编码的密钥。这相当于一个AI驱动的预提交检查。
• PreCompact / PostCompact ：Claude Code在上下文窗口快满时会进行“压缩”，丢弃一些早期信息。这常常导致重要指令被遗忘。 Compact Guard 技能在这两个事件上绑定脚本，在压缩前自动将当前会话的关键目标、正在进行的功能摘要等状态保存下来；压缩后，再将这个摘要重新注入，实现“状态保持”。
• FileChanged ：监控 package.json 、 .env 、CI配置文件等关键文件的变动。一旦检测到依赖变更或环境变量更新，可以自动触发重新安装依赖或更新上下文提示，确保AI助手始终基于最新项目状态工作。
• PermissionDenied ：当AI尝试执行一个被权限系统阻止的操作时（如删除根目录），此钩子会记录该模式。 permission-analyst 代理定期分析这些记录，并建议你是否将某些高频且安全的操作加入允许列表，从而减少不必要的确认弹窗，即“权限调优”。

这种事件驱动模型，使得Pro Workflow能够深度融入Claude Code的生命周期，实现细粒度的、上下文感知的自动化。

3. 核心功能与实操要点解析

3.1 多阶段开发流程： /develop 命令详解

/develop 是Pro Workflow的旗舰命令，它将一个功能从想法到上线拆解为有门控的四个阶段，强制推行一种严谨的工程纪律。

第一阶段：Research（研究）

• 操作 ： /develop add user authentication 命令触发后，系统首先进入研究模式。
• 背后逻辑 ： orchestrator 代理会指示 scout 代理（或主AI在隔离的上下文中）去调研当前项目已有的认证模式（如查看现有的 auth.js 、 middleware ）、依赖库（ package.json 中的 passport 、 next-auth 等），并快速浏览相关文档。它可能会生成一个简短的调研摘要，比较JWT vs Session、OAuth2提供商标记等。
• 实操要点 ：这个阶段 禁止 直接写业务代码。目的是避免AI在信息不全的情况下，基于过时或错误的假设开始实施。你可以通过 settings.json 配置研究阶段的超时时间或资源限制。

第二阶段：Plan（计划）

• 操作 ：研究摘要生成后，控制权交给 planner 代理。
• 背后逻辑 ： planner 根据研究结果，生成一份详细的实施计划。这份计划通常包括：1) API端点设计（ POST /api/auth/login ）；2) 数据库模式变更（新增 users 、 sessions 表）；3) 需要安装的依赖（ bcrypt , jsonwebtoken ）；4) 需要修改的现有文件（如全局中间件）；5) 测试策略。这份计划会呈现给你等待批准。
• 实操要点 ： 务必仔细审查计划 。这是纠正AI设计思路成本最低的时机。你可以说：“合并 login 和 register 端点到 /api/auth 路由下”，或者“使用Prisma而不是直接写SQL”。批准后，计划会被保存为任务清单，指导后续阶段。

第三阶段：Implement（实施）

• 操作 ：计划批准后，主AI或指定的实施代理开始编码。
• 背后逻辑 ：实施过程不是盲目的。 TaskCreated 和 TaskCompleted 钩子会跟踪每个子任务的进度。 PreToolUse (Edit/Write) 钩子会提醒AI遵循项目规范（这些规范可能来自之前会话学习的规则）。 PostToolUse (Edit) 钩子会进行实时基础检查。
• 实操要点 ：你可以使用 /parallel 命令创建Git worktree，让另一个AI代理并行处理诸如“编写数据库迁移脚本”或“生成单元测试”等独立子任务，实现“零空闲时间”开发。

第四阶段：Review（审查）

• 操作 ：代码编写完成后， /develop 流程自动调用 reviewer 代理。
• 背后逻辑 ： reviewer 代理基于一套可配置的检查清单（代码风格、安全漏洞、性能隐患、是否遵守既定计划）进行审查。它会生成审查报告，指出问题并提出修改建议。只有通过审查，流程才会进入最终的提交环节。
• 实操要点 ：审查报告是绝佳的学习材料。对于AI指出的但你认为不是问题的地方，可以用 /learn-rule 命令告诉它：“在这种工具函数里，允许使用 any 类型”，从而丰富它的规则库。

这个门控流程强制引入了“思考-计划-执行-检查”的循环，极大提升了AI生成代码的可靠性和架构合理性。

3.2 上下文工程与状态保持：应对令牌限制的实战策略

Claude Code的上下文窗口是宝贵且有限的资源。Pro Workflow的 Context Engineering 技能提供了一套系统方法论。

Write/Select/Compress/Isolate 四步法：

1. Write（写） ：主动将最重要的信息以清晰、结构化的方式写入上下文。这就是 CLAUDE.md 和 AGENTS.md 文件的作用。Pro Workflow的模板建议将它们拆分为模块（如 project-context.md , tech-stack.md , coding-rules.md ），使结构更清晰。
2. Select（选） ：不是所有文件都需要全部内容。通过 @ 符号引用文件特定部分（如 @src/utils/auth.ts#L10-L30 ），或让AI自己根据任务摘要选择相关文件，精准投放信息。
3. Compress（压） ：当上下文将满时， Compact Guard 技能开始工作。它会在压缩事件前，命令AI将当前核心任务状态、待办事项、关键决策摘要成一段简短的文本，并保存到临时状态中。
4. Isolate（隔） ：对于探索性、高风险或并行的任务，使用 claude -w <worktree-name> 在独立的Git worktree中开启完全隔离的会话。这样，即使实验失败，也不会污染主分支的上下文。 Parallel Worktrees 技能自动化管理了这些并行会话的生命周期。

实操心得 ：我习惯在项目根目录的 CLAUDE.md 开头，用一段“电梯演讲”定义项目核心。然后，利用 File Watcher 技能，让 .env.example 或 docker-compose.yml 的变更能自动触发上下文更新。最重要的是，信任 Compact Guard 。设置一个合理的“预算”（如 compactBudget: 50000 ），让它自动处理状态保存，你几乎可以忘记上下文限制的存在。

3.3 智能提交与质量门禁： /commit 命令的里里外外

/commit 远不止是 git commit -m 的包装。它是一个集成了多项检查的发布流水线。

执行流程：

1. 暂存区检查 ：首先检查是否有未暂存的更改。如果有，会提示你添加。
2. LLM Gate（代码质量） ：所有暂存的变更会被发送给一个配置好的、成本极低的审查模型（例如Claude Haiku）。这个模型快速扫描代码，寻找明显的“代码异味”——未移除的调试语句、残留的TODO、可能误提交的密钥或大型二进制文件。这一步拦截了大多数低级错误。
3. 分段审查 ：AI会将变更按文件或功能模块进行分组，并为你生成一个简洁的摘要，逐段询问“是否确认提交此部分？”。这迫使你在提交前进行最后一次人工确认，避免提交不完整的代码。
4. 生成提交信息 ：基于变更摘要和项目约定的提交规范（如Conventional Commits），AI会自动生成格式规范的提交信息，例如： feat(auth): implement JWT-based login and registration endpoints 。
5. 最终执行 ：在你确认提交信息和所有变更后，才执行最终的 git commit 命令。

配置示例（ settings.json 片段）：

{
  "commit": {
    "llmGate": {
      "enabled": true,
      "model": "claude-3-haiku-20240307",
      "checks": ["debugStatements", "todos", "secrets", "largeFiles"]
    },
    "stagedReview": true,
    "conventionalCommits": true
  }
}

避坑指南 ：LLM Gate虽然好用，但会对每一行变更消耗令牌。对于大型提交，成本可能上升。建议在 settings.json 中为 llmGate 设置一个 maxDiffTokens 限制（如8000），对于超过此限制的变更，可以降级为简单的正则表达式检查，或跳过此步骤直接进入人工分段审查。

4. 高级工作模式与集成方案

4.1 代理团队与并行化工作流

对于大型、复杂的任务，单一代理线性处理效率低下。Pro Workflow的 Agent Teams 技能允许你组建虚拟团队。

团队工作模式：

1. 任务分解 ： orchestrator 代理收到一个宏观任务（如“重构用户个人资料模块”）。
2. 创建子任务 ：它将任务分解为设计、后端API重构、前端组件更新、数据库迁移、测试编写等独立子任务。
3. 分配与执行 ： orchestrator 可以协调多个 claude 实例（每个实例可配置为不同的代理角色），或将子任务排入队列，由你手动分配给在并行worktree中运行的代理。
4. 状态同步 ：通过一个共享的、简单的任务状态文件（如 .claude/tasks.json ），各个代理可以更新进度、报告阻塞。 TeammateIdle 钩子能检测到某个代理长时间无进展，并发出通知。
5. 结果汇总 ：所有子任务完成后， orchestrator 会协助进行集成，并可能调用 reviewer 进行整体审查。

实操场景 ：假设你需要为10个API端点编写集成测试。你可以启动一个主会话使用 orchestrator ，然后创建两个worktree，分别运行配置为 tester 角色的代理。 orchestrator 将10个端点分成两组，分配给两个 tester 并行编写测试。主会话则继续处理其他功能开发，实现真正的并行生产力。

4.2 跨AI助手支持：通过SkillKit实现生态统一

一个令人头疼的问题是，不同AI编码助手（Claude Code, Cursor, Windsurf等）的插件和技能生态互不兼容。Pro Workflow通过 SkillKit 解决了这个问题。

SkillKit是什么？ 它是一个独立的CLI工具，充当了不同AI助手技能生态的“翻译层”和“包管理器”。Pro Workflow是SkillKit上的一个官方技能包。

如何实现跨平台工作？

1. 统一安装 ：在任何支持SkillKit的AI助手环境中，你都可以通过 npx skillkit install pro-workflow 来安装核心技能和配置。
2. 自动翻译 ：SkillKit会根据目标助手（如Cursor）的配置文件格式和API，自动将Pro Workflow的技能、命令、钩子“翻译”成该助手能理解的格式。命令 npx skillkit translate pro-workflow --agent cursor 就是完成这个转换。
3. 配置同步 ：你的规则数据库（SQLite文件）和核心设置可以放在项目目录或用户全局目录中，被不同助手的Pro Workflow实例共享。这意味着你在Claude Code中训练的规则，在Cursor中同样生效。

价值 ：这保证了你的AI工作流和积累的知识资产不绑定于某个特定工具，降低了切换成本，也使得团队协作时，无论成员偏好哪种编辑器，都能遵循同一套智能工作规范。

4.3 性能、成本与权限的精细化管控

v3.2版本显著加强了对“资源”和“安全”的管控能力。

成本跟踪器（Cost Tracker） ：

• 功能 ： /cost-tracker 命令会分析当前会话的令牌使用情况，按操作类型（编辑、读取、思考）分类统计。
• 洞察 ：它能识别出“高成本模式”，例如“反复读取同一个大型配置文件”或“生成了过于冗长的计划文档”。它会给出具体建议，如“将 tsconfig.json 的内容摘要后写入 CLAUDE.md ，避免多次读取”。
• 预算告警 ：你可以在设置中配置会话预算（如 sessionBudget: 100000 ）。当消耗接近预算时，系统会发出警告，建议你总结当前进度并开启新会话，避免因上下文过长导致压缩丢失关键信息。

MCP审计（MCP Audit） ：

• 功能 ：模型上下文协议（MCP）服务器极大地扩展了AI的能力，但每个MCP调用都可能带来额外的令牌开销。 /mcp-audit 命令会评估已配置的MCP服务器。
• 分析 ：它报告每个MCP服务器调用的平均令牌消耗、频率，并识别冗余或低效的服务器。例如，你可能同时配置了 filesystem 和 github 的MCP，但审计发现 github 的代码搜索功能很少使用且代价高昂。
• 黄金法则 ：Pro Workflow的哲学是“从3个MCP开始”。通常， filesystem （文件操作）、 bash （命令行）和一个领域特定的（如 playwright 用于测试）就足够了。仅在有明确、持续的需求时才添加新的MCP。

权限调优器（Permission Tuner） ：

• 痛点 ：过于严格的权限设置会导致频繁的确认弹窗（“是否允许运行 rm -rf node_modules ？”），干扰工作流；过于宽松则存在风险。
• 解决方案 ： Permission Tuner 持续学习。每次出现 PermissionDenied 事件，它都记录被拒绝的操作、上下文和你的后续选择（是永久允许、临时允许还是拒绝）。
• 自动化建议 ：经过一段时间的运行后，执行 /permission-tuner 命令。它会分析这些日志，生成一份优化建议报告。例如：“检测到你在 node_modules 目录下频繁允许 rm -rf 操作，建议添加规则： 允许在路径包含‘node_modules’时执行删除命令 。” 你可以一键应用这些规则，从而在安全和流畅之间找到最佳平衡点。

5. 部署、配置与日常使用心法

5.1 安装与初始化配置

安装本身很简单，但正确的初始化配置是发挥效力的关键。

基础安装（Claude Code）：

# 在Claude Code插件市场添加并安装
/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflow

安装后，项目根目录下会生成或更新 .claude 文件夹，里面包含了Pro Workflow的所有配置模板。

关键配置步骤：

1. 拆分你的 CLAUDE.md ：不要使用一个巨大的 CLAUDE.md 文件。使用Pro Workflow提供的模板，将其拆分为：

   • .claude/project-context.md ：项目愿景、核心业务逻辑。
   • .claude/tech-stack.md ：技术栈详情、版本号、关键配置。
   • .claude/coding-rules.md ：代码风格、架构规范（这部分会随着自我纠正循环自动丰富）。
   • .claude/agents.md ：各代理的职责和调用条件。 这样，AI可以根据当前任务动态加载最相关的上下文模块。

2. 配置 settings.json ：复制 settings.example.json 并定制。几个必改项：

   • selfCorrection.enabled : true （开启核心功能）。
   • databasePath : 指定一个全局路径或项目内路径，用于存储SQLite规则数据库。建议使用全局路径（如 ~/.config/pro-workflow/rules.db ）以便跨项目共享部分规则。
   • compactGuard.enabled : true ，并设置 compactBudget: 50000 （在上下文剩余5万令牌时触发状态保存）。
   • 根据团队习惯，配置 commit.llmGate 和 commit.conventionalCommits 。

3. 运行 /doctor ：这是你的健康检查命令。它会验证数据库连接、钩子脚本是否就位、关键配置是否正确，并给出修复建议。

5.2 日常习惯与最佳实践

将Pro Workflow融入日常，需要培养几个关键习惯：

习惯一：有始有终的“包装”仪式

• 开始 ：每开始一个明确的开发任务，使用 /develop <feature-name> 。即使是一个小修复，也让它走一遍精简版流程（研究可能很快跳过），这有助于AI建立任务边界。
• 结束 ：务必使用 /wrap-up 结束重要会话。这个命令会触发一个清单：1) 提示你总结本次会话的成果；2) 自动捕获对话中所有被标记为 [LEARN] 的内容（这是你主动教学的好机会）；3) 将本次会话的统计数据（编辑次数、规则触发次数）存入数据库；4) 生成一个简短的交接文档，方便你或他人下次接续。

习惯二：主动教学，而非被动纠正 当AI犯错时，不要只是说“这样不对”。使用 /learn-rule 命令。系统会引导你：

1. 指出有问题的代码片段。
2. 描述正确的做法或规则。
3. （可选）指定这条规则适用的范围（文件模式、目录等）。 这个过程虽然多花10秒钟，但产出的是一条结构化的、可搜索的、可复用的规则，其长期价值远高于一次性的纠正。

习惯三：定期进行“工作流审计” 每周或每完成一个里程碑后，花几分钟：

• 运行 /insights ，查看“纠正热图”。看看AI在哪些地方犯错最多（是测试写法？API设计？），这可能是你项目文档缺失或架构模糊的信号。
• 运行 /cost-tracker ，审视令牌花费。优化高成本操作。
• 运行 /mcp-audit ，清理不必要的MCP服务器。
• 浏览 /list 输出的规则，合并或清理过时、矛盾的规则。

习惯四：善用并行与隔离 对于探索性任务（“试试用Svelte重写这个组件”）、高风险重构（“升级主框架版本”）或独立的子任务（“生成数据迁移脚本”），养成使用 /parallel 创建Git worktree的习惯。这保持了主会话上下文的洁净，也让失败的成本降至零——直接删除worktree即可。

5.3 故障排除与常见问题

问题一：钩子脚本似乎没有生效。

• 检查 ：运行 /doctor ，查看钩子部分是否报错。
• 可能原因 ：Claude Code的插件系统更新可能导致钩子注册路径变化。尝试重新安装插件，或手动检查 .claude/plugins 目录下Pro Workflow的钩子脚本是否存在且可执行。
• 解决 ：查看Pro Workflow的日志文件（通常位于 ~/.claude/logs/ 或项目内的 .claude/.pro-workflow.log ），寻找错误信息。

问题二：自我纠正的规则好像没被加载。

• 检查 ：在新会话开始时，观察初始系统消息。Pro Workflow通常会打印类似“Loaded 15 prior learnings”的日志。
• 可能原因 ：规则数据库路径配置错误，或当前项目路径与规则记录的项目路径不匹配（规则可以绑定到特定项目或全局）。
• 解决 ：使用 /search 命令，例如 /search mock database ，看是否能搜到历史规则。确认 settings.json 中的 databasePath 指向正确的文件。

问题三： /commit 的LLM Gate步骤太慢或成本高。

• 调整 ：在 settings.json 中，调整 commit.llmGate 配置。
• 方案 ：1) 换用更快的模型（如 claude-3-haiku ）。2) 设置 maxDiffTokens: 4000 ，对于更大的变更跳过LLM检查，依赖后续的人工分段审查。3) 对于你完全信任的低风险变更（如文档更新），可以临时禁用 llmGate 。

问题四：权限弹窗太多，干扰工作。

• 行动 ：立即运行 /permission-tuner 。
• 操作 ：仔细阅读分析报告。对于报告中识别出的、你确实经常允许的安全操作（如在测试目录运行清理命令），应用其生成的优化规则。这能显著减少干扰。

Pro Workflow的本质，是将你从一个不断重复指令的“监工”，转变为一个设定目标、制定规则、并审查关键结果的“架构师”。它承担了记忆、协调、质量控制和重复性提示的繁重工作，让你能更专注于真正需要人类创造力和判断力的部分。这个工具的价值并非立竿见影，而是随着时间推移，在几十次、上百次会话的化合物效应中，让你与AI的协作变得无比流畅和高效。开始可能会觉得需要适应新的命令和流程，但一旦习惯养成，你会发现再也回不到那种每开新会话就要从头教起的原始模式了。