DeepSeek Harness AGENTS.md：项目指令文件怎么写
2026-08-16 13:15:15阅读 4
想让 agent 在每个会话都遵守某些规则——"别改 src 下的文件""测试必须跑 pytest""代码风格遵循公司规范"——就写进 AGENTS.md。这是 DSH 的"工作区指令"机制：一份放在项目里的说明书，agent 每次开工前自动阅读。
AGENTS.md 是什么
一个 Markdown 文件，内容是你给 agent 的长期指令。DSH 在会话开始时把它自动注入对话上下文，agent 全程可见、全程遵守。
和"你在聊天框里说的话"的区别：聊天指令是一次性的，AGENTS.md 是持久的——每个新会话都会自动加载，不用每次重复交代。
放哪里：按目录层级生效
DSH 按"从全局到局部"的顺序加载指令文件：
- $DSH_HOME/AGENTS.md # 全局：对你机器上所有项目生效
- 项目根 AGENTS.md # 项目级：对当前项目生效
- 子目录 AGENTS.md # 目录级：对该目录及以下生效
原则：越具体的指令优先级越高。项目里的规则覆盖全局规则，子目录的覆盖项目根的。这种"分层"让你可以：全局写通用习惯（"回复用中文"），项目里写项目规则（"跑测试用 pnpm"）。
兼容 CLAUDE.md
如果你从 Claude Code 生态迁移过来，已有的 CLAUDE.md 不用改——DSH 兼容读取它。规则：
AGENTS.md和CLAUDE.md同时存在时，都加载；若两者内容完全相同，只渲染一次（去重）- 同理支持本地覆盖版：
AGENTS.local.md/CLAUDE.local.md（叠加在基础文件之后，适合放"仅本机"的个人偏好，不进 git）
写一份好 AGENTS.md 的要点
# 项目指令
## 硬规则（必须遵守）
- 不要修改 src/core/ 下的任何文件
- 所有测试必须通过后才能提交
## 命令约定
- 包管理用 pnpm，不要用 npm
- 测试命令：pnpm test
## 风格
- 提交信息用中文，格式：类型: 说明三个建议：
- 写规则，别写教程——AGENTS.md 是约束不是文档，"做什么/不做什么"优先
- 短——它是每个会话都要消耗的上下文，越长越稀释重点。10 行能说清的别写 100 行
- 用"不要"比"要"更有效——禁止类规则 agent 执行得更稳
动态生效：改了立刻被感知
DSH 会跟踪指令文件的变化：
- 会话进行中，你改了 AGENTS.md，agent 会收到"指令已更新"的提示
- 新增嵌套的 AGENTS.md（比如刚 clone 的子模块带了一份），也会被发现并加载
所以修规则不用重启、不用新开会话，改完文件即可。
常见问题
| 问题 | 解答 |
|---|---|
| 规则对所有项目生效？ | 写到$DSH_HOME/AGENTS.md 才是全局；项目内只写项目根 |
| agent 没遵守规则？ | 检查：文件位置对不对、会话是否在文件改动前创建、规则是否太含糊 |
| 想放个人偏好又不想进 git？ | 用AGENTS.local.md（同级叠加，不入库） |
| CLAUDE.md 和 AGENTS.md 都要维护？ | 不需要。内容相同会去重，维护一份即可 |
接下来读什么
- 指令如何被注入会话 → 会话与记忆：持久化与会话恢复
- 人设与 persona 的区别 → 系统提示词：Persona 与变量机制
← 上一篇：3.3 系统提示词：Persona 与变量机制 | 下一篇：3.5 工具清单：内置工具与执行流水线 →
↑ 返回 教程总目录
