企业官网建设流程全解析

“Claude Code 不就是个终端里的聊天机器人吗？让它改代码、跑命令，再高级一点也就是多轮对话。”如果你还停留在这种用法，那今天要聊的内容，可能会改变你对 AI 编程助手的定位。

最近有一期《Claude Code 高级实战》视频，用中英双语字幕逐个演示了 Claude Code 的高阶功能：子代理、技能、钩子、MCP、工作树、无头模式，一共九个演示点。标题看起来是“功能列表”，但如果只是把每个功能单独念一遍，价值不大。真正值得拆解的是这一层逻辑：这些功能组合在一起，解决的不是“AI 能不能写代码”，而是“AI 能不能在可控、可回滚、可审计、可自动化的工程流程里干活”。

这篇文章就是那期视频的配套图文版。我会把九个演示点归并成六大方向，逐个讲清楚：它是什么、解决什么问题、怎么配置、实际项目里怎么用、容易踩哪些坑。目标是让你看完之后，能照着在自己的项目里把子代理、技能、钩子、MCP、工作树和无头模式跑通，而不是只在视频里看过一遍。

1. 这篇文章真正要解决的问题

先说你最可能遇到的几个痛点。

第一，AI 一口气改了几十个文件，改完发现核心逻辑错了，想回到改之前的状态很麻烦。你只能依赖 Git，但 AI 生成的过程中往往伴随着大量中间提交，回滚起来并不干净。

第二，主对话里塞了太多跨模块的上下文。让 AI 同时处理前端页面、后端接口、数据库脚本，它会越聊越乱，甚至把 A 模块的代码风格带到 B 模块。

第三，你想让 AI 调用外部工具，比如查数据库、查 GitHub PR、查内部文档平台，但它默认只能读文件、执行命令，外部数据源进不来。

第四，AI 生成了代码，但没人把关。它可能写了不安全的正则、忘记处理空值、误删了生产配置，而你直到提交之后才发现。

第五，你想让它定时跑周报、在 CI 里自动修测试，但它是一个交互式终端工具，没有人的点击，它就无法开始。

这几个问题，正好对应 Claude Code 的六类能力：工作树管变更、子代理管分工、技能管知识沉淀、钩子管流程校验、MCP 管外部集成、无头模式管自动化落地。

所以这篇文章的读者画像也很清晰：已经在用 Claude Code 但觉得“不够可控”的开发者，想把 AI 编程工具接入团队工作流的工程负责人，以及正在调研 AI Agent 工程化的技术爱好者。零基础读者也能看，但建议先掌握 Claude Code 的基本对话用法。

2. Claude Code 功能全景与核心概念

在进入实操之前，先把概念边界划清楚。很多教程把子代理、技能、MCP 混在一起讲，容易造成误解。

Claude Code是 Anthropic 推出的终端原生 AI 编程代理。它不是一个 IDE 插件，而是直接跑在命令行里，能读取项目文件、执行命令、编辑代码，以你当前项目的目录作为工作上下文。

下面这张表可以快速建立全局认知：

如果把 Claude Code 比作一个外包开发团队，这个类比更容易理解：

• 子代理是团队里不同角色的专职工程师：有人负责 Code Review，有人负责写测试，有人负责数据库脚本。
• 技能是团队的 SOP 手册：每次生成 API 模块应该按什么步骤来、模板长什么样、哪些文件不能动。
• 钩子是监理：AI 每次准备调用工具时，先经过监理检查；监理说停，就必须停。
• MCP 是工具箱：让工程师能拿到外部系统的数据。
• 工作树是沙箱：先在一个隔离环境里改，确认没问题再合回来。
• 无头模式是值班机器人：不用人盯着，按脚本自动执行任务。

这个框架想说明一个核心判断：单独看任何一个功能，都只是一个小技巧；把它们组合起来，Claude Code 才从“问答工具”变成“可编程的工程代理”。

3. 环境准备与基础配置

这一节先把运行环境搭好。如果是第一次使用 Claude Code，下面几步是必须的。

3.1 运行环境

