在 Claude Code 的使用光谱上，一端是仅靠一句模糊描述就能生成代码的「vibe coding」，另一端则是精心设计的 agentic 工作流。大多数开发者停留在前者，却对后者的工程化潜力视而不见。本文将从概念澄清出发，逐步展开从 vibe 到 agentic 的完整工程方法论，提供可直接落地的参数与监控建议。

一、两种开发范式的本质差异

Vibe coding 本质上是一种直觉驱动的开发方式：开发者用自然语言描述期望的「感觉」，将实现细节完全委托给 AI 模型。这种方式的优点是门槛极低 —— 任何人都可以仅凭一句「帮我写一个登录页面」获得可用代码。但其局限同样明显：无法处理复杂的多步骤任务，难以保证代码质量的一致性，面对需要多轮协作的大型需求时力不从心。

Agentic engineering 则是将 AI 协作视为一个结构化的系统工程。它不满足于「让 AI 帮我写代码」，而是思考「如何让 AI 以我希望的方式、在我指定的约束下、按照我定义的流程来工作」。这涉及对 AI 上下文的管理、工作流的编排、以及对模型行为的精细控制。Claude Code 提供了完整的机制来实现这一目标，包括 Subagents（子代理）、Commands（命令）、Skills（技能）、Hooks（钩子）和 MCP Servers（MCP 服务器）。

理解这一差异的关键在于：vibe coding 是一次性的 prompt-response 交互，而 agentic engineering 则是对 AI 行为的编程。前者依赖模型的泛化能力，后者则通过显式的结构化设计来约束和引导模型行为。

二、Claude Code 核心机制的工程定位

2.1 Subagents：独立上下文的角色化执行

Subagents 是 Claude Code 中最接近「 autonomous actor」的概念。每个子代理运行在完全隔离的上下文中，拥有自定义的工具、权限、模型选择和记忆。这意味着你可以在主会话中定义一个专门负责代码审查的子代理，它不会受到主任务上下文的污染，能够以更客观的视角进行审查。

工程实践中的典型应用场景包括：第一，使用测试时间计算（test time compute）—— 让一个子代理实现功能，让另一个子代理（即使是同一模型）来发现前者的 bug；第二，将复杂任务拆解后分配给不同专业的子代理，比如分别调用「后端子代理」和「前端子代理」来处理不同模块；第三，在子代理中使用 <important if="..."> 标签来动态注入条件性规则，根据任务上下文激活特定的约束。

子代理的定义位于 .claude/agents/<name>.md，最佳实践建议每个子代理应该围绕特定功能域进行设计，而不是创建通用的「QA 代理」或「后端代理」。功能特定的子代理配合渐进式披露的技能，比通用代理更能保持上下文的清晰与高效。

2.2 Commands：可复用的工作流模板

Commands 是用户主动触发的提示模板，位于 .claude/commands/<name>.md。与 Subagents 不同，Commands 不会创建新的上下文，而是将预定义的指令注入到当前会话中。它们是工作流编排的基础单元，适合那些需要反复执行的标准化流程。

最佳实践表明，如果你每天多次执行某个「内部循环」工作流，就应该将其创建为 Command。这些 Command 存放在 .claude/commands/ 目录下，随代码一起版本化管理。例如，可以创建一个 /weather-orchestrator 命令来协调多个子代理和技能共同完成一个复杂的天气数据查询任务。Command 相比 Subagents 更轻量，适合那些不需要独立上下文的场景。

一个重要的工程原则是：优先使用 Command 而非 Subagents 来处理重复性工作流。只有当任务需要独立的上下文、记忆或工具集时，才考虑使用 Subagents。

2.3 Skills：渐进式知识注入

Skills 位于 .claude/skills/<name>/SKILL.md，是 Claude Code 中最强大的知识封装机制。它们具备三个关键特性：可配置性、可预加载性和自动发现性。更重要的是，Skills 支持上下文分叉（context: fork）—— 允许技能在独立的子代理中运行，主上下文只会看到最终结果，而非中间的调用过程。

Skill 的描述字段是其核心触发器，写给模型而非人类，用于回答「我应该在什么时候调用这个技能」。最佳实践建议：不要在 Skills 中陈述显而易见的事情，而是聚焦于那些能够将模型「推出默认行为」的约束和目标；给予目标与约束，而非规定性的步骤 - by - 步骤 指令；使用子文件夹组织 monorepo 中的技能，并通过 references/、scripts/、examples/ 子目录实现渐进式披露。

一个具体的工程参数是：为每个 Skill 创建一个「Gotchas」板块，记录模型的失败点，随着时间推移持续补充高信号内容。这本质上是一种针对模型行为的知识沉淀。

2.4 Hooks 与 MCP：扩展与集成

