Claude Code — 完整开发指南

通过 Hermes 终端将编码任务委托给 Claude Code（Anthropic 的自主编码 Agent CLI）。Claude Code v2.x 可以自主读取文件、编写代码、运行 Shell 命令、生成子 Agent 以及管理 Git 工作流程。

前置条件

• 安装：npm install -g @anthropic-ai/claude-code
• 认证：运行 claude 进行一次登录（Pro/Max 用户使用浏览器 OAuth，或设置 ANTHROPIC_API_KEY）
• 控制台认证：claude auth login --console（API Key 计费模式）
• SSO 认证：claude auth login --sso（企业版）
• 查看状态：claude auth status（JSON 格式）或 claude auth status --text（人类可读）
• 健康检查：claude doctor — 检查自动更新器和安装健康状态
• 版本检查：claude --version（需要 v2.x+）
• 更新：claude update 或 claude upgrade

两种编排模式

Hermes 与 Claude Code 有两种完全不同的交互方式。根据任务选择。

模式1：Print 模式（-p）— 非交互式（推荐用于大多数任务）

Print 模式运行一次性任务，返回结果后退出。不需要 PTY，没有交互式提示。这是最干净的集成路径。

terminal(command="claude -p '为 src/ 中的所有 API 调用添加错误处理' --allowedTools 'Read,Edit' --max-turns 10", workdir="/path/to/project", timeout=120)

何时使用 Print 模式：

• 一次性编码任务（修复 Bug、添加功能、重构）
• CI/CD 自动化和脚本编写
• 使用 --json-schema 进行结构化数据提取
• 管道输入处理（cat file | claude -p "分析这个文件"）
• 任何不需要多轮对话的任务

Print 模式跳过所有交互式对话框 — 没有工作区信任提示，没有权限确认。这使得它非常适合自动化。

模式2：通过 tmux 的交互式 PTY — 多轮会话

交互式模式提供一个完整的对话式 REPL，你可以发送后续提示、使用斜杠命令，并实时观察 Claude 工作。需要 tmux 编排。

# 启动一个 tmux 会话
terminal(command="tmux new-session -d -s claude-work -x 140 -y 40")

# 在内部启动 Claude Code
terminal(command="tmux send-keys -t claude-work 'cd /path/to/project && claude' Enter")

# 等待启动，然后发送任务
# （大约等待 3-5 秒欢迎界面）
terminal(command="sleep 5 && tmux send-keys -t claude-work '将认证模块重构为使用 JWT 令牌' Enter")

# 通过捕获面板监控进度
terminal(command="sleep 15 && tmux capture-pane -t claude-work -p -S -50")

# 发送后续任务
terminal(command="tmux send-keys -t claude-work '现在为新的 JWT 代码添加单元测试' Enter")

# 完成后退出
terminal(command="tmux send-keys -t claude-work '/exit' Enter")

何时使用交互式模式：

• 多轮迭代工作（重构 → 审查 → 修复 → 测试周期）
• 需要人机协同决策的任务
• 探索性编码会话
• 需要使用 Claude 的斜杠命令时（/compact、/review、/model）

PTY 对话框处理（交互式模式关键）

Claude Code 在首次启动时会出现最多两个确认对话框。你必须通过 tmux send-keys 处理它们：

对话框1：工作区信任（首次访问目录）

❯ 1. 是的，我信任这个文件夹    ← 默认选项（直接按 Enter）
  2. 不，退出

处理：tmux send-keys -t <session> Enter — 默认选择正确。

对话框2：绕过权限警告（仅在启用 --dangerously-skip-permissions 时出现）

❯ 1. 不，退出              ← 默认（错误选项！）
  2. 是的，我接受

处理：必须先向下导航，再按 Enter：

tmux send-keys -t <session> Down && sleep 0.3 && tmux send-keys -t <session> Enter

稳健的对话框处理模式

# 使用权限绕过启动
terminal(command="tmux send-keys -t claude-work 'claude --dangerously-skip-permissions "你的任务"' Enter")

# 处理信任对话框（Enter 选择默认的"是"）
terminal(command="sleep 4 && tmux send-keys -t claude-work Enter")