Claude Code 是一个 Node.js 命令行工具，所以电脑上需要先有 Node.js 环境。建议使用当前官方要求的 Node.js LTS 版本，具体版本号以官方文档和你的项目环境为准。macOS 和 Linux 下体验最顺；Windows 用户建议使用 WSL，避免路径和权限问题。

安装命令：

npm install -g @anthropic-ai/claude-code

安装完成后验证：

claude --version

如果提示claude: command not found，通常是 npm 全局 bin 目录没有加入 PATH，可以用npm prefix -g找到全局目录后手动加入。

3.2 登录与授权

进入 Claude Code：

claude

首次运行会引导登录。你可以使用 Claude 订阅账号，也可以使用 API Key。登录完成后，Claude Code 会在当前会话中记住身份。

这一节最容易忽视的是授权模式。Claude Code 读取文件、编辑文件、执行命令时，都需要权限。默认情况下它会逐个询问；也可以使用--permission-mode指定计划模式（plan）、只读模式（read-only）等。建议刚开始使用默认交互模式，等熟悉后再配置自动化。

3.3 项目级配置与 CLAUDE.md

在一个项目里使用 Claude Code，第一步不是写代码，而是创建.claude目录和CLAUDE.md文件。

CLAUDE.md是 Claude Code 的项目记忆文件。每次会话启动时，它会自动读取这个文件，相当于给 AI 一份“项目背景说明书”。

示例，文件路径CLAUDE.md：

# 项目背景 这是一个订单管理系统，前端使用 React + TypeScript，后端使用 Node.js + Fastify。 # 常用命令 - 启动开发服务：npm run dev - 运行测试：npm test - 代码检查：npm run lint # 代码约定 - 接口返回格式统一为 { code, data, message } - 所有数据库操作必须经过 src/db 目录下的封装函数 - 不允许直接修改 migrations 目录下的文件

写清楚技术栈、命令、约定，Claude Code 后续生成代码时就会遵循这些规则。从工程角度看，CLAUDE.md就是团队新人手册，只是阅读者从“新同事”变成了“AI 代理”。

4. 子代理实战：让 AI 先分工再执行

子代理是 Claude Code 非常核心的高级能力。它允许你定义多个有独立角色、独立工具权限、独立系统提示词的代理实例。

4.1 子代理解决了什么问题

在默认用法里，你只面对一个“全能主代理”。让它做代码审查，它会做，但问题是：它同时还要完成你之前的编码任务，对话上下文里可能还残留着上一个模块的需求描述。这种状态叫“上下文污染”。

子代理的思路是：把任务分给不同角色，每个子代理只加载自己的角色设定和工具，主对话的上下文不会被无关内容干扰。

4.2 如何定义一个子代理

子代理定义在.claude/agents/目录下，每个子代理是一个 Markdown 文件。

目录结构示例：

.claude/ agents/ code-reviewer.md test-writer.md

文件路径.claude/agents/code-reviewer.md：

--- name: code-reviewer description: 资深代码审查专家，擅长发现边界条件、安全问题、性能隐患。当需要审查代码质量时使用。 tools: Read, Grep, Glob model: claude-sonnet-4-5 --- 你是一名资深代码审查工程师。当你收到审查任务时，按以下步骤执行： 1. 先阅读目标文件，再阅读与之相关的依赖文件。 2. 重点检查以下问题： - 边界条件：空值、越界、并发写入。 - 安全问题：注入、越权、敏感信息泄露。 - 错误处理：异常是否被捕获，是否返回统一错误结构。 - 性能隐患：循环内是否有数据库查询或同步等待。 3. 输出评审意见时，按严重级别标注：Critical、Major、Minor。 ## 注意事项 - 只做审查，不直接修改代码。 - 如果发现 Critical 问题，必须明确说明触发路径。

参数说明：

• name：子代理名称，调用时使用@name。
• description：描述子代理擅长什么。主代理会根据描述决定是否自动委派任务。
• tools：允许子代理使用的工具白名单。这里限制它只能读文件、搜索文件，不能执行任意命令。
• model：可选，指定使用的模型。不同版本的可用模型不同，以你账号实际可用模型为准。

4.3 调用子代理

在 Claude Code 对话中直接通过@code-reviewer指定子代理：

