docs: 共有技能收归 meta 单一份并加工作区级笔记校验入口

- write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本
- 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根
- workspace-layout 补「共有技能单一来源」的落位与理由
- .rgignore 排除 archived 历史快照
This commit is contained in:
cat-shark
2026-11-18 14:59:45 +08:00
parent a194477b65
commit f99e1e156d
27 changed files with 3767 additions and 11 deletions
+11 -7
View File
@@ -15,18 +15,22 @@
| 项目专属规则 | 各仓库自己的 `.agents/roles/` | 后端的迁移规范、前端的代码标准 |
| 项目知识与架构约定 | 各仓库 `AGENTS.md` | 端口、调用关系、命名约定 |
| 跨仓库待办与验收标准 | `OPTIMIZATION_BACKLOG.md` | 优化条目 |
| 工作区级技能 | `.agents/skills/` | `mermaid-diagram` |
| 工作区级技能(共有技能唯一来源) | 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/` 不是自动加载入口。** 规则要真正约束行为,必须在 `AGENTS.md` 里被引用——
`AGENTS.md` 是每次会话自动加载的项目指令入口,只有它(和按描述触发的 skills)会被读到。
所以:新增规则时,务必同时在 `AGENTS.md` 对应章节挂上入口。
**`.agents/roles/` 不是自动加载入口,任何 harness 都不会扫描它。** 规则要真正约束行为,必须在 `AGENTS.md` 里被引用——
`AGENTS.md` 是各 harness 通用的项目指令入口(Claude 体系另有 `CLAUDE.md`),只有它会被读到。
所以:新增规则时,务必同时在该仓库 `AGENTS.md` 挂上入口,并在 meta `AGENTS.md` 的子仓库索引里登记路径与触发场景。
配套事实:pi 加载 `AGENTS.md` 时会同时读**工作目录及其父目录**。
因此在 `lpt-be` 这类子目录里干活时,meta 的 `AGENTS.md` 仍会被读到——
这正是各子项目不再重复通用规则的前提。
配套事实:
- **agent 会话从 meta 根目录启动**,子项目靠 `subagent(cwd=<repo>)` 进入(见 meta `AGENTS.md` 首页)。因此共有技能放在 meta 就能被发现,不需要往子仓库复制。
- 在子目录里启动 agent 时,父目录的 `AGENTS.md` 也会被读到(各 harness 大体一致),但**这不是默认工作方式**,不要依赖它:在 `lpt-be` 里启动看不到另外四个仓库的约定,也看不见 meta 的共有技能。
- 反过来,在 meta 根目录干活时子仓库 `AGENTS.md` 不会自动加载,靠 meta 的子仓库索引带出。
## 规则文件的写法(强制)