pro-workflow

专业工作流

源自生产实践的完整 AI 编码工作流系统。涵盖编排模式、参考指南和经实战验证的习惯，这些习惯会随着时间不断积累。

适用对象： Claude Code、Cursor、Codex、Gemini CLI，以及通过 skills add 支持的 32+ 款 AI 编码 Agent。标记为 (Claude Code) 的部分使用 Claude Code 专属功能——Cursor 用户可以跳过，或使用注明的替代方案。

核心洞见

“我的代码有 80% 是 AI 写的，20% 的时间花在审查和修正上。” — Karpathy

这项技能针对这一比例进行优化。此处的每种模式都能减少修正周期。

---

1. 自我纠正循环

最强大的单一模式。 你的 CLAUDE.md 会通过纠正不断完善自身。

工作方式

当你纠正 Claude 时：

1. Claude 承认错误
2. 提出一条规则来避免重犯
3. 你批准后 → 规则写入记忆
4. 后续会话避免犯同样的错误

添加到 CLAUDE.md

## Self-Correction Protocol

When the user corrects me or I make a mistake:
1. Acknowledge specifically what went wrong
2. Propose a concise rule: `[LEARN] Category: One-line rule`
3. Wait for approval before adding to LEARNED section

### LEARNED

触发短语

• “把这条加到你的规则里”
• “记住这一点”
• “别再这样做了”

示例流程

User: You edited the wrong file
Claude: I edited src/utils.ts when you meant src/lib/utils.ts.

[LEARN] Navigation: Confirm full path before editing files with common names.

Should I add this?

---

1b. 事前检查纪律

自我纠正会在事后发现错误；这能在错误发生前发现它们。

Karpathy 关于 LLM 编码陷阱的观察 指出了上游问题：默默作出假设、让差异过于复杂、顺手修改无关内容、成功标准模糊。四条规则分别防止这些问题。

规则	防止的问题
明确说明，不要假设	错误理解、隐藏的困惑、遗漏权衡
最小可行代码	本应是 50 行却写成 200 行的差异、推测性抽象
各司其职	顺手重构、对相邻代码进行“改进”
目标可验证	无休止地重新澄清、“让它能用”的循环

完整规则位于 rules/pre-flight-discipline.mdc（alwaysApply: true）。与自我纠正配合使用：事前检查阻止错误，自我纠正则在错误漏网时记录教训。

添加到 CLAUDE.md

## Pre-Flight Discipline
Before coding: state assumptions, present ambiguity, push back if simpler exists.
Every changed line traces to the request - no drive-by edits.
Convert imperatives to verifiable goals: "fix bug" → "failing test → make it pass".

---

2. 使用工作树运行并行会话

不浪费一刻。 一个 Claude 思考时，你可以处理其他事情。

设置

Claude Code：

claude --worktree    # or claude -w (auto-creates isolated worktree)

Cursor / 任意编辑器：

git worktree add ../project-feat feature-branch
git worktree add ../project-fix bugfix-branch

后台 Agent 管理 (Claude Code)

• Ctrl+F — 终止所有后台 Agent（需按两次确认）
• Ctrl+B — 将任务发送到后台
• 子 Agent 支持在 Agent frontmatter 中使用 isolation: worktree

何时并行处理

场景	操作
等待测试	在工作树中开始开发新功能
长时间构建	并行调试问题
探索不同方案	同时尝试 2-3 种方案

添加到 CLAUDE.md

## Parallel Work
When blocked on long operations, use `claude -w` for instant parallel sessions.
Subagents with `isolation: worktree` get their own safe working copy.

---

3. 收尾仪式

有目的地结束会话。记录经验，确认状态。

/wrap-up 检查清单

1. 变更审查 - 列出已修改文件和未提交的变更
2. 状态检查 - 运行 git status、测试和 lint
3. 经验记录 - 犯了哪些错误？哪些做法有效？
4. 下次会话 - 接下来做什么？是否有阻塞因素？
5. 摘要 - 用一段话总结已完成的工作

