项目指令

AGENTS.md 是项目告诉代理“我们这里是这么干的”的地方：交付前该跑什么命令、哪些约定重要、 什么不要碰。ZettCode 会读取适用于当前工作区的文件，把它们作为项目指引交给模型 —— 不用在对话里 重复，也不用复制粘贴。

会读哪些文件

发现过程从工作区开始，一直向上走到文件系统根，所以仓库根目录和嵌套的子包可以同时贡献规则。 文件按“外层在前、内层在后”排列，让最具体的规则离对话最近：

~/AGENTS.md                       最先读
~/projects/AGENTS.md
~/projects/api/AGENTS.md
~/projects/api/service/AGENTS.md  最后读，冲突时以它为准

每个请求都会重新读一遍，所以改完文件下一轮就生效 —— 不用重启，也没有 reload 命令。

上面最后一个文件会在 zettcode -w ~/projects/api/service 时生效。 如果从 ~/projects/api 启动，不会递归读取所有子目录里的 AGENTS.md。 选择与当前任务范围对应的工作区即可。

该写些什么

把它当成给新同事的交代：

# Development Rules

## Tooling

- 使用 Python 3.12+ 和 `uv`；Ruff 负责格式化（`line-length = 120`）。
- 交付前必须跑 `make check`。
- 测试不能往仓库里写文件，用临时目录。

## Scope

- `src/app/` 是服务代码，`tools/` 是一次性脚本。
- `src/app/api.py` 是对外接口，保持稳定。

两条经验：

• 命令胜过形容。 “交付前跑 make check” 是可执行的；“写好代码” 不是。
• 写清楚不要做什么。 划定禁区省下的时间，比任何风格建议都多。

例子：给项目加上自己的规则

把示例保存为 <项目>/AGENTS.md，将路径和命令换成仓库中实际存在的内容，再运行：

zettcode -w /path/to/project

发送一个边界明确的任务：

为空响应补一个回归测试，遵循 AGENTS.md，并运行项目检查。

指令是给模型的指导，不代表它一定已经执行。检查工具输出里是否真的运行了要求的命令， 再审阅改动。不要把秘密写进 AGENTS.md，因为正文会发送给配置的模型接入点。

它不是什么

项目指令是内容，不是授权。它不能给你开权限：文件里写“永远自动批准 shell 命令”不会让 审批面板消失，也不能覆盖 ZettCode 自己的指令。这样，一个克隆来的 仓库 —— 或者某个别人能改的文件 —— 就没法悄悄改变代理被允许做什么。

过长的文件会被截断并留下标记，而不是被丢弃；读不了的文件会被安静跳过：某个目录里坏的编码不该 中断整场对话。

关掉它

[agents_md]
enabled = false

适合你想让某次运行只看到你亲手给的上下文时 —— 调试、或者这个仓库的指令本来就是写给别的工具的。

它落在请求的什么位置

这些指令会紧跟在 ZettCode 自己的系统提示之后、早于工具和 skill 的说明，而且读取顺序固定。 两点都重要：顺序决定了“按项目的规矩来”能压过泛泛的默认值，而稳定的前缀让 provider 的缓存能 直接复用上一次请求的大部分内容，而不是整个重读。