Claude Code 工程化实战系列

Claude Code 工程化实战系列

工程实践参考，不是教程。 34 篇文章覆盖从项目记忆到可治理 Agent 系统的完整路径。

本系列面向在真实项目中使用 Claude Code 的工程师和技术负责人。目标读者已经具备基本的 Claude Code 使用经验，需要解决的核心问题是：如何把一次性的 prompt 交互变成可复用、可验证、可治理的工程系统。

系列配套学习路径参见 Claude Code 工程化学习路径。建议先通读学习路径建立全景认知，再按需查阅以下各篇。

---

系列定位

Claude Code 工程化的核心命题不是"让 AI 更会写代码"，而是"让 AI 在真实代码库里受控地工作"。这涉及三组相互关联的工程问题：

上下文搬运——人类开发者通过长期协作积累了对项目结构、编码风格、命令习惯和安全边界的隐性认知。Claude Code 每次会话从零开始，需要通过 CLAUDE.md、rules 和 auto memory 显式获得这些认知。上下文写得不好，AI 行为就不稳定；写得太多，又会挤占有效上下文窗口。

验证缺失——代码生成之后，谁来确认结果是正确的？靠人肉 review 效率低，靠 AI 自我评价不可靠。工程化的做法是把测试、lint、类型检查、格式化等验证手段嵌入 AI 工作流，让每一步修改都有自动化的质量信号。

权限失控——一个能读代码、改文件、跑命令、连数据库的 agent，如果缺少权限边界和审计机制，就是安全事故的隐患。工程化要求在高风险操作上加拦截、在关键路径上加验证、在所有行为上留审计记录。

本系列按"单人可用 → 任务沉淀 → 复杂拆解 → 外部连接 → 确定性治理 → CI/CD 自动化 → 平台化分发"的顺序组织，每篇文章聚焦一个具体机制，包含问题分析、核心机制解释、配置示例和权衡讨论。文章之间有递进关系，但也可按需独立查阅。

---

系列目录

开篇：先建立正确问题

建立从"工具使用"到"系统设计"的视角转换。Claude Code 工程化的第一步不是学功能，而是理解自己到底要解决什么问题。

第一模块：单人可用

让一个工程师在单个真实仓库里高效使用 Claude Code。核心是把项目知识写成机器可消费的上下文，建立基本的权限意识和常用工作流模板。

第二模块：把重复任务变成能力

当同一个任务反复出现，应该从"每次重新描述"升级为"一次定义、反复调用"。Slash Commands 处理短流程，Skills 处理带资源和脚本的长流程。

第三模块：复杂任务拆解

复杂任务不适合在一个超长会话里完成。Subagents 把不同角色的任务隔离到独立上下文中，每个代理有自己的系统提示、工具权限和输出格式。

第四模块：连接外部世界

Claude Code 默认只能操作本地文件和命令。MCP（Model Context Protocol）让它安全地连接 GitHub、数据库、监控系统、设计工具等外部系统。MCP 提供能力，Skill 教流程，两者组合才能让工具按团队 SOP 被正确使用。

第五模块：确定性治理

仅靠提示词约束 AI 行为不够稳定。Hooks 在固定事件上执行确定性逻辑：记录每次操作、拦截高风险命令、在修改后自动验证。这是从"相信 AI 会遵守规则"到"系统级保证 AI 遵守规则"的转变。

第六模块：Headless 与 CI/CD

当本地工作流稳定后，可以把 Claude Code 放进脚本和 CI 流水线，实现 PR 自动审查、Issue 自动分类和低风险自动修复。Headless 模式是从"人机协作"到"机器自动化"的桥梁。

第七模块：平台化和分发

当多个团队需要复用同一套 Claude Code 能力时，本地命令和 Skill 已经不够。Agent SDK 把 Claude Code 的 agent loop 嵌入内部平台，Plugins 把整套能力打包分发。这一层只适合在本地工作流成熟之后进入。

---

架构图

Claude Code 工程化的分层架构。每一层解决不同维度的问题，层与层之间通过明确的接口协作。

flowchart TD
  A["用户目标 / Issue / PR / 任务"] --> B["Claude Code 主会话"]

  B --> C["项目上下文层<br/>CLAUDE.md / .claude/rules/ / auto memory"]
  B --> D["工作流层<br/>Slash Commands / Skills"]
  B --> E["委派层<br/>Subagents / Agent Teams"]
  B --> F["工具层<br/>Built-in Tools / MCP Servers"]
  B --> G["治理层<br/>Hooks / permissions / audit"]
  B --> H["自动化层<br/>Headless / GitHub Actions"]
  H --> I["平台层<br/>Agent SDK / Plugins / internal platform"]

  G -->|"拦截 / 记录 / 注入"| B
  F -->|"工具调用结果"| B
  E -->|"子代理返回结论"| B

  style C fill:#e8f5e9,stroke:#4caf50
  style D fill:#e3f2fd,stroke:#2196f3
  style E fill:#fff3e0,stroke:#ff9800
  style F fill:#fce4ec,stroke:#e91e63
  style G fill:#f3e5f5,stroke:#9c27b0
  style H fill:#e0f7fa,stroke:#00bcd4
  style I fill:#fff8e1,stroke:#ffc107

