Claude Code日常开发完全指南

我在一次重构上白白耗了四十分钟，而 Claude 本可以四分钟就交付。差距并不在模型，而在模型周围的一切。普通用户输入提示词，接受第一个建议，把 Claude 当成包装精美的自动补全工具。而我把它作为一个可编程的 AI 智能体来运行：持久化记忆、自定义命令、跨 worktree 启动的并行会话，以及一个随着每周使用而不断完善的项目布局。本指南假设你已经在终端里输入过 claude，也见过接下来会发生什么。现在，我们要更进一步……

1. Claude Code：不止于基础用法

别再把 Claude Code 当作一个输入提示词后等待回复的聊天机器人。把它当成一个需要护栏的自主 AI 智能体，你的整个工作流都会随之改变。Boris Cherny 和 Anthropic 团队总结出的核心原则很简单：为 Claude 提供一种验证自身工作的方式。如果没有这个反馈闭环，你就是唯一的反馈信号。有了它，Claude 会持续迭代，直到代码真正运行起来。Boris 估计，仅这一项调整就能将质量提高 2～3 倍。

下面是几种会改变你日常工作方式的模式。

先探索，再规划，最后编码。按两次 Shift+Tab 进入只读的规划模式。让 Claude 阅读文件、追踪流程、梳理数据模型，然后让它给出一份计划，再执行。小修复可以跳过规划；一旦改动涉及多个文件，就应该使用规划模式。

把规划模式当作设计文档来用。让一个 Claude 编写计划，再在全新会话中启动第二个 Claude，请它以资深工程师的身份审查这份计划。由于没有上下文偏见，它才能真正发现疏漏。如果实现过程偏离了方向，就回到规划模式重新制定计划，并把验证步骤直接写进计划中。

引用，不要描述。不要说“看看认证模块”，直接输入 @src/auth/login.py。不要粘贴错误，而是通过 cat error.log | claude 将其传入。每一次，精确上下文都胜过近似描述。

委派，而不是结对编程。Claude Code 团队的 Cat Wu 说得很直白：“如果你把模型当作一名接受任务委派的工程师，而不是一名需要你逐行指导的结对程序员，模型的表现会最好。”预先写一份清晰简洁的任务说明，然后让它自行执行。

：按 Ctrl+G 可以在编辑器中打开 Claude 的计划，并在 Claude 继续之前对其进行修改。计划本质上只是文本，因此要在它变成代码之前把它打磨好。

：当 Claude 犯错时，在提示词末尾加上：“更新 CLAUDE.md，确保你不会重复这个错误。”Boris 说，Claude 能根据自己的失败为自己编写规则，而且“好得令人毛骨悚然”。需要特别指出的是，这一个习惯带来的复利效应比本指南中的任何其他做法都更强。

2. 正确认识 .claude 目录

大多数人打开 .claude/，看到 CLAUDE.md，然后就退出了。实际上，它的背后是一套分层配置系统。

两种作用域。项目作用域位于仓库内的 .claude/ 中，可以提交到版本库供团队共享。全局作用域位于 ~/.claude/ 中，会应用于你这台机器上的每个项目。

心智模型：项目文件描述项目，全局文件描述你。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

my-repo/
├── .claude/
│   ├── settings.json
│   ├── agents/
│   │   ├── pr-review.md
│   │   └── test-writer.md
│   ├── skills/
│   │   └── api-conventions/SKILL.md
│   └── rules/
│       ├── frontend.md        # path-gated to src/frontend/
│       └── migrations.md      # path-gated to db/migrations/
├── CLAUDE.md                  # checked in, team-shared
├── CLAUDE.local.md            # gitignored, personal
└── .mcp.json                  # team-shared MCP servers

CLAUDE.md 文件会逐级叠加。在 monorepo 中，当你处理 billing 服务时，root/CLAUDE.md 和 root/services/billing/CLAUDE.md 都会被加载。当不同目录的约定不一致时，这非常方便。

