# Claude Code 快速入门 (/docs/claude-code-quick-start)



## 术语表 [#术语表]

本文涉及的核心术语如下，建议先快速浏览，遇到陌生概念时随时回查。

| 术语                     | 中文     | 释义                                                |
| ---------------------- | ------ | ------------------------------------------------- |
| Prompt Engineering     | 提示词工程  | 通过优化输入文本来引导模型输出，关注"怎么说"                           |
| Context Engineering    | 上下文工程  | 管理模型可见的动态信息，关注"让模型看到什么"                           |
| Harness Engineering    | 驾驭工程   | 通过硬约束、反馈回路和自动验证来确保模型可靠运作                          |
| Context Rot            | 上下文腐烂  | 对话变长后模型遗忘早期约定、产生幻觉和偏离                             |
| Vibe Coding            | 氛围编程   | 过度依赖自然语言描述、跳过验证环节的开发模式                            |
| Verification Tax       | 验证税    | 为确保 AI 生成代码正确性而必须投入的自动化验证成本                       |
| Plan Mode              | 计划模式   | Agent 只输出变更计划而不执行，用于人工审核                          |
| Subagent               | 子智能体   | 在独立上下文中执行子任务的智能体，用于隔离噪音                           |
| Progressive Disclosure | 渐进式披露  | 按需加载详细文档，避免一次性注入过多信息                              |
| Lifecycle Hooks        | 生命周期钩子 | 在特定事件后自动触发的回调，执行确定性逻辑                             |
| `CLAUDE.md`            | —      | Claude Code 项目指令文件，定义构建命令、架构边界和禁止事项               |
| `AGENTS.md`            | —      | 通用 Agent 行为规范，被 Claude Code、Cursor、Windsurf 等广泛支持 |

> **配置路径参考**
>
> * **全局配置**（所有项目共享）：
>   * `CLAUDE.md` 放于 `~/.claude/CLAUDE.md`
>   * `AGENTS.md` 放于 `~/.agents/AGENTS.md`
> * **项目配置**：项目根目录存放 `CLAUDE.md` 或 `AGENTS.md`
>
> 两者同时存在时，项目级配置会与全局配置合并生效。

***

## 前言 [#前言]

在 AI 编程工具层出不穷的今天，选择一个 Coding Agent 不只是选一个聊天框——而是选择一套工程方法论。Claude Code 之所以值得关注，不在于它的模型参数更大或生成速度更快，而在于它代表了一种范式的跃迁：**从"怎么跟模型说话"进化到"怎么驾驭模型做事"**。

本文将从工程实践的角度，带你快速掌握 Claude Code 的核心概念和最佳实践。

***

## 一、AI 编程的范式演进 [#一ai-编程的范式演进]

AI 编程工具的认知层次经历了三次跃迁，每一次都从根本上改变了开发者与模型的协作方式。

**第一层：Prompt Engineering（提示词工程）**

这是大多数人接触 AI 编程的起点——关注的是"怎么说"。"你是一个资深全栈工程师，请帮我……"这类前缀就是典型的 Prompt Engineering。它的本质是单次、无状态的经验积累，天花板很低。

**第二层：Context Engineering（上下文工程）**

随着项目规模增大，你会发现问题不在"怎么说"，而在"让模型看到什么"。Context Engineering 的核心是管理动态信息，对抗 **Context Rot**——对话越长，模型越容易遗忘早期约定，产生幻觉和偏离。

ETH Zurich 在 2026 年 2 月的一项研究给出了一个反直觉的结论：**上下文配置文件（AGENTS.md 等）反而降低了任务成功率，同时让推理成本增加了 20% 以上**。即使是人类精心编写的上下文文件，也只带来约 4% 的改善，且效果不稳定——在某个模型版本上性能甚至下降了 2%。

这说明 Context Engineering 的挑战不在"塞入更多信息"，而在"只保留信号，剔除噪音"。

**第三层：Harness Engineering（驾驭工程）**

将模型视为一匹能力强大但需要约束的"马"，通过构建**硬约束（缰绳）、反馈回路（马鞍）和自动验证（护具）**，确保模型在真实工程环境中安全、可靠地运作。

Anthropic 的 Harness 设计实践给出了一个关键洞察：**将"做事的 Agent"和"评判的 Agent"分离**。让同一个模型既写代码又审查自己的代码，它倾向于自信地夸赞自己的工作——即使质量明显不行。但将外部评估者调教为"怀疑论者"，远比让生成者自我批判容易得多。

这个范式的核心转变在于：不再试图通过更好的提示词来消除模型的局限，而是构建一套工程系统来兜底。

***

