Sonub Lab — Claude Code 实践

它是什么

Claude Code 是 Anthropic 开发的智能体编程工具（agentic coding tool）。你用自然语言描述任务，它就会读取文件、修改代码、运行命令，并在动手前先征求你的许可。它在终端中运行，也可以在 VS Code、JetBrains 等代码编辑器、Claude 桌面应用和网页上使用。

它可以在改动之前先展示计划，并在修改文件或运行命令之前征求同意 — 它能做什么由你决定（权限）。项目规则写在 CLAUDE.md 里，它每次会话开始时都会读取。

你需要什么

• 账户：Claude Pro、Max、Team 或 Enterprise 套餐，或 Console（API）账户。免费的 claude.ai 套餐不包含 Claude Code。
• 电脑：macOS 13 或更高版本、Windows 10（1809）或更高版本、Ubuntu 20.04 或 Debian 10 或更高版本，至少 4 GB 内存，并能连接互联网。
• 一个用来工作的项目文件夹 — 最好是 Git 仓库，这样每处改动都能查看和撤销。

安装

在 macOS、Linux 和 WSL 上运行第一行；在 Windows 上运行 PowerShell 那一行。这样安装后，它会在后台自动更新。用 Homebrew 和 WinGet 安装的不会自动更新。

macOS · Linux · WSL

curl -fsSL https://claude.ai/install.sh | bash 复制

Windows PowerShell

irm https://claude.ai/install.ps1 | iex 复制

Homebrew

brew install --cask claude-code 复制

WinGet

winget install Anthropic.ClaudeCode 复制

npm (Node.js 22+)

npm install -g @anthropic-ai/claude-code 复制

检查安装

打开一个新的终端窗口。claude --version 应显示版本号，claude doctor 会显示安装状态。如果看到“command not found”，请重新打开终端并检查 PATH。

第一次运行 — 五个步骤

1. 打开终端，用 cd <文件夹> 进入项目文件夹，然后输入 claude 并按 Enter（这会启动终端里的工具，而不是桌面应用）。第一次运行时会打开浏览器让你登录。
2. 问它“这个项目里有什么？”，让它阅读项目。
3. 运行 /init 创建 CLAUDE.md，然后加上你的测试命令和要遵守的规则。
4. 按 Shift+Tab 切换到计划模式，然后提出修改要求。阅读计划、修改，再批准。
5. 用 git diff 查看改了什么，自己运行测试，然后提交。

基础练习 — 从头试一次

1. 建一个练习文件夹(mkdir hello-ai && cd hello-ai)，用 git init 把它变成 Git 仓库，然后运行 claude。看到输入框就说明成功了。
2. 请它：“做一个显示今天日期的单页网页 index.html。”如果它在创建文件前询问，先读它打算做什么，再允许。
3. 用浏览器打开生成的 index.html，亲眼确认日期显示出来了。
4. 用 git status 看改了什么，再用 git add . 和 git commit -m "first page" 保存。
5. 再请它一次：“把日期的字放大。”如果不满意结果，用 git restore index.html 回到上一次提交的状态。

卡住时：claude 启动不了就用 claude doctor 检查安装；登录页没有打开就关掉终端、重新打开，再运行 claude。五项都做完了？进入 [进阶] 标签。

在 SONUB 上深入学习

• Claude Code 1：设置项目并写下长期指令
• Claude Code 2：计划、修改、测试、审查
• 智能体和子智能体：AI 是怎样一步步工作的
• 目标和 Ralph Loop：让智能体一直做到真正完成
• claude-skill 智能体技能 — 一步步学习 Claude Code，跟上新功能

官方文档

• Claude Code — Overview
• Claude Code — Advanced setup
• Claude Code — Quickstart
• Claude Code — Common workflows
• Claude Code — Use Claude Code with Chrome

已于 2026-10-19 对照官方文档核实。这些工具变化很快 — 如果命令不起作用，请查看官方文档。

模型和努力程度 — 该用哪个(推荐：Opus 5.5，High)

截至2026年11月，开发请用 Opus 5.5，强度选 High。它的默认强度是 medium，所以请按下面的方法设置，或运行 /model opus 和 /effort high。所有模型和强度，以及什么时候调低、什么时候调高，都在工具大师的“推荐用法”里。