Hooks 允许你在特定事件发生时执行自定义处理器（脚本、HTTP 请求、提示或子代理），这些处理器运行在 agentic 循环之外。工程价值体现在：使用 PreToolUse Hook 来测量技能使用情况，识别热门或触发不足的技能；使用 PostToolUse Hook 自动格式化代码 —— 模型生成格式良好的代码，Hook 处理最后 10% 以避免 CI 失败；使用 Stop Hook 在回合结束时引导模型继续工作或验证其成果。

MCP（Model Context Protocol）服务器则提供了与外部工具、数据库和 API 的连接能力，位于 .claude/settings.json 和 .mcp.json 中配置。通过 MCP，Claude Code 可以调用 Playwright 进行浏览器自动化、使用 Chrome DevTools MCP 直接读取控制台日志，或连接任何支持 MCP 协议的工具。

三、工作流编排的 C→A→S 架构

Claude Code 的工作流遵循一个清晰的编排模式：Command → Agent → Skill（C→A→S）。用户通过 Command 触发工作流，Command 可以调用一个或多个 Subagents 来处理不同子任务，每个 Subagent 又可以按需调用特定的 Skills 来执行具体操作。

这种架构的优势在于职责的清晰分离。Command 负责「做什么」，Agent 负责「谁来做」，Skill 负责「怎么做」。当需要调整工作流逻辑时，只需修改 Command； 当需要改变执行策略时，调整 Agent 配置； 当需要优化特定操作的细节时，更新 Skill 定义。三者的组合提供了足够的灵活性，同时保持了工程上的可维护性。

一个典型的工作流示例是「天气 orchestrator」：Command 接收用户的位置请求，调用地理编码 Agent 获取坐标，然后调用天气数据 Agent 获取预报，最后使用格式化 Skill 输出结果。每个环节都可以独立测试和替换。

四、工程落地的关键参数清单

4.1 CLAUDE.md 编写规范

CLAUDE.md 是项目级记忆的核心，其编写质量直接决定了 AI 协作的效率。最佳实践建议将每个 CLAUDE.md 文件控制在 200 行以内，人类层（HumanLayer）的实践更进一步，建议控制在 60 行左右。随着文件增长，可以使用 <important if="..."> 标签来防止模型忽略重要规则。

CLAUDE.md 中应该包含的内容：项目的构建、测试和运行命令（任何开发者都应该能够直接运行「跑一下测试」并首次成功）；项目的技术约束和架构决策；特定领域的编码规范和约定。应该避免的内容：过于笼统的通用规则（模型已经知道的内容）；与 settings.json 功能重复的配置（使用 attribution.commit: "" 而非在 CLAUDE.md 中写「NEVER add Co-Authored-By」）。

4.2 会话管理策略

避免陷入「agent dumb zone」—— 当上下文使用率超过 50% 时手动执行 /compact 进行压缩；使用 /clear 在切换任务时重置上下文；使用 /rename 标记重要会话以便后续恢复；使用 Esc 或 /rewind 在模型偏离轨道时回退而非在同一上下文中试图修正。

模型选择上，使用 Opus 进行计划模式（plan mode），Sonnet 进行代码编写，兼顾推理质量与成本效率。始终启用 thinking mode 以观察模型的推理过程，使用 Explanatory 输出风格以获得带有 ★ Insight 盒子标记的详细输出。

4.3 PR 与提交规范

保持 PR 的小而专注：统计显示，中位数为 118 行（141 个 PR，一天内更改 45K 行），一个功能一个 PR 更易于审查和回滚。始终使用 squash merge 以保持清晰的线性历史，一个提交对应一个功能，便于 git revert 和 git bisect。至少每小时尝试提交一次，任务完成后立即提交。

4.4 监控与持续优化

使用 status line（在 settings.json 中配置）实时显示上下文使用情况、模型选择、会话成本等信息。建立技能使用情况的监控机制：通过 PreToolUse Hook 记录哪些技能被触发、触发频率、是否有预期的技能未被触发，据此调整技能的描述字段和触发条件。

五、从直觉到工程的转变路径

从 vibe coding 到 agentic engineering 的转变不是一蹴而就的，而是一个渐进的过程。初期可以保持简单的 vibe 方式，但应该开始有意识地识别那些频繁重复的工作流，并将它们转化为 Command。随着项目复杂度提升，逐步引入 Subagents 来处理需要独立上下文的子任务。

对于 monorepo 或大型项目，Skills 的组织尤为重要。建议为每个领域创建独立的技能目录，使用子文件夹和渐进式披露来管理复杂度。定期回顾模型的行为模式，将常见失败点记录到对应的 Gotchas 板块中。

最终的目标是建立一个「任何开发者都能直接启动 Claude，说『跑一下测试』并首次成功」的项目环境。如果这做不到，说明 CLAUDE.md 缺少必要的内容；如果模型频繁忽略指令，可能需要检查是否应该将这些指令迁移到 settings.json 中（后者是强制执行的，而前者可能被模型忽略）。

资料来源

本文主要参考了 GitHub 仓库 shanraisshan/claude-code-best-practice，该仓库系统整理了 Claude Code 的最佳实践，包括概念定义、工作流模式、社区技巧和真实项目案例。