# Claude Code

> Delegate deep reasoning to Claude Code CLI (升级触发器: 上下文 >50k / pi 失败 / 链式判断 ≥3 层).

- Skill: `jajabong/claude-code` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jajabong/claude-code`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jajabong/claude-code/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: jajabong (https://skillmd.com/u/jajabong)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jajabong/claude-code

---


# Claude Code CLI

Delegate deep-reasoning / complex chains to [Claude Code](https://github.com/anthropics/claude-code). **Upgrade engine** — per SOUL §舰队表 L145 + §claude-code 升级触发器 L147-157, claude-code 仅在 pi 压不动时才派。

## When to Use (升级触发器)

**必升级（任一命中立刻升级）**:

- 上下文 >50k tokens (单任务描述 / 历史 / 引用总长)
- 前一轮 pi 失败 (verify 红 或 timeout >3min)

**建议升级（命中后优先考虑，可仍走 pi）**:

- 链式判断 ≥3 层 (e.g. A → B → C + 决策依赖)
- 任务涉架构权衡 / 失败调试 / 多步博弈

## Prerequisites

- Claude Code installed: `npm i -g @anthropic-ai/claude-code@latest`
- Auth: Anthropic API key in env, OR Claude Code OAuth (`claude auth login`)
- Verify: `claude --version` (current: 2.1.220+)

## One-Shot (Non-Interactive)

Per SOUL §舰队表 L145, default template:

```bash
claude -p "<goal>" --output-format json
```

`-p` / `--print` = non-interactive; `--output-format json` = machine-readable for dispatcher.

### Read-Only Variant

```bash
claude -p --allowedTools "Read,Grep,Glob,LS" "<review-goal>"
```

### With Extra Directories

```bash
claude -p --add-dir /path/to/repo "<goal>"
```

## Dispatcher Integration (v2.3+)

Claude is in `dispatcher.py:31 ENGINES = {"codex", "pi", "opencode", "shell", "claude"}` as of v2.3. When the dispatcher routes a task to `engine: "claude"`, `build_command` (dispatcher.py:441-450) constructs:

```python
["claude", "-p", prompt, "--output-format", "json", *task.get("extra_args", [])]
```

**This closes the gap**: before v2.3, §舰队表 had claude-code row but dispatcher.py would `raise ValueError`. Now both Queen-direct (`claude -p` shell) and dispatcher-routed work.

## Upgrade vs. Pi (Decision Rule)

Same model, different toolchain + context handling:

- **Default**: pi (cheaper, faster, Anchor-routed)
- **Upgrade to claude-code when**:
  - 上下文 >50k
  - pi verified red / timeout >3min
  - 链式判断 ≥3 层
  - 架构权衡 / 失败调试 / 多步博弈

Don't manually swap unless trigger fires; pi is the cheaper default.

## Pitfalls

- `claude` (without `-p`) starts **interactive session** — dispatcher calls must use `-p`.
- `--output-format json` makes output parseable; text mode dumps conversation transcript.
- `-p` 后加 positional prompt 即可；不要 `--prompt` flag (legacy)。
- OAuth users: `claude auth login` once, keychain cached. API-key users: `ANTHROPIC_API_KEY` env.
- `--bare` mode strips hooks/LSP/memory — useful in sandbox/CI contexts.
- `claude --resume` is interactive-only; one-shot jobs use `--session <id>` (rare).

## Verification

Smoke test:

```bash
claude -p "Respond with exactly: CLAUDE_SMOKE_OK" --output-format json
```

Success criteria: JSON output `{"result": "CLAUDE_SMOKE_OK"}` or text contains the marker, exit code 0.

## Rules

1. 永远带 `-p` + `--output-format json` for dispatcher context.
2. 默认走 pi; 升级触发器命中才走 claude-code.
3. Queen 直接 `claude -p` shell 调 与 dispatcher 派单 等价 (v2.3+).

## §Queen 协同协议 (v29.0)

### 何时被 Queen 派
- SOUL §舰队表 L145 + §claude-code 升级触发器 L147-157: **升级 engine**, 仅 pi 压不动时才派
- 必升级触发: 上下文 >50k / 前一轮 pi verify 红 + timeout >3min
- 建议升级: 链式判断 ≥3 层 / 架构权衡 / 失败调试 / 多步博弈

### Queen 派单时该传什么
- `goal`: 已升级的复杂任务 (pi 失败的延续)
- `context`: pi 失败的 finding + verify 输出 + 调研结论
- `execution_mode`: read_only 默认; write 需显式声明 (claude 写代码少见, 通常 pi 都压不动时 Queen 会换策略而不是派 claude 写)
- 通过 dispatcher 派单时, 沙箱由 dispatcher.py:441-470 自动管; Queen 直接 shell 需手传 `--allowedTools`

### 该期待什么产出
- `summary.md`: 推理结论 + path:line 引用
- `--output-format json` 让 stdout 可被 dispatcher 解析

### Verify 责任分工
- worker 跑 Queen 在 task 里给的 `verification_command`, 报 exit code
- Queen 复核 exit code 不重跑 (派单 §硬规则 L2)
- claude-code verify 通常涉及 LLM-judge, 不是简单的 exit 0 检查; Queen 应读 verdict 而非仅看 exit code

### Abort / 打断规则 (SOUL §打断处理)
- 用户插话引用 task_id 或改了 goal → 立即 abort `claude -p` (subprocess kill, 安全)
- abort 半成品: claude-code 通常写 `--allowedTools` 受限目录, 即使半成品影响小; 但仍需 Queen 后续 git status 检查
- 不续 session (`--resume` 在 abort 后不要用, 默认 `--no-session`)
- v2.3+ dispatcher ENGINES 支持 claude, abort 走 dispatcher.status.json#counters 标准路径

### 与其他 worker 接力
- claude-code 用于"压不动时" (per §升级触发器), 通常不写代码
- 接力: pi → claude-code (升级) / claude-code → pi (回退失败后)
- 升级时 context 必传: pi 失败的 finding + verify 输出

### 沙箱边界
- dispatcher 派单: read_only → `--allowedTools Read,Grep,Glob,LS`; write → `--add-dir project_root` (per dispatcher.py:441-470)
- Queen 直接 shell: 默认全权限, 需 `--allowedTools` 自加