Claude Code 作为日常主力工具：Claude.md、Skills、Subagents、Plugins 和 MCPs

# 超越提示词：Claude Code 使用进阶 来源：https://arps18.github.io/posts/claude-code-mastery/ Claude Code 这类工具，普通用户和深度内化它的人之间差距巨大。普通用户只是输入提示词、接受建议，把它当作更高级的自动补全。而日常驱动它的人则把它当作可编程的智能代理，拥有记忆、自定义命令、并行会话和会不断累积的项目配置。本指南写给第二种人，假设你已经知道在终端输入 `claude` 时会发生什么。 --- ## 1. Claude Code 超越基础 一旦你不再把 Claude Code 看作提示-等待式聊天机器人，而是当作一个需要护栏的自主代理，你的工作流就会转变。来自 Boris Cherny 和 Anthropic 团队的最重要原则是：**给 Claude 一种验证自己工作的方法**。没有这一点，你就是唯一的反馈循环。有了它，Claude 会不断迭代直到事情真正起效，Boris 说仅此一项就能带来 2-3 倍的质量提升。以下是一些改变日常操作的模式： **探索，然后规划，然后编码。** 计划模式（按两次 `Shift+Tab`）让 Claude 进入只读探索状态。读取文件、追踪流程、理解数据模型。然后获得计划。然后执行。对于小的修复可以跳过计划；但任何涉及多个文件的事情都使用它。 **把计划模式当作设计文档使用。** 让一个 Claude 编写计划，然后启动第二个 Claude 在一个全新会话中，以资深工程师的身份审查计划，没有上下文偏差，这样它就能真正发现漏洞。如果实现偏离轨道，回到计划模式重新规划，并包含验证步骤。 **引用，而不是描述。** 不要用“看看认证模块”，而是输入 `@src/auth/login.py`。不要粘贴错误，而是通过管道传递：`cat error.log | claude`。精确的上下文每次都胜过模糊的描述。 **委托，而不是结对编程。** Cat Wu（Claude Code 团队成员）：“如果你把模型当作你在委托工作的工程师，而不是逐行指导的结对编程伙伴，模型的表现最好。” 先写一个清晰的简要说明，然后让它运行。 > **提示：** 按 `Ctrl+G` 在编辑器中打开 Claude 的计划，在 Claude 继续之前调整它。计划只是文本，所以在它变成代码之前塑造它。 > **提示：** 当 Claude 犯错时，在提示词末尾加上“更新 CLAUDE.md，这样你就不会重复这个错误。” Boris 称 Claude “从自己的失败中为自己编写规则方面出奇地擅长”。这个习惯比本指南中的任何其他习惯积累得更多。 --- ## 2. 正确理解 .claude 目录 多数人打开 `.claude/` 一次，看到 `CLAUDE.md`，就不再深入了。实际上它是一个分层配置系统。两个作用域：**项目作用域**位于你仓库中的 `.claude/` 内，提交到 git 以便你的团队共享。**全局作用域**位于 `~/.claude/`，适用于你机器上的每个项目。心智模型：项目文件描述项目，全局文件描述你。 | 文件 | 作用域 | 提交 | 作用 | |------|--------|------|------| | `CLAUDE.md` | 项目和全局 | 是 | 每个会话加载的指令 | | `CLAUDE.local.md` | 仅项目 | 否，gitignore | 你的私有项目笔记 | | `settings.json` | 项目和全局 | 是 | 权限、钩子、环境变量、模型默认值 | | `settings.local.json` | 仅项目 | 否 | 个人覆盖，自动 gitignore | | `.mcp.json` | 仅项目 | 是 | 团队共享的 MCP 服务器 | | `skills//SKILL.md` | 项目和全局 | 是 | 通过 `/name` 调用的可复用提示词 | | `commands/*.md` | 项目和全局 | 是 | 单文件斜杠命令 | | `agents/*.md` | 项目和全局 | 是 | 子代理定义 | | `rules/*.md` | 项目和全局 | 是 | 按主题范围划分的指令，可选路径限制 | 一个典型的布局： ``` my-repo/ ├── .claude/ │ ├── settings.json │ ├── agents/ │ │ ├── pr-review.md │ │ └── test-writer.md │ ├── skills/ │ │ └── api-conventions/SKILL.md │ └── rules/ │ ├── frontend.md # 路径限制到 src/frontend/ │ └── migrations.md # 路径限制到 db/migrations/ ├── CLAUDE.md # 已提交，团队共享 ├── CLAUDE.local.md # gitignored，个人 └── .mcp.json # 团队共享的 MCP 服务器 ``` 容易漏掉的几点： `CLAUDE.md` **文件会级联。** 在单体仓库中，当你在账单服务中工作时，`root/CLAUDE.md` 和 `root/services/billing/CLAUDE.md` 都会加载。对于每个文件夹有不同约定的代码库非常强大。 `rules/*.md` **是路径限制的。** 针对 migrations 文件夹的指导不应属于 `CLAUDE.md` 使每个会话膨胀；它应该放在带有 glob 的 `.claude/rules/migrations.md` 中。 **技能优先于命令。** `.claude/commands/*.md` 和 `.claude/skills//SKILL.md` 都会创建斜杠命令，但技能支持辅助文件、`disable-model-invocation`、允许的工具和代理覆盖。新的工作应放在 `skills/` 中。 > **提示：** 运行 `claude project purge ~/path/to/repo --dry-run` 查看 Claude 为一个项目保存的确切本地状态，在交接笔记本之前很方便。 --- ## 3. Boris 编写 CLAUDE.md 的方式 `CLAUDE.md` 在每个会话开始时加载。写错了 Claude 会重复同样的错误。写对了，同一个提示词会产生明显更好的输出。Boris 直接指出了两件比其他更重要的事情： **保持简短。** 长的文件会埋没重要规则。对于每一行，问：“删除这一行会导致 Claude 犯错吗？” 如果不是，就删掉。 **让 Claude 为自己编写规则。** 每当 Claude 做了错事，告诉它：“更新 CLAUDE.md，这样你就不会重复这个错误。” Claude 非常擅长从自己的错误中提炼出精确的规则。这样坚持几周，文件就会成为你项目每个陷阱的精选列表。 ### 3.1 Claude Code 团队真实的 CLAUDE.md Boris 分享了 Claude Code 团队检入自己仓库的真实 `CLAUDE.md`。整个团队每周贡献多次： ``` # Development Workflow **Always use `bun`, not `npm`.** # 1. Make changes # 2. Typecheck (fast) bun run typecheck # 3. Run tests bun run test -- -t "test name" # Single suite bun run test:file -- "glob" # Specific files # 4. Lint before committing bun run lint:file -- "file1.ts" bun run lint # 5. Before creating PR bun run lint:claude && bun run test ``` 这就是整个文件。Claude 无法猜测的构建命令、执行的确切顺序、单测试调用、PR 前仪式。没有样式偏好。没有代码库导览。没有陈词滥调。 Boris 还在 PR 评论中使用 `@claude` 让 Claude 直接提交规则： ``` nit: use a string literal, not a ts enum @claude add to CLAUDE.md to never use enums, always prefer literal unions ``` 他称之为“累积式工程”，每次 PR 审查都成为 CLAUDE.md 的改进。 一个遵循相同哲学的完整模板： ``` # Code style - Use ES modules (import/export), not CommonJS (require) # Workflow - Always use `bun`, not `npm` - Run `bun run typecheck` before claiming done - Never push to main directly. Always open a PR. # Architecture - All API routes go through src/api/middleware/auth.ts - New database queries go in src/db/queries/. No inline raw SQL. # Gotchas - `User` and `UserRecord` are distinct types. UserRecord is the DB row, User is the runtime object. - `formatCurrency` assumes USD. For international use `formatCurrencyByLocale`. ``` “Gotchas”部分是魔法。每一项都是 Claude 犯过的错误，在发生时捕获。 **`CLAUDE.md` 中不该放的东西：** 标准语言约定、逐个文件的代码库描述、长教程、API 文档、任何经常变化的东西。 > **提示：** 像 `IMPORTANT` 或 `YOU MUST` 这样的词可以提高依从性。少用它们，这样它们才有分量。你可以使用 `@path` 语法导入其他文件以保持 `CLAUDE.md` 简短，同时引入详细信息： > ``` > See @README.md for project overview and @package.json for scripts. > @~/.claude/my-preferences.md > ``` ### 3.2 值得研究的流行 CLAUDE.md 文件 - **mattpocock/skills CLAUDE.md（https://github.com/mattpocock/skills/blob/main/CLAUDE.md）**：技能编写和测试的约定 - **anthropics/claude-code-action（https://github.com/anthropics/claude-code-action）**：Anthropic 自己的仓库，与内部工具待遇相同 - **awesome-claude-code（https://github.com/hesreallyhim/awesome-claude-code）**：链接到数十个跨语言生态的公开 `CLAUDE.md` 文件 - **claudelog.com（https://claudelog.com/）**：社区策划的按技术栈组织的示例 --- ## 4. 把 CLAUDE.local.md 当作日常驱动 `CLAUDE.local.md` 与 `CLAUDE.md` 并存，同样加载，但从不离开你的机器。将其加入 `.gitignore`。我的使用方式：每次我提交 PR 后，审查者都会留下评论。与其试图记住它们，我在看到它们的那一刻就把它们倒入 `CLAUDE.local.md`。随着时间的推移，它成为针对我最常收到的反馈的个性化规则文件。 ``` # Personal review notes (private) # From PR feedback - New SQS consumers need a DLQ and alarms in the same PR - Use `Optional` over null returns - Tests for new endpoints must include the auth-failure case - Prefer named tuples over plain dicts for return types with 3+ fields # My own quirks to correct - Stop using `console.log`; use the project logger instead - Always update the OpenAPI spec when adding endpoints ``` 每次会话加载，Claude 已经知道要包含认证失败的测试和更新 OpenAPI 规范，无需我提及。几周内，我 PR 上的吹毛求疵评论明显减少了。 > **提示：** 清晰地将两个部分分开：项目特定的反馈和个人习惯纠正。混在一起会使文件以后更难修剪。 > **提示：** 几周后修剪。已经变成肌肉记忆的东西可以去掉。文件应该捕获仍在学习的东西，而不是你已经自动做的事情。 --- ## 5. 深度技能 技能让 Claude Code 从“一个什么都能做的代理”变成“一个对你的项目特别擅长做特定事情的代理”。它们是可复用专业知识的单元。 ### 5.1 技能究竟是什么 技能是 `.claude/skills/<skill-name>/`（项目）或 `~/.claude/skills/<skill-name>/`（全局）下的一个文件夹，包含带有前置数据和指令的 `SKILL.md`。文件夹名称就是斜杠命令。最简单的技能： ``` --- description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff. --- ## Current changes !`git diff HEAD` ## Instructions Summarize the changes in two or three bullet points, then list any risks: missing error handling, hardcoded values, tests that need updating. ``` 保存到 `~/.claude/skills/summarize-changes/SKILL.md`，`/summarize-changes` 就在每个会话中可用。 **使技能强大的三件事：** - **渐进式展示**。Claude 在会话开始时只加载前置数据描述（每个约 100 个 token）。完整的 `SKILL.md` 和辅助文件仅在技能实际需要时加载。 - **技能是文件夹，不是文件**。可以捆绑模板、参考文档、脚本、配置。`SKILL.md` 只是入口点。 - **内联 Shell**。以 `!` 开头的行运行一个命令并将输出注入到调用时。 前置数据支持有用的额外字段： ``` --- name: my-skill description: When to use this skill disable-model-invocation: true allowed-tools: Read, Grep, Bash agent: read-only --- ``` > **提示：** 对有副作用的技能使用 `disable-model-invocation: true`。你希望 `/ship` 只在明确输入时部署，而不是当 Claude 决定它相关时。 ### 5.2 编写一个真实技能：Go API 约定 一个用于 Go 服务团队的完整技能，涵盖约定、陷阱和新的 HTTP 处理程序脚手架： ``` .claude/skills/go-handler/ ├── SKILL.md ├── templates/ │ └── handler.go.tmpl └── examples/ └── healthz.go ``` ``` --- description: Scaffolds a new HTTP handler in our Go service following team conventions for routing, validation, error handling, and tests. Use when the user asks to add a new endpoint, a new handler, or extend an existing route group. --- # Go HTTP Handler Skill ## Stack - Go 1.22 with chi router - sqlc for typed queries, never write raw SQL strings in handlers - zap for structured logging, never fmt.Println - testify for assertions, table-driven tests preferred ## Gotchas - `chi.URLParam` returns `""` for missing params, not an error. Always check. - Our `httperr.Wrap` does not log. Log separately with `h.log.Error` before returning. - Auth middleware injects via `context.Value(authkey.User)`. Type-assert to `*models.User`. - sqlc nullable strings use `pgtype.Text`. Check `.Valid` before calling `.String`. - Tests must use `httptest.NewRecorder` and `httptest.NewRequest`. No real server. ``` 这样一个技能让新开发者无需先阅读整个代码库就能编写完全符合约定的端点。 ### 5.3 值得安装的流行技能 **mattpocock/skills（https://github.com/mattpocock/skills）**，最流行的技能仓库（约 100k 星）。亮点： - `/grill-me`：在编写任何代码之前就你的计划进行访谈 - `/tdd`：严格执行红-绿-重构 - `/diagnose`：规范化的调试：复现、最小化、假设、修复、回归测试 安装：`npx skills@latest add mattpocock/skills` **Jeffallan/claude-skills（https://github.com/Jeffallan/claude-skills）** 提供了 66 个语言特定的配置文件：`go-pro`、`python-pro`、`java-architect`、`typescript-pro`、`rust-engineer`、`sql-pro` 等。可以组合使用；一个 Next.js 任务会同时引入 `nextjs-developer` 和 `typescript-pro`。 **Anthropic 官方技能：** - `/code-review`：四个并行代理审查差异，仅返回置信度打分的结果 - `/simplify`：审查最近的代码以寻找复用和效率改进 - `/batch`：将迁移扩展到数十个并行代理，每个在自己的工作树中 - `/webapp-testing`：让 Claude 使用 Playwright 控制来测试你的本地 Web 应用 > **提示：** 如果你一天做某事超过一次，就把它变成技能。任何你重复的事情都是一个等待编写的技能。 > **提示：** 把技能检入 git。它们成为机构知识，新工程师克隆仓库后就免费获得了团队积累的实践。 --- ## 6. 构建自定义子代理 子代理在自己的上下文窗口中运行，拥有自己的工具权限，并返回摘要。它可以读取五十个文件而不填满你的主会话。这就是全部价值主张。子代理是一个位于 `.claude/agents/`（项目）或 `~/.claude/agents/`（全局）下的 markdown 文件，包含声明名称、描述、工具和模型的前置数据块。 ### 6.1 逐步解析 /pr-review 代理 ``` --- name: pr-review description: Reviews the current branch diff against main, looking for bugs, security issues, missed edge cases, and project-convention violations. Use proactively before opening a PR. tools: Read, Grep, Glob, Bash model: opus --- You are a senior staff engineer reviewing a pull request. Thorough, direct, goal is to catch issues before human reviewers do. ## Process 1. Run `git diff main...HEAD` 2. Run `git log main..HEAD --oneline` 3. Read full files, not just diff context 4. Cross-check against CLAUDE.md, CLAUDE.local.md, and .claude/rules/ ## Flag - Correctness bugs: off-by-one, null handling, error paths, race conditions - Security: injection risks, missing auth checks, secrets in code - Missing tests for new logic - N+1 queries - Convention violations ...（后续内容被截断，但根据原文继续翻译） **提示：** 子代理在处理大型代码库时尤其有效。与其让主会话读取 30 个文件，不如将一个子代理指向一个目录，然后只取回摘要。 **命令模式注意事项：** 当在提示词中触发子代理时，使用 `@agent pr-review`。子代理运行完成后的输出会注入到当前会话中。 **真实世界例子：** 团队使用 `/batch` 技能将迁移任务分发给 15 个子代理，每个处理不同的子目录。子代理在 git 工作树中独立工作，完成后合并。整个过程比手动操作快一个数量级。 --- ## 总结 Claude Code 的真正力量不在于提示词工程，而在于系统化使用：建立正确的目录结构、编写简洁的 CLAUDE.md、利用技能和子代理创建可复用组件。按照 Boris 的建议，让 Claude 从自己的错误中学习，并将每次 PR 审查转化为规则更新。几周后，这些习惯会累积成一个为你工作的团队。不仅仅是自动补全——而是一个自主编程伙伴，了解你的项目、你的团队和你的个人偏好。