# 处理权限对话框（先向下再 Enter 选择"是的，我接受"）
terminal(command="sleep 3 && tmux send-keys -t claude-work Down && sleep 0.3 && tmux send-keys -t claude-work Enter")

# 现在等待 Claude 工作
terminal(command="sleep 15 && tmux capture-pane -t claude-work -p -S -60")

注意：在首次接受某个目录的信任后，信任对话框不会再次出现。只有权限对话框会在每次使用 --dangerously-skip-permissions 时重复出现。

CLI 子命令

子命令	用途
claude	启动交互式 REPL
claude "查询内容"	带初始提示启动 REPL
claude -p "查询内容"	Print 模式（非交互式，完成后退出）
cat file | claude -p "查询内容"	通过管道传递内容作为 stdin 上下文
claude -c	继续此目录中最近的对话
claude -r "id"	按 ID 或名称恢复特定会话
claude auth login	登录（加 --console 用于 API 计费，--sso 用于企业版）
claude auth status	检查登录状态（返回 JSON；加 --text 为人类可读格式）
claude mcp add <名称> -- <命令>	添加 MCP 服务器
claude mcp list	列出已配置的 MCP 服务器
claude mcp remove <名称>	移除 MCP 服务器
claude agents	列出已配置的 Agent
claude doctor	对安装和自动更新器运行健康检查
claude update / claude upgrade	将 Claude Code 更新到最新版本
claude remote-control	启动服务器，从 claude.ai 或移动应用控制 Claude
claude install [目标]	安装原生构建（稳定版、最新版或特定版本）
claude setup-token	设置长期有效的认证令牌（需要订阅）
claude plugin / claude plugins	管理 Claude Code 插件
claude auto-mode	检查自动模式分类器配置

Print 模式深入

结构化 JSON 输出

terminal(command="claude -p '分析 auth.py 的安全问题' --output-format json --max-turns 5", workdir="/project", timeout=120)

返回包含以下字段的 JSON 对象：

{
  "type": "result",
  "subtype": "success",
  "result": "分析文本...",
  "session_id": "75e2167f-...",
  "num_turns": 3,
  "total_cost_usd": 0.0787,
  "duration_ms": 10276,
  "stop_reason": "end_turn",
  "terminal_reason": "completed",
  "usage": { "input_tokens": 5, "output_tokens": 603, ... },
  "modelUsage": { "claude-sonnet-4-6": { "costUSD": 0.078, "contextWindow": 200000 } }
}

关键字段：session_id 用于恢复会话，num_turns 表示 Agent 循环次数，total_cost_usd 用于支出跟踪，subtype 用于成功/错误检测（success、error_max_turns、error_budget）。

流式 JSON 输出

如需实时 Token 流，使用带 --verbose 的 stream-json：

terminal(command="claude -p '写一段摘要' --output-format stream-json --verbose --include-partial-messages", timeout=60)

返回按换行符分隔的 JSON 事件。使用 jq 过滤实时文本：

claude -p "解释 X 的概念" --output-format stream-json --verbose --include-partial-messages | 
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

流事件包括 system/api_retry，包含 attempt、max_retries 和 error 字段（例如 rate_limit、billing_error）。

双向流式传输

如需实时输入和输出流式传输：

claude -p "任务描述" --input-format stream-json --output-format stream-json --replay-user-messages

--replay-user-messages 在 stdout 上重新输出用户消息，用于确认。

管道输入

# 通过管道传输文件进行分析
terminal(command="cat src/auth.py | claude -p '审查此代码中的 Bug' --max-turns 1", timeout=60)

# 通过管道传输多个文件
terminal(command="cat src/*.py | claude -p '查找所有 TODO 注释' --max-turns 1", timeout=60)

# 通过管道传输命令输出
terminal(command="git diff HEAD~3 | claude -p '总结这些变更' --max-turns 1", timeout=60)

用于结构化提取的 JSON Schema

terminal(command="claude -p '列出 src/ 中的所有函数' --output-format json --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' --max-turns 5", workdir="/project", timeout=90)

从 JSON 结果中解析 structured_output 字段。Claude 在返回前会根据 Schema 验证输出。