## 二、Coding Agent 这么多，我应该选择哪个？ [#二coding-agent-这么多我应该选择哪个]

如今的 Coding Agent 市场百花齐放——Claude Code、OpenCode、Codex、Factory.ai Droid、AmpCode 等等，各有侧重。如果你拿不定主意，我的建议很简单：**直接选 Claude Code**。

理由只有一个：**生态第一**。工具本身的能力差距在缩小，但围绕它生长的社区、插件、最佳实践和文档决定了你能走多远。Claude Code 背后是 Anthropic 对 Harness Engineering 范式的完整实践——不通过硬编码逻辑去"猜"模型该做什么，而是提供工具（文件读写、终端执行、浏览器操作）、知识和权限边界，然后信任模型自主推理。这种 **"Trust the Model"** 的哲学，使其在处理复杂任务时比传统 Workflow 方案更具灵活性。

Factory.ai 的 Agent Readiness 评估从侧面验证了这一点：CockroachDB（四级成熟度，74%）对 Agent 友好，而 Express（二级，28%）虽然同样成功，Agent 在其中工作却困难得多。**代码库本身的工程纪律，远比工具选择更能决定 Agent 的产出质量。**

***

## 三、快速上手：三步建立工作流 [#三快速上手三步建立工作流]

Claude Code 不是浏览器里的聊天框，而是一个运行在本地的**Agent Process**。下面的三步工作流是日常使用的基本框架。

### 3.1 建立项目契约：`/init` [#31-建立项目契约init]

进入项目目录后，第一步是执行 `/init` 生成 `CLAUDE.md`。这个文件不是团队知识库，而是你与 Claude 之间的**协作契约**。

好的 `CLAUDE.md` 只包含模型凭自身无法推断的信息：

* **构建和测试命令**：`bun run build`、`bun test` 等，让 Agent 知道如何验证自己的工作
* **架构边界**：哪些模块可以互相依赖，哪些禁止耦合
* **绝对禁止事项（NEVER 列表）**："永远不要修改 `schema.prisma` 中的既有字段"
* **项目特有的约定**：如统一响应结构 `{ code, data, message }`、错误处理模式（统一抛出 `AppError`）

**应该删掉的**：目录结构（Agent 能看见）、技术栈（在 `package.json` 里）、编码风格（Linter 已强制）、通用最佳实践（"写干净的代码"——模型在互联网上早已学会）。

> **原则：失败了才加，不是觉得需要就加。**
>
> Jan-Niklas Wortmann 的修剪方法：从 80+ 行砍到 30 行"失败驱动"的指令后，行为显著改善。每条规则必须能回答四个问题：
>
> 1. **是否防止过实际错误？**——没有具体失败案例的规则删除
> 2. **工具能否替代？**——Linter 能做的事，不要写在 `CLAUDE.md` 里
> 3. **是否编码了非显然的决策？**——记录的是 trade-off，不是常识
> 4. **是否可触发？**——是可执行指令，不是抽象愿望
>
> 四个问题全不过，删掉。**从空文件开始，每次踩坑再加一条。**

> **常见误区：上下文污染（Context Poisoning）**
>
> 上下文不是越多越好。塞入的内容越多，并不等于 Agent 越了解你的项目——过大的上下文会让模型推理质量明显下降，表现为答非所问、抓不住重点。
>
> * **规则不是越多越好**：模型已知的编码规范不需要重复声明，写了反而浪费 token、稀释注意力
> * **避免单次会话过载**：不要一次性粘贴大段日志、配置、代码。担心新会话不了解项目而把所有事堆在一起，只会适得其反
> * **"被看见" ≠ "被用上"**：模型存在上下文召回率问题，放入的内容不一定都会被有效利用
> * 原则：**只写模型凭自身无法推断的项目特定知识**

### 3.2 先谋后动：Plan Mode [#32-先谋后动plan-mode]

在让 Agent 动手写代码之前，按 `Shift+Tab` 切换到 **Plan Mode**。Agent 不会执行任何操作，而是输出一份变更计划：

* 涉及哪些文件
* 每个文件的改动点
* 预期的 diff 效果

**最佳实践**：让人类（或另一个 AI 实例充当"高级工程师"角色）审核计划无误后，再切换回执行模式。修改 10 行代码总比重写 200 行代码高效。对于复杂重构或跨模块变更，这一步能显著减少因错误假设导致的无用功。

