附录 · 速查手册
本附录是全书的案头查阅部分。所有命令与配置以 2026-07-08 核对、Claude Code v2.1.202+ 为准。
research preview/beta功能已标注。
A. 命令真实性总表(精简版)
完整版见第 06 章 6.4.2 节。核心原则:严格区分内置命令、Bundled Skills、自定义 skill,不把自定义伪装成内置。
A.1 CLI 启动参数
| 写法 | 行为 | 内置 |
|---|---|---|
claude | 启动交互会话 | 是 |
claude -p "query" | Print mode,执行后退出 | 是 |
claude -p "..." --output-format json | 指定输出格式 | 是 |
claude --permission-mode plan | 指定权限模式启动 | 是 |
claude --worktree | 在新 git worktree 启动 | 是 |
cat log | claude -p "..." | 管道输入(脚本/CI) | 是 |
A.2 真正内置命令
| 命令 | 行为 |
|---|---|
/help /status /doctor /login /logout | 帮助/状态/诊断/认证 |
/init | 生成 CLAUDE.md |
/compact /clear /context /cost | 上下文与成本 |
/config /model /effort /fast /theme /output-style | 配置/模型/档位/主题 |
/permissions /memory /plan | 权限/记忆/计划模式 |
/mcp /agents /workflows /plugin /add-dir | MCP/子代理/工作流/插件/目录 |
A.3 Bundled Skills(官方随包附带)
/code-review /security-review /review /commit /pr /loop /deep-research /claude-api /run /verify /simplify /debug /fewer-permission-prompts /update-config /dataviz /init
A.4 陷阱(不是内置或已移除)
| 写法 | 真相 | 正确做法 |
|---|---|---|
/bug | /feedback 别名,报告问题非修 Bug | 自然语言或自定义 /fix-bug |
/vim | 已移除 | /config → Editor mode 或 editorMode: "vim" |
/dev /search /explain | 官方默认表不存在 | 自定义 skill 实现 |
/agent-skills:plan | 插件 namespace,非内置 | 必须带 插件名: 前缀 |
B. 设置文件层级与字段速查
B.1 配置文件优先级(从高到低)
| 层级 | 路径 | 用途 |
|---|---|---|
| Managed policy | /Library/Application Support/ClaudeCode/(macOS) | 企业强制策略 |
| User | ~/.claude/settings.json | 用户全局 |
| Project | .claude/settings.json(提交 Git) | 项目团队共享 |
| Local | .claude/settings.local.json(gitignore) | 个人本地 |
B.2 settings.json 关键字段
json
{
"permissions": { "allow": [...], "deny": [...], "ask": [...] },
"hooks": { "PreToolUse": [...], "PostToolUse": [...], "Stop": [...] },
"mcpServers": { "server-name": { "command": "...", "args": [...], "env": {...} } },
"statusLine": { "type": "command", "command": "..." },
"editorMode": "vim",
"model": "opus",
"outputStyle": "explanatory"
}B.3 CLAUDE.md 层级
Managed policy > User(~/.claude/CLAUDE.md) > Project(./CLAUDE.md 或 ./.claude/CLAUDE.md) > Local(./CLAUDE.local.md)。@import 最深 4 层。建议每个 < 200 行。
C. 权限规则语法速查
C.1 规则数组
allow— 自动允许deny— 始终拒绝ask— 每次询问
C.2 规则语法示例
json
{
"permissions": {
"allow": ["Bash(npm test)", "Bash(npm run lint)", "Bash(git diff*)", "Read", "Edit"],
"deny": ["Bash(rm -rf)", "Bash(git push*)", "Bash(npm publish)"]
}
}C.3 权限模式
| 模式 | 行为 | 切换 |
|---|---|---|
default | Manual,标准提示 | Shift+Tab |
acceptEdits | 自动接受文件编辑 | Shift+Tab |
plan | 计划模式,只读 | /plan 或 Shift+Tab |
bypassPermissions | 跳过所有提示(危险) | Shift+Tab |
auto(新,preview) | 后台分类器自动审核(93% 批准) | Shift+Tab |
dontAsk | 自动拒绝(显式允许的仍可用) | --permission-mode |
关键结论:bypassPermissions 下 deny 规则仍生效——deny 是硬边界。
D. Hook 事件全表(30+)
详见第 14 章。按分组:
| 分组 | 事件 |
|---|---|
| 会话级 | SessionStart SessionEnd Setup |
| 每轮 | UserPromptSubmit UserPromptExpansion Stop StopFailure |
| 工具循环 | PreToolUse PostToolUse PostToolUseFailure PostToolBatch PermissionRequest PermissionDenied |
| Subagent | SubagentStart SubagentStop |
| 上下文 | PreCompact PostCompact |
| 文件/目录 | FileChanged CwdChanged WorktreeCreate WorktreeRemove |
| 配置/指令 | ConfigChange InstructionsLoaded |
| 任务/团队 | TaskCreated TaskCompleted TeammateIdle |
| 交互 | Notification MessageDisplay Elicitation ElicitationResult |
决策控制:PreToolUse 用 hookSpecificOutput.permissionDecision(allow/deny/ask/defer);其他事件用 decision: "block"。
Hook 类型(5 种):command(shell)、http、mcp_tool、prompt(LLM 评估)、agent(实验性,带工具验证 subagent)。
E. frontmatter 字段速查
E.1 Skills(.claude/skills/<name>/SKILL.md)
yaml
---
description: 何时触发此 skill(必填)
disable-model-invocation: true # 禁止模型自动调用,仅用户 / 触发
user-invocable: true # 用户可调用
allowed-tools: [Read, Edit, Bash] # 限制可用工具
context: fork # 在 fork 上下文运行
paths: ["src/**/*.ts"] # 条件路径
arguments: [...] # 命名参数
---E.2 Subagents(.claude/agents/<name>.md)
yaml
---
name: security-auditor # 必填
description: 安全审查专用子代理 # 必填
tools: [Read, Grep, Bash] # 限制工具
model: opus # 模型
permissionMode: plan # 权限模式
effort: high # 推理档
isolation: worktree # worktree 隔离
background: true # 后台运行
mcpServers: [...] # 挂载 MCP
hooks: {...} # 子代理专属 hook
memory: true # 启用记忆
skills: [...] # 可用 skill
---E.3 Commands(.claude/commands/<name>.md,已合并进 Skills)
yaml
---
description: 命令说明
argument-hint: "<file-path>"
arguments: [...]
disable-model-invocation: true
allowed-tools: [Read]
---参数引用:$ARGUMENTS、$ARGUMENTS[0]、$1、命名参数。
F. 常见报错与解决速查
| 症状 | 原因 | 解决 |
|---|---|---|
| Claude 遗忘早期对话 | 上下文窗口溢出 | /compact 压缩;/clear 切换任务;关键信息写文件 |
| 每次命令都问确认 | 权限未配置 | settings.json 的 allow 加白名单 |
| 回复半途停止 | 输出截断 | 拆步骤(骨架→扩写)或用子代理并行 |
| Shell 命令非零退出 | 依赖/类型/环境变量 | 喂 stderr 给 Claude 定位修复 |
| 引用不存在的文件/API | 幻觉 | 让 Claude 先 Read 文件再分析;CLAUDE.md 记录准确 API 名 |
API Error: 429 | 账户速率限制 | 降低子代理并发;错峰;小批量重试 |
| Skill 不触发 | 第三方模型触发率低 | 换 Claude 原生模型(触发率 ~98%) |
命令找不到(/dev 等) | 非内置命令 | 用自定义 skill,勿当内置 |
G. Claude Code 版本与新功能时间线(2025-2026)
| 时间 | 功能 | 状态 |
|---|---|---|
| 2024-11 | MCP(Model Context Protocol)发布 | GA |
| 2025-09-29 | Claude Agent SDK(原 Claude Code SDK) | GA |
| 2025-10-16 | Agent Skills | GA |
| 2025 Q4 | Hooks 大幅扩展(prompt/agent/http/mcp_tool 类型,30+ 事件) | GA |
| 2026-04-08 | Managed Agents | beta |
| 2026-05-28 | Dynamic Workflows + Ultracode + Opus 4.8 + Fast Mode | research preview |
| 2026 H1 | Auto Mode 权限、Agent Teams、Fork、Artifacts | 部分 preview |
版本基准:本书 v2.1.202+(2026-07-08 核对)。CC 迭代极快(2025 年 176 次更新),定稿前请核对 GitHub CHANGELOG。
H. 官方资料与延伸阅读
H.1 官方文档
- Claude Code 文档主页
- CLI reference
- Commands
- Permissions / Permission modes
- Settings
- Memory
- Skills
- Subagents
- Hooks / Hooks guide
- MCP quickstart / MCP reference
- Workflows
- Agent SDK
- Managed Agents
- GitHub Actions
- Best practices
H.2 公告博客
- Agent Skills(2025-10-16)
- Dynamic Workflows(2026-05-28)
- Managed Agents(2026-04-08)
- Claude Opus 4.8
- Auto Mode
H.3 GitHub
H.4 本书配套素材(读者可自行拓展)
- 三家架构哲学深度分析(本书第 23 章素材来源)
- Agent 产品可复用骨架(本书第 24 章素材来源)
- 20+ 真实项目代码审查报告(本书第 25 章案例来源)
速查表建议打印或常驻副屏。理解原理(第 06 章)后,本附录足以支撑日常案头。