@code-reviewer 请审查 src/api/user.ts，重点关注权限校验是否完整

也可以不显式指定，而是让主代理自己判断：“先让 code-reviewer 审查刚才修改的接口代码”。只要描述足够清晰，主代理会查阅子代理的 description，决定是否委派。

4.4 子代理实战建议

子代理不能太多。每个子代理即使不被调用，也会成为主代理决策时的一个候选，描述太多反而增加判断成本。建议按角色划分：代码审查、测试生成、数据库脚本、文档编写。

另外要注意，子代理也有自己的上下文窗口。如果你丢给它一个超大单文件让它“看完再评论”，它一样会截断。大文件先让主代理拆解，再把关键片段交给子代理。

一句话总结：子代理的本质是“上下文隔离 + 固定角色模板”。它把 AI 的多重能力拆成了多个可复用的专业角色。

5. 技能实战：把高频操作打包成可复用能力

技能和子代理很容易混淆。子代理是一个“角色”，技能是一套“做事流程”。你可以在技能里定义步骤、模板、脚本、注意事项，AI 遇到匹配任务时会主动加载这套流程。

5.1 技能目录与 SKILL.md

技能定义在.claude/skills/目录下，每个技能是一个子目录，目录里必须有SKILL.md。

目录结构示例：

.claude/ skills/ create-api-module/ SKILL.md templates/ controller-template.ts

文件路径.claude/skills/create-api-module/SKILL.md：

--- name: create-api-module description: 按团队规范创建一个完整的 API 模块，包含 Controller、Service、DTO 校验模块。当需要新增接口时使用。 --- ## 目标 创建一个符合团队规范的 API 模块，而不是临时拼装一段可运行但风格混乱的代码。 ## 实施步骤 1. 在 src/modules 下创建以模块名命名的目录。 2. 创建 controller 文件：继承 BaseController，路由前缀为 /api/{moduleName}。 3. 创建 service 文件：必须处理业务异常并返回统一 Result 结构。 4. 创建 dto 文件：所有入参必须使用 class-validator 装饰器。 5. 在模块 index.ts 中导出以上内容。 ## 模板位置 controller 模板位于 templates/controller-template.ts。 ## 约束 - 不要修改 database/migrations 目录下的文件。 - 不要生成超出需求范围的额外接口。 - 单元测试文件放在同一模块的 __tests__ 目录下。

5.2 使用技能

在对话中显式调用：

@create-api-module 帮我新增一个 user 模块，包含登录和注册两个接口

也可以不显式调用，而是把任务描述得足够具体。AI 会扫描技能的description，判断是否匹配当前任务。比如用户提出“帮我创建用户相关的 API”，主代理就可能加载create-api-module。

对比一下子代理和技能：

5.3 技能的工程价值

技能最有价值的一点，是它能把“团队规范”变成 AI 可执行的内容。以前新人加入项目，需要读几十页文档才能写出符合规范的接口；现在只要技能写得好，AI 生成出来的代码风格和团队模板基本一致。

但要注意，SKILL.md 不能太长。技能文件本身会被读进上下文，太长的技能文档会占用大量 token。建议控制在一次能读完的篇幅，核心步骤精炼，模板和脚本放在同目录资源里。

6. 钩子实战：在关键节点约束和校验 AI 行为

钩子是很多人最感兴趣、也最容易被低估的功能。它允许你在 Claude Code 生命周期中的关键节点执行外部命令，从而实现拦截、校验、通知、审计。

6.1 什么是钩子

简单说，钩子就是事件回调。当某个事件发生时，Claude Code 会执行你配置的命令，然后根据命令返回值决定是否继续。

常用事件包括：

• PreToolUse：AI 准备调用工具前触发，可用于拦截危险操作。
• PostToolUse：AI 调用工具之后触发，可用于自动格式化和审计。
• UserPromptSubmit：用户输入提示词之后触发。
• Stop：AI 完成一轮回复之后触发。

钩子配置在.claude/settings.json。先看一个项目级别的示例，文件路径.claude/settings.json：

{ "hooks": { "PreToolUse": [ { "matcher": "Read|Glob|Grep", "hooks": [ { "type": "command", "command": "bash .claude/scripts/guard-sensitive-files.sh" } ] } ] } }