会话延续

# 开始一个任务
terminal(command="claude -p '开始重构数据库层' --output-format json --max-turns 10 > /tmp/session.json", workdir="/project", timeout=180)

# 使用会话 ID 恢复
terminal(command="claude -p '继续并添加连接池' --resume $(cat /tmp/session.json | python3 -c 'import json,sys; print(json.load(sys.stdin)["session_id"])') --max-turns 5", workdir="/project", timeout=120)

# 或恢复同一目录中最近的会话
terminal(command="claude -p '上次做了什么？' --continue --max-turns 1", workdir="/project", timeout=30)

# Fork 会话（新建 ID，保留历史）
terminal(command="claude -p '尝试不同的方法' --resume <id> --fork-session --max-turns 10", workdir="/project", timeout=120)

CI/脚本的 Bare 模式

terminal(command="claude --bare -p '运行所有测试并报告失败项' --allowedTools 'Read,Bash' --max-turns 10", workdir="/project", timeout=180)

--bare 跳过钩子、插件、MCP 发现和 CLAUDE.md 加载。启动最快。需要 ANTHROPIC_API_KEY（跳过 OAuth）。

在 bare 模式下选择性加载上下文：

要加载的内容	标志
系统提示补充	--append-system-prompt "文本" 或 --append-system-prompt-file 路径
设置	--settings <文件或JSON>
MCP 服务器	--mcp-config <文件或JSON>
自定义 Agent	--agents '<json>'

过载时的备用模型

terminal(command="claude -p '任务描述' --fallback-model haiku --max-turns 5", timeout=90)

当默认模型过载时，自动回退到指定的备用模型（仅限 print 模式）。

完整 CLI 标志参考

会话与环境

标志	效果
-p, --print	非交互式一次性模式（完成后退出）
-c, --continue	恢复当前目录中最近的对话
-r, --resume <id>	按 ID 或名称恢复特定会话（无 ID 时显示交互式选择器）
--fork-session	恢复时创建新会话 ID，而非复用原 ID
--session-id <uuid>	使用特定的 UUID 作为会话标识
--no-session-persistence	不将会话保存到磁盘（仅限 print 模式）
--add-dir <路径...>	授予 Claude 访问额外工作目录的权限
-w, --worktree [名称]	在 .claude/worktrees/<名称> 的隔离 git worktree 中运行
--tmux	为 worktree 创建 tmux 会话（需要 --worktree）
--ide	启动时自动连接到有效的 IDE
--chrome / --no-chrome	启用/禁用 Chrome 浏览器集成（用于 Web 测试）
--from-pr [编号]	恢复与特定 GitHub PR 关联的会话
--file <规格...>	启动时下载的文件资源（格式：file_id:相对路径）

模型与性能

标志	效果
--model <别名>	模型选择：sonnet、opus、haiku 或全名如 claude-sonnet-4-6
--effort <级别>	推理深度：low、medium、high、max、auto
--max-turns <n>	限制 Agent 循环次数（仅限 print 模式；防止失控）
--max-budget-usd <n>	API 支出上限（美元），仅限 print 模式
--fallback-model <模型>	默认模型过载时自动回退（仅限 print 模式）
--betas <功能...>	包含在 API 请求中的 Beta 标头（仅限 API Key 用户）

权限与安全

标志	效果
--dangerously-skip-permissions	自动批准所有工具使用（写文件、bash、网络等）
--allow-dangerously-skip-permissions	启用绕过选项但默认不启用
--permission-mode <模式>	default、acceptEdits、plan、auto、dontAsk、bypassPermissions
--allowedTools <工具...>	白名单特定工具（逗号或空格分隔）
--disallowedTools <工具...>	黑名单特定工具
--tools <工具...>	覆盖内置工具集（""=无，"default"=全部，或工具名称）

输出与输入格式

标志	效果
--output-format <格式>	text（默认）、json（单个结果对象）、stream-json（换行分隔）
--input-format <格式>	text（默认）或 stream-json（实时流式输入）
--json-schema <schema>	强制使用匹配 Schema 的结构化 JSON 输出
--verbose	完整的逐轮输出
--include-partial-messages	包含到达的部分消息块（stream-json + print）
--replay-user-messages	在 stdout 上重新输出用户消息（stream-json 双向传输）

