# 安装 Claude Code
npm install -g @anthropic-ai/claude-code

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

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

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

# 更新到最新版
claude update

# 检查安装健康状态
claude doctor

# 使用最新 Sonnet 模型（速度与质量平衡，推荐日常使用）
claude --model sonnet

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

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

> 解释 @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 是否合规

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

# 在提示符前加 ! 直接执行
! npm test
! git status
! git diff HEAD
! ls -la src/

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

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

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

! npm run dev        # 启动后按 Ctrl+B 放后台
! jest --watch       # 启动后按 Ctrl+B 放后台

> /init

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

# 查看消耗
> /cost

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

# 代码审查
> /review

# 继续最近一次的对话（最常用）
claude --continue
claude -c

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

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

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

> /resume    # 打开会话选择器

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

> /memory

> /init

# my-project/CLAUDE.md

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

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

# [项目名称]

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

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

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

## 项目结构

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

> /commit

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

> /review

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

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

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

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

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

# 添加 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

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

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

> /agents

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

mkdir -p ~/.claude/agents
# 同上，放到 ~/.claude/agents/ 目录

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

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

系统提示词内容...

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

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

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

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

你是根因分析专家。

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

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

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

你是测试自动化专家。

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

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

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

你是技术文档专家。

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

# 查看所有 subagent（内置 + 用户 + 项目）
> /agents

# 查看健康状态
> /doctor

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

# ── 步骤 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

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

#!/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 "🎉 全部任务完成！"

chmod +x parallel-claude.sh
./parallel-claude.sh

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

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

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

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

<!-- 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
- 验收：所有端点有测试，集成测试通过

> 我要用 Subagent 驱动开发模式执行 @docs/plans/add-2fa.md。
  请读取计划，提取所有任务创建 TodoList，然后逐任务：
  1. 派发实现者 Subagent 执行
  2. 派发规范审查 Subagent 验证
  3. 派发代码质量 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. 自审（完整性/质量/是否过度设计/测试是否有效）

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

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

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

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

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

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

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

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

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

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

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

你：读取 @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]
        ...

# 主仓库开发 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

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

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

git worktree remove ../project-feature-a
git worktree remove ../project-bugfix

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

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

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

# 纯文本输出（默认）
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

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

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

# 1. 克隆并进入项目
git clone https://github.com/company/project.git && cd project

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

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

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

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

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

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

# 4. 代码审查
> /review

# 5. 提交
> /commit

# 6. 创建 PR
> create a pr

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 描述里

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

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

# ===== 启动方式 =====
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                       # 健康检查