学习-claude code 工程化实战的笔记

工作开发中一直在使用claude解决一些编码问题，没有进行过系统了解。看下黄佳老师写的《claude code 工程化实战的笔记》课程，才知道claude中有这么多门道，这么多功能技巧。收益匪浅。以下是学习过程的笔记。学习完课程真的是太有帮助。 完整课程内容：blog.shenshuai.site/pages/3dde4...

📋 文章摘要

本文是《Claude Code 工程化实战》课程的学习笔记，系统梳理了Claude Code作为AI Agent框架的核心架构与工程化实践。主要内容包括：

核心架构

• 记忆系统：五层记忆架构（企业策略、用户级、项目级、项目规则、本地级）通过CLAUDE.md文件实现长期记忆
• 子代理系统：通过Sub-Agents实现上下文隔离，让专业Agent做专业事，支持并行执行和流水线编排
• 技能系统：Skills作为按需加载的能力包，采用渐进式披露架构设计
• 扩展机制：Hooks（事件驱动自动化）、MCP（外部工具连接）、Tools（工具系统内核）

工程化实践

• 权限控制：构建只读型安全审计子代理，通过工具权限设置角色边界
• 噪声隔离：使用子代理处理高噪声任务，保持主对话上下文清洁
• 多代理协作：Sub-Agents与Agent Teams的选型决策，支持多会话协作
• CI/CD集成：Headless模式支持无头运行，可无缝融入自动化流程

高级特性

• Agent SDK：将Claude Code能力封装为可编程接口，支持Python/TypeScript调用
• 插件系统：标准化打包和分发方式，支持团队工具集共享
• 规则系统：指令规则与权限规则的双重约束机制

设计原则

• 渐进式披露：按需加载，避免信息过载
• 隔离与约束：通过上下文隔离和工具权限确保系统安全
• 知识本位：Skills设计遵循声明式、自包含、知识本位原则，实现跨平台复用

本文从基础概念到高级应用，全面介绍了如何将Claude Code从简单的代码助手转变为可工程化部署的AI Agent系统，适合开发者系统学习Claude Code的架构设计与实战应用。

00共生而非替代

Claude code非常懂工程，它会自动规划任务，拆解任务，自动雇佣一些Sub Agents 做事情，自动判断什么时候需要引入人类的决策。

Claude code直接把Agent和工程治理写入产品架构------ Sub Agents、Skill、hooks，这些从Claude code的设计过程中创建出来的概念，形成了通用智能体设计模式的一部分。

• Sub Agents：一个复杂任务拆解给多个专职角色；cc把它做成开箱即用的工程能力，只需要一个配置，就能创建有明确职责、受控权限的子代理
• Skills：AI应该什么使用什么技能。采用渐进式架构，按需加载。
• Memory：解决 Agent 每次对话都"从零开始"、不理解项⽬背景 的问题，让 AI 真正记住你的代码结构、约束和上下⽂。
• Hooks：解决 Agent 执⾏过程不可控、缺乏检查点、容易"越权 操作"的问题，在关键节点引⼊⾃动校验和⼈⼯兜底。
• Headless：解决 Agent 只能在 IDE ⾥交互、⽆法进⼊⾃动化流 程的问题，让 AI 能在 CI/CD 中⽆⼈值守地运⾏。

课程代码仓库链接： github.com/huangjia201...

01CC底层概览

Claude code 技术栈全貌的导览、核心目的是建立 Claude Code 的「心理地图」。

Claude Code 不是一个产品、而是一套以 CLI 为入口的 AI Agent 框架、由九大模块组成：记忆（CLAUDE.md）、子代理（SubAgents）、技能（Skills）、命令（Commands）、Hooks、MCP、Headless、Agent SDK、Plugins。每个模块有清晰的职责边界、组合后形成「可扩展的 AI 团队」。

如果不订阅官方账号，可以使用 API Key + 中转代理

DeepSeek、Qwen、 Kimi、GLM 等国内模型的 API 都能够很好的支持。

**多账号API，多模型怎么切换？**推荐社区⼯具 CC Switch。跨平台桌⾯ + CLI ⼀体化

Claude Code 底层技术全景图

从技术上拆解可以分为四个层次：基础 层、扩展层、集成层和编程接⼝层