系统提示与上下文

标志	效果
--append-system-prompt <文本>	添加到默认系统提示（保留内置能力）
--append-system-prompt-file <路径>	添加文件内容到默认系统提示
--system-prompt <文本>	替换整个系统提示（通常建议使用 --append）
--system-prompt-file <路径>	替换系统提示为文件内容
--bare	跳过钩子、插件、MCP 发现、CLAUDE.md、OAuth（最快启动）
--agents '<json>'	以 JSON 格式动态定义自定义子 Agent
--mcp-config <路径>	从 JSON 文件加载 MCP 服务器（可重复）
--strict-mcp-config	仅使用 --mcp-config 中的 MCP 服务器，忽略其他所有 MCP 配置
--settings <文件或JSON>	从 JSON 文件或内联 JSON 加载额外设置
--setting-sources <源>	逗号分隔的加载源：user、project、local
--plugin-dir <路径...>	仅为此会话从指定目录加载插件
--disable-slash-commands	禁用所有技能/斜杠命令

调试

标志	效果
-d, --debug [过滤器]	启用调试日志（可选的类别过滤器，如 "api,hooks"、"!1p,!file"）
--debug-file <路径>	将调试日志写入文件（隐式启用调试模式）

Agent 团队

标志	效果
--teammate-mode <模式>	Agent 团队的显示方式：auto、in-process 或 tmux
--brief	启用 SendUserMessage 工具，实现 Agent 到用户的消息通信

--allowedTools / --disallowedTools 的工具名称语法

Read                    # 所有文件读取
Edit                    # 文件编辑（已有文件）
Write                   # 文件创建（新文件）
Bash                    # 所有 Shell 命令
Bash(git *)             # 仅 Git 命令
Bash(git commit *)      # 仅 Git commit 命令
Bash(npm run lint:*)    # 通配符模式匹配
WebSearch               # 网页搜索能力
WebFetch                # 网页抓取
mcp__<服务器>__<工具>     # 特定的 MCP 工具

设置与配置

设置优先级（从高到低）

1. CLI 标志 — 覆盖一切
2. 本地项目：.claude/settings.local.json（个人，被 gitignore）
3. 项目：.claude/settings.json（团队共享，被 Git 跟踪）
4. 用户：~/.claude/settings.json（全局）

设置中的权限配置

{
  "permissions": {
    "allow": ["Bash(npm run lint:*)", "WebSearch", "Read"],
    "ask": ["Write(*.ts)", "Bash(git push*)"],
    "deny": ["Read(.env)", "Bash(rm -rf *)"]
  }
}

记忆文件（CLAUDE.md）层级

1. 全局：~/.claude/CLAUDE.md — 适用于所有项目
2. 项目：./CLAUDE.md — 项目特定上下文（被 Git 跟踪）
3. 本地：.claude/CLAUDE.local.md — 个人项目覆盖（被 gitignore）

在交互模式中使用 # 前缀快速添加到记忆：# 始终使用 2 空格缩进。

交互式会话：斜杠命令

会话与上下文

命令	用途
/help	显示所有命令（包括自定义和 MCP 命令）
/compact [焦点]	压缩上下文以节省 Token；CLAUDE.md 不受压缩影响。例如：/compact focus on auth logic
/clear	清空对话历史，重新开始
/context	可视化上下文使用情况（彩色网格+优化提示）
/cost	查看 Token 使用情况（按模型和缓存命中细分）
/resume	切换或恢复不同的会话
/rewind	回退到对话或代码中的先前检查点
/btw <问题>	在不增加上下文成本的情况下提问
/status	显示版本、连接状态和会话信息
/todos	列出对话中跟踪的待办事项
/exit 或 Ctrl+D	结束会话

开发与审查

命令	用途
/review	请求对当前变更进行代码审查
/security-review	对当前变更执行安全分析
/plan [描述]	进入计划模式（自动启动任务规划）
/loop [间隔]	在会话内安排周期性任务
/batch	为大型并行变更自动创建工作区（5-30 个工作区）

