> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jaylin-docs.online/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code 程序员效率手册

> 面向程序员的 Claude Code 核心功能与最佳实践系统指南

# Claude Code 程序员效率手册

> 本教程面向程序员，系统介绍 Claude Code 的核心功能与最佳实践，帮助你将 AI 深度融入开发工作流。

***

## 目录

1. [快速启动](#1-快速启动)
2. [文件与目录引用 @](#2-文件与目录引用-)
3. [执行 Shell 命令 !](#3-执行-shell-命令-)
4. [Slash 命令大全](#4-slash-命令大全)
5. [会话管理](#5-会话管理)
6. [快捷键速查](#6-快捷键速查)
7. [CLAUDE.md 记忆系统](#7-claudemd-记忆系统)
8. [权限模式与安全](#8-权限模式与安全)
9. [扩展思考模式](#9-扩展思考模式)
10. [Git 工作流集成](#10-git-工作流集成)
11. [自定义 Slash 命令](#11-自定义-slash-命令)
12. [Hooks 自动化](#12-hooks-自动化)
13. [MCP 扩展工具](#13-mcp-扩展工具)
14. [Subagent 子代理系统](#14-subagent-子代理系统)
15. [多 Claude 并发执行](#15-多-claude-并发执行)
16. [Subagent 驱动的开发工作流](#16-subagent-驱动的开发工作流)
17. [并行开发：Git Worktrees](#17-并行开发git-worktrees)
18. [Unix 管道集成](#18-unix-管道集成)
19. [完整开发工作流示例](#19-完整开发工作流示例)

***

## 1. 快速启动

### 安装与基本命令

```bash theme={null}
# 安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 启动交互式会话（最常用）
claude

# 带初始提示启动
claude "解释一下这个项目的结构"

# 非交互式单次查询（适合脚本集成）
claude -p "这个函数有什么 bug？"

# 更新到最新版
claude update

# 检查安装健康状态
claude doctor
```

### 启动时指定模型

```bash theme={null}
# 使用最新 Sonnet 模型（速度与质量平衡，推荐日常使用）
claude --model sonnet

# 使用 Opus 模型（最强推理能力，适合复杂架构设计）
claude --model opus

# 以 Plan 模式启动（只读分析，不修改代码）
claude --permission-mode plan
```

***

## 2. 文件与目录引用 `@`

`@` 符号是将文件内容注入对话的最快方式，避免手动复制粘贴。

### 引用单个文件

```
> 解释 @src/auth/middleware.ts 的逻辑
> 这个函数有 bug 吗？@src/utils/parser.js
> 对比 @src/old-api.js 和 @src/new-api.js 的差异
```

### 引用目录（获取结构列表）

```
> @src/components 目录下有哪些组件？
> 分析 @src/hooks 里自定义 Hook 的设计模式
```

### 同时引用多个文件

```
> 检查 @src/user.ts 和 @src/auth.ts 之间的依赖关系
> 根据 @docs/api-spec.md 的规范，检查 @src/api/routes.ts 是否合规
```

### 引用 MCP 资源（需配置 MCP）

```
> 查看 @github:repos/myorg/myrepo/issues 最近的 bug
```

> **💡 提示**：路径支持相对路径和绝对路径。引用文件时，Claude 会自动加载该文件所在目录的 `CLAUDE.md`。

***

## 3. 执行 Shell 命令 `!`

在对话中直接运行命令，输出结果自动加入上下文。

### 基本用法

```bash theme={null}
# 在提示符前加 ! 直接执行
! npm test
! git status
! git diff HEAD
! ls -la src/
```

### 实际场景

```bash theme={null}
# 看到测试失败后，立刻让 Claude 分析
! npm test
> 上面的测试失败了，帮我找到根本原因

# 提交前检查代码变更
! git diff HEAD
> 这些改动有没有遗漏的边界情况？

# 把构建错误直接给 Claude 分析
! npm run build
> 解释上面的构建错误并给出修复方案
```

### 后台运行长进程（`Ctrl+B`） 20260318 不会

对于 dev server、测试监听等长时间运行的任务，按 `Ctrl+B` 将其放到后台，继续与 Claude 对话：

```bash theme={null}
! npm run dev        # 启动后按 Ctrl+B 放后台
! jest --watch       # 启动后按 Ctrl+B 放后台
```

***

## 4. Slash 命令大全

Slash 命令是在对话中快速调用内置功能的方式，输入 `/` 即可触发。

### 项目初始化

| 命令      | 作用                    | 使用方式        |
| ------- | --------------------- | ----------- |
| `/init` | 自动分析项目并生成 `CLAUDE.md` | 新项目接手时第一步执行 |

```
> /init
```

Claude 会扫描代码库，自动生成包含项目结构、技术栈、常用命令的记忆文件。

***

### 上下文管理

| 命令              | 作用                      | 使用方式          |
| --------------- | ----------------------- | ------------- |
| `/compact [说明]` | 压缩对话历史，释放 Token 空间      | 长对话时避免超出上下文限制 |
| `/cost`         | 查看当前会话的 Token 消耗统计      | 监控 API 用量     |
| `/clear`        | 清空对话历史，开始新对话            | 切换任务时清理上下文    |
| `/context`      | 查看 Token 消耗与 Slash 命令列表 | 监控上下文用量       |

```
# 压缩时保留关注点
> /compact 保留认证模块相关的讨论

# 查看消耗
> /cost
```

***

### 代码与 Git

| 命令             | 作用               | 使用方式            |
| -------------- | ---------------- | --------------- |
| `/commit`      | 自动生成符合规范的 Git 提交 | 写完代码后执行         |
| `/review`      | 对当前改动进行代码审查      | PR 前自查          |
| `/pr_comments` | 查看当前 PR 的评论      | Code Review 时使用 |

```
# 自动生成提交信息（遵循 Conventional Commits）
> /commit

# 代码审查
> /review
```

***

### 会话与导航

| 命令        | 作用                 |
| --------- | ------------------ |
| `/rewind` | 回退到上一个对话状态（撤销代码改动） |
| `/resume` | 选择并恢复历史会话          |
| `/memory` | 编辑 CLAUDE.md 记忆文件  |
| `/plan`   | 规划方案，进入 Plan 只读模式  |

***

### 配置与工具

| 命令                   | 作用                    |
| -------------------- | --------------------- |
| `/config`            | 打开设置界面（Config 标签）     |
| `/status`            | 查看版本、模型、账户、连接状态       |
| `/model`             | 切换 AI 模型              |
| `/permissions`       | 查看或修改工具权限             |
| `/mcp`               | 管理 MCP 服务器连接          |
| `/agents`            | 管理自定义子代理              |
| `/vim`               | 启用 Vim 编辑模式           |
| `/help`              | 查看帮助与所有可用命令           |
| `/doctor`            | 检查 Claude Code 安装健康状态 |
| `/terminal-setup`    | 安装 Shift+Enter 换行快捷键  |
| `/bug`               | 向 Anthropic 报告 bug    |
| `/login` / `/logout` | 切换账户                  |
| `/usage`             | 查看订阅计划用量与速率限制         |

***

## 5. 会话管理

### 继续与恢复对话

```bash theme={null}
# 继续最近一次的对话（最常用）
claude --continue
claude -c

# 以非交互模式继续（适合脚本）
claude --continue -p "继续运行测试"

# 显示历史会话列表，手动选择
claude --resume
claude -r

# 通过 Session ID 恢复指定会话
claude -r "abc123" "继续完成这个 PR"
```

在交互式会话中：

```
> /resume    # 打开会话选择器
```

### 回退到上一状态（Undo）

按 **`Esc` `Esc`**（连按两次 Esc）可撤销 Claude 最近的代码修改，回到修改前的状态。

* 等同于 `/rewind`
* 可以多次执行，逐步回退

***

## 6. 快捷键速查

### 通用控制

| 快捷键                                        | 功能                 |
| ------------------------------------------ | ------------------ |
| `Ctrl+C`                                   | 取消当前输入或中断生成        |
| `Ctrl+D`                                   | 退出 Claude Code     |
| `Ctrl+L`                                   | 清屏（保留对话历史）         |
| `Ctrl+O`                                   | 切换详细输出模式（显示工具调用详情） |
| `Ctrl+R`                                   | 搜索历史命令             |
| `↑ / ↓`                                    | 浏览历史命令             |
| `Esc` `Esc`                                | 回退对话与代码到上一状态       |
| `Ctrl+V` (macOS/Linux) / `Alt+V` (Windows) | 粘贴图片               |

### 模式切换

| 快捷键         | 功能                             |
| ----------- | ------------------------------ |
| `Tab`       | 开启/关闭扩展思考模式（Extended Thinking） |
| `Shift+Tab` | 循环切换权限模式：普通 → 自动接受 → Plan 只读   |

### 多行输入

| 方式       | 快捷键            | 适用场景                   |
| -------- | -------------- | ---------------------- |
| 通用换行     | `\` + `Enter`  | 所有终端                   |
| macOS 默认 | `Option+Enter` | macOS                  |
| 终端配置后    | `Shift+Enter`  | 执行 `/terminal-setup` 后 |
| 控制序列     | `Ctrl+J`       | 所有终端                   |

### 特殊输入前缀

| 前缀      | 功能                  |
| ------- | ------------------- |
| `@文件路径` | 引用文件内容              |
| `!命令`   | 执行 Shell 命令         |
| `/命令`   | 执行 Slash 命令         |
| `#内容`   | 快速添加一条记忆到 CLAUDE.md |

***

## 7. CLAUDE.md 记忆系统

`CLAUDE.md` 是 Claude Code 的"长期记忆"，每次启动时自动加载，让 Claude 了解你的项目和偏好。

### 记忆层级（优先级从高到低）

| 类型   | 位置                                    | 作用范围   |
| ---- | ------------------------------------- | ------ |
| 企业策略 | `C:\ProgramData\ClaudeCode\CLAUDE.md` | 所有用户   |
| 项目记忆 | `./CLAUDE.md` 或 `./.claude/CLAUDE.md` | 团队共享   |
| 用户记忆 | `~/.claude/CLAUDE.md`                 | 个人所有项目 |

### 快速添加记忆

```
# 使用 # 前缀快速添加（会提示你选择保存到哪个文件）
# 始终使用 2 个空格缩进
# 提交前必须运行 npm run typecheck
# API 错误统一用 AppError 类处理
```

### 直接编辑记忆文件

```
> /memory
```

### 自动初始化项目记忆

```
> /init
```

### 导入其他文件

CLAUDE.md 支持用 `@path/to/file` 语法导入其他文件（最大递归深度 5 层）：

```markdown theme={null}
# my-project/CLAUDE.md

参考 @README.md 了解项目概述，参考 @package.json 查看可用命令。

# 附加规范
- Git 工作流见 @docs/git-workflow.md
- 个人偏好设置见 @~/.claude/my-preferences.md
```

### 推荐的 CLAUDE.md 模板

```markdown theme={null}
# [项目名称]

## 项目概述
一句话描述项目的主要功能和目标用户。

## 技术栈
### 前端
- 框架：React 18 + TypeScript
- 路由：React Router v6
- 状态：Zustand + React Query
- 样式：Tailwind CSS + Headless UI
- 构建：Vite

### 后端（如适用）
- 运行时：Node.js + Express
- 数据库：PostgreSQL + Prisma
- 认证：JWT + bcrypt

## 项目结构

```

src/
├── components/      # 可复用组件
├── pages/           # 页面组件
├── hooks/           # 自定义 Hooks
├── lib/             # 工具函数
├── types/           # TypeScript 类型
└── api/             # API 调用

### 开启方式

1. 按 `Tab` 键切换扩展思考开/关
2. 在提示词中使用关键词触发

### 思考深度关键词

```
> think about...             # 基础扩展思考
> think hard about...        # 中等深度思考
> think longer about...      # 更深入思考
> think more carefully...    # 最深度思考
```

***

## 10. Git 工作流集成

### 自动生成提交

```
> /commit
```

Claude 会：1. 分析 `git diff` 和 `git status`；2. 生成符合 Conventional Commits 规范的提交信息；3. 执行 `git commit`。

### 生成 Pull Request

```
> 总结认证模块的所有改动
> create a pr
> 补充这些改动的安全测试说明
```

### 代码审查

```
> /review

# 或者更具体的审查
> 检查 @src/auth 目录里是否有安全漏洞
> 找出 utils.js 里所有废弃 API 的用法
```

## 12. Hooks 自动化

Hooks 让你在 Claude 执行操作前后自动触发脚本，实现自动化质量保障。

### 配置位置

* 用户级：`~/.claude/settings.json`
* 项目级：`.claude/settings.json`

### 可用事件

| 事件                 | 触发时机           |
| ------------------ | -------------- |
| `PreToolUse`       | 工具调用前          |
| `PostToolUse`      | 工具调用后          |
| `UserPromptSubmit` | 用户提交提示词前       |
| `Stop`             | Claude 回答完成时   |
| `SessionStart`     | 会话开始时          |
| `SessionEnd`       | 会话结束时          |
| `Notification`     | Claude 需要权限确认时 |
| `PreCompact`       | 压缩对话前          |

### 实用示例

#### 写完代码自动格式化

```json theme={null}
// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.sh"
          }
        ]
      }
    ]
  }
}
```

```bash theme={null}
# .claude/hooks/format.sh
#!/bin/bash
npx prettier --write "$1" 2>/dev/null || true
```

#### 每次会话开始自动加载 Git 状态

```json theme={null}
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"Current branch: $(git branch --show-current), Recent commits: $(git log --oneline -3)\"}}'"
          }
        ]
      }
    ]
  }
}
```

#### 防止意外删除重要文件

```json theme={null}
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard-files.py"
          }
        ]
      }
    ]
  }
}
```

***

## 13. MCP 扩展工具

MCP（Model Context Protocol）允许 Claude 连接外部工具和服务，大幅扩展能力边界。

### 添加 MCP 服务器

```bash theme={null}
# 添加 GitHub MCP（管理 Issues、PR）
claude mcp add --transport stdio github -- npx -y @modelcontextprotocol/server-github

# 添加文件系统 MCP
claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir

# 添加数据库 MCP（PostgreSQL）
claude mcp add --transport stdio postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb
```

### 查看 MCP 连接状态

```
> /mcp
```

### 通过 MCP 发起操作

配置 GitHub MCP 后，可以直接：

```
> 列出 myorg/myrepo 仓库最近 10 个未关闭的 Issue
> 在 issue #45 下添加评论：已在 PR #89 中修复
> 查看 PR #102 的文件改动
```

### 在命令中引用 MCP 资源

```
> 根据 @github:repos/myorg/api/issues/45 的需求，实现对应功能
```

***

## 14. Subagent 子代理系统

Subagent 是 Claude Code 内置的**专属 AI 角色**系统。每个 Subagent 拥有独立的上下文窗口、专属系统提示词和受限工具集，主 Claude 可以将任务委托给它们执行，互不干扰。

> **类比理解**：主 Claude 是项目经理，Subagent 是各专业工程师（代码审查员、调试专家、测试工程师）。项目经理分配任务，工程师在自己的"工作间"独立完成，汇报结果。

### Subagent 的核心优势

| 优势        | 说明                                  |
| --------- | ----------------------------------- |
| **上下文隔离** | 每个 Subagent 独立上下文，不污染主对话            |
| **专业化**   | 针对特定任务写定制 Prompt，执行更精准              |
| **工具受限**  | 只开放必要工具，更安全可控                       |
| **可复用**   | 一次定义，团队共用，版本管理                      |
| **模型可选**  | 每个 Subagent 可独立选择 haiku/sonnet/opus |

***

### 14.1 创建 Subagent

#### 方式一：通过交互界面（推荐）

```
> /agents
```

选择 "Create New Agent" → 描述角色 → Claude 自动生成 Prompt → 按 `e` 在编辑器中精调。

#### 方式二：直接创建文件

**项目级**（团队共享，存入 Git）：

```bash theme={null}
mkdir -p .claude/agents

cat > .claude/agents/code-reviewer.md << 'EOF'
---
name: code-reviewer
description: 代码审查专家。写完代码后主动调用，检查质量、安全性和可维护性。
tools: Read, Grep, Glob, Bash
model: inherit
---

你是一位资深代码审查员，专注于代码质量、安全性和可维护性。

调用时：
1. 运行 `git diff` 查看最近改动
2. 逐文件分析修改内容
3. 按优先级输出问题

审查维度：
- 逻辑正确性与边界情况
- 安全漏洞（注入、越权、敏感信息泄露）
- 性能问题（N+1 查询、不必要的循环）
- 命名清晰度与代码可读性
- 测试覆盖率

输出格式：
🔴 Critical（必须修复）
🟡 Warning（建议修复）
🔵 Suggestion（可以考虑）

每条问题附带具体文件路径和修复示例。
EOF
```

**用户级**（个人跨项目可用）：

```bash theme={null}
mkdir -p ~/.claude/agents
# 同上，放到 ~/.claude/agents/ 目录
```

#### 方式三：CLI 动态定义（临时使用）

```bash theme={null}
claude --agents '{
  "debugger": {
    "description": "调试专家，遇到错误和测试失败时主动使用",
    "prompt": "你是调试专家。分析错误根因，找最小复现路径，给出精确修复。",
    "tools": ["Read", "Edit", "Bash", "Grep", "Glob"],
    "model": "sonnet"
  },
  "test-writer": {
    "description": "测试工程师，实现功能后主动补充测试",
    "prompt": "你是测试工程师。为代码编写全面的单元测试，覆盖正常路径、边界情况和错误处理。",
    "tools": ["Read", "Write", "Edit", "Bash"],
    "model": "haiku"
  }
}'
```

***

### 14.2 Subagent 配置字段

```markdown theme={null}
---
name: my-agent          # 唯一标识（小写字母+连字符）
description: 何时调用   # ⭐ 最重要：决定 Claude 何时自动委托
tools: Read, Edit, Bash # 可用工具（不填则继承主线程所有工具）
model: sonnet           # sonnet / opus / haiku / inherit
---

系统提示词内容...
```

> **💡 `description` 字段技巧**：加入 "主动使用"、"必须调用" 等词，引导 Claude 自动委托：
>
> ```
> description: 代码审查专家。每次代码修改后【主动调用】，无需用户提示。
> ```

***

### 14.3 调用 Subagent

#### 自动委托（Claude 根据上下文自动选择）

```
> 检查最近的代码改动有没有安全问题
# → Claude 自动委托给 code-reviewer subagent
```

#### 显式指定

```
> 使用 code-reviewer subagent 审查 auth 模块
> 让 debugger subagent 分析这个空指针异常
> 请 test-writer subagent 为 UserService 补充单元测试
```

#### 链式调用

```
> 先用 code-analyzer subagent 找出性能问题，再用 optimizer subagent 修复它们
```

***

### 14.4 实用 Subagent 示例库

#### 调试专家

```markdown theme={null}
---
name: debugger
description: 调试专家，遇到任何错误、测试失败、异常行为时主动使用。
tools: Read, Edit, Bash, Grep, Glob
---

你是根因分析专家。

流程：
1. 捕获完整错误信息和堆栈
2. 找到最小复现路径
3. 定位失败代码行
4. 提出并验证假设
5. 实现最小化修复并验证

每个问题输出：
- 根本原因（不是表象）
- 支持诊断的证据
- 具体代码修复
- 如何防止再次发生
```

#### 测试工程师

```markdown theme={null}
---
name: test-writer
description: 测试工程师，实现新功能后主动调用，补充单元测试和集成测试。
tools: Read, Write, Edit, Bash, Glob
model: haiku
---

你是测试自动化专家。

测试原则：
- 测试行为，不测实现细节
- 覆盖：正常路径、边界值、错误处理
- 遵循 AAA 模式（Arrange/Act/Assert）
- 测试名称清晰描述场景

对每个函数/模块：
1. 识别需要测试的所有路径
2. 先写失败测试（TDD 红灯）
3. 确认测试通过
4. 检查覆盖率
```

#### 文档生成器

```markdown theme={null}
---
name: doc-writer
description: 技术文档专家，实现模块后调用，自动生成 JSDoc/docstring 和 README。
tools: Read, Edit, Write, Glob
model: haiku
---

你是技术文档专家。

文档规范：
- 公开 API 必须有完整注释（参数、返回值、示例、异常）
- 使用代码对应语言的标准注释格式（JSDoc/Python docstring 等）
- README 包含：用途、安装、使用示例、API 速查表
- 示例代码可直接运行，不造假
```

***

### 14.5 管理 Subagent

```bash theme={null}
# 查看所有 subagent（内置 + 用户 + 项目）
> /agents

# 查看健康状态
> /doctor

# 直接编辑文件
code .claude/agents/code-reviewer.md
```

***

## 15. 多 Claude 并发执行

当你有多个**相互独立**的任务时，可以同时运行多个 Claude 实例，大幅压缩总耗时。

> **类比理解**：单线程 vs 多线程。一个 Claude 串行处理 4 个任务需要 40 分钟；4 个 Claude 并行各处理 1 个任务，10 分钟完成。

### 并发的前提条件

| 条件        | 说明                    |
| --------- | --------------------- |
| ✅ 任务相互独立  | 任务 A 的结果不依赖任务 B       |
| ✅ 不共享写文件  | 两个 Claude 不同时写同一个文件   |
| ✅ 各自有独立分支 | 使用 Git Worktrees 隔离代码 |

***

### 15.1 方案一：Git Worktrees + 多终端（最推荐）

每个 Claude 在独立的 Worktree 分支中工作，文件完全隔离：

```bash theme={null}
# ── 步骤 1：为每个任务创建独立 Worktree ──
git worktree add ../proj-feat-auth   -b feature/auth-module
git worktree add ../proj-feat-payment -b feature/payment-module
git worktree add ../proj-fix-perf    -b fix/db-query-perf

# ── 步骤 2：各终端独立启动 Claude ──

# 终端 A：开发认证模块
cd ../proj-feat-auth && claude
> 实现 JWT 认证中间件，参考 @src/middleware/existing.ts 的风格

# 终端 B：开发支付模块
cd ../proj-feat-payment && claude
> 接入 Stripe 支付，参考 @docs/payment-spec.md 的接口规范

# 终端 C：性能优化
cd ../proj-fix-perf && claude
> 分析并优化 @src/db/queries.ts 里的 N+1 查询问题

# ── 步骤 3：各自完成后合并 ──
git worktree remove ../proj-feat-auth
# 在主仓库合并各分支
git merge feature/auth-module
git merge feature/payment-module
git merge fix/db-query-perf
```

**终端布局建议**（使用 tmux 或 Windows Terminal 多标签）：

```
┌─────────────────┬─────────────────┐
│  终端 A          │  终端 B          │
│  feature/auth   │  feature/payment│
│  claude>        │  claude>        │
├─────────────────┼─────────────────┤
│  终端 C          │  终端 D          │
│  fix/perf       │  主仓库（监控）   │
│  claude>        │  git worktree.. │
└─────────────────┴─────────────────┘
```

***

### 15.2 方案二：Headless 模式并行脚本

适合 CI/CD 或自动化批处理场景：

```bash theme={null}
#!/bin/bash
# parallel-claude.sh —— 并行运行多个 Claude 任务

# 任务 1：生成测试
claude -p "为 @src/services/UserService.ts 补全单元测试，保存到 tests/" \
  --output-format json > task1.json &
PID1=$!

# 任务 2：生成文档
claude -p "为 @src/api/routes.ts 生成 OpenAPI 注释" \
  --output-format json > task2.json &
PID2=$!

# 任务 3：安全审查
git diff main | claude -p "安全漏洞审查，输出 JSON 格式问题列表" \
  --output-format json > task3.json &
PID3=$!

echo "🚀 3 个 Claude 任务并行运行中..."

# 等待全部完成
wait $PID1 && echo "✅ 测试生成完成"
wait $PID2 && echo "✅ 文档生成完成"
wait $PID3 && echo "✅ 安全审查完成"

echo "🎉 全部任务完成！"
```

```bash theme={null}
chmod +x parallel-claude.sh
./parallel-claude.sh
```

***

### 15.3 方案三：同一会话内的并行 Subagent

在**单个 Claude 会话**中，通过 Subagent 并行处理多个子任务（Claude 内部调度）：

```
> 我有三个独立任务，请同时处理：
  1. 用 test-writer subagent 为 UserService 补测试
  2. 用 doc-writer subagent 为 PaymentService 补文档
  3. 用 code-reviewer subagent 审查最近的 git diff
```

Claude 会并发调度这三个 Subagent，各自在独立上下文中工作。

***

### 15.4 并发模式对比

| 方案                      | 隔离级别       | 适用场景           | 复杂度 |
| ----------------------- | ---------- | -------------- | --- |
| **Git Worktrees + 多终端** | 完全隔离（独立分支） | 并行开发多个功能/修复    | 中   |
| **Headless 并行脚本**       | 进程级隔离      | CI/CD、批量处理、自动化 | 低   |
| **会话内 Subagent 并行**     | 上下文隔离      | 同一任务的多维度分析     | 低   |

> **⚠️ 注意**：永远不要让两个 Claude 实例同时写同一个文件，会产生冲突。Git Worktrees 通过独立分支从根本上避免了这个问题。

***

## 16. Subagent 驱动的开发工作流

这是最高效的大型功能开发模式：**主 Claude 负责规划和协调，Subagent 负责实现和审查**，每个任务都经过"实现 → 规范审查 → 质量审查"的三重质量门。

### 工作流概览

```
规划阶段（主 Claude）
  └─→ 读取 Plan 文件，提取所有任务
  └─→ 创建 TodoList 追踪进度

对每个任务循环：
  ├─→ 【实现者 Subagent】实现代码 + 写测试 + 自审 + 提交
  ├─→ 【规范审查 Subagent】核查实现是否完全符合需求（不多不少）
  │     └─→ 不通过 → 实现者修复 → 重新审查
  ├─→ 【代码质量 Subagent】审查代码质量（可读性/安全/性能）
  │     └─→ 不通过 → 实现者修复 → 重新审查
  └─→ 标记任务完成

最终阶段：
  └─→ 整体代码审查
  └─→ 合并 / 创建 PR
```

***

### 16.1 第一步：写 Plan 文件

先用 `/plan` 或自然语言让 Claude 生成详细计划，保存到文件：

```markdown theme={null}
<!-- docs/plans/add-2fa.md -->
# 实现双因素认证（2FA）

## 任务列表

### Task 1：安装依赖与配置
- 安装 `speakeasy`（TOTP 生成）和 `qrcode`（二维码）
- 更新 package.json 和类型声明
- 验收：npm install 成功，TypeScript 无类型错误

### Task 2：数据库 Schema 变更
- User 表增加字段：`totp_secret`、`totp_enabled`、`backup_codes`
- 生成并运行 migration
- 验收：migration 运行成功，字段存在

### Task 3：TOTP 核心服务
- 实现 `TotpService`：生成密钥、验证 code、生成备用码
- 单元测试覆盖所有方法
- 验收：100% 测试通过

### Task 4：API 端点
- POST /auth/2fa/setup：初始化 2FA
- POST /auth/2fa/verify：验证并启用
- POST /auth/2fa/disable：关闭 2FA
- 验收：所有端点有测试，集成测试通过
```

***

### 16.2 第二步：启动 Subagent 驱动执行

在 Claude 会话中，按以下模式驱动：

#### 启动指令（告诉 Claude 进入此工作流）

```
> 我要用 Subagent 驱动开发模式执行 @docs/plans/add-2fa.md。
  请读取计划，提取所有任务创建 TodoList，然后逐任务：
  1. 派发实现者 Subagent 执行
  2. 派发规范审查 Subagent 验证
  3. 派发代码质量 Subagent 审查
  每个任务通过双重审查后才进入下一个。
```

#### 实现者 Subagent 提示词模板

```
Task tool:
  description: "实现 Task 2：数据库 Schema 变更"
  prompt: |
    你正在实现 Task 2：数据库 Schema 变更

    ## 任务需求
    [粘贴 Plan 中 Task 2 的完整文字]

    ## 背景上下文
    - 项目使用 Prisma ORM + PostgreSQL
    - 已完成 Task 1（依赖安装），可直接使用 speakeasy
    - 当前 User model 在 prisma/schema.prisma

    ## 开始前
    如果有任何不清楚的需求或假设，**先提问**，不要猜测。

    ## 你的任务
    明确后：
    1. 按需求实现（不多也不少）
    2. 编写测试并确保通过
    3. 提交代码
    4. 自审（完整性/质量/是否过度设计/测试是否有效）

    ## 完成后汇报
    - 实现了什么
    - 测试结果
    - 修改的文件
    - 自审发现（如有）
```

#### 规范审查 Subagent 提示词模板

```
Task tool:
  description: "规范审查 Task 2"
  prompt: |
    你在验证一个实现是否完全符合需求规范。

    ## 需求规范
    [粘贴 Task 2 的完整需求]

    ## 实现者的汇报
    [粘贴实现者的汇报内容]

    ## 重要：不要相信汇报，亲自核查代码

    验证维度：
    - ✅ 需求全部实现了吗？有遗漏吗？
    - ✅ 有没有实现需求之外的东西（过度设计）？
    - ✅ 实现方式和需求意图一致吗？

    输出：
    - ✅ 规范合规（所有需求均已实现且无多余）
    - ❌ 发现问题：[列出具体问题，附文件:行号]
```

#### 代码质量 Subagent 提示词模板

```
Task tool (code-reviewer subagent):
  description: "代码质量审查 Task 2"
  prompt: |
    审查以下实现的代码质量（规范合规已通过）。

    实现内容：[实现者汇报]
    对应 commits：[base_sha]..[head_sha]

    重点关注：
    - 代码可读性与命名
    - 安全隐患
    - 性能问题
    - 测试质量（测行为而非实现）
    - 是否遵循项目已有模式

    输出：
    - 优点（值得保留的设计）
    - 🔴 Critical 问题（必须修复）
    - 🟡 Important 问题（强烈建议修复）
    - 🔵 Minor 问题（可选改进）
    - 最终评审结论：✅ 通过 / ❌ 需修复
```

***

### 16.3 完整执行示例

```
你：读取 @docs/plans/add-2fa.md，创建任务列表，开始 Subagent 驱动开发。

Claude：[读取计划，创建 4 个待办任务]
        开始 Task 1...

[实现者 Subagent 被派发]
实现者："Task 1 中 speakeasy 的 TypeScript 版本配置有歧义，
        请问是用 @types/speakeasy 还是 speakeasy 自带的类型？"

你："用 @types/speakeasy"

实现者：[完成实现，运行测试，提交]
        "已安装依赖，TypeScript 编译通过，提交 a1b2c3d"

[规范审查 Subagent 被派发]
规范审查："✅ 规范合规 —— package.json 已更新，类型正确，无多余内容"

[代码质量 Subagent 被派发]
质量审查："✅ 通过
           优点：依赖版本锁定合理
           🔵 Minor：建议在 package.json 加注释说明 speakeasy 用途"

Claude：[标记 Task 1 完成，进入 Task 2]
        ...
```

***

### 16.4 最佳实践

| 实践               | 原因                     |
| ---------------- | ---------------------- |
| **给实现者提供完整任务文字** | 不让 Subagent 自己读文件，减少歧义 |
| **先规范审查，再质量审查**  | 确保方向正确再打磨细节            |
| **实现者发现问题及时提问**  | 宁可提前澄清，不要猜测实现          |
| **审查不通过必须修复再重审** | 不接受"差不多"的实现            |
| **每个任务独立提交**     | 便于回滚和 Code Review      |
| **计划文件写明验收标准**   | 给规范审查者明确的判断依据          |

***

## 17. 并行开发：Git Worktrees

当需要同时处理多个功能或 Bug 时，用 Git Worktrees 创建隔离的工作目录，每个目录启动独立的 Claude 会话。

### 创建并行工作区

```bash theme={null}
# 主仓库开发 feature-A
git worktree add ../project-feature-a -b feature/user-profile

# 同时修复 Bug
git worktree add ../project-bugfix -b fix/login-error

# 查看所有工作区
git worktree list
```

### 在每个工作区启动独立 Claude

```bash theme={null}
# 终端 1：开发新功能
cd ../project-feature-a
claude
> 实现用户个人资料页面

# 终端 2：修复 Bug
cd ../project-bugfix
claude
> 调试并修复登录报错：@logs/error.log
```

### 清理工作区

```bash theme={null}
git worktree remove ../project-feature-a
git worktree remove ../project-bugfix
```

> **💡 优势**：两个 Claude 实例完全独立，互不干扰；共享同一个 Git 历史；非常适合并行处理 Code Review 反馈和新功能开发。

***

## 18. Unix 管道集成

将 Claude 融入命令行工具链，用于 CI/CD 或脚本自动化。

### 基本管道用法

```bash theme={null}
# 分析构建错误
cat build-error.txt | claude -p "简洁解释这个构建错误的根本原因"

# 分析日志文件
cat server.log | claude -p "找出日志中所有的错误模式，按严重程度分类"

# 代码审查输出到文件
git diff HEAD | claude -p "作为代码审查员，指出所有潜在问题" > review.md
```

### 指定输出格式

```bash theme={null}
# 纯文本输出（默认）
claude -p "分析这段代码" --output-format text

# JSON 格式（便于脚本解析）
cat code.py | claude -p "找出所有 bug" --output-format json > analysis.json

# 流式 JSON（实时处理）
cat log.txt | claude -p "解析日志错误" --output-format stream-json
```

### 集成到 npm scripts（作为 AI Linter）

```json theme={null}
// package.json
{
  "scripts": {
    "lint:ai": "claude -p '你是代码审查员。检查与 main 分支的差异，报告拼写错误和潜在 bug。格式：文件名:行号 | 问题描述'",
    "review:security": "git diff main | claude -p '专注安全漏洞审查，输出 JSON 格式的问题列表' --output-format json"
  }
}
```

### 集成到 CI/CD

```yaml theme={null}
# .github/workflows/ai-review.yml
- name: AI Code Review
  run: |
    git diff origin/main | claude -p \
      "审查这个 PR 的代码质量，重点检查安全性和性能，输出 Markdown 格式报告" \
      --output-format text > ai-review.md
```

***

## 19. 完整开发工作流示例

### 场景：接手新项目

```bash theme={null}
# 1. 克隆并进入项目
git clone https://github.com/company/project.git && cd project

# 2. 启动 Claude，初始化记忆
claude
> /init

# 3. 快速了解项目
> 给我一个这个代码库的高层次概览
> 解释主要的架构模式
> 认证是怎么处理的？

# 4. 找到相关代码
> 找到处理用户认证的所有文件
> 追踪登录流程从前端到数据库的完整链路
```

### 场景：开发新功能

```bash theme={null}
# 1. 在 Plan 模式下规划（不修改任何文件）
claude --permission-mode plan
> 我需要给用户添加二次验证（2FA）功能，分析现有认证代码并制定详细实施方案

# 2. 确认方案后切换到普通模式开始实现
# 按 Shift+Tab 退出 Plan 模式
> 按照上面的方案，先实现 TOTP 生成模块

# 3. 添加测试
> 为刚才实现的 2FA 模块补充单元测试，覆盖正常和异常情况

# 4. 代码审查
> /review

# 5. 提交
> /commit

# 6. 创建 PR
> create a pr
```

### 场景：调试复杂 Bug

```bash theme={null}
claude
# 1. 提供错误信息
! npm test 2>&1 | head -50
> 上面的测试失败了，帮我找到根本原因

# 2. 深度分析（开启扩展思考）
# 按 Tab 开启扩展思考
> think hard about why this race condition occurs in @src/eventEmitter.ts

# 3. 查看相关文件
> 分析 @src/eventEmitter.ts 和 @tests/eventEmitter.test.ts

# 4. 应用修复
> 基于你的分析，实现修复方案，确保不破坏现有功能

# 5. 验证
! npm test
> 测试通过了，帮我总结一下这个 bug 的原因和修复思路，我需要写在 PR 描述里
```

### 场景：批量重构

```bash theme={null}
# 1. 在自动接受模式下高效执行（按 Shift+Tab 两次进入）
# 2. 或者命令行启动
claude --permission-mode acceptEdits

> 找到所有使用废弃的 axios 直接调用的地方，统一替换为我们封装的 apiClient
> 完成后运行测试验证没有破坏功能
! npm test
```

***

## CLI 快速参考卡

```bash theme={null}
# ===== 启动方式 =====
claude                              # 交互式会话
claude "解释这个项目"               # 带初始提示启动
claude -p "查询"                    # 非交互式单次查询
claude -c                           # 继续最近会话
claude -r                           # 选择历史会话
claude --model sonnet               # 指定模型
claude --permission-mode plan       # Plan 只读模式
claude --verbose                    # 详细日志模式

# ===== 管道与自动化 =====
cat file.txt | claude -p "分析"                        # 管道输入
claude -p "查询" --output-format json                  # JSON 输出
claude -p "查询" --output-format stream-json           # 流式 JSON
claude -p --max-turns 3 "查询"                         # 限制最大轮次

# ===== MCP 管理 =====
claude mcp add --transport stdio name -- command       # 添加 stdio MCP
claude mcp add --transport http name http://url        # 添加 HTTP MCP
claude mcp list                                        # 列出所有 MCP
claude mcp remove name                                 # 移除 MCP

# ===== 其他 =====
claude update                       # 更新版本
claude doctor                       # 健康检查
```

***

> **参考资料**：[Claude Code 官方文档](https://docs.claude.com/en/docs/claude-code)