> **常见误区：误信"超级 IDE 插件"是银弹**
>
> super claude、superpowers、oh-my-opencode 等插件号称"一键扫仓库""自动改代码"，本质仍是"聊天 + 代码索引"，上限由模型本身、索引质量和提问方式共同决定。
>
> * 把插件当作**快捷入口和重复劳动加速器**，而不是替你做架构决策的上帝视角
> * 警惕部分插件的 Prompt Cache 污染：粗糙的实现会把时间戳、UUID 等动态信息塞进 System Prompt，导致缓存命中率接近 0——贵、慢、还啰嗦
> * 相比把希望寄托在"超级插件一口吃掉全仓库"上，**有意识地驱动内置的 plan → build 流程更可靠也更可控**

### 3.3 构建自动反馈循环：Build-Verify Loop [#33-构建自动反馈循环build-verify-loop]

Harness Engineering 得以运转的前提是为 Agent 提供充分的验证手段。LangChain 团队在优化 deepagents-cli 时发现，Agent 最常见的失败模式是：写完代码，重新读一遍，确认"看起来没问题"，然后停下——**从不实际运行测试**。

他们的解决方案是一个四阶段循环：

1. **Plan & Discover**：阅读任务，扫描代码库，制定包含验证策略的计划
2. **Build**：以可验证为目标实现功能，同时编写 happy path 和 edge case 测试
3. **Verify**：运行测试，读取完整输出，\*\*对照任务规格（而非代码本身）\*\*判断结果
4. **Fix**：分析错误，重新审视规格，解决问题

在此基础上，原则很简单：**成功应该是沉默的，失败才发出声音。**

通过配置生命周期 Hooks（如 `PostToolUse`），在 Agent 每次编辑代码后自动运行测试或 Linter：

* **测试通过**：Harness 保持静默，节省宝贵的上下文空间
* **测试失败**：只向上下文注入精炼的错误日志，驱动 Agent 自动进入修复循环

Tw93 在 Rust + Lua 混合项目中验证了这种做法的价值：按文件扩展名绑定不同的检查（`*.rs` → `cargo check`，`*.lua` → `luajit -b`），每次编辑后即时反馈，避免了"写了一堆才发现最初的错误"。每次编辑节省 30-60 秒，100 次编辑累积节省 1-2 小时。

验证手段的层次：

* **最底层**：退出码、Lint、类型检查、单元测试
* **中间层**：集成测试、截图对比、契约测试、冒烟测试
* **更高层**：生产日志验证、监控指标、人工审核清单

验证手段越完善，Agent 的自我修复闭环就越可靠。

***

## 四、进阶技巧：驾驭复杂系统 [#四进阶技巧驾驭复杂系统]

当项目规模变大、任务变复杂时，你需要掌握三项核心能力。

### 4.1 Skills：按需加载的方法论 [#41-skills按需加载的方法论]

Skill 的核心设计原则是：**描述"何时触发"，而非"能做什么"**。

一个好的 Skill 描述是路由条件，不是功能说明书。Tw93 的实验数据：描述中加入反例后，路由准确率从 53% 提升到 85%。一个约 9 token 的描述（"用于关注正确性的 PR 审查"）比约 45 token 的详细描述效果更好——省 token，且更精准。

Skill 体应该只包含导航和核心约束，大型参考材料放在支持文件中：

```
.claude/skills/
└── incident-triage/
    ├── SKILL.md          # 任务语义、边界、执行框架
    ├── runbook.md        # 领域细节
    ├── examples.md       # 案例
    └── scripts/
        └── collect-context.sh
```

**三种 Skill 类型**：

| 类型            | 用途                | 示例               |
| ------------- | ----------------- | ---------------- |
| Checklist     | 质量门，发布前逐项检查       | release-check    |
| Workflow      | 高风险操作的标准化流程，含回滚步骤 | config-migration |
| Domain Expert | 决策框架，引导固定证据收集路径   | incident-triage  |

**自动触发策略**：高频（每会话超过 1 次）保持自动触发并优化描述；低频（每会话低于 1 次）关闭自动触发，手动调用；极低频（低于 1 次/月）直接删除 Skill，移到 `AGENTS.md` 作为文档。

### 4.2 Subagents：上下文防火墙 [#42-subagents上下文防火墙]

主对话窗口的上下文空间是有限的。对于耗时的搜索、试错或大规模代码扫描任务，应该指派Subagent 在**独立上下文**中执行：

* Subagent 自主完成探索和调试
* 只返回高度压缩的结论给主 Agent
* 防止无关的调试细节污染主对话

Claude Code 内置三种Subagent：**Explore**（只读，默认 Haiku）、**Plan**（规划与研究）、**General-purpose**（通用）。关键约束：

* Subagent 的权限应**小于**主线程，否则隔离失去意义
* 设置 `maxTurns` 防止失控
* 需要文件修改时使用 `isolation: worktree` 隔离文件系统
* 输出格式必须结构化，否则主线程无法消费