配置与工具

命令	用途
/model [模型]	会话中切换模型（使用方向键调整 effort）
/effort [级别]	设置推理努力程度：low、medium、high、max、auto
/init	创建 CLAUDE.md 文件作为项目记忆
/memory	打开 CLAUDE.md 进行编辑
/config	打开交互式设置配置
/permissions	查看/更新工具权限
/agents	管理专门的子 Agent
/mcp	管理 MCP 服务器的交互式 UI
/add-dir	添加额外的工作目录（对单体仓库很有用）
/usage	显示计划限制和速率限制状态
/voice	启用按键通话语音模式（20 种语言；按住 Space 录制，松开发送）
/release-notes	版本发布说明的交互式选择器

自定义斜杠命令

创建 .claude/commands/<名称>.md（项目共享）或 ~/.claude/commands/<名称>.md（个人）：

# .claude/commands/deploy.md
运行部署流程：
1. 运行所有测试
2. 构建 Docker 镜像
3. 推送到镜像仓库
4. 更新 $ARGUMENTS 环境（默认：staging）

使用方式：/deploy production — $ARGUMENTS 会被替换为用户输入的内容。

技能（自然语言调用）

与需要手动调用的斜杠命令不同，.claude/skills/ 中的技能是 Markdown 指南，当任务匹配时 Claude 通过自然语言自动调用：

# .claude/skills/database-migration.md
当被问到创建或修改数据库迁移时：
1. 使用 Alembic 生成迁移
2. 始终创建回滚函数
3. 在本地数据库副本上测试迁移

交互式会话：键盘快捷键

通用控制

按键	操作
Ctrl+C	取消当前输入或生成
Ctrl+D	退出会话
Ctrl+R	反向搜索命令历史
Ctrl+B	将正在运行的任务放入后台
Ctrl+V	粘贴图片到对话
Ctrl+O	Transcript 模式 — 查看 Claude 的思考过程
Ctrl+G 或 Ctrl+X Ctrl+E	在外部编辑器中打开提示
Esc Esc	回退对话或代码状态 / 总结

模式切换

按键	操作
Shift+Tab	循环切换权限模式（Normal → Auto-Accept → Plan）
Alt+P	切换模型
Alt+T	切换思考模式
Alt+O	切换快速模式

多行输入

按键	操作
+ Enter	快速换行
Shift+Enter	换行（替代方式）
Ctrl+J	换行（替代方式）

输入前缀

前缀	操作
!	直接执行 bash，绕过 AI（例如 !npm test）。单独使用 ! 切换 Shell 模式。
@	引用文件/目录（带自动补全），例如 @./src/api/
#	快速添加到 CLAUDE.md 记忆（例如 # 使用 2 空格缩进）
/	斜杠命令

专业技巧：「ultrathink」

在提示中使用「ultrathink」关键词以在特定轮次中获得最大推理努力。这会触发最深层的思考模式，无论当前的 /effort 设置如何。

PR 审查模式

快速审查（Print 模式）

terminal(command="cd /path/to/repo && git diff main...feature-branch | claude -p '审查此差异中的 Bug、安全问题和风格问题。请做到全面。' --max-turns 1", timeout=60)

深度审查（交互式 + Worktree）

terminal(command="tmux new-session -d -s review -x 140 -y 40")
terminal(command="tmux send-keys -t review 'cd /path/to/repo && claude -w pr-review' Enter")
terminal(command="sleep 5 && tmux send-keys -t review Enter")  # 信任对话框
terminal(command="sleep 2 && tmux send-keys -t review '审查与 main 分支的所有差异。检查 Bug、安全问题、竞态条件和缺失的测试。' Enter")
terminal(command="sleep 30 && tmux capture-pane -t review -p -S -60")

按编号进行 PR 审查

terminal(command="claude -p '全面审查此 PR' --from-pr 42 --max-turns 10", workdir="/path/to/repo", timeout=120)

带 tmux 的 Claude Worktree

terminal(command="claude -w feature-x --tmux", workdir="/path/to/repo")