6.2 拦截读取敏感文件

很多项目会把.env.production、密钥文件放在仓库里（这本身不规范，但现实如此）。现在用钩子禁止 AI 读取这类文件。

文件路径.claude/scripts/guard-sensitive-files.sh：

#!/usr/bin/env bash # 钩子命令会通过 stdin 收到 JSON 格式的工具调用信息 INPUT_JSON=$(cat) if echo "$INPUT_JSON" | grep -q "env.production"; then echo "{\"decision\": \"block\"}" else echo "{\"decision\": \"allow\"}" fi

这里的关键逻辑是：AI 准备调用Read、Glob、Grep工具时，先执行这个脚本；如果工具输入里包含env.production，脚本输出 block，工具调用被拦截。如果脚本输出 allow，则放行。

不同版本的 Claude Code 在 hook 输出格式上可能有差异，所以建议先在脚本里记录日志：

#!/usr/bin/env bash INPUT_JSON=$(cat) echo "[hook] $(date) $INPUT_JSON" >> /tmp/claude-hooks.log echo "{\"decision\": \"allow\"}"

然后手动触发一次 AI 操作，查看日志里的 JSON 结构，再根据实际格式调整拦截逻辑。这个做法既能用于调试，也能作为 AI 行为的审计留痕。

6.3 自动执行代码检查

另一个常见用法是：AI 每次写完文件后，自动执行 lint。

文件路径.claude/settings.json：

{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "bash .claude/scripts/run-lint-check.sh" } ] } ] } }

脚本内容可以按项目情况定制，比如只检查最近修改过的文件：

#!/usr/bin/env bash echo "AI 已完成文件修改，开始执行 lint 检查" npm run lint -- --quiet

这种钩子最大的价值是尽早发现问题。AI 生成的代码如果有 ESLint 报错，会在生成当下就被自动暴露出来，而不是等提交到 Git 之后才被 CI 拒绝。

从工程角度说，钩子让 AI 的行为有了“护栏”。没有护栏时，AI 是提意见的参谋；有了护栏，AI 变成了在既定规则下干活的员工。

7. MCP 实战：把外部工具和数据源接入工作台

MCP 全称是 Model Context Protocol，模型上下文协议。它定义了 AI 应用程序如何通过统一接口调用外部工具和数据源。

7.1 MCP 解决什么问题

默认情况下，Claude Code 能访问的是文件系统、命令终端、项目代码。但真实开发需要的外部数据源太多了：GitHub PR、数据库表结构、内部 API 文档、监控平台、Jira 工单。

如果没有 MCP，AI 只能“猜测”外部数据。有了 MCP，AI 可以直接调用外部系统提供的工具，拿到真实数据再决策。

一个通俗类比：MCP 是 AI 界的 USB 接口。以前每个设备（数据库、浏览器、CI 系统）都有自己的连接方式；现在它们都变成标准的 MCP Server，Claude Code 作为客户端，统一插上就能用。

7.2 配置 MCP Server

Claude Code 支持通过 CLI 添加 MCP Server。常用命令示例：

# 添加一个 HTTP 类型的 MCP Server claude mcp add github --transport http --url https://your-mcp-server.example.com/github # 添加一个本地 stdio 类型 MCP Server claude mcp add local-tools --transport stdio --command npx --args "-y" "@your-org/mcp-local-tools" # 查看已配置的 server claude mcp list

也可以使用项目级配置文件.mcp.json，方便团队共享：

{ "mcpServers": { "github": { "type": "http", "url": "https://your-mcp-server.example.com/github" }, "local-db": { "type": "stdio", "command": "npx", "args": ["-y", "@your-org/mcp-db-reader"] } } }

注意，MCP Server 的接入方式有 HTTP 和 stdio 两种，具体字段以你当前版本支持为准。配置完成后重启 Claude Code 会话，再通过claude mcp list验证。

7.3 怎么确认 MCP 生效

在 Claude Code 对话里直接提需要外部工具的任务：

用 github MCP 查看当前仓库最近的 5 个 Open PR，并总结变更内容