{
  "model": "opus",
  "effortLevel": "high"
}

claude --model opus --effort high

# inside Claude Code
/model opus
/effort high

• 推荐模型 — 工具大师

CLAUDE.md — 每次会话都会读取的项目指令

CLAUDE.md 是 Claude Code 每次会话开始时都会读取的 Markdown 文件。把你懒得反复说的内容写进去：构建和测试命令、代码规则、绝对不能做的事。运行 /init，它会阅读项目并写出第一版 CLAUDE.md。放在多个位置的 CLAUDE.md 不会互相覆盖 — 它们会被一起读取。

• ~/.claude/CLAUDE.md — 适用于所有项目的个人指令
• ./CLAUDE.md 或 ./.claude/CLAUDE.md — 团队共享的项目指令（提交到 Git）
• ./CLAUDE.local.md — 只有你在这个项目里使用的指令（加入 .gitignore）。但只要有一个，AGENTS.md 就不会被读取
• 子文件夹里的 CLAUDE.md — Claude 读取或编辑该文件夹里的文件时也会读取。.claude/rules/ 里的规则文件可以用 paths 只对特定文件生效

# My App

## Commands
- Install: npm install
- Test: npm test
- Lint: npm run lint

## Rules
- TypeScript strict mode. Do not use `any`.
- Put new API routes in src/routes/.
- Never edit files in vendor/.
- Run the tests before you say a task is done.

@docs/architecture.md

保持简短（官方文档建议少于 200 行）。它每次都会被读取，太长的文件会占用空间，还会把重要的规则淹没。/memory 会显示已加载的指令文件并打开它们供你编辑，@path（比如 @docs/architecture.md）可以引入另一个文件。如果你同时使用多个 AI，最好在项目里只放 AGENTS.md，而不是 CLAUDE.md — 请看紧接着的下一节。

只用 AGENTS.md — 让所有 AI 按同一份指令工作

为什么要这样做？如果一个项目在 Claude Code 之外还用 Codex、Cursor、Gemini 等其他 AI，每个工具各自的指令文件很快就会变得不一致。AGENTS.md 是许多编程智能体都会读取的开放格式。把规则在 AGENTS.md 里写一次，无论你用哪个 AI，大家都遵守同样的指令。下面的方法正是为此而存在 — 让一个项目里的多个 AI 通过 AGENTS.md 使用同一份指令。

Claude Code 也能直接读取 AGENTS.md（v2.1.277 或更高版本），但方式和 CLAUDE.md 不太一样。

• 在默认设置下，只有当工作文件夹及其上层任何文件夹里都没有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 时，它才会读取 AGENTS.md。只要为个人笔记加一个 CLAUDE.local.md，AGENTS.md 就不再被读取（~/.claude/CLAUDE.md 和 .claude/rules/ 在这里不算）。
• 子文件夹里的 AGENTS.md 只有在 Claude 用 Read 工具打开那里的文件时才会被读取。如果它直接往那个文件夹写新文件，可能还不知道那些规则。子文件夹里的 CLAUDE.md 在读取、写入和编辑时都会被读取。
• AGENTS.local.md、AGENTS.override.md 和 .agents/ 文件夹下的文件都不会被读取，用 --add-dir 添加的文件夹里的 AGENTS.md 也不会。

最好的方法是在项目文件夹里完全不用 CLAUDE.md，只用 AGENTS.md。这样，你的全局指令 ~/.claude/CLAUDE.md 仍会默认被读取，而在项目文件夹里使用的是 AGENTS.md。Codex 等其他 AI 也读取同一个 AGENTS.md，所以规则只需在一个地方修改 — AGENTS.md。

但只要你在任何一个地方使用 CLAUDE.md — 项目文件夹、当前文件夹、上级文件夹或子文件夹 — 就必须在所有文件夹里都使用 CLAUDE.md。只要工作文件夹或其上级有一个 CLAUDE.md，Claude Code 就不会读取 AGENTS.md，所以混着用会导致有些文件夹的规则被读取，有些文件夹的规则被漏掉。这种情况下如果仍想使用 AGENTS.md，只要在每个 CLAUDE.md 里加一行 @AGENTS.md 即可。@path 是把文件内容引入到该位置的语法，官方文档也说明，这种引入绝不会让 Claude 把 AGENTS.md 读两遍。

