- write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本 - 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根 - workspace-layout 补「共有技能单一来源」的落位与理由 - .rgignore 排除 archived 历史快照
70 lines
4.1 KiB
Markdown
70 lines
4.1 KiB
Markdown
# 通用规则(`.agents/roles/`)
|
||
|
||
存放**跨仓库通用的代理行为规则**。
|
||
|
||
目录名叫 `roles`,但里面不放「角色扮演」式定义(没有「你是某某角色、你的职责是……」),
|
||
**只记录规则本身**:什么情况下必须做什么、怎么核对。
|
||
|
||
## 放什么,不放什么
|
||
|
||
判断标准只有一句:**这条规则换到另一个仓库还成立吗?**
|
||
|
||
| 内容 | 位置 | 例子 |
|
||
|------|------|------|
|
||
| 通用规则(不限仓库) | meta 仓库 `.agents/roles/` | 提交规范、调研汇报、并行委派 |
|
||
| 项目专属规则 | 各仓库自己的 `.agents/roles/` | 后端的迁移规范、前端的代码标准 |
|
||
| 项目知识与架构约定 | 各仓库 `AGENTS.md` | 端口、调用关系、命名约定 |
|
||
| 跨仓库待办与验收标准 | `OPTIMIZATION_BACKLOG.md` | 优化条目 |
|
||
| 工作区级技能(共有技能唯一来源) | meta `.agents/skills/` | `mermaid-diagram`、`write-notes-like-deepseek` |
|
||
| 项目专属技能 | 各仓库自己的 `.agents/skills/` | `lpt-be/.agents/skills/comment-cleanup` |
|
||
|
||
> 共有技能**只在 meta 放一份**,子项目内不建副本、不建符号链接;理由与验收见 `.agents/roles/workspace-layout.md`。
|
||
|
||
## 生效方式(重要)
|
||
|
||
**`.agents/roles/` 不是自动加载入口,任何 harness 都不会扫描它。** 规则要真正约束行为,必须在 `AGENTS.md` 里被引用——
|
||
`AGENTS.md` 是各 harness 通用的项目指令入口(Claude 体系另有 `CLAUDE.md`),只有它会被读到。
|
||
所以:新增规则时,务必同时在该仓库 `AGENTS.md` 挂上入口,并在 meta `AGENTS.md` 的子仓库索引里登记路径与触发场景。
|
||
|
||
配套事实:
|
||
|
||
- **agent 会话从 meta 根目录启动**,子项目靠 `subagent(cwd=<repo>)` 进入(见 meta `AGENTS.md` 首页)。因此共有技能放在 meta 就能被发现,不需要往子仓库复制。
|
||
- 在子目录里启动 agent 时,父目录的 `AGENTS.md` 也会被读到(各 harness 大体一致),但**这不是默认工作方式**,不要依赖它:在 `lpt-be` 里启动看不到另外四个仓库的约定,也看不见 meta 的共有技能。
|
||
- 反过来,在 meta 根目录干活时子仓库 `AGENTS.md` 不会自动加载,靠 meta 的子仓库索引带出。
|
||
|
||
## 规则文件的写法(强制)
|
||
|
||
每个规则文件的**开头必须是如下三段**,顺序不变,方便 agent 在决定是否继续读之前就能判断该不该用:
|
||
|
||
1. **名称**——作为 `#` 一级标题;
|
||
2. **功能简述**——一句话说明这条规则解决什么问题;
|
||
3. **关键字 / 情况**——告诉 agent **何时需要用到这条规则**。这部分要简洁(一行枚举触发场景即可),**不要在这里展开内容**,正文放到后面。
|
||
|
||
模板:
|
||
|
||
```markdown
|
||
# <名称>
|
||
|
||
- **功能**:<一句话说明这条规则做什么>
|
||
- **何时用**:<触发场景 / 关键字的简短枚举>
|
||
|
||
## <正文…>
|
||
```
|
||
|
||
新增或修改规则后自查:标题是名称?有「功能」行?有「何时用」行?「何时用」是否够短?
|
||
|
||
## 规则清单
|
||
|
||
| 规则 | 文件 | 何时用(触发点) |
|
||
|------|------|--------|
|
||
| todo 收口纪律 | `todo-discipline.md` | 提交后 / 轮末 / 会话压缩后 |
|
||
| 并行与委派 | `parallel-and-delegation.md` | 开工排期、派发子任务时 |
|
||
| 子代理执行与复核 | `subagent-execution.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` | 被登录/权限/凭据卡住、同一问题反复尝试未解决时 |
|
||
| 业务名词收敛 | `business-terminology.md` | 描述系统概念、拆需求、派子代理、写笔记或提交信息时 |
|