Files
lpt-meta/.agents/roles/README.md
T

64 lines
3.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 通用规则(`.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` | 被登录/权限/凭据卡住、同一问题反复尝试未解决时 |