如果 MCP Server 已正常连接，AI 会调用该 server 提供的工具，而不是凭空猜测。你也可以在对话中问“你现在有哪些 MCP 工具可用”，AI 会列出当前会话已加载的工具清单。

7.4 MCP 的安全边界

MCP 是把双刃剑。它给 AI 带来外部能力的同时，也扩大了攻击面。一个不可信的 MCP Server 理论上可以读取 AI 传出的上下文、把外部数据混入决策。所以实际项目中要注意：

• 只接入可信组织维护的 MCP Server。
• 给 MCP Server 的权限遵循最小原则，能只读就不要读写。
• 不要把数据库高权限账号、云厂商密钥直接传给第三方 server。
• 在团队内部维护 MCP Server 清单，而不是让每个人随意添加。

8. 工作树与无头模式：版本控制与无人值守

把工作树和无头模式放在一起，是因为它们分别对应 AI 编程“可信”和“自动化”两个维度。

8.1 工作树：会话级变更沙箱

视频里提到的“工作树”，核心思想是：让 AI 在一个可回滚的文件变更集合里工作。AI 改完代码后，你可以先审查变更树，再决定保留还是丢弃。这相当于给 AI 的操作加了一层 Git 之外的会话级沙箱。

在 Claude Code 的使用中，有几种常见手段实现类似效果：

• 使用/rewind将会话内文件回滚到某个历史状态。
• 使用/clear清空上下文，避免旧状态影响新任务。
• 把每轮较大的修改放到独立 Git 分支上执行，确认无误后再合并。

实际项目中最推荐的做法是结合 Git。先创建一个专用分支，让 Claude Code 在该分支上完成修改，然后人工审查 diff：

git checkout -b feat/ai-generated-order-refactor claude "重构订单模块，把查询逻辑拆分为 service 层，保持接口不变" git diff --stat

这样做的优势是：AI 的修改被隔离在独立分支，即使改崩了也不会污染主分支；审查时可以像普通 PR 一样看 diff。如果团队有 Code Review 流程，AI 生成的代码依然要走正常评审。

真正的“工作树”如果是指 Claude Code 自身提供的变更管理能力，在使用时建议先查看当前版本的支持情况。但无论如何，AI 越能干，回滚手段越重要。这个原则不会变。

8.2 无头模式：无需交互的 CLI 调用

无头模式（headless mode）允许你通过纯命令行的方式调用 Claude Code，不进入交互式终端，直接输出结果。这是 Claude Code 接入脚本和 CI/CD 的关键。

一个最简单的无头模式调用：

claude -p "分析当前仓库里的 TODO 注释，按文件输出一个 Markdown 清单" --output-format text

-p代表 print/prompt，执行完直接退出。--output-format text表示纯文本输出。

如果需要结构化结果，可以指定 JSON 输出：

claude -p "读取 README.md，总结项目结构，输出 JSON" --output-format json > project-summary.json

无头模式在 CI 中的一个典型场景是自动修复测试：

#!/usr/bin/env bash set -euo pipefail npx @anthropic-ai/claude-code -p "运行 npm test，如果测试失败，修复失败用例并重新运行，直到通过。注意不要跳过测试" --allowedTools "Read,Edit,Bash,Grep" --permission-mode acceptEdits

注意，这里的--allowedTools和--permission-mode是权限约束参数。在无人值守环境中，没有人工确认环节，所以权限配置远比交互模式严格。建议先使用只读任务验证，比如生成周报、分析代码、整理文档：

claude -p "根据最近 7 天 git log 生成一份周报草稿" --allowedTools "Read,Bash"

8.3 无头模式的安全清单

无头模式越方便，越需要控制权限。以下几条直接写进团队规范：

• 只读任务不要放开 Edit 和 Bash 写操作权限。
• 必须在命令里显式声明--allowedTools白名单。
• 需要修改代码的任务，先跑在独立分支上。
• CI 日志可能包含 prompt，不要在 prompt 中传入密钥。
• 使用 API Key 认证时，把密钥存在 CI 平台的 Secret 中，不要写进命令历史。

9. 运行验证与常见问题排查

配置完成后，可以用下面这套验证清单确认功能是否生效。

9.1 验证清单

9.2 常见问题