1. 在项目顶层的 AGENTS.md 里写共享规则（安装和测试命令、代码规则、不能做的事）。也可以用 Codex 的 /init 来创建它。
2. 不要在项目里（当前文件夹、上级文件夹、子文件夹都不行）创建 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md。
3. 把你用于所有项目的个人指令放在 ~/.claude/CLAUDE.md — 它总是和 AGENTS.md 一起被读取。
4. 如果某个子文件夹有自己的规则（比如 api/），也在那里放一个 AGENTS.md。
5. 在 Claude Code 里打开 /memory，确认 AGENTS.md 已加载。如果你决定使用 CLAUDE.md，还要确认每个文件夹的 CLAUDE.md 里都有一行 @AGENTS.md。

~/.claude/CLAUDE.md    ← your personal rules (still loaded by default)

my-project/
├── AGENTS.md          ← shared rules for every AI (Claude Code, Codex, Cursor, Gemini …)
└── api/
    └── AGENTS.md      ← rules only for api/

(no CLAUDE.md anywhere in the project)

my-project/
├── AGENTS.md
├── CLAUDE.md          ← @AGENTS.md
└── api/
    ├── AGENTS.md
    └── CLAUDE.md      ← @AGENTS.md

@AGENTS.md

值得了解的事和其他方法。① 只用 AGENTS.md 时，子文件夹的 AGENTS.md 会在 Claude 用 Read 打开该文件夹里的文件时被读取。② 在 /config 里把 Project instructions 设为 claude-md-and-agents-md，每个文件夹的 AGENTS.md 会紧接着它的 CLAUDE.md 被读取。③ 符号链接（ln -s AGENTS.md CLAUDE.md）也可以，但如果有人用 Windows，一行 @AGENTS.md 更安全。

• Codex 读取 AGENTS.md 的顺序 — Codex 进阶

权限和模式 — 决定哪些事不用问就能做

Claude Code 在编辑文件或运行命令之前会先问你。如果每次批准同样的事情让你觉得麻烦，就把它变成规则，并根据工作切换模式。

• Shift+Tab — 切换模式：default（每次都问）→ acceptEdits（编辑文件不用问）→ plan（只读并展示计划）。如果你是以 auto 模式启动的，第一次按下会切换到 default。
• /permissions — 查看和编辑 allow、ask、deny 规则，以及每条规则来自哪个文件。
• .claude/settings.json 放团队共享的规则（提交它），.claude/settings.local.json 放只有你用的规则，~/.claude/settings.json 放适用于你所有项目的规则。
• 规则按 deny → ask → allow 的顺序检查。在任何地方被 deny 的事，在别处都无法 allow，所以要用 deny 挡住 .env 这样的机密文件。

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

bypassPermissions（--dangerously-skip-permissions）会关闭所有检查。只在出问题也无所谓的地方使用，比如不能上网的容器或虚拟机。

管理上下文 — 当对话变长时

Claude 一次能看到的量（上下文窗口）是固定的。对话、读过的文件和命令输出都会堆积在那里，满了之后前面的部分会被总结。对话越长，前面的指令就越模糊，所以要养成整理的习惯。

• /context — 用彩色方块查看是什么占用了上下文、占了多少。
• /compact — 总结到目前为止的对话来腾出空间。你可以说明要保留什么（比如 /compact 重点保留登录 bug 的修复）。
• /clear — 开始不相关的工作时，开启一个全新的对话。
• claude -c 继续这个文件夹里的上一次对话，claude -r 或 /resume 可以选一个更早的对话继续。
• 按两次 Esc（或 /rewind）— 从检查点列表中选一个更早的时间点，把对话和代码都回退过去。用 Bash 删除或移动的文件不会恢复，所以它不能代替 Git 提交。

一个对话只做一件事。工作换了，用 /clear 重新开始是最简单的整理方法。

节省上下文 — SONUB 标准：约 400k 时自动压缩，基础上下文不超过 6%