各层职责说明：

• 项目上下文层：解决"AI 不知道项目常识"的问题。CLAUDE.md 放每次都应该知道的规则，.claude/rules/ 放按目录加载的条件规则，auto memory 记录用户偏好和历史经验。
• 工作流层：解决"每次都要重新描述任务"的问题。Slash Commands 封装短流程，Skills 封装带资源和脚本的长流程。
• 委派层：解决"单次会话上下文不够"的问题。Subagents 在独立上下文中完成探索、审查、测试等专门任务。
• 工具层：解决"AI 只能操作本地文件"的问题。Built-in Tools 覆盖文件和命令操作，MCP 连接外部系统和 API。
• 治理层：解决"AI 行为不可审计"的问题。Hooks 在事件上执行确定性逻辑，permissions 控制工具调用，audit 记录所有行为。
• 自动化层：解决"AI 只能在终端里用"的问题。Headless 支持脚本化运行，GitHub Actions 接入 CI 流水线。
• 平台层：解决"能力无法跨项目复用"的问题。Agent SDK 嵌入内部系统，Plugins 打包分发整套能力。

---

机制速查

不同机制解决不同问题，混用或错用会增加系统复杂度而不增加价值。以下速查表帮助快速判断应该使用哪个机制。

决策矩阵

组合模式速查

---

最小可落地路线

团队在一周内可以完成的最小可行 Claude Code 工程化配置。不要从 Subagents 和 MCP 开始——先把单仓库协作的基础跑通。

第一步：写 CLAUDE.md

在仓库根目录创建 CLAUDE.md，控制在 120 行以内。内容应包含：

# CLAUDE.md

## Commands
- Install: pnpm install
- Test: pnpm test
- Typecheck: pnpm typecheck
- Build: pnpm build

## Architecture
- src/ - 源码
- tests/ - 测试
- migrations/ - 数据库迁移，改动前需确认

## Working Rules
- Keep diffs small.
- Reuse existing helpers before adding new abstractions.
- Update tests when public behavior changes.

## Safety
- Do not edit .env* files.
- Ask before changing migrations.
- Never run deployment commands without explicit request.
- Never commit directly to main.

写完后让 Claude Code 用自己的话复述项目规则，检查哪些描述仍然模糊，迭代修正。

第二步：创建 3 个 Slash Commands

在 .claude/commands/ 目录下创建三个高频命令：

• /review：审查当前 diff，输出风险、遗漏和改进建议
• /fix-test：分析失败测试，定位原因，提出修复方案
• /update-docs：检查代码变更是否需要更新文档

Review the current unstaged changes. For each file changed:
1. Summarize what changed and why.
2. Flag any risks or missing tests.
3. Check against project rules in CLAUDE.md.
Output a structured review with risk level (low/medium/high).

第三步：加 1 个只读 code-review Subagent

创建一个工具权限严格受限的审查代理：

You are a code reviewer. You have read-only access.
Tools allowed: Read, Grep, Glob.
Purpose: Review diffs for bugs, style violations, and missing tests.
Output: Structured findings with severity and location.
Never suggest direct file edits. Return findings only.

第四步：加 2 个 Hooks

在 .claude/settings.json 中配置两个最基础的 Hook：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'BLOCK: dangerous command detected' && exit 1"
          }
        ],
        "matcher_regex": ".*(rm -rf|DROP TABLE|truncate|force push).*"
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: run pnpm test before committing'"
          }
        ]
      }
    ]
  }
}

第五步：接 1 个 MCP

优先接入 GitHub MCP，让 Claude Code 能直接查看 Issue、PR 和代码上下文：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

注意：不要在初期就接入数据库写权限。先只接读取类工具，验证稳定后再逐步扩展。

第六步：建 20 条评测任务

从真实工作中收集 20 个典型任务作为评测基准，覆盖以下类别：

评测任务用于衡量后续每次规则、Skill 或配置变更的效果。

---

度量维度

工程化需要量化反馈。以下七个维度覆盖 Claude Code 使用效果的核心指标，建议至少跟踪前四个维度。

任务完成维度

修改质量维度

上下文质量维度

权限控制维度

工具使用维度

成本维度

稳定性维度

---

延伸阅读

• Claude Code 工程化学习路径——系统梳理各机制的设计意图与组合方式，建议在本系列之前阅读
• Claude Code 资料与项目索引——官方文档、工程文章、生态项目和评测研究的完整索引
• Claude Code 官方文档——Anthropic 官方维护的 Claude Code 使用指南
• Claude Code Best Practices——Anthropic 工程团队总结的使用建议
• Claude Code Advanced Patterns——Subagents、MCP 和大规模代码库的进阶模式
• The Complete Guide to Building Skills for Claude——Skill 设计和构建的完整指南
• Dive into Claude Code——Claude Code 设计空间的学术论文，适合理解系统设计原理

2026-07-22 增补专题

以下文章记录 2026 年新增或发生明显变化的工程能力。原有 00-33 篇保持不变，编号 34 预留，不创建 34-unified-execution-surfaces.md。

---

GitHub 原文：README.md