Claude Code 快速入门

术语表

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

前言

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

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

一、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 市场百花齐放——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

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

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

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

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

3.2 先谋后动：Plan Mode

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

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

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

3.3 构建自动反馈循环：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：按需加载的方法论

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 类型：

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

4.2 Subagents：上下文防火墙

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

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

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

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

4.3 自动化治理：对抗代码腐化

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

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

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

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

五、Vibe Coding 的陷阱

生产力悖论

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

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

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

技术债的自我复制

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

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

真实事故

根本解法：缴纳 Verification Tax

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

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

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

六、Claude Code 的架构内幕

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

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：工具发现的优化

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

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

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

七、参考资源

• Claude Code 使用经验 & 进阶学习
  • 我的 Claude Code 使用小记 | 笔记 / AI | 余弦の博客
  • 我的 Claude Code 使用小记 2 | 笔记 / AI | 余弦の博客
  • 你不知道的 Claude Code：架构、治理与工程实践 - Tw93
  • 你不知道的 Agent：原理、架构与工程实践 - Tw93
  • Learn Claude Code
  • GitHub - shareAI-lab/learn-claude-code
• Harness Engineering
  • Introducing Agent Readiness | Factory.ai
  • Harness design for long-running application development | Anthropic
  • 工程技术：在智能体优先的世界中利用 Codex | OpenAI
  • Improving Deep Agents with harness engineering
• DORA 报告
  • DORA 2025: Measuring Software Delivery After AI – Alt + E S V
  • DORA Report 2024 – A Look at Throughput and Stability – Alt + E S V
• 上下文管理
  • Your agent's context is a junk drawer | Augment Blog