• 基础层也可以称为是 Claude Code 的⻓期记忆系统，它的核⼼⽂ 件是 CLAUDE.md 。
• 扩展层：是 Claude Code 的能⼒中⼼，包含 Commands（斜杠命 令）、Skills（技能）、SubAgents（⼦代理）、Hooks（钩⼦）四个 核⼼组件。
• 集成层：负责连接外部世界，包含 Headless（⽆头模式）和 MCP（Model ContextProtocol）两⼤技术。
• 编程接口层 Agent SDK：当配置式的扩展不够⽤时，你可以⽤代码来驱动 Claude。这种⽅ 式适合 构建⾃定义 Agent ------完全控制执⾏流程、⾃定义⼯具、 复杂⼯作流

02CC的记忆系统

CLAUDE.md 就是治疗这种失忆症的药。

当项目目录启动claude code时，发生的"记忆系统初始化"过程如下图

Claude 每次对话都会重新"入职"------所以这份手册必须简洁有效。

Claude Code 的五层记忆架构：

1. 企业策略(/etc/claude-code/CLAUDE.md)
2. 用户级(~/.claude/CLAUDE.md)
3. 项目级(./CLAUDE.md或./.claude/CLAUDE.md)
4. 项目规则(.claude/rules/*.md)
5. 本地级(./CLAUDE.local.md)

从上到下，按层级结构组织------高层级的文件优先加载，为底层文件提供基础；

重点说下rules，这是一个比较高阶的技巧；Rules 是按主题组织的规则文件，支持条件作用域；适合场景包括 CLAUDE.md 变得太长时，不同文件类型需要不同规范时，以及前后端分离的项目。

例如目录结构：

.claude/
└── rules/
    ├── typescript.md      # TypeScript 规范
    ├── testing.md         # 测试规范
    ├── api-design.md      # API 设计规范
    └── security.md        # 安全规范

编写CLAUDE.md的原则

原则 1：Less is More

原则 2：具体优于泛泛

原则 3：关键三问题 WHY为什么要这样做？ / WHAT 具体要做什么，不要做什么？ / HOW 按什么步骤去做？

原则 4：渐进式披露：不要把一切都塞进 CLAUDE.md

03分而治之 Sub-Agents的核⼼概念与应⽤价值

⼦代理，通过上下⽂隔离，让专业的 Agent 做专业的事⼉，不是为了让 Claude 做得更多， ⽽是为了让 Claude 记得更少，但记得对

⼦代理相当于⼀个"专职⼩助⼿"，带着⾃⼰的规则、⼯具权限、上下⽂窗⼝，去完成某⼀类任务，然后把"结果摘要"带回来。你可以把它理解成：把⼀个⼤脑拆成多个岗位⻆⾊ ，每个岗位只做⼀件事，并且有明确的权限边界。

.claude/
└── agents/
    ├── test-runner.md      # 测试运⾏专员
    ├── code-reviewer.md    # 代码审查专员
    ├── log-analyzer.md     # ⽇志分析专员
    └── bug-fixer.md        # Bug 修复专员

db-reader.md

---
name: db-reader
description: Execute read-only database queries.
tools: Bash
hooks:
  PreToolUse:
  - matcher: "Bash"
hooks:
  - type: command
  command: "./scripts/validate-readonly-query.sh"
---

子代理核心工程能力归结起来的四件事

• 隔离 ：让主对话保持清洁，避免执⾏噪声污染上下⽂。
• 约束 ：通过⼯具权限把⻆⾊边界变成系统规则
• 复⽤ ：把⼀次好⽤的经验沉淀为可版本化的配置
• 并⾏ ：让原本串⾏的复杂任务可以同时推进

04量体裁衣｜从Sub-Agents 到Multi-Agent的⼯程指南

Skills 模式与 Sub-Agent 模式

• Sub-Agent：独⽴的上下⽂ → 适合⼤量信息过滤
• Skill：共享的上下⽂ → 适合需要连贯对话的场景

从单⼀ Agent 到复杂智能体系统设计的⼀系列⻩⾦法则：

• 从单 Agent 开始 → 只在遇到明确瓶颈时才升级
• 先加⼯具，再加 Agent → Tools 是最⼩的扩展单位
• 选对模型 > 堆更多 token → 升级模型的效果超过翻倍预算
• 上下⽂隔离是核⼼价值 → 多 Agent 的第⼀价值不是并⾏，是隔离
• Token 成本要求⾼价值任务 → 不是所有场景都值得多 Agent

最好的架构不是最复杂的架构，⽽是恰好满⾜需求的最简架构

05构建只读型安全审计⼦代理

子代理的功能主要是权限边界

一些不用创建子代理的场景：

• ⼀次性任务 ：直接在主对话中完成即可
• 简单的 prompt 模板 ：直接⽤ Skill ⽂件，不需要独⽴上下⽂和⼯具隔离
• ⾃动化触发动作 ：⽤ Hook，不需要 AI 分析判断

06⾼噪声任务处理

为什么需要噪声隔离-从token消耗说起

⼦代理去执⾏产⽣⼤量输出的任务，只把精炼的结论带回主对话，⽽主对话上下⽂保持清洁。

07多任务并⾏探索与流⽔线编排

并行执行子代理

并⾏执⾏的价值显⽽易⻅。传统情况下，如果不使⽤⼦代理并⾏处理，假设每个模块⽤时 30 秒，串⾏总耗时 90 秒，主对话上下⽂会被三个模块的探索过程塞满；⽽并⾏整体⽤时 30 秒，且只有三份简洁报告。并⾏执⾏不仅更快，⽽且主对话的上下⽂更清洁。

流⽔线串行执行代理

.claude/
└── agents/
    ├── bug-locator.md     # 定位：找到问题在哪
    ├── bug-analyzer.md    # 分析：理解为什么出问题
    ├── bug-fixer.md       # 修复：实施修复
    └── bug-verifier.md    # 验证：确认修复有效

对于复杂 bug、需要系统性排查的情况，流⽔线尤其有价值。⽽且每个⼦代理职责清晰，便于追踪问题；且权限递进，只有必要时才给写权限。

流⽔线编排 ⽀持多个⼦代理顺序⼯作，适合有依赖关系的连续阶段，⼦代理之间职责清晰 + 权限递进，其核⼼价值是 清晰度 + 可控性。

08群策群力｜Agent Teams多会话协作架构

注意 ：Agent Teams 是 Claude Code 的实验性功能，默认关 闭。需要在相关级别的设置⽂件中（如⽤户级设置 ~/.claude/settings.json 或 项⽬级设置project_folder/.claude/settings.json）添加

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 环境变量 来启⽤。

如果存在3个代理任务，需要把其中一个的处理结果传递给另外一个代理，这就是Agent teams要解决的问题。

Sub-Agents vs Agent Teams：选型决策树

你的任务需要多个 workers 吗？
├── 否 → 直接在主对话或⽤单个⼦代理
└── 是 → Workers 需要互相通信吗？
    ├── 否 → Sub-Agents
    │ 	└── 特点：
    │			 • 更低 token 成本
    │			 • 更简单的协调
    │ 		 • 适合：并⾏探索、流⽔线编排
    │
    └── 是 → Agent Teams
        └── 特点：
        • ⽀持讨论和挑战
        • 共享任务列表
        • 适合：竞争假设、协作开发、多⻆度审查

适合 Agent Teams 的任务特征包括

• 并⾏探索能带来真正的价值
• 讨论和挑战能提⾼结果质量
• 任务复杂度值得额外成本

09SKILL.md结构与触发机制

当团队规范过多时，不能完全写入CLAUDE.md文件中，这样会浪费tokens，还会稀释关键注意力。基于这个原因产生skill的定义。本质上是⼀种按需加载的认知结构。与其把所有知识常驻在上下⽂中，不如把它们封装成可独⽴触发的能⼒单元。当模型判断当前任务涉及某个特定领域时，再加载对应的知识与操作流程。

** Skills 是⼀种可被 语义触发的能⼒包，它包含领域知识、执⾏步骤、输出规范与约束条件，并在需要时渐进式加载到主 Agent 的认知空间中。**

skill 通过 description 告诉模型：在什么情况下应该加载这项能⼒

定义skill的description应该具体；

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Claude能否激活skill，全靠 description 的定义；是skill的灵魂。

# 代码审查 Skill
description: Review code for quality, security, and best practices. Checks for bugs, performance
issues, and style violations. Use when the user asks for code review, wants feedback on their code,
mentions reviewing changes, or asks about code quality.

# API ⽂档 Skill
description: Generate API documentation from code.
Extracts endpoints, parameters, and response
schemas. Use when the user wants to document APIs,
create API reference, generate endpoint
documentation, or needs help with OpenAPI/Swagger
specs.

# 数据库查询 Skill
description: Query databases and analyze results.
Supports SQL generation, query optimization, and
result interpretation. Use when the user asks about
data, wants to run queries, needs database
information, or mentions tables/schemas.

Skill 的 description 不是⽂档，⽽是触发器 ，其构建公式为： 做什么 + 怎么做 + 什么时候⽤

10任务skill实战

在skill中加上 disable-model-invocation: true就不会让模型自动调用，需要使用命令进行调用。

命令类型skill还可以接受参数，使用$ARGUMENTS进行参数接收，可以接单参数或多参数。

还可以动态获取上下文信息，!command`` 是 Skill ⽂件的 预处理器 ------在⽂件内容发送给 模型 之前 ，先在 shell 中执⾏这些预设的命令

## Current Context (Auto-detected)
Current branch:
!`git branch --show-current`
Recent commits on this branch:
!`git log origin/main..HEAD --oneline 2>/dev/null
|| echo "No commits ahead of main"`
Files changed:
!`git diff --stat origin/main 2>/dev/null || git
diff --stat HEAD~3`

11渐进式披露架构设计

Skill 的渐进式披露设计：

• 第⼀层只扫描 description 作为 "⽬录"，
• 第⼆层在触发时加载 SKILL.md 主⽂件作为"章节"，
• 第三 层再按需加载被引⽤的具体⽂件作为"附录"。

结构化分层替代信息堆叠，让系统在规模变⼤时依然⾼效、可控

如下的财务分析skill，只有当 SKILL.md 中引⽤了这些⽂件，Claude 才会去读取这⼀类 ⽂件。

.claude/skills/financial-analyzing/ # 标准 Skill⽬录
  ├── SKILL.md # 主⽂件（总是加载）
  ├── reference/ # 参考资料
  │ ├── revenue.md # 收⼊分析公式
  │ ├── costs.md # 成本分析公式
  │ └── profitability.md # 盈利分析公式
  ├── templates/ # 报告模板
  │ ├── quarterly_report.md
  │ └── annual_report.md
  ├── data/ # 数据⽂件
  │ └── industry_benchmarks.json
  └── scripts/ # 分析脚本
  ├── calculate_ratios.py
  └── generate_report.sh

工作中可以按照使用功能分类创建skill

.claude/skills/my-skill/
  ├── SKILL.md # ⼊⼝ + 路由（< 500 ⾏）
  ├── reference/ # 知识库（公式、规范、基准）
  ├── templates/ # 输出模板（报告、代码⻣架）
  ├── examples/ # 示例集（输⼊输出样本）
  ├── scripts/ # 可执⾏脚本（计算、⽣成、验证）
  └── data/ # 静态数据（JSON、CSV）

12 Skills与SubAgent配合实战

子代理中配置skills

# ⼦代理在创建时预加载 Skill 作为领域知识
---
name: api-doc-generator
skills:
  - api-generating # 预加载 API ⽂档⽣成知识
---

skills中包含SubAgent

Skill ⾃带任务指令，Skill 包含 SubAgent，通过 context: fork 派⼦代理去执⾏。该模式的适⽤场景是⼀个独⽴完整的任务，不需要与主对话交互，执⾏完把结果送回来就⾏

---
name: codebase-research
description: Deep research into codebase topics
context: fork # 关键点！
agent: Explore
---
Research $ARGUMENTS thoroughly

想做⼀次代码质量扫描，但不想让⼤量中间⽂件内容污染主对话。这正是 context: fork 的典型场景 ------ Skill ⾃

⼰派⼀个⼦代理去做，做完把报告送回来 。

13 Skills架构定位与⾼级能⼒

Skills 在实际应用中的组合能力。四种设计模式------模板驱动、脚本增强、知 识分层、⼯具隔离------分别控制表达结构、确定性执⾏、上下⽂ 规模与安全边界。

14 Skills从Claude Code到⾏业开放标准

skills在Agents中通用的标准

声明式 → 任何 LLM 都能读

⾃包含 → 任何⽂件系统都能存

知识本位 → 知识的价值不绑定平台

15 Hooks事件驱动⾃动化

在 Claude 执⾏⼯具前后插⼊⾃定义检查，阻⽌危险命令、保护敏感⽂件、⾃动格式化代码。

Hooks 是 Claude Code 三⼤扩展机制中唯⼀能 拦截和修改 Claude ⾏为的机制，也是⼯程化实践中安全防线的最后⼀道闸⻔。

Hooks和 Commands 和 Skills 相⽐， Hooks 是三者中唯⼀能拦截和修 改 Claude ⾏为的机制 。

16 Hooks ⾼级模式与⼯程实践

Hooks 的基础概念------中间件本质、事件体系、配置结构，以及最常⽤的 PreToolUse 和 PostToolUse 两⼤实战。PreToolUse 在⼯具执⾏前做"⼊⼝安检"，PostToolUse 在⼯具执⾏后做"过程质检"。

Stop Hook 是claude code的最后一道安全检验

17 MCP 协议与外部⼯具连接

Model Context Protocol (MCP)

MCP 配置可以放在多个位置：

• 团队共享的服务配置放到.mcp.json------提交到 git
• 敏感凭证放到.claude/settings.local.json------不提交
• 个⼈常⽤服务放到 ~/.claude/settings.local.json------跨项⽬

{
  "mcpServers": {
    "server-name": {
      "type": "stdio | sse | http",
      "command": "...",
      "args": ["..."],
      "url": "...",
      "headers": {},
      "env": {}
    }
  }
}

Context7------实时技术⽂档

Context7 是开发者社区最⽕的 MCP 服务器之⼀。它的价值在 于，当你让 Claude 帮你写代码时，Claude 可以实时拉取你⽤的 库的最新⽂档，⽽不是依赖训练数据中可能过时的知识。

在.mcp.json 中⼿动配置

{
"mcpServers": {
  "context7": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

创建自定义的MCP

当现有的 MCP 服务器⽆法满⾜需求时，你可以⾃⼰创建

18 Tools ⼯具系统内核剖析

Claude（模型）负责推理，Tools 负责⾏动。⽽ Claude Code 扮演的⻆⾊是 Agentic Harness，它把模型和⼯具连接起来，提供执⾏环境、上下⽂管理、权限控制等基础设施。

19 Headless 模式与 CICD 集成

Headless 模式下的 Claude Code 没有交互式终端界⾯，但拥有和交互模式完全相同的代码分析能⼒、⼯具调⽤能⼒和推理能⼒。

启⽤ Headless 模式的关键是 -p（或 --print）标志。

配合 --output-format 可以 选择 text、json 或 stream-json 三种输出格式，分别适⽤于⼈类 阅读、程序解析和实时监控。

在CI/CD环境中，建议你总是同时设置--allowedTools和-max-turns。这不是因为不信任Claude，而是因为无人值守环境中的任何意外都会被放大一一一个失控的循环可能消耗大量APltokens，一个意外的文件修改可能破坏构建。

Claude Code 的⼀个独特优势是它能⽆缝融⼊ Unix 管道。你可 以⽤ cat file | claude -p "分析" 将⽂件内容传给 Claude，也可以将 Claude 的输出通过管道传给其他⼯具。

20Rules 规则系统深度剖析

Claudecode中存在2中规则

• 指令规则：.claude/rules/ ⽬录下的每个.md ⽂件
• 权限规则：写在.claude/settings.json 或.claude/settings.local.json 中，由 Claude Code 客户端在⼯具调⽤前硬拦截

指令规则是 Claude 的认知约束，权限规则是客户端的⾏为约束

21 通过Agent SDK 掌控 Claude Code

Claude Agent SDK-它把 Claude Code 的所有能⼒封装成了可编程的接⼝。你可以⽤ Python 或 TypeScript 编

写代码，像调⽤普通函数⼀样调⽤ AI Agent。

通过调用SDK可以自动调用claude code的功能，从命令⾏⼯具到可编程 SDK，Claude Code 的应⽤边界被⼤⼤拓展

22Agent SDK ⾼级应⽤

深⼊学习 Claude Agent SDK 的⾼级特性，并构建⼀个完整的⽣产级 Agent

⾃定义⼯具让 Agent 能够调⽤你定义的函数。使⽤ @tool 装饰器定义⼯具，使⽤ create_sdk_mcp_server 创建承载⼯具的 MCP 服务器，然后通过 mcp_servers 选项注⼊到 Agent 中。⼯具命名遵循 mcp__{服务器名}__{⼯具名} 格式。设计⼯具时要遵循单⼀ 职责、清晰描述、安全优先的原则。

23 Plugins 插件打包与分发

插件系统让你把所有的⼯具、命令、配置、规范打包成⼀个整体。

插件的价值不在于它引⼊了新的机制，⽽在于它提供了⼀个标准化的打包和分发⽅式。你在前 20 讲⾥学到的所有扩展能⼒，都可以通过插件系统组合、封装、传递给他⼈。

每个插件必须有.claude-plugin/plugin.json ⽂件，作⽤类似于 npm 的 package.json。

Claude Code 的 插件分发基于 Git，插件本质上就是⼀个 Git 仓库

项目代码参考：github.com/huangjia201...

完整课程内容：blog.shenshuai.site/pages/3dde4...

讲次范围	内容	推荐投入
第 01-08 讲	开篇 + 记忆 + 子代理 5 讲	★★★★★ 必读,核心思维转变
第 09 讲	子代理专题总结	★★★ 复习时回看
第 10-15 讲	Skills 6 讲(从基础到出圈)	★★★★★ 必读,性价比最高
第 16 讲	Skills 专题总结	★★★ 复习时回看
第 17-25 讲	Hooks/MCP/Tools/Headless/Rules/SDK/Plugins	★★★★ 进阶,工程化必备