Claude Code 编码代理

委派编码任务给 Claude Code CLI（功能开发、PR 提交）

Claude Code — Hermes 编排指南

通过 Hermes 终端将编码任务委派给 Claude Code（Anthropic 的自主编码代理 CLI）。Claude Code v2.x 可以读取文件、编写代码、运行 shell 命令、生成子代理（subagent），并自主管理 git 工作流。

前置条件

两种编排模式

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

模式 1：Print 模式（`-p`）— 非交互式（大多数任务的首选）

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

terminal(command="claude -p 'Add error handling to all API calls in src/' --allowedTools 'Read,Edit' --max-turns 10", workdir="/path/to/project", timeout=120)

何时使用 print 模式：

Print 模式会跳过所有交互式对话框 — 没有工作区信任提示，没有权限确认。因此非常适合自动化场景。

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

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

# Start a tmux session
terminal(command="tmux new-session -d -s claude-work -x 140 -y 40")

# Launch Claude Code inside it
terminal(command="tmux send-keys -t claude-work 'cd /path/to/project && claude' Enter")

# Wait for startup, then send your task
# (after ~3-5 seconds for the welcome screen)
terminal(command="sleep 5 && tmux send-keys -t claude-work 'Refactor the auth module to use JWT tokens' Enter")

# Monitor progress by capturing the pane
terminal(command="sleep 15 && tmux capture-pane -t claude-work -p -S -50")

# Send follow-up tasks
terminal(command="tmux send-keys -t claude-work 'Now add unit tests for the new JWT code' Enter")

# Exit when done
terminal(command="tmux send-keys -t claude-work '/exit' Enter")

何时使用交互式模式：

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

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

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

❯ 1. Yes, I trust this folder    ← DEFAULT (just press Enter)
  2. No, exit

处理方法： tmux send-keys -t Enter — 默认选项即为正确选项。

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

❯ 1. No, exit                    ← DEFAULT (WRONG choice!)
  2. Yes, I accept

处理方法：必须先按 DOWN 键导航，再按 Enter：

tmux send-keys -t  Down && sleep 0.3 && tmux send-keys -t  Enter

健壮的对话框处理模式

# Launch with permissions bypass
terminal(command="tmux send-keys -t claude-work 'claude --dangerously-skip-permissions "your task"' Enter")

# Handle trust dialog (Enter for default "Yes")
terminal(command="sleep 4 && tmux send-keys -t claude-work Enter")

# Handle permissions dialog (Down then Enter for "Yes, I accept")
terminal(command="sleep 3 && tmux send-keys -t claude-work Down && sleep 0.3 && tmux send-keys -t claude-work Enter")

# Now wait for Claude to work
terminal(command="sleep 15 && tmux capture-pane -t claude-work -p -S -60")

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

CLI 子命令

Print 模式深入解析

结构化 JSON 输出

terminal(command="claude -p 'Analyze auth.py for security issues' --output-format json --max-turns 5", workdir="/project", timeout=120)

返回一个包含以下内容的 JSON 对象：

