📌 本讲摘要

本讲是整门课的导言、核心论点是：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+)
npm install -g @anthropic-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-Table Mode, LastWriteTime, Name

2. 项目级目录（只对当前项目生效，随 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-Table Mode, LastWriteTime, Name

3. 路径写法速查（写 CLAUDE.md / .mcp.json / settings.json 时常错）

场景	推荐写法	也可用	备注
家目录	~（Claude Code 自动展开）	$env:USERPROFILE	PowerShell 命令行同样认 ~
项目相对路径	./src/api/	.\src\api\	配置文件统一用正斜杠
绝对路径	D:/projects/my-app	D:\\projects\\my-app	JSON 里反斜杠必须双写
MCP server 命令	node server.js（靠 PATH）	"C:\\Program Files\\nodejs\\node.exe"	JSON 中可执行文件路径同上
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 插件 + LLM	CLI + 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 讲直接学 SDK

Agent 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 年程序员最稀缺的转型。

---