在 .claude/worktrees/feature-x 创建隔离的 Git Worktree，同时创建一个 tmux 会话。在可用时使用 iTerm2 原生面板，添加 --tmux=classic 使用传统 tmux。

并行运行多个 Claude 实例

同时运行多个独立的 Claude 任务：

# 任务1：修复后端
terminal(command="tmux new-session -d -s task1 -x 140 -y 40 && tmux send-keys -t task1 'cd ~/project && claude -p "修复 src/auth.py 中的认证 Bug" --allowedTools "Read,Edit" --max-turns 10' Enter")

# 任务2：编写测试
terminal(command="tmux new-session -d -s task2 -x 140 -y 40 && tmux send-keys -t task2 'cd ~/project && claude -p "为 API 端点编写集成测试" --allowedTools "Read,Write,Bash" --max-turns 15' Enter")

# 任务3：更新文档
terminal(command="tmux new-session -d -s task3 -x 140 -y 40 && tmux send-keys -t task3 'cd ~/project && claude -p "使用新的 API 端点更新 README.md" --allowedTools "Read,Edit" --max-turns 5' Enter")

# 监控所有任务
terminal(command="sleep 30 && for s in task1 task2 task3; do echo '=== '$s' ==='; tmux capture-pane -t $s -p -S -5 2>/dev/null; done")

CLAUDE.md — 项目上下文文件

Claude Code 自动从项目根目录加载 CLAUDE.md。用它来持久化项目上下文：

# 项目：我的 API

## 架构
- FastAPI 后端，SQLAlchemy ORM
- PostgreSQL 数据库，Redis 缓存
- pytest 测试，覆盖率目标 90%

## 关键命令
- `make test` — 运行完整测试套件
- `make lint` — ruff + mypy
- `make dev` — 在 :8000 启动开发服务器

## 代码规范
- 所有公共函数使用类型提示
- 使用 Google 风格的文档字符串
- YAML 使用 2 空格缩进，Python 使用 4 空格
- 禁止通配符导入

要具体。不要写「写出好代码」，而是用「JS 使用 2 空格缩进」或「测试文件使用 .test.ts 后缀」。具体的指令能节省纠正周期。

规则目录（模块化 CLAUDE.md）

对于有很多规则的项目，使用规则目录代替一个庞大的 CLAUDE.md：