{
  "type": "result",
  "subtype": "success",
  "result": "The analysis text...",
  "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 为代理循环次数，total_cost_usd 用于支出追踪，subtype 用于成功/错误检测（success、error_max_turns、error_budget）。

流式 JSON 输出

如需实时 token 流式输出，请使用 stream-json 搭配 --verbose：

terminal(command="claude -p 'Write a summary' --output-format stream-json --verbose --include-partial-messages", timeout=60)

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

claude -p "Explain 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 "task" --input-format stream-json --output-format stream-json --replay-user-messages

--replay-user-messages 会将用户消息重新输出到 stdout 以作确认。

管道输入

# Pipe a file for analysis
terminal(command="cat src/auth.py | claude -p 'Review this code for bugs' --max-turns 1", timeout=60)

# Pipe multiple files
terminal(command="cat src/*.py | claude -p 'Find all TODO comments' --max-turns 1", timeout=60)

# Pipe command output
terminal(command="git diff HEAD~3 | claude -p 'Summarize these changes' --max-turns 1", timeout=60)

用于结构化提取的 JSON Schema

terminal(command="claude -p 'List all functions in 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 验证输出。

会话延续

# Start a task
terminal(command="claude -p 'Start refactoring the database layer' --output-format json --max-turns 10 > /tmp/session.json", workdir="/project", timeout=180)

# Resume with session ID
terminal(command="claude -p 'Continue and add connection pooling' --resume $(cat /tmp/session.json | python3 -c 'import json,sys; print(json.load(sys.stdin)["session_id"])') --max-turns 5", workdir="/project", timeout=120)

# Or resume the most recent session in the same directory
terminal(command="claude -p 'What did you do last time?' --continue --max-turns 1", workdir="/project", timeout=30)

# Fork a session (new ID, keeps history)
terminal(command="claude -p 'Try a different approach' --resume  --fork-session --max-turns 10", workdir="/project", timeout=120)

用于 CI/脚本的 Bare 模式

terminal(command="claude --bare -p 'Run all tests and report failures' --allowedTools 'Read,Bash' --max-turns 10", workdir="/project", timeout=180)

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

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

过载时的回退模型

terminal(command="claude -p 'task' --fallback-model haiku --max-turns 5", timeout=90)

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

完整 CLI 标志参考

会话与环境

模型与性能

权限与安全

输出与输入格式

系统提示词与上下文

调试

代理团队

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

Read                    # All file reading
Edit                    # File editing (existing files)
Write                   # File creation (new files)
Bash                    # All shell commands
Bash(git *)             # Only git commands
Bash(git commit *)      # Only git commit commands
Bash(npm run lint:*)    # Pattern matching with wildcards
WebSearch               # Web search capability
WebFetch                # Web page fetching
mcp____   # Specific MCP tool

设置与配置

设置优先级（从高到低）

设置中的权限配置

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

记忆文件（CLAUDE.md）层级

在交互式模式中使用 # 前缀可快速添加到记忆：# Always use 2-space indentation。

交互式会话：斜杠命令

会话与上下文

开发与审查

配置 & Tools

自定义斜杠命令

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

# .claude/commands/deploy.md
Run the deploy pipeline:
1. Run all tests
2. Build the Docker image
3. Push to registry
4. Update the $ARGUMENTS environment (default: staging)

用法：/deploy production — $ARGUMENTS 会被替换为用户输入。

Skills（自然语言调用）

与斜杠命令（手动调用）不同，.claude/skills/ 中的 skills 是 markdown 指南，当任务匹配时 Claude 会通过自然语言自动调用：

# .claude/skills/database-migration.md
When asked to create or modify database migrations:
1. Use Alembic for migration generation
2. Always create a rollback function
3. Test migrations against a local database copy

交互式会话：键盘快捷键

常规控制

模式切换

多行输入

输入前缀

专业技巧："ultrathink"

在提示词中使用关键词 "ultrathink" 可让特定一轮使用最大推理努力。无论当前 /effort 设置如何，这都会触发最深的思考模式。

PR 审查模式

快速审查（Print 模式）

terminal(command="cd /path/to/repo && git diff main...feature-branch | claude -p 'Review this diff for bugs, security issues, and style problems. Be thorough.' --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")  # Trust dialog
terminal(command="sleep 2 && tmux send-keys -t review 'Review all changes vs main. Check for bugs, security issues, race conditions, and missing tests.' Enter")
terminal(command="sleep 30 && tmux capture-pane -t review -p -S -60")

按编号审查 PR

terminal(command="claude -p 'Review this PR thoroughly' --from-pr 42 --max-turns 10", workdir="/path/to/repo", timeout=120)

Claude Worktree 配合 tmux

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

在 .claude/worktrees/feature-x 创建独立的 git worktree，并为其创建 tmux 会话。可用时会使用 iTerm2 原生面板；如需传统 tmux，请添加 --tmux=classic。

并行 Claude 实例

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

# Task 1: Fix backend
terminal(command="tmux new-session -d -s task1 -x 140 -y 40 && tmux send-keys -t task1 'cd ~/project && claude -p "Fix the auth bug in src/auth.py" --allowedTools "Read,Edit" --max-turns 10' Enter")

# Task 2: Write tests
terminal(command="tmux new-session -d -s task2 -x 140 -y 40 && tmux send-keys -t task2 'cd ~/project && claude -p "Write integration tests for the API endpoints" --allowedTools "Read,Write,Bash" --max-turns 15' Enter")

# Task 3: Update docs
terminal(command="tmux new-session -d -s task3 -x 140 -y 40 && tmux send-keys -t task3 'cd ~/project && claude -p "Update README.md with the new API endpoints" --allowedTools "Read,Edit" --max-turns 5' Enter")

# Monitor all
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。用它来持久化项目上下文：

# Project: My API

## Architecture
- FastAPI backend with SQLAlchemy ORM
- PostgreSQL database, Redis cache
- pytest for testing with 90% coverage target

## Key Commands
- `make test` — run full test suite
- `make lint` — ruff + mypy
- `make dev` — start dev server on :8000

## Code Standards
- Type hints on all public functions
- Docstrings in Google style
- 2-space indentation for YAML, 4-space for Python
- No wildcard imports

要具体。不要写“编写好的代码”，而要写“JS 使用 2 空格缩进”或“测试文件使用 .test.ts 后缀命名”。具体的指令能节省反复纠正的周期。

Rules 目录（模块化 CLAUDE.md）

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

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

自动记忆

Claude 会自动将学到的项目上下文存储在 ~/.claude/projects//memory/ 中。

自定义子代理

在 .claude/agents/（项目）、~/.claude/agents/（个人）中定义专用代理，或通过 --agents CLI 标志（会话级）定义：

代理位置优先级

创建代理

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: Security-focused code review
model: opus
tools: [Read, Bash]
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication/authorization flaws
- Secrets in code
- Unsafe deserialization

调用方式：@security-reviewer review the auth module

通过 CLI 动态创建代理

terminal(command="claude --agents '{"reviewer": {"description": "Reviews code", "prompt": "You are a code reviewer focused on performance"}}' -p 'Use @reviewer to check auth.py'", timeout=120)

Claude 可以编排多个代理：“Use @db-expert to optimize queries, then @security to audit the changes.”（先让 @db-expert 优化查询，然后让 @security 审计更改。）

Hooks — 事件驱动的自动化

在 .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 'Blocked!' && exit 2; fi""}]
    }],
    "Stop": [{
      "hooks": [{"type": "command", "command": "echo 'Claude finished a response' >> /tmp/claude-activity.log"}]
    }]
  }
}

全部 8 种 Hook 类型

Hook 环境变量

安全说明 Hook Examples

{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{"type": "command", "command": "if echo "$CLAUDE_TOOL_INPUT" | grep -qE 'rm -rf|git push.*--force|:(){ :|:& };:'; then echo 'Dangerous command blocked!' && exit 2; fi""}]
  }]
}

MCP 集成

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

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

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

# Puppeteer for web testing
terminal(command="claude mcp add puppeteer -- npx @anthropic-ai/server-puppeteer", timeout=30)

MCP 作用域

Print/CI 模式下的 MCP

terminal(command="claude --bare -p 'Query database' --mcp-config mcp-servers.json --strict-mcp-config", timeout=60)

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

在聊天中引用 MCP 资源：@github:issue://123

MCP 限制与调优

监控交互式会话

读取 TUI 状态

# Periodic capture to check if Claude is still working or waiting for input
terminal(command="tmux capture-pane -t dev -p -S -10")

留意以下指示信息：

上下文窗口健康度

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

环境要求 Variables

成本与性能技巧

陷阱与注意事项

Hermes 代理规则