《Claude Code工程化实战》--第 1 讲 与 AI 的共舞

本讲摘要本讲是整门课的导言、核心论点是Claude Code 与传统 AI 编程工具Copilot/Cursor/Windsurf存在范式差异——它不是更聪明的代码补全、而是一套以「Sub-Agents / Skills / Hooks / MCP / Headless / SDK / Plugins」为骨架的 AI 工程治理系统。课程目标是把 Claude Code 从「对话式 AI 工具」升级为「可持续运转的 AI 工程团队」。黄佳老师提出三个关键判断第一、AI 不会取代程序员、但会取代「不会用 AI 的程序员」第二、工程化才是 LLM 落地的瓶颈、不是模型本身第三、极客geek与 AI 的关系是「共生而非替代」——极客负责设计架构、设置边界、定义意图、AI 负责执行具体任务、提供全量知识、不知疲倦。课程适合所有想用 Claude Code 构建严肃产品的人从初学者到资深工程师、从单兵作战到团队管理。配套仓库 huangjia2019/claude-code-engineering 提供 10 章 226 个代码片段、配套书《Claude Code 实战》提供纸质深度阅读。 详细内容为什么这门课是「工程化」而不是「基础课」?市面上 90% 的 Claude Code 教程只讲「怎么用」安装、登录、敲斜杠、看输出。但当你真的要把 Claude Code 用在生产项目——一个 5 万行代码的微服务、一个需要审计日志的金融系统、一个有 20 人协作的团队——单靠「基础用法」会立刻碰壁。工程化解决的就是这些碰壁。它包含四个层面架构层怎么组织 SubAgent、Skill、Hook 的层次、治理层怎么约束权限、审计操作、回滚变更、协作层怎么让 Skills 库、Plugins 包在团队里复用、进化层怎么让 AI 系统随项目成长、而不是三个月后变成要重写的历史包袱。本课程不讲基础、基础默认你会本课程讲的是你手上的 Claude Code 怎么从「玩具」变成「基础设施」。「共生」关系的三层含义第一层含义能力互补。LLM 的强项是「通识 模式匹配 长上下文保持」、弱项是「精确性、实时性、本地知识」。极客正好反过来——知道项目架构、业务规则、代码风格、但容易疲劳、容易遗漏、不会同时跟踪 100 个文件。Claude Code 解决了「知识无穷但不会自动用」的问题、极客解决了「知识有限但会判断」的问题。第二层含义角色分工。极客是「指挥者 验收者」、AI 是「执行者 备选项」。Claude Code 提的代码永远只是「草稿」、最终由人 review 后合入。这不是低效、而是责任分配——生产环境的代码不能由 AI 直接 commit。第三层含义长期演化。AI 模型会越来越强、但项目的领域知识、合规要求、团队习惯是 AI 学不到的。极客的价值在于「把项目 DNA 沉淀成机器可读的形式」——CLAUDE.md / Skills / Hooks / Rules——让 AI 永远按团队的规矩办事。这就是「共生」的真正含义。课程地图九大模块 八个加餐九大模块按层次组织、从下到上是基础层——记忆CLAUDE.md、权限Rules、工具Tools。这是 Claude Code 的「宪法」、决定了它「知道什么、能做什么」。执行层——子代理SubAgents、技能Skills、命令Commands。这是 Claude Code 的「四肢」、决定了它「怎么被组织成团队」。治理层——Hooks、MCP。这是 Claude Code 的「神经系统」、决定了它「怎么被观察、怎么被扩展」。运行层——Headless、Agent SDK、Plugins。这是 Claude Code 的「运行模式」、决定了它「怎么脱离 IDE、怎么被嵌入其他系统、怎么被分发」。八个加餐覆盖五个维度直播回放全篇导览、热点加餐OpenClaw/Harness 等爆款产品分析、配套书精读、实战落地团队路线图、性能优化、安全治理、毕业项目。学习路径从单兵到团队课程推荐三条学习路径、对应三种角色路径 A使用者视角、推荐新手开篇词 → 记忆 → 子代理 → Skills → 命令 → 毕业项目。预计 4-6 周。学完后能用 Claude Code 独立完成中等复杂度的开发任务。路径 B工程化视角、推荐资深工程师在路径 A 基础上加 Hooks → MCP → Headless → Agent SDK → Plugins → 性能优化 → 安全治理。预计 6-8 周。学完后能设计企业级 Claude Code 部署方案。路径 C架构师视角、推荐 tech lead)在路径 B 基础上加直播回放、热点加餐OpenClaw/Harness、配套书精读、毕业项目。预计 8-12 周。学完后能主导团队 AI 化转型。三条路径在第 1 讲汇合——所有学员都需要先建立「Claude Code 不只是聊天工具」的认知。配套资源全景本课程有5类配套资源、定位不同官方课程极客时间 23 讲音频 文字、黄佳老师主理、讲概念、讲思路、讲取舍。本课程的「原声」。课程仓库github.com/huangjia2019/claude-code-engineering,12 个主题目录、226 个可运行代码片段。本课程的「代码」。配套书《Claude Code 实战》京东 item.jd.com/15374814.html),10 章纸质书。本课程的「深度阅读」。速查仓库github.com/shanraisshan/claude-code-best-practice、本仓库以「最佳实践」视角整理 Claude Code 全功能地图、擅长横向对比与架构选型。本课程的「参考视角」。本笔记仓库github.com/zhuligu/CC-Practice。5类资源互相补充课讲概念、仓库跑代码、书深读、仓库看对比。建议至少用其中两类。️ 实战代码 第 1 讲配套第一次安装 Claude Code 验证环境# 1. 安装 Claude Code(需要 Node 18)npminstall-ganthropic-ai/claude-code# 2. 验证安装(应该看到版本号 2.1.x)claude--version# 3. 登录账号(浏览器会跳出 OAuth 页面)claude auth login# 4. 在你的项目根目录运行cd/path/to/your-project claude# 5. 第一次跑通:让 Claude 介绍一下自己# 你能用一句话告诉我,在这个项目里我应该最先配置哪 3 个文件?# 预期回答:CLAUDE.md / .claude/settings.json / .mcp.json# 这三个就是课程第 2 讲(记忆)和第 19 讲(MCP)的主题 第 1 讲配套Windows 下的目录布局与配置Windows 用户最常被卡的三件事用户级配置在哪、项目级配置在哪、路径怎么写。下面三节是后续 30 讲会反复引用的速查参考。说明本节示例统一用 PowerShell 7自带的 5.1 不支持/||建议先winget install Microsoft.PowerShell升级。1. 用户级目录全局跨项目共享家目录~在 Windows 上是C:\Users\你的用户名\。Claude Code 把所有用户级数据写在C:\Users\you\.claude\C:\Users\you\.claude\ ├── CLAUDE.md ← 用户级全局入职文档所有项目都加载 ├── settings.json ← 用户级设置主题、模型、键位、Hook 注册 ├── .mcp.json ← 用户级 MCP server 注册 ├── memories\ ← Auto Memory跨会话记忆 │ └── *.md ← 每条记忆一个 .md ├── agents\ ← 用户级 SubAgent少见 ├── skills\ ← 用户级 Skills ├── commands\ ← 用户级 Commands ├── plugins\ ← 已安装的 Plugin │ └── plugin-name\ ├── projects\ ← 每个项目的会话历史按路径哈希分目录 ├── todos\ ← 任务列表持久化 ├── statsig\ ← 内部遥测缓存 └── shell-snapshots\ ← shell 状态快照⚠️ 用户级 vs 项目级90% 的「为什么换个项目设置又得重配」答案是你只配了项目级没配用户级或反过来。先建立这两个概念。PowerShell 一键查看Get-ChildItem-Force$env:USERPROFILE\.claude|Format-TableMode,LastWriteTime,Name2. 项目级目录只对当前项目生效随 git 走D:\projects\your-project\ ← 项目根 ├── CLAUDE.md ← 项目入职文档 ├── .mcp.json ← 项目级 MCP 配置 ├── .claudeignore ← 不让 Claude 读的文件清单 └── .claude\ ├── settings.json ← 项目级设置 ├── settings.local.json ← 本地个人覆盖 ├── agents\name.md ← SubAgent 定义 ├── skills\name\SKILL.md ← Skill每个一个子目录 ├── commands\name.md ← Command ├── rules\name.md ← Rule ├── hooks\name.ps1 ← Hook 脚本PowerShell ├── audit\ ← Hook 审计日志 └── state\ ← Skill / SubAgent 状态文件PowerShell 一键查看Get-ChildItem-Force.\.claude|Format-TableMode,LastWriteTime,Name3. 路径写法速查写 CLAUDE.md /.mcp.json/settings.json时常错场景推荐写法也可用备注家目录~Claude Code 自动展开$env:USERPROFILEPowerShell 命令行同样认~项目相对路径./src/api/.\src\api\配置文件统一用正斜杠绝对路径D:/projects/my-appD:\\projects\\my-appJSON 里反斜杠必须双写MCP server 命令node server.js靠 PATHC:\\Program Files\\nodejs\\node.exeJSON 中可执行文件路径同上JSON 内路径分隔/\\Node.js 在 Windows 上对/全兼容核心建议所有 Claude Code 配置文件CLAUDE.md/.mcp.json/settings.json/.claude/agents/*.md等统一用正斜杠/——能跨平台、避开 JSON 反斜杠转义、避开 PowerShell 字符串里\当转义符的坑。记住一句话在 Claude Code 的配置文件里把 Windows 当成 Linux 写路径。 第 1 讲配套项目根目录最小可运行 CLAUDE.md# CLAUDE.md —— 项目的「入职文档」 ## 项目目标 本项目是一个 XX 工具,服务于 YY 用户群体。 ## 关键技术栈 - Python 3.12 FastAPI - PostgreSQL 15 SQLAlchemy 2.0 - 前端 React 18 TypeScript ## 代码风格 - 遵循 PEP 8,行宽 100 - 优先使用类型注解 - 函数必须有 docstring ## 禁区 - 不要直接改 migration 文件 - 不要碰 src/billing/ 目录(交给财务团队) - 涉及 user_pii 字段时,先停下来问 ## 常用命令 - 测试: pytest -x - 启动 dev: docker compose up - 跑 lint: ruff check . 把这个文件放在项目根目录,Claude Code 每次启动会自动加载。 流程图┌─────────────────────────────────────────┐ │ 极客 · 指挥者 │ │ 设计架构 · 定义意图 · 设置边界 │ └─────────────────┬───────────────────────┘ ▼ ┌─────────────────────────────────────────┐ │ Claude Code 工程治理系统 │ │ │ │ ① 基础层 │ │ ┌──────────┐ ┌──────────┐ │ │ │ 记忆层 │ │ 权限层 │ │ │ │ CLAUDE.md│ │ Rules │ │ │ └──────────┘ └──────────┘ │ │ │ │ ② 执行层 · 四肢 │ │ ┌─────────┬─────────┬─────────┬──────┐ │ │ │SubAgents│ Skills │Commands │Hooks │ │ │ └─────────┴─────────┴─────────┴──────┘ │ │ │ │ ③ 扩展 / 运行层 │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ 扩展层 │ │ 运行层 │ │ │ │ MCP · Plugins│ │ Headless · SDK│ │ │ └──────────────┘ └──────────────┘ │ └─────────────────┬───────────────────────┘ ▼ 草稿代码待 review ▼ ┌─────────────────────────────────────────┐ │ 极客 · 验收者 │ └─────────────────┬───────────────────────┘ ▼ 责任分配 ▼ ┌─────────────────────────────────────────┐ │ 生产代码 │ └─────────────────────────────────────────┘ 对比表维度传统 AI 编程工具Claude Code本课程定位更聪明的代码补全AI 工程治理系统架构核心IDE 插件 LLMCLI SubAgents Skills Hooks扩展机制API/插件市场MCP Plugins 自定义 Skill自动化能力单次对话Headless 模式 Agent SDK团队协作各自为战Plugins 共享 团队 Skills 库生产可用需要大量后期处理Hook 审计 Rules 权限 自动测试⚠️ 常见坑⚠️ 把 Claude Code 当 Copilot 用如果你只把它当「代码补全工具」、那你只用了 5% 的能力。Claude Code 的核心价值在于 SubAgent 编排、Skill 沉淀、Hook 审计——这些是 Copilot 没有的。一旦你开始用 Skills 沉淀团队 SOP、用 Hooks 自动跑测试、LTV 立刻上去。⚠️ 只读课程不跑代码本课程 33 讲里有 25 讲带实战代码或工程项目。代码不跑起来、概念永远停在「听懂了」。建议每讲结束后用 30-60 分钟亲自跑一遍配套仓库里对应的项目。哪怕只跑通 1/3、也比纯读收获大 10 倍。⚠️ 跳过前 8 讲直接学 SDKAgent SDK 是高级主题、但它依赖前 8 讲讲的子代理、Skills、命令等基础。跳读会看不懂 SDK 示例代码的「为什么」。如果时间紧、至少把第 4 讲分而治之、第 10 讲Skills 基础、第 17 讲Hooks看完再碰 SDK。⚠️ 在生产环境用默认配置本课程第 17-18 讲Hooks和第 22 讲Rules是生产必备。第 32 讲安全治理给出了完整的企业级部署清单。在没配置 Hook 审计、权限收窄、API Key 隔离前、不要让 Claude Code 直接碰生产数据库。 一句话预告这门课的目标不是教你用 Claude Code、而是让你从「AI 工具使用者」蜕变为「AI 工程团队指挥者」——这是 2025-2026 年程序员最稀缺的转型。