# 把 Claude Code 当成分层 Agent 系统：从项目记忆到自动化治理的实操教程

> 本文整理自 MarkTechPost《Claude Code Guide 2026: 25 Features with Examples + Demo》。原文作者：Michal Sutter。  
> 原文链接：https://www.marktechpost.com/2026/06/14/claude-code-guide-2026-25-features-with-examples-demo/  
> 说明：本文是面向工程实践的教程化改写，不是 Anthropic 官方文档。命令和配置请以当前 Claude Code 官方文档为准。

## 适合谁读

如果你已经把 Claude Code 当作“能帮我写代码的终端助手”使用，这篇教程的目标是帮你升级到下一层：把它当成一个**可配置、可拆分、可审计、可回滚的 Agent 开发系统**。

读完后你应该能回答三个问题：

1. 项目规则应该放在 `CLAUDE.md`、Skill、Subagent、Hook 还是 MCP？
2. 哪些任务适合让 Claude Code 自动做，哪些必须保留审批？
3. 如何给团队搭一个最小但可维护的 Claude Code 工作流？

## 先建立一个心智模型：Claude Code 不是一个提示词

原文最有价值的观点是：Claude Code 已经不是单一的终端聊天工具，而是由多层能力组成的 agentic system。

可以这样理解：

| 层级 | 解决的问题 | 典型组件 |
|---|---|---|
| 项目记忆层 | 让 Claude 知道这个仓库怎么工作 | `CLAUDE.md` |
| 可复用流程层 | 把重复任务沉淀成可调用流程 | Skills、Slash Commands |
| 任务拆分层 | 把探索、审查、分类等工作隔离出去 | Subagents |
| 安全治理层 | 用确定性脚本拦截危险动作 | Hooks、Permission Modes、Sandbox |
| 外部工具层 | 接入 GitHub、数据库、浏览器等系统 | MCP Servers |
| 分发层 | 把一组规则和工具打包给团队复用 | Plugins |
| 自动化层 | 在 CI、定时任务或无 TTY 环境中运行 | Headless CLI、Agent SDK |

不要把所有规则都写进一个巨大的提示词里。更好的做法是：**规则进规则层，流程进流程层，工具进工具层，风险控制进治理层。**

## 第一步：用 `CLAUDE.md` 固定项目默认行为

`CLAUDE.md` 是项目级记忆文件。它适合放稳定、长期有效、每次会话都应该知道的信息。

适合写入：

- 构建、测试、Lint 命令；
- 项目目录结构；
- 代码风格；
- 提交格式；
- 禁止事项；
- 重要安全边界。

不适合写入：

- 临时任务进度；
- 一次性 bug 排查记录；
- 大段业务背景；
- 会频繁变化的计划。

示例：

```markdown
# Project: my-tool

## Build
npm run build

## Test
npm test

## Conventions
- TypeScript strict mode
- No default exports
- Commit format: feat/fix/chore(scope): description

## Safety Boundaries
- Do not run destructive database commands without confirmation.
- Do not commit secrets or local environment files.
- Run tests before reporting completion.
```

验证标准：

- 新开一个 Claude Code 会话后，它能主动遵守项目命令和约束；
- 它不会在不知道测试命令时乱猜；
- 它能在提交或修改前复述关键安全边界。

## 第二步：把重复任务做成 Skill

Skill 适合封装“有固定流程、会反复出现、需要说明上下文”的任务。例如：代码审查、发布检查、故障复盘、接口文档生成。

一个最小 Skill 可以长这样：

```markdown
---
name: code-review
description: Review changed files against our team standards.
---

Review staged changes.

Checklist:
1. Identify correctness risks.
2. Check security-sensitive changes.
3. Verify tests or explain missing coverage.
4. Suggest concrete fixes.

Output format:
- Blocking issues
- Non-blocking suggestions
- Verification evidence
```

使用建议：

- Skill 里写流程，不要写临时任务状态；
- 如果需要附带脚本、模板、参考资料，把它们放在 Skill 目录里；
- 对复杂 Skill，最好加入“何时使用 / 何时不用 / 验证标准”。

判断是否该做成 Skill：

| 情况 | 建议 |
|---|---|
| 一次性问题 | 不做 Skill |
| 同类任务每周都会出现 | 做 Skill |
| 任务步骤超过 5 步且容易漏 | 做 Skill |
| 需要团队统一口径 | 做 Skill 或 Plugin |