rules/*.md 会根据路径生效。仅适用于 migrations 目录的指导不应该通过 CLAUDE.md 塞进每个会话，而应该放进带有 glob 的 .claude/rules/migrations.md。

Skills 优于 commands。.claude/commands/*.md 和 .claude/skills/<name>/SKILL.md 都能注册斜杠命令，但 skills 可以携带支持文件、disable-model-invocation、允许使用的工具以及 AI 智能体覆盖配置。去年，我把仓库自动化中的一大部分做成了零散的 commands/*.md；后来需要支持文件时，不得不把它们全部迁移到 skills/。现在的新工作都放进 skills/。

：运行 claude project purge ~/path/to/repo --dry-run，可以准确查看 Claude 为某个项目保存了哪些本地状态。在把笔记本电脑交给别人之前，这非常有用。

3. Boris 编写 CLAUDE.md 的方式

CLAUDE.md 会在每次会话开始时加载。如果写错了，Claude 就会反复踩中同一把耙子；如果写对了，同样的提示词突然就能生成真正可以交付的成果。

Boris 在这里关注两件事。掌握这两点之后，其他内容基本都是噪声。我曾花了一个月编写越来越复杂的上下文文件，最后又回到了他的思路，而且从所有可衡量的指标来看，那些复杂版本的效果都更差……

保持简短。文件过长会淹没真正重要的规则。对于写下的每一行，都用 Boris 的标准进行筛选，问自己：“删除这一行会导致 Claude 犯错吗？”如果答案是否定的，就删掉。要果断。这个文件不是知识库，而是护栏。

让 Claude 为自己编写规则。每当 Claude 做错事情时，就告诉它：“更新 CLAUDE.md，确保你不会重复这个错误。”Claude 非常善于把自己的错误提炼成精确的规则。坚持几周后，这个文件就会变成一份经过筛选的清单，收录项目积累下来的每一个陷阱，并采用模型最容易响应的准确措辞。你不再需要猜测该往里面写什么，因为模型会告诉你。

3.1 Claude Code 团队真实使用的 CLAUDE.md

在一次演讲中，Boris 展示了 Claude Code 团队提交到自家仓库中的真实 CLAUDE.md。整个团队每周都会多次为它贡献内容。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 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 直接提交一条规则：

1
2

nit: use a string literal, not a ts enum
@claude add to CLAUDE.md to never use enums, always prefer literal unions

他把这种做法称为“复利工程”（Compounding Engineering）：每一次 PR 审查都会转化为对 CLAUDE.md 的改进。审查者只需发现一次错误，Claude 就永远不会再重复它。

下面是一份遵循相同理念、内容更完整的模板：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# 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 在真实 PR 中犯过的真实错误，并在错误发生的那一刻被记录下来。想象一下，当你意识到模型刚刚向一位法国用户交付了 USD 格式化功能时，那种心里一沉的感觉？把它写下来一次，它就永远不会再次发生。

不要把这些内容放进 CLAUDE.md：标准语言约定、逐个文件的代码库说明、长篇教程、API 文档，以及任何频繁变化的内容。

：IMPORTANT 或 YOU MUST 之类的词可以提高规则遵循度。谨慎使用，让它们保持足够的分量。

你可以使用 @path 语法导入其他文件，在保持 CLAUDE.md 简短的同时按需引入详细信息：

1
2

See @README.md for project overview and @package.json for scripts.
@~/.claude/my-preferences.md

文件虽短，收益巨大。务必保持精简。

3.2 值得研究的热门 CLAUDE.md 文件

向已经完成这项工作的人借鉴。下面四个是我经常回头参考的资源。

mattpocock/skills 的 CLAUDE.md：关于如何编写和测试 skills 的约定

anthropics/claude-code-action：Anthropic 自己的仓库，采用与内部工具相同的方式维护

awesome-claude-code：收录不同语言生态中数十个公开 CLAUDE.md 文件的链接

claudelog.com：按技术栈整理、由社区筛选的示例

读三个，然后开始编写你自己的文件。

4. 将 CLAUDE.local.md 用作日常主力配置

CLAUDE.local.md 与 CLAUDE.md 放在同一位置，以相同方式加载，但永远不会离开我的机器。它会被直接加入 .gitignore。

我是这样使用它的。每次 PR 之后，评审者都会留下评论。我不会试图把它们全记在脑子里，而是在读到评论的第一时间将其粘贴到 CLAUDE.local.md 中。几周下来，它就会变成一份针对我反复收到的具体反馈而量身定制的个人规则文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# 个人评审笔记（私有）

# 来自 PR 的反馈

- 新增 SQS 消费者时，必须在同一个 PR 中添加 DLQ 和告警
- 使用 `Optional<T>`，不要返回 null
- 新端点的测试必须包含身份验证失败的情况
- 返回类型包含 3 个以上字段时，优先使用命名元组而非普通字典

# 我自己需要纠正的习惯

- 不要再使用 `console.log`；改用项目日志记录器
- 添加端点时，始终同步更新 OpenAPI 规范

每个会话都会加载它。现在无需我提醒，Claude 就会加入身份验证失败测试并更新 OpenAPI 规范。不到两周，我的 PR 中吹毛求疵式的评论就减少了。

：将两个部分明确分开：项目特定的反馈和需要纠正的个人习惯。混在一起会让这个文件日后更难清理。

：几周后进行清理。任何已经形成肌肉记忆的内容都可以删除。这个文件应该记录仍在变化中的事项；已经能够自动完成的内容可以移除。

Skills 能让 Claude Code 从“什么都能做的智能体”变成“按照团队的方式，做好项目真正需要的三件具体事情的智能体”。它们是可复用专业能力的基本单元；只要写过一两个，你就会不断想要使用它们……

5.1 Skills 究竟是什么

上周二，我需要 Claude 每次都以相同方式总结尚未提交的 diff，于是便在 ~/.claude/skills/ 中放了一个文件夹，然后就没再管它。这个文件夹就是 skill。里面有一个携带 frontmatter 和指令的 SKILL.md，文件夹名称本身会成为你在提示符中输入的斜杠命令。项目级 skill 位于 .claude/skills/<name>/ 下，全局 skill 则位于 ~/.claude/skills/<name>/ 下。

下面是一个足以发挥实际作用的最小版本：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

---
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。

Skills 之所以强大，源于三个特性：

渐进式披露。会话开始时，Claude 只会读取 frontmatter 中的描述，每个大约占用 100 个 token。只有真正触发该 skill 时，才会加载完整的 SKILL.md 及所有辅助文件。

每个 skill 都有自己的独立文件夹，因此你可以在 SKILL.md 旁边放置一个 templates/ 目录，将参考文档保存在同一位置，并把脚本放在同一目录树中。SKILL.md 只是交给 Claude 的入口。

内联 shell。任何以 ! 开头的行都会在调用时执行命令，并将输出直接插入提示词。

frontmatter 本身还支持许多可选配置项：

1
2
3
4
5
6
7

---
name: my-skill
description: When to use this skill
disable-model-invocation: true # only runs when user explicitly types /my-skill
allowed-tools: Read, Grep, Bash
agent: read-only
---

：对于具有副作用的 skill，请使用 disable-model-invocation: true。你肯定希望 /ship 仅在显式输入时才执行部署，而不是 Claude 认为它相关时就自行运行。

设置一次，永远不必再操心。

5.2 编写一个真正的 Skill：Go API 约定

下面是一个面向 Go 服务团队的完整 skill。它包含团队约定、易踩的坑，以及搭建全新 HTTP 处理程序所需的脚手架。

1
2
3
4
5
6

.claude/skills/go-handler/
├── SKILL.md
├── templates/
│   └── handler.go.tmpl
└── examples/
    └── healthz.go

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

---
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` doesn't 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 值得安装的热门 Skills

mattpocock/skills 是最受欢迎的 skills 仓库，Star 数约为 10 万。我常驻加载其中几个：

/grill-me：在编写任何代码之前，就计划向你进行访谈式提问

/tdd：严格执行红—绿—重构流程

/diagnose：遵循严谨的调试流程——复现、最小化、提出假设、修复、回归测试

使用 npx skills@latest add mattpocock/skills 安装。

Jeffallan/claude-skills 提供了 66 个针对特定语言的配置，例如 go-pro、python-pro、java-architect、typescript-pro、rust-engineer、sql-pro 等。你可以将它们组合使用。Next.js 任务会同时引入 nextjs-developer 和 typescript-pro。

Anthropic 官方提供的 skills：

/code-review：由四个并行智能体审查 diff，只报告带有置信度评分的发现

/simplify：检查近期代码的复用程度和效率

/batch：将迁移任务分发给数十个并行智能体，每个智能体都隔离在独立的 worktree 中

/webapp-testing：赋予 Claude Playwright 控制能力，以测试你的本地 Web 应用

以前，我每周都要把同一个提示词写上三次，后来才终于意识到……

：如果一件事每天要做不止一次，就把它变成一个 skill。任何重复执行的事情，都是一个等待被编写出来的 skill。

：将 skills 提交到 git。它们会成为组织知识，新工程师克隆仓库后，无需额外成本就能获得团队积累下来的实践经验。

6. 构建自定义子智能体

启动一个子智能体，它就能处理 50 个文件而不会让主会话变得臃肿，最后再交回一份整洁的总结。隔离的上下文、限定范围的工具权限、独立的影响半径。我曾眼睁睁看着一次调试会话为了在 monorepo 中追踪导入关系而烧光上下文预算，从那以后便开始使用子智能体，现在更是默认优先使用它们。

若要限定在项目范围内，请将 Markdown 文件放入 .claude/agents/；若希望全局可用，则放入 ~/.claude/agents/。frontmatter 声明名称、描述、工具和模型。五行内容，就是一份完整契约。

6.1 逐步解析 /pr-review 智能体

上周五，我差点提交了一个缺少 null 检查的 PR，也正是在那时，我构建了这个智能体。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

---
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 from CLAUDE.md or rules/

## Do NOT flag

- Style preferences not in project rules
- Refactoring suggestions for working code
- Anything outside this diff

## Output

Group by severity (Critical / High / Medium / Low). File + line + issue + suggested fix.
End with a verdict: **SHIP**, **FIX FIRST**, or **REWORK**.

我会在会话中输入 Have the pr-review agent look at my current branch. 来触发它。子智能体会在隔离的上下文中完成工作，而我的主会话不会塞满评审过程中的各种讨论。

这里有几个选择值得特别说明。工具列表被刻意限制为只读，因为一旦评审者能够修改代码，它就会开始为自己的修复寻找理由，而不是把问题标出来。我选择 model: opus，因为赶在人工评审者之前发现安全漏洞，值得付出这部分成本。顺带一提，真正让输出变得可用的是“Do NOT flag”部分。如果没有它，我会被各种有关变量命名的吹毛求疵意见淹没。

十分钟就做好了。已经救了我两次。

6.2 值得抄作业的热门子智能体#

直接参考 Claude Code 团队自己的工作流，你会发现 build-validator、code-architect、code-simplifier、oncall-guide 和 verify-app 每天都在运行。

下面这些是社区经常使用的……

如果你想要精选合集，VoltAgent/awesome-claude-code-subagents 提供了 100 多个智能体，hesreallyhim/a-list-of-claude-code-agents 也整理了另一套可靠的集合。

：串联智能体：会话 A 完成实现，然后调用 Use the code-reviewer subagent to check the work.。审查器会在全新的上下文中进行评估，不受实现过程的偏见影响。

：增加隔离：在 frontmatter 中加入 worktree，让子智能体在自己的 git worktree 中运行。当你将一项迁移任务分派给数十个并行智能体时，这尤其强大。

今天就把这些模式拿走，明天你会疑惑自己以前没有它们究竟是怎么交付的。

7. 插件与市场#

插件把技能、钩子、子智能体和 MCP 服务器打包成一个可安装单元。运行 /plugin 打开市场浏览器。使用 /plugin marketplace add owner/repo 添加社区市场。

/code-review 会并行启动四个智能体。两个检查是否符合 CLAUDE.md，一个寻找 bug，另一个读取 git blame 以了解上下文。输出会附带置信度评分，信号始终清晰，噪声始终很低。

/feature-dev 是官方市场中安装量最高的技能。给它一份功能简述，就能得到可运行的代码。整个过程分为七个阶段：需求、探索、架构、实现、测试、审查和文档。

语言服务器插件会将符号级导航和编辑时诊断直接接入你的会话。团队一直将它列为你能安装的、杠杆效应最高的插件。

/security-guidance 是 Anthropic 的官方安全技能，能在问题进入交付环节之前将其暴露出来。

值得了解的插件类别（截至 2026 年年中，75 多个市场中共有 1,000 多个插件）：

Git 工作流、代码智能（LSP）、文档生成器、测试、浏览器自动化（Playwright）、设计系统（Figma）、可观测性（Sentry、Datadog）

：团队共享的 .mcp.json 配上几个精挑细选的插件，能让新工程师在克隆仓库后的几分钟内进入高效工作状态。把插件选择当作新人入职流程的一部分。

8. 未被充分利用的 Claude Code 命令#

大多数人学会 /clear、/compact 和 /init 后，就不再继续探索了。真正能提升生产力的功能藏在其余命令里，却几乎无人问津。

下面深入看看我每天都会使用的两个命令……

/compact 与 /clear：如果你要开始一项真正全新的任务，就使用 /clear，然后手动编写一份新的任务简述。如果下一个任务仍然依赖你刚完成的工作，就运行 /compact，并提示哪些内容应该保留下来。/compact 是由 LLM 对会话生成的有损摘要；/clear 则是你有意识地亲手编写任务简述。我把两者混淆了好几个星期，还一直疑惑为什么会话总在逐渐跑偏。理解这个区别之后，我的上下文可以连续数小时保持干净。

/rewind 会在每次提示时创建一个检查点，而且这些检查点会跨会话保留。因此，当 Claude 走上错误的路径时，要克制住输入“这没用，试试 X”的冲动。这样输入只会把失败的尝试埋进你的上下文，让模型不断被它绊倒。回退到犯错之前，再结合你观察失败过程后学到的信息重新发出提示。你的上下文窗口会感谢你。

：使用 ! 转义到 shell。!git status 或 !npm test 会立即运行，并将输出放入上下文。

：设置 CLAUDE_CODE_AUTO_COMPACT_WINDOW=400000。在 1M 模型上，上下文大约会在 30 万至 40 万个 token 时开始劣化，因此应强制提前压缩以保持敏锐。

扇出模式：先写出任务列表，然后遍历它。上个季度，我用这种方式迁移了大约两千个组件文件。生成列表，手动抽查其中三个，不断收紧提示词，直到这三个都能返回干净的结果，然后将它用于其余文件，自己去喝杯咖啡。

1
2
3
4
5

for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)" \
    --bare
done

8.1 /goal，内置的 Ralph 循环#

上周二，我输入了一行命令，合上笔记本电脑去吃晚饭，回来时已经有了一个全绿的 PR。/goal 会设定完成条件，Claude 将持续工作，直到该条件成立。每次尝试停止时，它都会根据会话记录进行检查。

1

/goal all tests in test/auth pass and the lint step is clean

1
2
3
4

/goal all integration tests in tests/api pass without flaking 3 runs in a row
/goal the OpenAPI spec validates and matches the actual response shapes
/goal docker compose up runs cleanly and the healthcheck endpoint returns 200
/goal coverage on src/billing/ is above 80% and all new tests are not placeholders

选择可验证且确定的目标。将它与测试命令、CLI 退出码或某种可通过 grep 检查的文件状态绑定起来。如果写的是“代码是好的”，那你已经输了……

适合搭配使用的功能：

/loop：按一定间隔重复执行，逐步清空积压任务

/schedule：按计划在云端定期运行

Stop 钩子：通过你自己的测试套件或 CI 端点设置关卡

Auto 模式：移除权限提示，防止长期目标因等待确认而停滞

：组合使用 /goal、Auto 模式和 /focus。写一份清晰明确的任务简述，设定目标，然后离开。回来时就能看到一个已经完成的 PR。这正是 Boris 和 Cat Wu 为 Opus 4.7 倡导的工作流。

9. 将 MCP 用作强力工具#

MCP（Model Context Protocol，模型上下文协议）是一条纽带，让 Claude Code 从编码智能体变成能感知整个系统的智能体。MCP 服务器通过标准契约向 Claude 暴露外部工具（数据库、设计画布、错误跟踪器、笔记等），使智能体可以像调用其他工具一样调用它们。

没有 MCP 时，Claude 读取文件并运行命令。有了 MCP，它就能读取你的 Linear 工单、查询 Postgres、调出 Figma 组件、获取实时 Sentry 堆栈跟踪，或者读取你的 Obsidian 仓库，而你全程无需离开终端。

工程工作中常用的 MCP：

本地服务器通过 stdio 通信，厂商托管的服务器则通过带有 O