每次你提出请求，Claude 都会重新读取当前的整个上下文。上下文越大，每次请求花的 token 就越多。所以用 auto compact(自动压缩)，只用约 400k token 工作，而不是用满 1M，并把对话开始前就已占用的基础上下文(默认系统提示词、技能、MCP 等)保持在 6% 以下。这样可以大幅减少用量。 约 400k 和 6% 是 SONUB 自己定的经验标准，不是官方推荐值——官方文档只说明设置方法。

• /autocompact 444k — 上下文达到 444k token 时自动压缩。它会保存到当前模型的用户设置中，用 /autocompact auto 恢复。
• 要用于所有模型，就在 ~/.claude/settings.json 中加入 "autoCompactWindow": 444000(见下例)。只用一次时，用 claude --autocompact 444k 启动。
• 打开新对话后立刻运行 /context。还没提任何请求就已占用的部分 — 系统提示词、系统工具、MCP 工具、技能、记忆文件(CLAUDE.md · AGENTS.md)— 就是基础上下文，合计应不超过 6%。
• 超过 6% 就精简 — 在 /mcp 中关闭不用的 MCP 服务器，删掉不用的技能和插件，CLAUDE.md · AGENTS.md 只留下真正需要的规则。

{
  "autoCompactWindow": 444000
}

基础上下文会随每次请求一起发送，所以哪怕只省几个百分点，也会在整段对话中累积，大幅减少用量。即使还没压缩，工作一换就用 /clear 重新开始，是最大的节省。

• 工具上下文 — 约 400k，而不是 1M

好好提问 — 在哪里、做什么、怎么检查

好的请求有三个部分：在哪里（文件和文件夹）、做什么（你想要的行为）、怎么检查（测试、命令、画面）。这三点越清楚，Claude 就越少走弯路，也越会自己检查结果。

• 模糊的请求：“修一下登录”
• 清楚的请求：“在 @app/Http/Controllers/LoginController.php 里，密码错误时会出现 500 错误。改成返回 422 和错误信息，在 tests/Feature/LoginTest.php 里加一个测试，并确认测试通过。”

• 输入 @ 选择文件并附加到请求里（@src/login.ts）。
• 错误画面和设计稿，可以粘贴或拖入截图。
• 大任务先说“先阅读，只给我看计划 — 暂时什么都不要改”，或者用 /plan 进入计划模式。
• 遇到难题时，在 /model 里提高模型和努力程度，或者在请求里写上 ultrathink，让它只在这一轮更深入地思考。
• /goal <终点线> — 不用再提新请求，Claude 会一轮接一轮地工作，直到达到终点线（例：/goal tests/ 里的测试全部通过, or stop after 20 turns）。只输入 /goal 查看状态，/goal clear 删除。

最佳实践 — Anthropic 推荐的 Claude Code 用法

简单说：给 Claude 一个能自己检查的办法，难的事先做计划，请求要具体，CLAUDE.md 要简短，任务之间清空上下文。两份官方指南里的六个好习惯，以及 Claude Code 和 Codex 的命令，都在“推荐用法”里。

• 六个好习惯 — 工具大师

常见错误 — 以及如何纠正

官方指南警告了五种失败模式——什么都塞的会话、反复纠正、过长的 CLAUDE.md、不检查就相信、没完没了地探索。两份指南里的十个常见错误及改正方法，都在“推荐用法”里。

• 十个常见错误 — 工具大师

进阶练习 — 在你自己的项目里试试

1. 在你的项目顶层创建 AGENTS.md，写上测试命令和三条规则，并确认项目里没有 CLAUDE.md。
2. 打开 /memory，确认 AGENTS.md 和 ~/.claude/CLAUDE.md 都已加载。
3. 在 .claude/settings.json 里 allow 一个测试命令、deny .env，然后用 /permissions 确认。
4. 在计划模式下请求一个小功能，阅读并调整计划，然后批准。
5. 用 /context 查看用了多少，用 /compact 压缩后再看一次。

五项都做完了？进入 [高级] 标签。

官方文档

• Use Claude Code with Chrome
• Memory — CLAUDE.md · AGENTS.md
• Permissions
• Settings
• Checkpointing
• Model configuration — auto-compact window
• Best practices
• Best practices — common failure patterns

已于 2026-10-19 对照官方文档核实。这些工具变化很快 — 如果命令不起作用，请查看官方文档。

智能体技能 — 教它你重复做的工作

