用好 Agent 的关键：用 CLAUDE.md 建立分层约束体系

用好智能体（Agent）的关键，往往不是再多学几个 Prompt（提示词）技巧，也不是给它安装更多 Skills，而是先把工作边界、目录规则、命名方式、验证流程写清楚。

四个字概括就是：约束先行。

Agent 很擅长执行局部任务，但它不会天然理解一个工作区应该如何长期演进。如果没有规则，它会倾向于立刻开始干活：生成文件、创建临时脚本、保存测试结果、写报告、改代码。短期看效率很高，过几天再打开目录，就可能发现源码、压缩包、测试图片、评估报告混在一起，test_v2、new_test、final_final 这类名字到处都是。

问题不在于 Agent 不够聪明，而在于它没有可持续读取的制度。

人的脑子里知道“测试文件应该放到 tests 目录”“实验材料应该进 sandbox”“报告应该有固定命名”，但如果这些要求没有写进 Agent 会加载的文档里，对 Agent 来说就等于不存在。

约束先行解决的不是一次任务，而是长期协作

Agent 的一次对话能力再强，也很难天然维护一个项目几周甚至几个月的秩序。因为它每次进入工作区时，能稳定依赖的通常只有几类信息：

• 当前对话里的上下文；
• 工作目录里的文件；
• 工具自身加载的规则文件；
• 记忆系统或历史任务记录。

对话上下文是短期的，窗口关掉、任务切换、上下文压缩之后，很多细节都会丢。真正能跨任务留下来的，是那些写在文件里的规则。

这就是 CLAUDE.md 这类规则文件的价值。它不是普通说明文档，而是 Agent 进入某个范围后必须遵守的工作准则。

可以把它理解成项目里的“制度层”：

flowchart TD
    A[用户需求] --> B{当前工作区有规则吗}
    B -- 没有 --> C[先创建 CLAUDE.md 和目录约定]
    B -- 有 --> D[读取并遵守现有规则]
    C --> E[按规则执行任务]
    D --> E
    E --> F[运行验证或检查]
    F --> G{规则需要调整吗}
    G -- 需要 --> H[先更新规则文档]
    H --> I[再修改实践和文件结构]
    G -- 不需要 --> J[保留产物并更新必要记录]

“约束先行”不是让 Agent 少做事，而是让它在正确的边界内做事。它的核心原则可以写成三句话：

1. 新工作区先建规则，再开始产出。
2. 已有规则的工作区，严格按规则执行。
3. 规则要改时，先改文档，再改文件和代码。

第三点很关键。规则不是一成不变的，但规则的变化也要被记录。如果 Agent 为了完成眼前任务临时绕过约定，事后再补文档，很容易补不完整，项目会逐渐变成“看起来有规范，实际没人遵守”的状态。

Skills 提升能力，约束决定行为

Skills 可以让 Agent 会做更多事情，比如处理图片、生成报告、调用特定工具、执行固定流程。但 Skills 解决的是“能不能做”，约束解决的是“应该怎么做”。

两者的区别很明显：

一个没有约束的高能力 Agent，就像一个执行力很强但不看制度的人：它能快速产出很多东西，也能快速制造很多后续整理成本。

规则应该分层，而不是全塞进一个文件

很多 Agent 工具都支持类似的规则加载方式。以 Claude Code 为例，常见规则可以分成几层：

flowchart TB
    G[全局 CLAUDE.md<br/>长期协作原则、沟通方式、安全底线]
    P[项目级 CLAUDE.md<br/>项目目标、目录结构、命令、命名规范]
    D[设计与规范文档<br/>架构说明、接口约定、数据结构、决策记录]
    M[任务记录 / Memory<br/>阶段状态、历史上下文、待办事项]

    G --> P
    P --> D
    D --> M

每一层负责不同范围的约束：

全局规则越往上，越应该稳定、抽象、少而精。项目规则越往下，越应该具体、可执行、能直接指导文件如何摆放、命令如何运行。

全局 CLAUDE.md 应该写什么

全局规则的作用不是管理某一个项目，而是告诉 Agent：无论进入哪个工作区，都要用什么方式协作。

一份可用的全局 CLAUDE.md 可以包含这些部分：

# 全局协作规则

## 工作语言

- 默认使用中文交流。
- 代码、命令、变量名、文件名使用英文。
- 解释技术决策时，优先说明原因、影响和风险，不只给实现步骤。

## 思考方式

