--- title: Claude Code 快速入门 description: 从 Prompt Engineering 到 Harness Engineering：如何驾驭 AI 编程 Agent --- ## 术语表 本文涉及的核心术语如下，建议先快速浏览，遇到陌生概念时随时回查。 | 术语 | 中文 | 释义 | | --- | --- | --- | | 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 编程工具的认知层次经历了三次跃迁，每一次都从根本上改变了开发者与模型的协作方式。 **第一层：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 已强制）、通用最佳实践（"写干净的代码"——模型在互联网上早已学会）。 > **原则：失败了才加，不是觉得需要就加。** > > Jan-Niklas Wortmann 的修剪方法：从 80+ 行砍到 30 行"失败驱动"的指令后，行为显著改善。每条规则必须能回答四个问题： > > 1. **是否防止过实际错误？**——没有具体失败案例的规则删除 > 2. **工具能否替代？**——Linter 能做的事，不要写在 `CLAUDE.md` 里 > 3. **是否编码了非显然的决策？**——记录的是 trade-off，不是常识 > 4. **是否可触发？**——是可执行指令，不是抽象愿望 > > 四个问题全不过，删掉。**从空文件开始，每次踩坑再加一条。** > **常见误区：上下文污染（Context Poisoning）** > > 上下文不是越多越好。塞入的内容越多，并不等于 Agent 越了解你的项目——过大的上下文会让模型推理质量明显下降，表现为答非所问、抓不住重点。 > > - **规则不是越多越好**：模型已知的编码规范不需要重复声明，写了反而浪费 token、稀释注意力 > - **避免单次会话过载**：不要一次性粘贴大段日志、配置、代码。担心新会话不了解项目而把所有事堆在一起，只会适得其反 > - **"被看见" ≠ "被用上"**：模型存在上下文召回率问题，放入的内容不一定都会被有效利用 > - 原则：**只写模型凭自身无法推断的项目特定知识** ### 3.2 先谋后动：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 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 类型**： | 类型 | 用途 | 示例 | | --- | --- | --- | | Checklist | 质量门，发布前逐项检查 | release-check | | Workflow | 高风险操作的标准化流程，含回滚步骤 | config-migration | | Domain Expert | 决策框架，引导固定证据收集路径 | incident-triage | **自动触发策略**：高频（每会话超过 1 次）保持自动触发并优化描述；低频（每会话低于 1 次）关闭自动触发，手动调用；极低频（低于 1 次/月）直接删除 Skill，移到 `AGENTS.md` 作为文档。 ### 4.2 Subagents：上下文防火墙 主对话窗口的上下文空间是有限的。对于耗时的搜索、试错或大规模代码扫描任务，应该指派Subagent 在**独立上下文**中执行： - Subagent 自主完成探索和调试 - 只返回高度压缩的结论给主 Agent - 防止无关的调试细节污染主对话 Claude Code 内置三种Subagent：**Explore**（只读，默认 Haiku）、**Plan**（规划与研究）、**General-purpose**（通用）。关键约束： - Subagent 的权限应**小于**主线程，否则隔离失去意义 - 设置 `maxTurns` 防止失控 - 需要文件修改时使用 `isolation: worktree` 隔离文件系统 - 输出格式必须结构化，否则主线程无法消费 > **模型分层策略**：探索阶段的 Subagent 使用 Haiku 等小模型——推理快、费用极低、可以多开并行。探索完成后，将精炼的高价值上下文交给 Opus 等大模型做深度推理。**不是小模型不行，而是用错了角色。** ### 4.3 自动化治理：对抗代码腐化 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**：用自然语言驱动开发，跳过验证环节。看起来快，实际埋雷。 ### 生产力悖论 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 幻觉无法通过优化提示词消除，只能用**硬性防御**兜底： 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 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 | 余弦の博客](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)