## 第三步：用 Subagent 隔离高噪声任务

Subagent 的价值不是“更聪明”，而是**隔离上下文和风险**。

适合交给 Subagent 的任务：

- 读大量文件做代码地图；
- 独立审查一个模块；
- 对多个方案做并行调研；
- 分类大量反馈；
- 汇总日志或测试失败模式。

不适合交给 Subagent 的任务：

- 需要主线持续决策的高风险改动；
- 需要用户实时确认的操作；
- 需要持有凭证或直接改生产系统的任务。

只读探索 Subagent 示例：

```markdown
---
name: explorer
description: Read-only codebase exploration.
tools: Read, Grep, Glob
---

Map the repository structure and summarize entry points.
Do not edit files.
Do not run commands with side effects.
Return:
1. Main modules
2. Test layout
3. Risky areas
4. Suggested next inspection targets
```

验证标准：

- Subagent 输出的是路径、证据和结论，而不是泛泛建议；
- 它没有编辑文件；
- 主会话只接收摘要，不被大量中间日志污染。

## 第四步：用 Slash Command 做轻量入口

Slash Command 适合做“快速插入的提示模板”。如果任务只是固定话术，不需要附带文件和复杂逻辑，用 Slash Command 就够了。

例子：

```text
/review
/security-review
/context
/compact
/init
```

经验规则：

| 需求 | 选什么 |
|---|---|
| 只是触发一个固定提示 | Slash Command |
| 有一套流程和判断标准 | Skill |
| 需要独立上下文执行 | Subagent |
| 需要执行确定性校验 | Hook |
| 需要连接外部系统 | MCP |
| 要发给团队统一安装 | Plugin |

## 第五步：用 Hook 把安全规则从“提醒”变成“拦截”

只靠提示词提醒模型“不要做危险操作”是不够的。Hook 的价值在于：它可以在生命周期事件上运行确定性脚本。

原文强调 `PreToolUse` 是重要安全检查点。一个典型用途是：在 Bash 命令执行前调用 `scripts/guard.sh`。