排查时遵循一个原则：先确认是配置问题还是版本问题。配置问题看日志和文件路径；版本问题看claude --version和官方更新日志。

10. 最佳实践与工程建议

最后这组建议，是这套高级功能真正落地时最容易产生效果的部分。

10.1 CLAUDE.md 要持续维护

把 CLAUDE.md 当成团队文档来写。技术栈、目录结构、常见命令、命名规范、禁止事项，都可以沉淀进去。项目越大，CLAUDE.md 的收益越明显。建议在每次新功能开发前，先补丁式更新相关约定。

10.2 子代理按角色划分，技能按流程划分

一个团队级项目，建议先定义三到五个子代理：代码审查、测试生成、数据库脚本、文档编写。技能则围绕高频任务建设：新建 API 模块、接入新页面、生成单元测试、修改数据库迁移。子代理和技能的数量都控制在个位数，避免上下文开销膨胀。

10.3 钩子先记录，再拦截

不要第一天就写严格的 block 钩子。先做一个记录所有工具调用的日志钩子，运行几天，观察 AI 的真实行为模式，再针对高风险操作添加拦截。这比一开始就全副武装更符合实际情况。

10.4 MCP 交给团队维护

把.mcp.json纳入版本管理，MCP Server 列表由团队统一决策。开发者在本地新增临时 server 时，只用于调试，不写入共享配置。涉及数据库、内部系统的 MCP，必须有账号权限的最小化方案。

10.5 无头模式从小任务开始

先在 CI 里跑一个只读任务，比如生成变更摘要、整理 Todo 清单、生成周报。跑通之后再尝试“运行测试并修复失败用例”。每一步都增加一点权限，但始终保持独立分支和人工审查。

10.6 安全边界是最高优先级

无论功能多强大，有几条底线不要突破：

• 不要把生产密钥写进 prompt、CLAUDE.md 或技能文档。
• 不要让 AI 直接操作生产数据库。
• 不要让无头模式拥有超出任务范围的工具权限。
• 生产环境的任何变更，必须走 Git 分支、Code Review、部署流水线。

10.7 把 .claude 目录纳入版本库

.claude/下的子代理、技能、settings.json 都是团队资产，应该随项目一起版本化。但如果里面有本地路径、密钥或团队内部工具地址，需要在提交前过滤。可以在.gitignore中排除敏感文件，只保留通用配置。

10.8 综合配置示例

一个比较稳妥的项目级配置结构如下：

项目根目录/ CLAUDE.md .claude/ agents/ code-reviewer.md test-writer.md skills/ create-api-module/ SKILL.md templates/ scripts/ guard-sensitive-files.sh hook-logger.sh settings.json .mcp.json

这个结构既覆盖了可复用知识，也覆盖了审批流程和安全护栏。从零搭建时，不用一次配齐，可以先从CLAUDE.md和子代理开始，再逐步加入钩子和 MCP。

11. 总结：从“用 AI 聊天”到“让 AI 进工程流水线”

回到开头的问题：为什么这套高级功能值得专门写一篇长文？

因为 Claude Code 的真正分水岭，从来不是“能不能生成代码”，而是“生成完之后，代码能不能安全地进入你的工程系统”。子代理解决了角色分工，技能解决了流程统一，钩子解决了行为校验，MCP 解决了工具集成，工作树解决了变更回滚，无头模式解决了无人值守。六个方向合在一起，才构成一个完整的 AI 工程化闭环。

你不需要一次性把全部功能都用上。更现实的路线是：先用CLAUDE.md把项目背景写清楚，然后建一个code-reviewer子代理，再加一个记录日志的钩子，最后把无头模式接入一个只读的 CI 任务。等这条链路跑顺了，再继续扩展技能和 MCP。每一步都小、都稳，产生的问题也能快速定位。

文章里的配置示例，是基于当前 Claude Code 功能形态整理的通用手法。不同版本在字段名、事件名、CLI 参数上可能有细微差异，如果不是你预期中的行为，先查看claude --help和官方更新日志确认版本特性。建议把这篇收藏备用，下次在项目里接入 AI 代理工作流时，拿出来对着配置，能少走不少弯路。