技能就是一个装有 SKILL.md 的文件夹。平时 Claude 只知道每个技能的名称和说明；当工作符合说明时，它才会读取正文并照着做。所以技能再多也几乎不占空间。以前的自定义命令（.claude/commands/）现在已经合并进技能。

• .claude/skills/<名称>/SKILL.md 用于这个项目，~/.claude/skills/<名称>/SKILL.md 用于你的所有项目。
• 在 description 里清楚写明它做什么、什么时候用，Claude 就会自己选中它。
• 也可以用 /<技能名称> 直接调用，/skills 会显示列表。
• 把脚本和参考文档放在同一个文件夹里，并在 SKILL.md 中指向它们。SKILL.md 保持简短，少于 500 行。

---
name: release-notes
description: Write release notes from the git log. Use when the user asks for release notes, a changelog or "what changed since the last tag".
---

# Release notes

1. Find the last tag: `git describe --tags --abbrev=0`
2. Read the commits since then: `git log <tag>..HEAD --oneline`
3. Group them under Added / Fixed / Changed.
4. Write plain sentences a user can understand. Skip internal refactors.

• 了解智能体技能 — 制作、安装、SONUB 技能

技能是开放标准 — 但 Claude Code 有自己的做法

技能最早由开发 Claude 的公司 Anthropic 创建并免费公开。如今它是一个名为 Agent Skills 的开放标准，由 agentskills.io 管理。Codex、Cursor、Gemini CLI、GitHub Copilot 等许多 AI 工具都读取同样的 SKILL.md 文件夹。

不过要注意：标准只规定技能文件夹里放什么。去哪里找技能、名称冲突时用哪一个，都由各个工具自己决定，而 Claude Code 的做法和 agentskills.io 推荐的不同。所以在别的工具里好用的技能，在 Claude Code 里可能表现不同。

• 文件夹：agentskills.io 推荐许多工具共用的 .agents/skills/，但 Claude Code 读取的是 .claude/skills/（项目）和 ~/.claude/skills/（个人），不读取 .agents/skills/。
• 同名时：标准的通用规则是项目技能优先于个人技能。Claude Code 正好相反 — 企业（enterprise）优先于个人，个人（~/.claude/skills/）优先于项目。
• 上级和下级文件夹：标准没有规定。Claude Code 读取你启动时所在的文件夹，以及往上直到 git 仓库根目录的每一级上级文件夹；下级文件夹只有在它到那里工作时才读取（见下一节）。
• frontmatter：标准有六个字段 — name、description、license、compatibility、metadata 和 allowed-tools。Claude Code 另外加了 disable-model-invocation、context: fork、paths 等字段。其他工具会忽略它们，而 claude.ai 上传和 Skills API 会报错停止。

要和其他 AI 工具共用的技能，frontmatter 只写六个标准字段。这样在 Claude Code 和其他工具里都能原样加载，不用修改。

Claude Code 在哪里找技能 — 当前文件夹和上级文件夹一起

如果你所在的文件夹有 .claude/skills 文件夹，上级文件夹也有，Claude Code 会把两边的技能一起使用。往上最多只到 git 仓库根目录。

• 它读取你启动 claude 的文件夹，以及往上直到仓库根目录的每一级上级文件夹里的 .claude/skills/。即使在 apps/web/ 启动，根目录的技能也能用。
• 仓库根目录之上的 .claude/skills/ 不会被读取。所有项目都要用的技能请放在 ~/.claude/skills/。在 git worktree 中，只往上到 worktree 的根目录。
• 启动位置之下的文件夹里的技能，一开始不会读取。Claude 第一次读取或修改该文件夹中的文件时才加载，并一直保留到会话结束 — 在那之前，它们不会出现在 / 菜单里。想提前加载，就用 /add-dir 加上那个文件夹。
• 如果根目录和 apps/web/ 都有名为 deploy 的技能，两个都能用：/deploy 运行根目录的，/apps/web:deploy 运行下级文件夹的。Claude 会被告知使用它正在处理的文件所在文件夹的技能。
• 插件技能是分开的，用 /<插件名>:<技能名> 调用，所以永远不会和你的技能冲突。

