# 通用规则(`.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 在决定是否继续读之前就能判断该不该用: 1. **名称**——作为 `#` 一级标题; 2. **功能简述**——一句话说明这条规则解决什么问题; 3. **关键字 / 情况**——告诉 agent **何时需要用到这条规则**。这部分要简洁(一行枚举触发场景即可),**不要在这里展开内容**,正文放到后面。 模板: ```markdown # <名称> - **功能**:<一句话说明这条规则做什么> - **何时用**:<触发场景 / 关键字的简短枚举> ## <正文…> ``` 新增或修改规则后自查:标题是名称?有「功能」行?有「何时用」行?「何时用」是否够短? ## 规则清单 | 规则 | 文件 | 何时用(触发点) | |------|------|--------| | 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` | 被登录/权限/凭据卡住、同一问题反复尝试未解决时 |