- 从问题本身出发，不因为惯例存在就直接照搬。
- 如果需求模糊，先给出最合理的默认方案，再指出需要确认的关键点。
- 不进行无意义赞美，不用“这是个好问题”作为开场。
- 发现方案有风险时直接说明，并给出替代方案。

## 约束先行

- 进入新项目或新工作区时，先检查是否存在 CLAUDE.md。
- 如果没有项目规则，不要直接开始大量创建文件，先建立最小可用规则。
- 新目录需要先定义用途、命名方式和清理策略。
- 已有项目规则时，严格遵守项目 CLAUDE.md。
- 如果实践需要改变，先更新规则文档，再调整目录、代码或脚本。

## 开发习惯

- 修改代码后主动运行可用验证，例如 test、lint、build。
- 不通过注释错误代码来掩盖问题，要定位根因。
- 密钥、token、密码不得写入代码、日志或文档。
- 涉及破坏性操作时，先说明影响范围并等待确认。

## 交互体验

- GUI、CLI、对话流程和自动化脚本都属于用户体验。
- 优先让系统承担复杂性，能自动推断的不要让用户手动输入。
- 错误提示要给出下一步行动，而不只是报告失败。
- 默认展示核心信息，细节按需展开。

这类全局规则不需要写得很长。写太多会带来两个问题：Agent 抓不住重点；后续项目规则和全局规则容易互相打架。

好的全局规则应该像“宪法”，只管长期原则和底线。具体项目怎么构建、报告放在哪里、测试命令是什么，都应该交给项目级规则。

项目级 CLAUDE.md 要具体到能执行

项目级规则要比全局规则具体得多。Agent 进入项目后，应该能通过它知道：

• 项目是做什么的；
• 哪些目录可以放源码，哪些目录放临时文件；
• 新文件如何命名；
• 开发、测试、构建、部署命令是什么；
• 哪些操作必须先确认；
• 实验产物何时清理；
• 文档更新有什么要求。

例如，一个用于开发 Agent Skills 的工作区，可以这样设计：

agent-skills-workspace/
├── CLAUDE.md              # 项目级规则
├── skills/                # 正式 Skill 源码
│   └── image-resizer/
├── packages/              # 打包产物
├── reports/               # 评估报告、测试结果
├── docs/                  # 设计说明和规范
├── tests/                 # 自动化测试脚本和测试数据
└── _sandbox/              # 临时实验区，可定期清理

对应的 CLAUDE.md 可以这样写：

# Agent Skills 工作区规则

## 工作区目标

本项目用于开发、测试和评估 Agent Skills。所有正式 Skill 必须放入 `skills/`，临时实验只能放入 `_sandbox/`。

## 目录约定

- `skills/<skill-name>/`：正式 Skill 源码，每个 Skill 一个独立目录。
- `tests/<skill-name>/`：对应 Skill 的测试脚本和测试数据。
- `reports/<skill-name>/`：评估报告、运行结果、截图说明。
- `packages/`：打包产物，文件名必须包含 Skill 名称和版本号。
- `_sandbox/`：临时验证材料，超过 30 天可以清理。
- `docs/`：长期设计文档、规范说明、决策记录。

## 命名规则

- Skill 目录使用 kebab-case，例如 `image-resizer`。
- 测试文件使用 `<skill-name>.test.<ext>`。
- 报告文件使用 `<skill-name>-evaluation-YYYY-MM-DD.md`。
- 禁止使用 `test_v2`、`new_test`、`final`、`temp` 这类无法表达归属的名称。

## 新建 Skill 流程

1. 在 `skills/<skill-name>/` 创建源码目录。
2. 在 `tests/<skill-name>/` 创建测试材料。
3. 在 `reports/<skill-name>/` 保存评估结果。
4. 如果需要临时验证，放入 `_sandbox/<skill-name>/`。
5. 完成后更新必要文档，不把临时文件混入正式目录。

## 验证要求

- 修改正式 Skill 后，必须运行对应测试。
- 如果测试无法运行，需要记录原因和替代验证方式。
- 打包前检查源码、测试、报告是否分别放在正确目录。

## 修改规则

如果现有目录结构无法满足新需求，先修改本文件，再调整已有文件。

这种规则的价值在于它足够具体。Agent 不需要猜“测试结果放哪”，也不需要临时发明命名方式。它只要按制度执行即可。

一次任务应该如何启动

有了规则文件后，任务启动方式也要改变。不要一上来就让 Agent “帮我实现某某功能”，而是让它先确认约束环境。

可以使用这样的任务开场：