> **模型分层策略**：探索阶段的 Subagent 使用 Haiku 等小模型——推理快、费用极低、可以多开并行。探索完成后，将精炼的高价值上下文交给 Opus 等大模型做深度推理。**不是小模型不行，而是用错了角色。**

### 4.3 自动化治理：对抗代码腐化 [#43-自动化治理对抗代码腐化]

AI 生成的代码如果不加治理，技术债会以指数级速度累积。两个关键手段：

**`/simplify` 命令**：任务完成后执行，要求 Agent 进行三维检查——代码复用性、质量、运行效率，清除 AI 生成残留物。

**定期"垃圾回收"**：让 Agent 扫描代码库是否违反架构约束，对违规处自动发起重构 PR，防止 AI 生成的"快捷方案"逐渐侵蚀系统架构。

Tw93 提出的六层治理模型值得参考：

| 层                            | 职责    | 核心问题           |
| ---------------------------- | ----- | -------------- |
| `CLAUDE.md` / rules / memory | 长期上下文 | "Agent 是什么"    |
| Tools / MCP                  | 行动能力  | "Agent 能做什么"   |
| Skills                       | 按需方法论 | "Agent 怎么做"    |
| Hooks                        | 强制行为  | 不依赖模型判断的硬约束    |
| Subagents                    | 上下文隔离 | 受控自主执行         |
| Verifiers                    | 验证闭环  | 让输出可验证、可回滚、可审计 |

***

## 五、Vibe Coding 的陷阱 [#五vibe-coding-的陷阱]

> **Vibe Coding**：用自然语言驱动开发，跳过验证环节。看起来快，实际埋雷。

### 生产力悖论 [#生产力悖论]

Faros AI 的遥测数据揭示了一个反直觉的规律——**个人越快，团队越慢**。

| 层面     | 指标              | 变化          |
| ------ | --------------- | ----------- |
| 个人产出 ↑ | 任务完成量 / PR 合并量  | +21% / +98% |
| 团队交付 ↓ | PR 审查时间 / Bug 率 | +91% / +9%  |
| 系统级 ↓  | PR 规模（认知过载的根源）  | 膨胀 154%     |

Google DORA 2025 报告进一步确认：AI 采用率每增加 25%，交付稳定性预计下降 **7.2%**。更值得警惕的是，2024 年 AI 与吞吐量、有价值工作时间的关系还是**负相关**，到 2025 年才逆转为正——**唯独稳定性从未改善，持续恶化**。

DORA 的作者直言：**"稳定性，而非速度，才是软件交付成功的定义性指标。"**

### 技术债的自我复制 [#技术债的自我复制]

传统开发中，技术债是**线性累积**的。AI 协作模式下，它变成了**病毒式传播**：

> AI Agent 看到代码库中的糟糕模式（硬编码、绕过 Service 层），会把它当成"合法先例"，**系统性地复用到每个角落**。

如果不定期清理，AI 生成的低质代码（**"AI Slop"**）会迅速侵蚀架构，导致系统不可维护。

### 真实事故 [#真实事故]

| 项目              | 经过                      | 后果                          |
| --------------- | ----------------------- | --------------------------- |
| **Moltbook**    | 完全 Vibe Coding，未配置安全默认值 | **150 万** API 密钥泄露          |
| **Replit**      | AI Agent 忽略指令，自主操作数据库   | 删除 **1200+** 条生产记录     |
| **Gemini CLI**  | 整理文件时"追逐幻觉"             | 误删用户真实文件                    |
| **Amazon Kiro** | AI 自主"修复"配置，重建错误环境      | **13h** + **6h** 宕机，数百万订单损失 |

### 根本解法：缴纳 Verification Tax [#根本解法缴纳-verification-tax]

幻觉无法通过优化提示词消除，只能用**硬性防御**兜底：

1. **自动化验证器**：测试 + 类型检查 + Linter → 不通过不合入
2. **强类型系统**：编译器约束行为，而非依赖注释
3. **架构约束 Linter**：用规则守护边界，而非口头约定

Tw93 的总结精辟：**"明确标成不可信输入"**——将外部内容显式标记为不可信来源，在写入操作前要求明确确认，在关键路径上引入独立 LLM 验证。

> 人类的价值不在于写更多代码，而在于定义\*\*"什么是做对了"\*\*。

***

## 六、Claude Code 的架构内幕 [#六claude-code-的架构内幕]

理解 Claude Code 的内部机制，有助于更高效地使用它。