创建命令

~/.claude/commands/wrap-up.md：

Execute wrap-up checklist:
1. `git status` - uncommitted changes?
2. `npm test -- --changed` - tests passing?
3. What was learned this session?
4. Propose LEARNED additions
5. One-paragraph summary

---

4. 拆分式记忆架构

对于复杂项目，将 Claude 记忆模块化。

结构

.claude/
├── CLAUDE.md        # Entry point
├── AGENTS.md        # Workflow rules
├── SOUL.md          # Style preferences
└── LEARNED.md       # Auto-populated

AGENTS.md

# Workflow Rules

## Planning
Plan mode when: >3 files, architecture decisions, multiple approaches.

## Quality Gates
Before complete: lint, typecheck, test --related.

## Subagents
Use for: parallel exploration, background tasks.
Avoid for: tasks needing conversation context.

SOUL.md

# Style

- Concise over verbose
- Action over explanation
- Acknowledge mistakes directly
- No features beyond scope

---

5. 80/20 审查模式

在检查点集中审查，而不是每次变更都审查。

审查时机

1. 计划获批后
2. 每个里程碑完成后
3. 执行破坏性操作前
4. 在 /wrap-up 时

添加到 CLAUDE.md

## Review Checkpoints
Pause for review at: plan completion, >5 file edits, git operations, auth/security code.
Between: proceed with confidence.

---

6. 模型选择

当前阵容（2026 年）： Fable 5.1、Opus 5.5、Sonnet 5 和 Haiku 4.5。旗舰级别模型的上下文窗口为 1M 个 token；Haiku 4.5 为 200K 个 token。前沿模型的能力已趋于一致，因此，脚手架和 effort 设置对输出质量的影响大于模型选择。字符串、价格和路由信息请参阅 references/models-2026.md。

任务	模型	Effort
快速修复、查询	Haiku 4.5	low
功能开发、均衡型工作	Sonnet 5	high
重构、架构、棘手的调试	Opus 5.5	xhigh
长周期自主构建	Fable 5.1	high / xhigh

Effort 与自适应思考

当前级别已不再使用固定的思考预算。通过 effort（从 low 到 xhigh，再到 max）控制思考深度；对于编码和 Agent 工作，默认值为 xhigh。自适应思考允许模型为每个步骤调整推理，无需固定预算。在 Haiku 上以 low effort 运行繁重的子 Agent，并将推理流程留给能力更强的级别。

添加到 CLAUDE.md

## Model Hints
Route by task: Haiku 4.5 for lookups, Sonnet 5 for features, Opus 5.5 for
architecture and hard debugging, Fable 5.1 for long-horizon builds.
Effort is the lever, not thinking budgets: xhigh for coding, low for subagents.

---

7. 上下文管理

即使有 1M 个 token 的上下文窗口（Haiku 4.5 为 200K 个 token），上下文仍然有限。请做好管理。

规则

1. 先阅读，再编辑
2. 在任务边界处压缩上下文
3. 禁用未使用的 MCP（启用的少于 10 个，工具少于 80 个）
4. 总结探索过程
5. 使用子 Agent 隔离大量输出（测试、日志、文档）

上下文压缩

• 容量达到约 95% 时自动压缩（保持长时间运行的 Agent 不退出）
• 提前配置压缩：CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50
• 使用 PreCompact hook 在压缩前保存状态
• 子 Agent 会独立于主会话自动压缩上下文

适合压缩的时机

• 规划完成后、执行开始前
• 功能完成后
• 上下文使用率超过 70% 时
• 切换任务领域前

---

8. 学习日志

自动记录会话中的见解。

添加到 CLAUDE.md

## Learning Log
After tasks, note learnings:
`[DATE] [TOPIC]: Key insight`

Append to .claude/learning-log.md

---

学习 Claude Code

运行 /learn，按主题查看涵盖会话、上下文、CLAUDE.md、子 Agent、hook 等内容的指南（参见 commands/learn.md）。官方文档：https://code.claude.com/docs/

---