请先检查当前工作区的 CLAUDE.md 和相关 docs，不要直接修改代码。
确认项目规则、目录结构、测试命令后，再给出执行计划。
如果发现当前任务缺少规则约束，先补充最小规则文档，再继续实现。

对于全新的目录，可以直接要求 Agent 建立规则：

这是一个新的 Agent Skills 工作区。
请先不要开发具体 Skill，先完成三件事：

1. 设计目录结构；
2. 创建项目级 CLAUDE.md；
3. 说明后续新增 Skill、测试材料、报告、打包产物分别应该放在哪里。

规则完成后再等待我确认。

这样做会牺牲最开始的几分钟，但能避免后续大量整理成本。尤其是知识管理、研究报告、实验评估、素材处理这类非代码项目，更需要显式规则，因为它们不像软件工程项目那样天然有 src/、tests/、docs/ 的习惯结构。

约束要覆盖开发，也要覆盖知识管理

很多人只在代码项目里写规则，研究、写作、画图、资料整理、报告生成时就随手让 Agent 干活。结果代码项目还算整齐，知识类工作区却很快变乱。

Agent 做知识管理时同样需要约束。例如：

research-workspace/
├── CLAUDE.md
├── sources/          # 原始资料
├── notes/            # 拆解笔记
├── outlines/         # 提纲
├── drafts/           # 草稿
├── reports/          # 最终报告
└── archive/          # 已完成项目归档

对应规则可以写清楚：

# 研究工作区规则

## 资料处理

- 原始资料只能放入 `sources/`，不要直接改写。
- 拆解后的要点放入 `notes/`。
- 结构化提纲放入 `outlines/`。
- 草稿放入 `drafts/`。
- 可交付版本放入 `reports/`。

## 命名规则

- 文件名使用英文小写和连字符。
- 每个研究主题使用独立目录。
- 不使用 `new`、`final`、`copy` 作为版本标识。
- 日期写入文件名时使用 `YYYY-MM-DD`。

## 工作流程

- 先整理资料索引，再写提纲。
- 没有提纲时不要直接生成长报告。
- 最终报告生成后，将中间材料归档到对应主题目录。

Agent 并不会自动知道“研究工作流”和“开发工作流”有什么区别。只要任务长期存在、会产生多个文件、未来还要复用，就应该有项目级规则。

规则冲突时怎么处理

分层规则带来一个常见问题：全局规则和项目规则冲突怎么办？

推荐原则是：全局规则管底线，项目规则管细节。

例如：

项目规则可以覆盖实现细节，但不能突破全局安全底线。全局规则也不应该管太细，否则不同项目会被同一套僵硬规则限制。

不要把全局 CLAUDE.md 写成杂物间

全局规则最容易犯的错，是把所有经验都往里面塞。每踩一个坑就加一段，几个月后文件变得又长又乱，Agent 每次加载都要读大量不相关内容。

更好的做法是定期整理规则，把它们分到正确层级：

一个简单判断标准：如果这条规则对所有项目都成立，放全局；如果只对当前项目成立，放项目；如果只对当前任务成立，放任务记录。

约束先行的落地清单

每次让 Agent 进入一个新目录，可以按这个清单检查：

## Agent 工作区启动清单

- [ ] 当前目录是否存在 CLAUDE.md？
- [ ] 是否写清楚项目目标？
- [ ] 是否写清楚目录结构？
- [ ] 是否写清楚文件命名规则？
- [ ] 是否写清楚测试、构建或验证命令？
- [ ] 是否写清楚临时文件放哪里、何时清理？
- [ ] 是否写清楚哪些操作需要确认？
- [ ] 是否说明规则变更必须先更新文档？

如果任意一项缺失，就不要急着让 Agent 生成大量产物。先补规则，再执行任务。

什么时候不需要重规则

约束不是越重越好。一次性的小实验、临时问答、不会落盘的代码片段，不一定需要完整规则体系。规则的重量应该和任务的持续时间、产物数量、风险等级匹配。

规则的目的不是制造流程负担，而是减少返工。只要任务会反复发生，规则就会回本。

最重要的一条原则

Agent 不会自动继承人脑里的秩序感。你没写出来的规则，它就不会稳定遵守。

所以，真正可执行的协作方式不是“每次都提醒它小心一点”，而是把提醒沉淀成文件，让 Agent 每次进入工作区都能读取、理解、执行。

全局 CLAUDE.md 是主干道，项目 CLAUDE.md 是支路，设计文档和任务记录是路牌。路网先规划好，后面的开发、研究、写作、测试、归档才不会一路长歪。

一句话记住：没有规范的工作空间，不要让 Agent 直接动手。