通用规则(.agents/roles/)
存放跨仓库通用的代理行为规则。
目录名叫 roles,但里面不放「角色扮演」式定义(没有「你是某某角色、你的职责是……」),
只记录规则本身:什么情况下必须做什么、怎么核对。
放什么,不放什么
判断标准只有一句:这条规则换到另一个仓库还成立吗?
| 内容 | 位置 | 例子 |
|---|---|---|
| 通用规则(不限仓库) | meta 仓库 .agents/roles/ |
提交规范、调研汇报、并行委派 |
| 项目专属规则 | 各仓库自己的 roles/ |
后端的迁移规范、前端的代码标准 |
| 项目知识与架构约定 | 各仓库 AGENTS.md |
端口、调用关系、命名约定 |
| 跨仓库待办与验收标准 | OPTIMIZATION_BACKLOG.md |
优化条目 |
| 工作区级技能 | .agents/skills/ |
mermaid-diagram |
| 项目专属技能 | 各仓库自己的 skills/ |
lpt-be/skills/comment-cleanup |
生效方式(重要)
.agents/roles/ 不是自动加载入口。 规则要真正约束行为,必须在 AGENTS.md 里被引用——
AGENTS.md 是每次会话自动加载的项目指令入口,只有它(和按描述触发的 skills)会被读到。
所以:新增规则时,务必同时在 AGENTS.md 对应章节挂上入口。
配套事实:pi 加载 AGENTS.md 时会同时读工作目录及其父目录。
因此在 lpt-be 这类子目录里干活时,meta 的 AGENTS.md 仍会被读到——
这正是各子项目不再重复通用规则的前提。
规则文件的写法(强制)
每个规则文件的开头必须是如下三段,顺序不变,方便 agent 在决定是否继续读之前就能判断该不该用:
- 名称——作为
#一级标题; - 功能简述——一句话说明这条规则解决什么问题;
- 关键字 / 情况——告诉 agent 何时需要用到这条规则。这部分要简洁(一行枚举触发场景即可),不要在这里展开内容,正文放到后面。
模板:
# <名称>
- **功能**:<一句话说明这条规则做什么>
- **何时用**:<触发场景 / 关键字的简短枚举>
## <正文…>
新增或修改规则后自查:标题是名称?有「功能」行?有「何时用」行?「何时用」是否够短?
规则清单
| 规则 | 文件 | 何时用(触发点) |
|---|---|---|
| todo 收口纪律 | todo-discipline.md |
提交后 / 轮末 / 会话压缩后 |
| 并行与委派 | parallel-and-delegation.md |
开工排期、派发子任务时 |
| 提交规范 | commit-convention.md |
写提交信息时 |
| 调研与问题定位 | research-and-reporting.md |
调研/排查/定位问题类任务 |
| Windows / PowerShell 环境 | shell-environment.md |
执行 shell 命令、报错排查时 |
| 工作区资产归属 | workspace-layout.md |
决定文档/规则/技能放哪时 |
| 跨仓库 Git 操作 | repo-operations.md |
对子项目执行 git 命令时 |
| 开发环境自解锁与求助阈值 | dev-unblock-and-escalation.md |
被登录/权限/凭据卡住、同一问题反复尝试未解决时 |