快速设置

最简设置

添加到你的 CLAUDE.md：

## Pro Workflow

### Self-Correction
When corrected, propose rule → add to LEARNED after approval.

### Planning
Multi-file: plan first, wait for "proceed".

### Quality
After edits: lint, typecheck, test.

### LEARNED

完整设置

git clone https://github.com/rohitg00/pro-workflow.git /tmp/pw
cp -r /tmp/pw/templates/split-claude-md/* ./.claude/
cp -r /tmp/pw/commands/* ~/.claude/commands/

---

Hook (Claude Code)

Pro-workflow 包含自动化 hook，用于强制执行这些模式。Cursor 用户可通过 rules/ 目录中的 .mdc 规则实现同等约束。

PreToolUse Hook

触发条件	操作
Edit/Write	跟踪编辑次数，在编辑 5 次/10 次时提醒
git commit	提醒运行质量门禁
git push	提醒使用 /wrap-up

PostToolUse Hook

触发条件	操作
代码编辑（.ts/.js/.py/.go）	检查 console.log、TODO 和密钥
测试命令	根据失败情况建议添加 [LEARN]

会话 Hook

Hook	操作
SessionStart	加载已学习的模式，显示 worktree 数量
Stop	使用 last_assistant_message 提供上下文相关的提醒
SessionEnd	检查未提交的更改，提示记录经验
ConfigChange	检测会话中途是否修改了质量门禁或 hook

安装 Hook

# Copy hooks to your settings
cp ~/skills/pro-workflow/hooks/hooks.json ~/.claude/settings.local.json

# Or merge with existing settings

Hook 理念

基于 Twitter 话题串中的见解：

• 非阻塞——Hook 只提醒，不阻止（危险操作除外）
• 基于检查点——按间隔执行质量门禁，而非每次编辑都执行
• 关注学习——始终提示捕获模式

---

上下文模式

根据当前任务切换模式。

上下文	触发语句	行为
dev	“Let's build”	优先编写代码，快速迭代
review	“Review this”	只读，关注安全性
research	“Help me understand”	探索、总结、规划

使用：“Switch to dev mode”，或加载上下文文件。

---

Agent

用于专注处理任务的专用子 Agent。

Agent	用途	工具
planner	拆解复杂任务	只读
reviewer	代码审查、安全审计	读取 + 测试

何时委派

在以下情况下使用规划 Agent：

• 任务涉及超过 5 个文件
• 需要做出架构决策
• 需求不明确

在以下情况下使用审查 Agent：

• 提交之前
• 审查 PR
• 存在安全方面的顾虑

自定义子 Agent （Claude Code）

在 .claude/agents/ 中创建项目专属子 Agent，或在 ~/.claude/agents/ 中创建用户级子 Agent：

• 使用 YAML frontmatter 和 Markdown 系统提示词进行定义
• 控制工具、模型、权限模式、钩子和持久化记忆
• 使用 /agents 以交互方式创建、编辑和管理
• 为子 Agent 预加载技能，以提供领域知识

Agent 团队 （Claude Code，实验性）

协调多个 Claude Code 会话组成团队：

• 启用：CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
• 主会话负责协调，队友独立工作
• 队友可以直接相互发送消息（而不只是汇报结果）
• 共享任务列表并管理依赖关系
• 显示方式：进程内（按 Shift+Down 导航，可循环切换）或分屏窗格（tmux/iTerm2）
• 委派模式（Shift+Tab）：主会话只负责协调，不编辑代码
• 适用于：并行审查、竞争性假设、跨层变更
• 文档： https://code.claude.com/docs/agent-teams

---

9. 编排：命令 > Agent > 技能

这是处理复杂功能时最强大的模式。分为三层，每层只负责一项工作。

架构

Command (user-facing entry point)
  └── Agent (execution, constrained tools, preloaded skills)
        └── Skill (domain knowledge, injected at startup)

多阶段开发（/develop）

对于涉及超过 5 个文件或需要架构决策的功能：

1. 研究 → 编排器 Agent 探索代码库并评估置信度（0-100）
2. 计划 → 展示方案、要修改的文件和风险。等待批准。
3. 实现 → 逐步执行计划，每修改 5 次进行一次质量检查
4. 审查 → 审查 Agent 检查安全性、逻辑和质量

四个阶段按顺序执行。每个阶段都需要用户明确批准后，才能开始下一阶段。

Agent 技能（预加载）

# Agent frontmatter
skills: ["api-conventions", "project-patterns"]

Agent 启动时会注入完整的技能内容。适用于 Agent 始终需要的知识。

按需技能（调用）

设置了 user-invocable: true 的技能可通过 /skill-name 调用。使用 context: fork 可隔离执行，避免污染主上下文。

何时进行编排

场景	模式
功能涉及超过 5 个文件	使用编排器运行 /develop
调查 Bug	调试器 Agent
快速探索	侦察 Agent（后台运行）
代码审查	审查 Agent
简单任务	直接处理

---

10. 日常习惯

每次会话

• 如果感觉不对劲，运行 /doctor
• 在上下文达到 50% 时手动运行 /compact，不要等自动压缩
• 在提示词中使用 ultrathink，进行最大限度的推理
• 使用 /rename 为会话命名，方便通过 /resume 恢复
• 结束时运行 /wrap-up，记录经验

上下文管理

• CLAUDE.md：根目录下少于 60 行，最多少于 150 行
• 使用 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50 主动压缩上下文
• 将繁重的探索工作委派给子 Agent
• MCP 数量少于 10 个，工具数量少于 80 个

跨 Agent 提示

• 使用 Cursor 进行 Tab 补全，并在终端中使用 Claude Code 处理难题
• 两者可使用相同的 MCP 服务（在项目根目录共享 .mcp.json）
• 使用 npx skills add rohitg00/pro-workflow 将技能安装到任意 Agent

---

MCP 配置 （Claude Code）

从 3 个 MCP 开始。仅在有明确需求时添加。

必备项：

• context7 — 实时查阅文档
• playwright — 浏览器自动化（Token 效率最高）
• github — PR、问题、代码搜索

请参阅 mcp-config.example.json 了解设置方法和精选建议。

---

命令（Claude Code）

命令	用途	Cursor 对应项
/wrap-up	会话结束仪式	wrap-up 技能
/learn-rule	将更正提取到记忆中	learn-rule 技能
/develop	多阶段功能开发	orchestrate 技能
/doctor	健康检查	—
/commit	带质量门禁的智能提交	smart-commit 技能
/insights	会话分析和模式	insights 技能
/replay	展示过往经验	replay-learnings 技能
/handoff	会话交接文档	session-handoff 技能
/search	按关键词搜索经验	—
/list	列出所有已存储的经验	—
/learn	按主题逐一介绍 Claude Code	—

---

参考指南

深入了解配置和功能：

指南	主题
references/settings-guide.md	所有设置键、权限模式、层级、沙盒、环境变量
references/cli-cheatsheet.md	所有 CLI 标志、键盘快捷键、斜杠命令
references/orchestration-patterns.md	Command > Agent > Skill 架构、frontmatter 参考
references/context-loading.md	CLAUDE.md 单体仓库加载、Agent 记忆、技能发现
references/cross-agent-workflows.md	Claude Code + Cursor 配置映射、后台 Agent
references/new-features.md	语音模式、Agent 团队、检查点、新钩子事件
references/daily-habits.md	会话习惯、调试技巧、终端设置、反模式

---

理念

1. 改进叠加 - 小小的更正能带来巨大提升
2. 信任但核验 - 让 AI 工作，并在检查点进行审查
3. 零空闲时间 - 并行会话保持推进势头
4. 记忆弥足珍贵 - 无论是你的记忆还是 AI 的记忆
5. 编排，而非事无巨细地管理 - 将模式连接起来，让 Agent 执行

---

在 Claude Code、Cursor 等工具的生产实践中形成的完整 AI 编码工作流系统。