~/projects/                    ← above the repository root
├── .claude/skills/            ← not loaded (put shared skills in ~/.claude/skills/)
└── repo/                      ← git repository root
    ├── .claude/skills/        ← loaded
    └── apps/web/              ← run claude here
        ├── .claude/skills/    ← loaded (used together with the root)
        └── src/
            └── .claude/skills/  ← not at start — loads when Claude first reads or edits a file in src/

repo/
├── .claude/skills/deploy/SKILL.md            → /deploy
└── apps/web/.claude/skills/deploy/SKILL.md   → /apps/web:deploy

运行 /skills 可以查看现在加载了哪些技能。上下级文件夹里技能很多时，最少用的技能的说明会最先被截断，所以要不时用 /skill-doctor 检查一下。

子智能体 — 把部分工作交出去

子智能体是拥有自己的上下文窗口、指令和工具的助手。把大规模的搜索或审查交给它：无论它读了多少文件，回到主对话的只有结果，主对话因此保持干净。

• .claude/agents/<名称>.md 用于项目（提交后与团队共享），~/.claude/agents/ 只给你自己用。只有 name 和 description 是必需的。
• 用 tools 限制它能使用的工具会更安全 — 让审查者只能读取。
• 可以这样调用：“用 code-reviewer 子智能体审查这次改动”，或者当 description 符合时，Claude 会自己把工作交给它。
• 要创建新的子智能体，可以请 Claude 帮你创建，或者自己在上面的文件夹里写文件。Explore、Plan 等内置子智能体一开始就有。

---
name: code-reviewer
description: Reviews code changes for bugs, security problems and missing tests. Use after writing or changing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a careful senior reviewer.
Run `git diff` to see the changes, then report:
1. Bugs (with file and line)
2. Security problems
3. Missing tests
Do not edit files.

钩子 — 在设定的时机必定运行的命令

CLAUDE.md 是一种请求，有时可能会被忘记，而钩子是 Claude Code 在设定的时机必定运行的 shell 命令。可以用钩子在编辑文件后运行格式化工具、挡住危险命令或对机密文件的编辑，以及在工作完成时收到通知。

• PreToolUse — 使用工具之前（可以阻止它），PostToolUse — 使用工具之后
• UserPromptSubmit — 你发送请求时，Stop — Claude 回答完毕时，SessionStart — 会话开始时，Notification — 需要你注意时
• matcher 选择钩子作用于哪些工具（比如 Edit|Write、Bash）。
• 如果钩子命令以退出码 2 结束，该操作会被阻止，写到 stderr 的原因会传给 Claude。
• /hooks 显示已设置的钩子。上面的例子会用 Prettier 整理每个被编辑的文件（需要 jq）。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

钩子以你的权限在你的电脑上运行。别人写的钩子，要先读懂它的命令再添加。

MCP — 连接外部工具

MCP（Model Context Protocol）是让 AI 工具使用外部服务（问题跟踪、数据库、浏览器、文档工具）的开放标准。添加一个 MCP 服务器后，Claude 就能使用该服务器提供的工具。

• claude mcp add --transport http <名称> <url> — 添加互联网上的远程服务器。
• claude mcp add <名称> -- <命令> — 添加在你电脑上运行的服务器（stdio）。-- 后面的所有内容都会原样传给服务器。
• 用 --scope project 添加时，它会保存在仓库顶层的 .mcp.json 里并与团队共享（第一次使用时会请求批准）。
• /mcp 显示连接状态并进行登录（OAuth）。claude mcp list 显示列表。

# A remote server (HTTP)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# A server that runs on your computer (stdio)
claude mcp add playwright -- npx @playwright/mcp@latest

# Share it with the team — saved in .mcp.json
claude mcp add --scope project playwright -- npx @playwright/mcp@latest

claude mcp list

只添加你信任的 MCP 服务器。获取外部文字的服务器，可能会把藏在文字里的指令带进来（提示注入）。

无界面运行 — 不用聊天界面的脚本

claude -p "…" 不打开聊天界面运行一次，输出结果后退出。可以把 Claude 当作积木，用在 shell 脚本、cron 和 CI 中。

