工作开发中一直在使用claude解决一些编码问题没有进行过系统了解。看下黄佳老师写的《claude code 工程化实战的笔记》课程才知道claude中有这么多门道这么多功能技巧。收益匪浅。以下是学习过程的笔记。学习完课程真的是太有帮助。完整课程内容https://blog.shenshuai.site/pages/3dde48 文章摘要本文是《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把它做成开箱即用的工程能力只需要一个配置就能创建有明确职责、受控权限的子代理SkillsAI应该什么使用什么技能。采用渐进式架构按需加载。Memory解决 Agent 每次对话都“从零开始”、不理解项⽬背景 的问题让 AI 真正记住你的代码结构、约束和上下⽂。Hooks解决 Agent 执⾏过程不可控、缺乏检查点、容易“越权 操作”的问题在关键节点引⼊⾃动校验和⼈⼯兜底。Headless解决 Agent 只能在 IDE ⾥交互、⽆法进⼊⾃动化流 程的问题让 AI 能在 CI/CD 中⽆⼈值守地运⾏。课程代码仓库链接 https://github.com/huangjia2019/claude-code-engingeering01CC底层概览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⽆头模式和 MCPModel ContextProtocol两⼤技术。编程接口层 Agent SDK当配置式的扩展不够⽤时你可以⽤代码来驱动 Claude。这种⽅ 式适合 构建⾃定义 Agent ——完全控制执⾏流程、⾃定义⼯具、 复杂⼯作流02CC的记忆系统CLAUDE.md 就是治疗这种失忆症的药。当项目目录启动claude code时发生的“记忆系统初始化”过程如下图Claude 每次对话都会重新“入职”——所以这份手册必须简洁有效。Claude Code 的五层记忆架构企业策略(/etc/claude-code/CLAUDE.md)用户级(~/.claude/CLAUDE.md)项目级(./CLAUDE.md或./.claude/CLAUDE.md)项目规则(.claude/rules/*.md)本地级(./CLAUDE.local.md)从上到下按层级结构组织——高层级的文件优先加载为底层文件提供基础重点说下rules这是一个比较高阶的技巧Rules 是按主题组织的规则文件支持条件作用域适合场景包括 CLAUDE.md 变得太长时不同文件类型需要不同规范时以及前后端分离的项目。例如目录结构.claude/ └── rules/ ├── typescript.md# TypeScript 规范├── testing.md# 测试规范├── api-design.md# API 设计规范└── security.md# 安全规范编写CLAUDE.md的原则原则 1Less is More原则 2具体优于泛泛原则 3关键三问题 WHY为什么要这样做 / WHAT 具体要做什么不要做什么 / HOW 按什么步骤去做原则 4渐进式披露不要把一切都塞进 CLAUDE.md03分而治之 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:Bashhooks: - type:commandcommand:./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的灵魂。# 代码审查 Skilldescription: Review codeforquality, security, and best practices. Checksforbugs, performance issues, and style violations. Use when the user asksforcode review, wants feedback on their code, mentions reviewing changes, or asks about code quality.# API ⽂档 Skilldescription: 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 needshelpwith OpenAPI/Swagger specs.# 数据库查询 Skilldescription: 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:!gitbranch --show-currentRecent commits on this branch:!gitlog origin/main..HEAD--oneline2/dev/null||echoNo commits ahead of mainFiles changed:!gitdiff--statorigin/main2/dev/null||gitdiff--statHEAD~311渐进式披露架构设计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、CSV12 Skills与SubAgent配合实战子代理中配置skills# ⼦代理在创建时预加载 Skill 作为领域知识--- name: api-doc-generator skills: - api-generating# 预加载 API ⽂档⽣成知识---skills中包含SubAgentSkill ⾃带任务指令Skill 包含 SubAgent通过 context: fork 派⼦代理去执⾏。该模式的适⽤场景是⼀个独⽴完整的任务不需要与主对话交互执⾏完把结果送回来就⾏--- name: codebase-research description: Deep research into codebase topics context: fork# 关键点agent: Explore --- Research$ARGUMENTSthoroughly想做⼀次代码质量扫描但不想让⼤量中间⽂件内容污染主对话。这正是 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-mcplatest]}}}创建自定义的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 CodeClaude Agent SDK-它把 Claude Code 的所有能⼒封装成了可编程的接⼝。你可以⽤ Python 或 TypeScript 编写代码像调⽤普通函数⼀样调⽤ AI Agent。通过调用SDK可以自动调用claude code的功能从命令⾏⼯具到可编程 SDKClaude 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 仓库项目代码参考https://github.com/huangjia2019/claude-code-engineering/tree/main/10-Plugins/projects/03-team-toolkit完整课程内容https://blog.shenshuai.site/pages/3dde48讲次范围内容推荐投入第 01-08 讲开篇 记忆 子代理 5 讲★★★★★ 必读,核心思维转变第 09 讲子代理专题总结★★★ 复习时回看第 10-15 讲Skills 6 讲(从基础到出圈)★★★★★ 必读,性价比最高第 16 讲Skills 专题总结★★★ 复习时回看第 17-25 讲Hooks/MCP/Tools/Headless/Rules/SDK/Plugins★★★★ 进阶,工程化必备
学习-claude code 工程化实战的笔记-极客时间
发布时间：2026/7/10 17:06:57
工作开发中一直在使用claude解决一些编码问题没有进行过系统了解。看下黄佳老师写的《claude code 工程化实战的笔记》课程才知道claude中有这么多门道这么多功能技巧。收益匪浅。以下是学习过程的笔记。学习完课程真的是太有帮助。完整课程内容https://blog.shenshuai.site/pages/3dde48 文章摘要本文是《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把它做成开箱即用的工程能力只需要一个配置就能创建有明确职责、受控权限的子代理SkillsAI应该什么使用什么技能。采用渐进式架构按需加载。Memory解决 Agent 每次对话都“从零开始”、不理解项⽬背景 的问题让 AI 真正记住你的代码结构、约束和上下⽂。Hooks解决 Agent 执⾏过程不可控、缺乏检查点、容易“越权 操作”的问题在关键节点引⼊⾃动校验和⼈⼯兜底。Headless解决 Agent 只能在 IDE ⾥交互、⽆法进⼊⾃动化流 程的问题让 AI 能在 CI/CD 中⽆⼈值守地运⾏。课程代码仓库链接 https://github.com/huangjia2019/claude-code-engingeering01CC底层概览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⽆头模式和 MCPModel ContextProtocol两⼤技术。编程接口层 Agent SDK当配置式的扩展不够⽤时你可以⽤代码来驱动 Claude。这种⽅ 式适合 构建⾃定义 Agent ——完全控制执⾏流程、⾃定义⼯具、 复杂⼯作流02CC的记忆系统CLAUDE.md 就是治疗这种失忆症的药。当项目目录启动claude code时发生的“记忆系统初始化”过程如下图Claude 每次对话都会重新“入职”——所以这份手册必须简洁有效。Claude Code 的五层记忆架构企业策略(/etc/claude-code/CLAUDE.md)用户级(~/.claude/CLAUDE.md)项目级(./CLAUDE.md或./.claude/CLAUDE.md)项目规则(.claude/rules/*.md)本地级(./CLAUDE.local.md)从上到下按层级结构组织——高层级的文件优先加载为底层文件提供基础重点说下rules这是一个比较高阶的技巧Rules 是按主题组织的规则文件支持条件作用域适合场景包括 CLAUDE.md 变得太长时不同文件类型需要不同规范时以及前后端分离的项目。例如目录结构.claude/ └── rules/ ├── typescript.md# TypeScript 规范├── testing.md# 测试规范├── api-design.md# API 设计规范└── security.md# 安全规范编写CLAUDE.md的原则原则 1Less is More原则 2具体优于泛泛原则 3关键三问题 WHY为什么要这样做 / WHAT 具体要做什么不要做什么 / HOW 按什么步骤去做原则 4渐进式披露不要把一切都塞进 CLAUDE.md03分而治之 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:Bashhooks: - type:commandcommand:./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的灵魂。# 代码审查 Skilldescription: Review codeforquality, security, and best practices. Checksforbugs, performance issues, and style violations. Use when the user asksforcode review, wants feedback on their code, mentions reviewing changes, or asks about code quality.# API ⽂档 Skilldescription: 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 needshelpwith OpenAPI/Swagger specs.# 数据库查询 Skilldescription: 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:!gitbranch --show-currentRecent commits on this branch:!gitlog origin/main..HEAD--oneline2/dev/null||echoNo commits ahead of mainFiles changed:!gitdiff--statorigin/main2/dev/null||gitdiff--statHEAD~311渐进式披露架构设计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、CSV12 Skills与SubAgent配合实战子代理中配置skills# ⼦代理在创建时预加载 Skill 作为领域知识--- name: api-doc-generator skills: - api-generating# 预加载 API ⽂档⽣成知识---skills中包含SubAgentSkill ⾃带任务指令Skill 包含 SubAgent通过 context: fork 派⼦代理去执⾏。该模式的适⽤场景是⼀个独⽴完整的任务不需要与主对话交互执⾏完把结果送回来就⾏--- name: codebase-research description: Deep research into codebase topics context: fork# 关键点agent: Explore --- Research$ARGUMENTSthoroughly想做⼀次代码质量扫描但不想让⼤量中间⽂件内容污染主对话。这正是 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-mcplatest]}}}创建自定义的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 CodeClaude Agent SDK-它把 Claude Code 的所有能⼒封装成了可编程的接⼝。你可以⽤ Python 或 TypeScript 编写代码像调⽤普通函数⼀样调⽤ AI Agent。通过调用SDK可以自动调用claude code的功能从命令⾏⼯具到可编程 SDKClaude 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 仓库项目代码参考https://github.com/huangjia2019/claude-code-engineering/tree/main/10-Plugins/projects/03-team-toolkit完整课程内容https://blog.shenshuai.site/pages/3dde48讲次范围内容推荐投入第 01-08 讲开篇 记忆 子代理 5 讲★★★★★ 必读,核心思维转变第 09 讲子代理专题总结★★★ 复习时回看第 10-15 讲Skills 6 讲(从基础到出圈)★★★★★ 必读,性价比最高第 16 讲Skills 专题总结★★★ 复习时回看第 17-25 讲Hooks/MCP/Tools/Headless/Rules/SDK/Plugins★★★★ 进阶,工程化必备