### Prompt Caching：核心性能杠杆 [#prompt-caching核心性能杠杆]

Claude Code 的整个架构围绕 Prompt Caching 构建。缓存的匹配方式是**前缀匹配**——从请求开始到每个 `cache_control` 断点之间的内容被缓存。高缓存命中率不仅省钱，还放宽速率限制。Anthropic 甚至对低命中率发出 SEV 级别告警。

**缓存友好的顺序**：

1. System Prompt（静态，锁定）
2. Tool Definitions（静态，锁定）
3. Chat History（动态，在后）
4. Current User Input（最后）

**常见缓存破坏者**：在 System Prompt 中放入时间戳、非确定性地打乱工具定义顺序、会话中途增减工具。动态信息（如当前时间）应注入到用户消息中，而非 System Prompt。Claude Code 自身就是这样做的——用 `<system-reminder>` 标签将动态信息注入用户消息，保持 System Prompt 不变。

**不要中途切换模型**：Prompt Cache 与模型绑定。如果已经用 Opus 积累了 100K token 的对话，切换 Haiku 回答一个简单问题，**实际比继续用 Opus 更贵**——因为 Haiku 需要重建全部缓存。

### defer\_loading：工具发现的优化 [#defer_loading工具发现的优化]

Claude Code 有几十个 MCP 工具。全量包含在每次请求中会很昂贵，但中途移除工具会破坏缓存。解决方案：发送只含工具名的轻量 stub，标记 `defer_loading: true`。模型通过 ToolSearch 发现工具，完整 schema 仅在选中后才加载。缓存前缀保持稳定。

### Compaction 机制 [#compaction-机制]

当上下文接近上限时，Claude Code fork 一个调用，将完整对话历史发送给模型要求"总结这段对话"。由于此步骤命中缓存，成本仅为正常价格的 1/10。压缩后，几十轮对话被 \~20K token 的摘要替代。System Prompt + Tools 保持不变，文件引用重新附加，空间释放给新一轮对话。

**关键陷阱**：默认压缩算法倾向于删除早期的工具输出和文件内容——同时也会丢失**架构决策和约束理由**。两个小时后，模型可能不记得早期的决策，导致难以解释的 bug。

解决方案：在 `CLAUDE.md` 中显式指定 Compact Instructions：

1. 架构决策（绝不总结）
2. 已修改文件及关键变更
3. 当前验证状态（pass/fail）
4. 未完成的 TODO 和回滚记录
5. 工具输出（可删除，仅保留 pass/fail）

### 主动替代方案：HANDOFF.md [#主动替代方案handoffmd]

比依赖压缩算法更可靠的做法是：在开始新会话前，让 Claude 写一份 `HANDOFF.md`，记录当前进度、尝试过什么、什么有效、什么走不通、下一步做什么。新会话的 Claude 只读这个文件即可接续——不受压缩算法质量影响。

***

## 七、参考资源 [#七参考资源]

* Claude Code 使用经验 & 进阶学习
  * [我的 Claude Code 使用小记 | 笔记 / AI | 余弦の博客](https://blog.cosine.ren/post/my-claude-code-record)
  * [我的 Claude Code 使用小记 2 | 笔记 / AI | 余弦の博客](https://blog.cosine.ren/post/my-claude-code-record-2/)
  * [你不知道的 Claude Code：架构、治理与工程实践 - Tw93](https://tw93.fun/2026-03-12/claude.html)
  * [你不知道的 Agent：原理、架构与工程实践 - Tw93](https://tw93.fun/2026-03-21/agent.html)
  * [Learn Claude Code](https://learn.shareai.run/en/)
  * [GitHub - shareAI-lab/learn-claude-code](https://github.com/shareAI-lab/learn-claude-code)
* Harness Engineering
  * [Introducing Agent Readiness | Factory.ai](https://factory.ai/news/agent-readiness)
  * [Harness design for long-running application development | Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)
  * [工程技术：在智能体优先的世界中利用 Codex | OpenAI](https://openai.com/zh-Hans-CN/index/harness-engineering/)
  * [Improving Deep Agents with harness engineering](https://blog.langchain.com/improving-deep-agents-with-harness-engineering/)
* DORA 报告
  * [DORA 2025: Measuring Software Delivery After AI – Alt + E S V](https://redmonk.com/rstephens/2025/12/18/dora2025/)
  * [DORA Report 2024 – A Look at Throughput and Stability – Alt + E S V](https://redmonk.com/rstephens/2024/11/26/dora2024/)
* 上下文管理
  * [Your agent's context is a junk drawer | Augment Blog](https://www.augmentcode.com/blog/your-agents-context-is-a-junk-drawer)