• 通过管道传入输入（cat error.log | claude -p "…"）。
• --output-format json 以 JSON 给出结果、会话 id 和费用；stream-json 会逐行发送进度。
• --allowedTools 设置这次运行允许的工具，--max-turns 设置最多的轮数。
• claude -p --continue 继续上一次运行，--resume <会话 id> 继续那个会话。

# One question, one answer
claude -p "Explain what src/auth.ts does in 5 lines"

# Pipe input in
cat build-error.log | claude -p "Find the cause and suggest a fix"

# JSON output for scripts (result, session_id, total_cost_usd)
claude -p "List the TODO comments in src/" --output-format json

# Limit what it may do and how long it runs
claude -p "Run the tests and fix failures" \
  --allowedTools "Read,Edit,Bash(npm test *)" --max-turns 10

在脚本里，--bare 不读取 CLAUDE.md、钩子、插件和 MCP，启动很快（官方文档说它将成为 -p 的默认行为）。如果需要项目指令，就不要加它。

高级练习

1. 把一件常做的工作（发布说明、提交信息）做成 .claude/skills/ 里的技能，并用 /skill-name 调用。
2. 做一个只读的 code-reviewer 子智能体，让它审查你当前的改动。
3. 用 PostToolUse 钩子，让每次编辑文件时都运行格式化工具或 linter。
4. 添加一个 MCP 服务器，用 /mcp 检查连接。
5. 写一个用 claude -p 总结错误日志的单行 shell 脚本。

五项都做完了？进入 [大师] 标签。

官方文档

• Skills
• Subagents
• Hooks
• MCP
• Headless (-p)

已于 2026-10-19 对照官方文档核实。这些工具变化很快 — 如果命令不起作用，请查看官方文档。

Git worktree — 同时运行多个会话

两个会话在同一个文件夹里编辑同样的文件时，会互相覆盖。git worktree 会把同一个仓库以另一个分支检出到另一个文件夹，这样每个文件夹运行一个 Claude，就能同时推进多项工作。

• claude --worktree <名称>（-w）会在 .claude/worktrees/<名称>/ 创建 worktree 和分支并在那里启动。如果结束时没有任何改动，它会被自动删除。
• 把 .claude/worktrees/ 加入 .gitignore，并把 .env 这类被 Git 忽略的文件列在 .worktreeinclude 里，就能把它们复制到新的 worktree。
• 每个 worktree 可能都需要单独安装依赖（npm install 等）。
• 把工作拆成修改不同文件的独立任务，完成后通过 PR 合并。

# Claude Code makes the worktree for you (.claude/worktrees/<name>/)
claude --worktree feature-login
claude -w bugfix-cart

# Or with plain git
git worktree add ../myapp-search -b feature-search
cd ../myapp-search && claude

git worktree list
git worktree remove ../myapp-search

GitHub Actions — 在 issue 和 PR 里使用 @claude

安装 Claude Code GitHub Actions 后，只要在 issue 或 PR 评论里写 @claude，Claude 就会阅读仓库、修复问题并开一个 PR 或留下审查意见。它在 GitHub 的运行器上运行，所以你的电脑关机也没关系。

1. 在终端的 Claude Code 里运行 /install-github-app。它会引导你安装 GitHub 应用并添加密钥（ANTHROPIC_API_KEY 或用 claude setup-token 生成的令牌）— 需要 gh 和仓库的管理员权限。
2. 像上面那样的工作流文件会出现在 .github/workflows/ 里。
3. 在 issue 或 PR 里评论，比如“@claude 修复这个 bug”。
4. Claude 开的 PR，要由人审查并测试后再合并。

name: Claude
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Actions 里的 Claude 也会读取仓库的指令文件（AGENTS.md，或 CLAUDE.md）。让它遵守你的规则，最简单的方法就是写好指令文件。

插件和市场 — 打包并分享设置

插件把技能、子智能体、钩子和 MCP 服务器打包成一个。市场是一个带有插件列表的仓库。团队用一条命令安装同样的工具箱，并一起更新。

• /plugin — 查找、安装、启用和停用插件。
• 用 /plugin marketplace add <owner/repo> 添加市场，用 /plugin install <插件>@<市场> 安装。
• 插件文件夹的 .claude-plugin/ 里只放 plugin.json。skills/、agents/ 和 hooks/ 放在文件夹顶层。用 claude --plugin-dir ./my-plugin 测试。
• 如果只分享技能，用 npx skills add 也可以 — SONUB 技能就是这样分享的。