• 项目规则：.claude/rules/*.md — 团队共享，被 Git 跟踪
• 用户规则：~/.claude/rules/*.md — 个人，全局

规则目录中的每个 .md 文件都会作为额外上下文加载。这比把所有内容塞进一个 CLAUDE.md 更清晰。

自动记忆

Claude 自动学习项目上下文并存储在 ~/.claude/projects/<项目>/memory/ 中。

• 限制：每个项目 25KB 或 200 行
• 这与 CLAUDE.md 分开 — 是 Claude 自己对项目的笔记，跨会话累积

自定义子 Agent

在 .claude/agents/（项目）、~/.claude/agents/（个人）或通过 --agents CLI 标志（会话）定义专门的 Agent：

Agent 位置优先级

1. .claude/agents/ — 项目级别，团队共享
2. --agents CLI 标志 — 会话特定，动态
3. ~/.claude/agents/ — 用户级别，个人

创建 Agent

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: 安全专注的代码审查
model: opus
tools: [Read, Bash]
---
你是一名资深安全工程师。审查代码时关注：
- 注入漏洞（SQL、XSS、命令注入）
- 认证/授权缺陷
- 代码中的密钥
- 不安全的反序列化

通过以下方式调用：@security-reviewer review the auth module

通过 CLI 动态定义 Agent

terminal(command="claude --agents '{"reviewer": {"description": "审查代码", "prompt": "你是一个专注于性能的代码审查者"}}' -p '使用 @reviewer 来检查 auth.py'", timeout=120)

Claude 可以编排多个 Agent：「使用 @db-expert 优化查询，然后使用 @security 审计变更。」

钩子 — 事件自动化

在 .claude/settings.json（项目）或 ~/.claude/settings.json（全局）中配置：

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write(*.py)",
      "hooks": [{"type": "command", "command": "ruff check --fix $CLAUDE_FILE_PATHS"}]
    }],
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{"type": "command", "command": "if echo "$CLAUDE_TOOL_INPUT" | grep -q 'rm -rf'; then echo '已拦截！' && exit 2; fi"}]
    }],
    "Stop": [{
      "hooks": [{"type": "command", "command": "echo 'Claude 完成了一条响应' >> /tmp/claude-activity.log"}]
    }]
  }
}

全部 8 种钩子类型

钩子	触发时机	常见用途
UserPromptSubmit	Claude 处理用户提示之前	输入验证、日志记录
PreToolUse	工具执行之前	安全门、阻止危险命令（exit 2 = 阻止）
PostToolUse	工具执行完成后	自动格式化代码、运行 linter
Notification	权限请求或等待输入时	桌面通知、告警
Stop	Claude 完成一条响应时	完成日志、状态更新
SubagentStop	子 Agent 完成时	Agent 编排
PreCompact	上下文记忆被清除之前	备份会话记录
SessionStart	会话开始时	加载开发上下文（例如 git status）

钩子环境变量

变量	内容
CLAUDE_PROJECT_DIR	当前项目路径
CLAUDE_FILE_PATHS	正在修改的文件
CLAUDE_TOOL_INPUT	JSON 格式的工具参数

安全钩子示例

{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{"type": "command", "command": "if echo "$CLAUDE_TOOL_INPUT" | grep -qE 'rm -rf|git push.*--force|:(){ :|:& };:'; then echo '危险命令已拦截！' && exit 2; fi"}]
  }]
}

MCP 集成

为数据库、API 和服务添加外部工具服务器：

# GitHub 集成
terminal(command="claude mcp add -s user github -- npx @modelcontextprotocol/server-github", timeout=30)

# PostgreSQL 查询
terminal(command="claude mcp add -s local postgres -- npx @anthropic-ai/server-postgres --connection-string postgresql://localhost/mydb", timeout=30)

# Puppeteer Web 测试
terminal(command="claude mcp add puppeteer -- npx @anthropic-ai/server-puppeteer", timeout=30)

MCP 作用域

标志	作用域	存储位置
-s user	全局（所有项目）	~/.claude.json
-s local	本项目（个人）	.claude/settings.local.json（被 gitignore）
-s project	本项目（团队共享）	.claude/settings.json（被 Git 跟踪）

Print/CI 模式中的 MCP

terminal(command="claude --bare -p '查询数据库' --mcp-config mcp-servers.json --strict-mcp-config", timeout=60)

--strict-mcp-config 忽略除 --mcp-config 之外的所有 MCP 服务器。

在对话中引用 MCP 资源：@github:issue://123

MCP 限制与调优

• 工具描述：每个服务器 2KB 上限（工具描述和服务器指令）
• 结果大小：默认有上限；使用 maxResultSizeChars 注释允许最多 500K 字符用于大输出
• 输出 Token：export MAX_MCP_OUTPUT_TOKENS=50000 — 限制 MCP 服务器输出，防止上下文溢出
• 传输协议：stdio（本地进程）、http（远程）、sse（服务器推送事件）

监控交互式会话

读取 TUI 状态

# 定期捕获以检查 Claude 是在工作还是在等待输入
terminal(command="tmux capture-pane -t dev -p -S -10")

关注这些指示器：

• ❯ 在底部 = 等待你的输入（Claude 已完成或正在提问）
• ● 行 = Claude 正在主动使用工具（读取、写入、运行命令）
• ⏵⏵ bypass permissions on = 状态栏显示权限模式
• ◐ medium · /effort = 状态栏中的当前努力级别
• ctrl+o to expand = 工具输出被截断（可在交互模式下展开）

上下文窗口健康

在交互模式中使用 /context 查看上下文使用情况的彩色网格。关键阈值：

• < 70% — 正常运行，全精度
• 70-85% — 精度开始下降，考虑 /compact
• > 85% — 幻觉风险显著增加，使用 /compact 或 /clear

环境变量

变量	效果
ANTHROPIC_API_KEY	用于认证的 API Key（OAuth 的替代方案）
CLAUDE_CODE_EFFORT_LEVEL	默认 effort：low、medium、high、max、auto
MAX_THINKING_TOKENS	限制思考 Token（设为 0 完全禁用思考）
MAX_MCP_OUTPUT_TOKENS	限制 MCP 服务器的输出（默认值不定；设如 50000）
CLAUDE_CODE_NO_FLICKER=1	启用 alt-screen 渲染以消除终端闪烁
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB	从子进程中清理凭证，提高安全性

成本与性能技巧

1. 使用 --max-turns 在 print 模式中防止失控循环。大多数任务从 5-10 开始。
2. 使用 --max-budget-usd 设置成本上限。注意：系统提示缓存创建最低约 $0.05。
3. 使用 --effort low 处理简单任务（更快、更便宜）。high 或 max 用于复杂推理。
4. CI/脚本使用 --bare 跳过插件/钩子发现的开销。
5. 使用 --allowedTools 限制到仅需要的工具（例如审查时仅 Read）。
6. 交互式会话中在上下文变大时使用 /compact。
7. 管道输入代替让 Claude 读取文件，当你只需要分析已知内容时。
8. 使用 --model haiku 处理简单任务（更便宜），--model opus 用于复杂的多步骤工作。
9. print 模式中使用 --fallback-model haiku 优雅处理模型过载。
10. 不同任务开启新会话 — 会话持续 5 小时；新鲜上下文更高效。
11. CI 中使用 --no-session-persistence 避免在磁盘上积累保存的会话。

常见陷阱与注意事项

1. 交互式模式必须使用 tmux — Claude Code 是一个完整的 TUI 应用。在 Hermes 终端中单独使用 pty=true 可以工作，但 tmux 提供了 capture-pane 用于监控和 send-keys 用于输入，这对编排至关重要。
2. --dangerously-skip-permissions 对话框默认为「不，退出」 — 你必须先按 Down 再按 Enter 来接受。Print 模式（-p）完全跳过此对话框。
3. --max-budget-usd 最低约 $0.05 — 仅系统提示缓存创建就需要这个成本。设置更低会立即报错。
4. --max-turns 仅限 print 模式 — 在交互式会话中被忽略。
5. Claude 可能使用 python 而不是 python3 — 在没有 python 符号链接的系统上，Claude 的 bash 命令首次尝试会失败但会自动修正。
6. 会话恢复需要同一目录 — --continue 找到当前工作目录最近的会话。
7. --json-schema 需要足够的 --max-turns — Claude 在生成结构化输出之前需要读取文件，这需要多轮交互。
8. 信任对话框每个目录只出现一次 — 仅首次，之后缓存。
9. 后台 tmux 会话持续存在 — 完成后始终使用 tmux kill-session -t <名称> 清理。
10. 斜杠命令（如 /commit）仅在交互模式中可用 — 在 -p 模式中，用自然语言描述任务。
11. --bare 跳过 OAuth — 需要 ANTHROPIC_API_KEY 环境变量或设置中的 apiKeyHelper。
12. 上下文退化是真实存在的 — 上下文窗口使用超过 70% 时 AI 输出质量明显下降。使用 /context 监控并主动 /compact。

Hermes Agent 使用规则

1. 优先为单一任务使用 print 模式（-p） — 更干净，无需对话框处理，结构化输出
2. 多轮交互式工作使用 tmux — 编排 TUI 的唯一可靠方法
3. 始终设置 workdir — 让 Claude 专注于正确的项目目录
4. print 模式中设置 --max-turns — 防止无限循环和失控成本
5. 监控 tmux 会话 — 使用 tmux capture-pane -t <会话> -p -S -50 检查进度
6. 寻找 ❯ 提示符 — 表示 Claude 正在等待输入（已完成或在提问）
7. 清理 tmux 会话 — 完成后终止它们以避免资源泄漏
8. 向用户报告结果 — 完成后总结 Claude 做了什么以及有什么变化
9. 不要终止慢速会话 — Claude 可能正在做多步骤工作；检查进度而不是直接杀掉
10. 使用 --allowedTools — 将能力限制到任务实际需要的范围