示例配置：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "scripts/guard.sh" }
        ]
      }
    ]
  }
}
```

`guard.sh` 可以检查：

- 是否包含 `rm -rf`、`DROP DATABASE`、`kubectl delete` 等危险动作；
- 是否访问生产数据库；
- 是否尝试读取或提交密钥；
- 是否绕过测试或禁用安全检查。

建议策略：

| 风险等级 | 处理方式 |
|---|---|
| 明显安全命令，如读文件、跑单元测试 | 放行 |
| 可能有副作用，如安装依赖、改配置 | 要求确认 |
| 高风险或不可回滚，如删库、删集群资源 | 拒绝或强制人工审批 |

## 第六步：通过 MCP 接外部系统，但不要把权限放太大

MCP Server 让 Claude Code 连接 GitHub、数据库、浏览器、文件系统等外部系统。

原文示例：

```bash
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects
claude -p "List the largest files under src and explain why" --output-format json
```

使用 MCP 的核心不是“能接多少工具”，而是“每个工具的权限边界是否清楚”。

建议清单：

- 文件系统 MCP 只暴露必要目录；
- 数据库 MCP 默认只读；
- GitHub MCP 区分读权限、评论权限、合并权限；
- 浏览器 MCP 不默认带登录态执行敏感操作；
- 所有会修改外部状态的工具都需要审批或审计日志。

## 第七步：用 Plan Mode、Permission Modes、Checkpoints 控制改动风险

Claude Code 的自动化能力越强，越需要明确的刹车系统。

推荐工作流：

1. **Plan Mode**：先让 Claude 探索、列计划，不改文件；
2. **人工确认范围**：确认目标、影响文件、回滚方式；
3. **小步执行**：一次只改一组相关文件；
4. **测试验证**：跑最小必要测试；
5. **Checkpoint / Git Diff**：每一步都能回退；
6. **复盘沉淀**：可复用流程再写入 Skill 或项目文档。

适合自动执行的任务：

- 代码格式化；
- 低风险重命名；
- 只读分析；
- 测试失败归因；
- 文档生成草稿。

必须保留确认的任务：

- 数据库变更；
- 生产配置；
- 删除资源；
- 依赖升级；
- CI/CD 权限变更；
- 带凭证的外部系统调用。

## 第八步：把 Headless CLI 用在 CI 和定时任务中

Headless CLI 的价值是让 Claude Code 在无交互环境中做一次性任务，例如 PR 审查、日志总结、定时扫描。

原文给出的形式是：

```bash
claude -p "List the largest files under src and explain why" --output-format json
```

适合场景：

- 每个 PR 自动总结变更；
- 每晚扫描 flaky test；
- 发布前检查 changelog；
- 定时汇总错误日志。

但要注意：CI 里的 Agent 更需要硬边界。

最小治理建议：

- 输出 JSON，便于机器检查；
- 默认只读；
- 不允许自动合并；
- 对外部 API 和生产系统禁写；
- 失败时给出证据路径，不要只输出“看起来没问题”。

## 一个最小可落地方案

如果你想把 Claude Code 从“个人助手”升级成“团队可复用工具”，可以先做这 5 件事。

### 1. 建一个项目级 `CLAUDE.md`

包括：

- 项目简介；
- 构建 / 测试 / Lint 命令；
- 编码规范；
- 安全红线；
- 完成定义。

### 2. 建两个 Skill

建议从这两个开始：

- `code-review`：审查 diff、风险、测试覆盖；
- `debug-failure`：从失败日志定位根因并给修复建议。

### 3. 建一个只读 Subagent

用于代码地图、模块探索、日志归因，工具权限只给读操作。

### 4. 配一个 `PreToolUse` Hook

至少拦截危险 Bash 命令和生产资源操作。

### 5. 把 CI 场景先做成只读报告

不要一上来让 Agent 自动修复、自动提交、自动合并。先让它生成结构化报告，等质量稳定后再逐步扩大权限。

## 常见错误

### 错误 1：把所有上下文都塞进 `CLAUDE.md`

`CLAUDE.md` 应该放稳定规则，不应该变成日志仓库。临时任务状态应留在当前会话、issue、PR 或任务文档中。

### 错误 2：用 Skill 代替权限治理

Skill 是流程说明，不是安全边界。危险操作要靠 Hook、Permission Mode、Sandbox、审计日志和人工确认。

### 错误 3：Subagent 没有限权

如果探索型 Subagent 也能写文件、跑命令、访问外部系统，就失去了隔离价值。探索任务默认只读更安全。

### 错误 4：把 MCP 当万能入口

MCP 接得越多，攻击面越大。每个 MCP 都应该回答：谁拥有它、能做什么、默认是否只读、失败如何审计。

### 错误 5：过早相信 Auto Mode

原文把 Auto Mode 标注为 research preview。它可以减少摩擦，但不能替代生产级审批、测试和回滚机制。

## 落地检查表

- [ ] 项目有 `CLAUDE.md`，且包含真实构建、测试、Lint 命令。
- [ ] 重复任务已拆成 Skill，而不是散落在聊天记录里。
- [ ] 探索/审查类任务有只读 Subagent。
- [ ] Bash 或外部工具调用前有 Hook 或审批边界。
- [ ] MCP Server 权限最小化，敏感工具默认不自动执行。
- [ ] CI/headless 场景默认只读输出报告。
- [ ] 每次自动化改动都有测试证据和回滚点。
- [ ] 社区实践和第三方工具没有被当成官方保证。

## 结论

Claude Code 的关键不是“多会写代码”，而是它已经提供了构建工程化 Agent 工作流的多个层次：记忆、技能、子 Agent、钩子、外部工具、插件、自动化入口和安全边界。

真正可维护的用法不是让模型拥有无限权限，而是把能力拆层：

- 用 `CLAUDE.md` 固定项目规则；
- 用 Skill 固化重复流程；
- 用 Subagent 隔离复杂探索；
- 用 Hook 和权限模式守住安全边界；
- 用 MCP 接工具但限制权限；
- 用 Headless CLI / SDK 做自动化，但从只读报告开始。

这样 Claude Code 才更像一个可治理的开发系统，而不是一个随时可能跑偏的聊天窗口。

## 来源与边界

- 原文：MarkTechPost《Claude Code Guide 2026: 25 Features with Examples + Demo》
- 作者：Michal Sutter
- 链接：https://www.marktechpost.com/2026/06/14/claude-code-guide-2026-25-features-with-examples-demo/
- 本文性质：教程化整理，部分“落地建议”为基于原文的工程化改写。
- 风险提示：涉及 Claude Code CLI 参数、Hook 配置、MCP 命令时，请以当前官方文档和本地版本为准；生产环境操作必须保留审批、审计和回滚。