my-plugin/
├── .claude-plugin/
│   └── plugin.json        ← name, description, version
├── skills/
│   └── release-notes/SKILL.md
├── agents/
│   └── code-reviewer.md
├── hooks/
│   └── hooks.json
└── .mcp.json

/plugin marketplace add my-team/claude-plugins
/plugin install my-plugin@claude-plugins
/plugin

• 安装 SONUB 智能体技能

管理团队设置 — 让规则越积越多也依然清楚

当很多人和很多 AI 在一个仓库里工作时，设置会很快堆积起来。要决定哪些共享、哪些个人，哪些是请求、哪些是强制。

• 共享（提交）：AGENTS.md、.claude/settings.json、.claude/skills/、.claude/agents/、.mcp.json（如果使用 CLAUDE.md，还有每个文件夹的 CLAUDE.md）
• 个人（不提交）：.claude/settings.local.json、~/.claude/ — 个人指令放在 ~/.claude/CLAUDE.md（不要在项目里放 CLAUDE.local.md，因为它会让 AGENTS.md 不被读取）
• 指令文件保持简短。只有同样的错误反复出现时才加规则，错误的或不再有用的规则就删掉。
• 必须遵守的事，用权限（deny）和钩子来强制，而不是靠指令。
• 公司范围的规则通过托管设置下发 — 其他设置无法覆盖它们。

长任务 — 自己检查直到完成

大师会给 Claude 一个“完成的标准”，并让它自己检查这个标准。有了机器能判断的检查 — 测试、lint、构建 — 它就能在没人看着的情况下长时间工作。

• 用命令给出完成的标准 —“直到 npm test 和 npm run lint 都通过”。
• 让它把已完成和剩下的事写进 PROGRESS.md 这样的文件，这样即使上下文被总结或会话换了，也能接着做。
• 让它每完成一小步就提交，这样随时都能回退。
• 让它尝试三次失败后停下并写明原因，避免原地打转。
• 全部完成后，把交叉审查交给另一个 AI（比如 codex review）或子智能体。

• 目标和 Ralph Loop：让智能体一直做到真正完成
• VPS 和 tmux：让智能体一天 24 小时工作

大师练习 — 多个会话与自动化

1. 用 git worktree add ../my-project-b -b try-b 再建一个工作文件夹，在两个文件夹里各运行一个 claude，分别交给它们不同的小任务。两个文件夹的 git status 各自变化，就说明成功了。
2. 用 git diff | claude -p "List bugs in this diff" 做一条单行审查命令。故意放进一个 bug，看它能否找出来。
3. 把一条团队规则(例如：提交前先运行测试)写进 AGENTS.md，并用钩子强制执行。故意违反规则，确认钩子会拦下。
4. 按上面插件一节的做法，把你的一个技能和一个子代理打包成插件并安装，确认在另一个项目里也能加载。
5. 用命令写清完成标准(例如：npm test 通过)再交给它一个长任务；它说完成后，亲自检查 diff 和测试结果。

卡住时：用 git worktree list 查看 worktree，用 git worktree remove 删除。钩子拦得太多，就先从 settings.json 里暂时拿掉，再用 /hooks 确认。五项都做完了？用下面的检查清单自查。

大师检查清单

• 项目里只放 AGENTS.md — 所有 AI 按同一份指令工作（如果使用 CLAUDE.md，就在每个文件夹都放一个，只写一行 @AGENTS.md）
• 权限规则让安全的命令不用问就能运行，并用 deny 挡住机密文件
• 重复的工作交给技能，大规模搜索和审查交给子智能体
• 必须遵守的事用钩子强制执行
• 并行工作在 worktree 里进行；重复的工作用 claude -p 和 GitHub Actions 自动化
• 你用命令给出完成的标准，并亲自用 diff 和测试检查结果

工具变化很快。通过 claude-skill 技能里的 /claude-skill update 或官方更新日志（CHANGELOG）跟上新功能。

官方文档

• Worktrees
• GitHub Actions
• Plugins
• Settings

已于 2026-10-19 对照官方文档核实。这些工具变化很快 — 如果命令不起作用，请查看官方文档。