docs: 共有技能收归 meta 单一份并加工作区级笔记校验入口
- write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本 - 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根 - workspace-layout 补「共有技能单一来源」的落位与理由 - .rgignore 排除 archived 历史快照
This commit is contained in:
+11
-7
@@ -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 的子仓库索引带出。
|
||||
|
||||
## 规则文件的写法(强制)
|
||||
|
||||
|
||||
@@ -14,11 +14,55 @@
|
||||
|
||||
### meta 仓库的维护边界
|
||||
|
||||
- 本 meta 仓库只维护 `AGENTS.md`、`.gitignore`、`.agents/`(代理技能与通用规则)和 `docs/diagrams/`(图表评审产物),不要在本仓库根目录创建业务代码或系统文档。
|
||||
- 本 meta 仓库只维护 `AGENTS.md`、`.gitignore`、`.agents/`(代理技能、通用规则、校验脚本、跨仓库笔记)和 `docs/diagrams/`(图表评审产物),不要在本仓库根目录创建业务代码或系统文档。
|
||||
- `.gitignore` 忽略所有子项目目录,只放行上述根级条目,避免把独立 Git 仓库提交进本 meta 仓库。
|
||||
|
||||
### 业务决策笔记的归属
|
||||
|
||||
业务决策写在**各自的业务仓库**里,不集中到 meta,也不放进 `lpt-docs`。
|
||||
|
||||
- `lpt-be` / `lpt-fe` / `lpt-ai` / `lpt-android` 的决策笔记 → 该仓库自己的 `.agents/notes/`,与该仓库的代码同一次提交。
|
||||
- 为什么:决策要被读到,前提是改这段代码的 agent 必然翻到它。放在同仓库同一次改动里,读代码就会撞见;集中到别的仓库,等于写给人看而不是写给下一个人用。
|
||||
- `lpt-docs` 只维护概念定义与设计思路,**不承接决策流水账与开发过程记录**(见下节「文档归属」)。
|
||||
- 只有在跨仓库口径(如分支↔环境对应、服务间字段耦合)无法归属到单一仓库时,才写进 meta 的 `.agents/notes/`,并在 `AGENTS.md` 里列出路径。
|
||||
- 所有记录内容的标题与正文一律用简体中文(`Agent Note:` / `Status:` 头块、代码、命令、路径、专有名词除外);笔记格式与校验沿用 meta 仓库 `.agents/skills/write-notes-like-deepseek/`。
|
||||
|
||||
### 规则与技能的落位
|
||||
|
||||
- 通用规则(跨仓库)→ meta 仓库 `.agents/roles/`。
|
||||
- 项目专属规则 → 该仓库自己的 `roles/`。
|
||||
- 工作区级技能 → `.agents/skills/<技能名>/`;子项目专属技能 → 该仓库 `skills/`。
|
||||
规则和技能都收在 `.agents/` 下,不要放在仓库根目录的 `roles/`、`skills/`。
|
||||
|
||||
**先回答「这东西换个仓库还成立吗?」**
|
||||
|
||||
| 内容 | 位置 | 例子 |
|
||||
|------|------|------|
|
||||
| 通用规则(不限仓库) | meta `.agents/roles/` | 提交规范、调研汇报、并行委派 |
|
||||
| 项目专属规则 | 该仓库 `.agents/roles/` | 后端的迁移规范、前端的代码标准 |
|
||||
| **共有技能(单一来源)** | **只在 meta `.agents/skills/`** | `write-notes-like-deepseek`、`mermaid-diagram` |
|
||||
| 项目专属技能 | 该仓库 `.agents/skills/` | `lpt-be` 的 `comment-cleanup`、`lpt-fe` 的 `ui-review` |
|
||||
| 决策笔记 | 该仓库 `.agents/notes/` | 能归属到单一仓库的决定 |
|
||||
| 跨仓库决策笔记 | meta `.agents/notes/` | 分支↔环境口径这类无法归属的决定 |
|
||||
|
||||
### 共有技能只在 meta,子项目不放副本
|
||||
|
||||
跨仓库通用的技能一律以 meta 的 `.agents/skills/<技能名>/` 为**唯一真实副本**,子项目里不建副本、不建符号链接。
|
||||
|
||||
理由(每条都可验证):
|
||||
|
||||
- **agent 只在 meta 运行**(见 meta `AGENTS.md`),工作目录向上扫描技能目录时能发现 meta 的 `.agents/skills/`;子项目里的副本对 agent 没有任何额外作用。
|
||||
- **副本必漂移。** 本工作区曾把 `write-notes-like-deepseek` 分别复制进三个仓库(三份 sha1 完全一致),之后对上游的中文标题补丁就得手改三处;一旦漏改一处,各仓校验行为就不一致。
|
||||
- **符号链接在 Windows / `core.symlinks=false` 下会退化成普通文本文件**(内容是一行路径字符串),`node path/SKILL.md` 直接 `Not a directory`;而 `lpt-fe/Dockerfile` 是 `COPY . .`,指向构建上下文之外的链接会让 `docker build` 报 forbidden path。两个坑都在本工作区实测过。
|
||||
- **单独 clone 子仓库时(CI、别的机器)不依赖 meta**,技能本来就读不到,所以「副本能自包含」这个好处并不成立。
|
||||
|
||||
新增共有技能的步骤:在 meta `.agents/skills/<技能名>/` 建好 → 在 meta `AGENTS.md` 的「共有技能」段登记一行(路径 + 触发场景)→ 子项目里什么都不用做。
|
||||
|
||||
需要项目专属技能时,才在该仓 `.agents/skills/` 下建,并登记到 meta `AGENTS.md` 的子仓库索引。
|
||||
|
||||
### 生效方式的事实
|
||||
|
||||
三条事实决定了上述落位,写错位置等于写了没人读:
|
||||
|
||||
- **`.agents/roles/` 不会被任何 harness 自动加载。** 规则要生效,必须在该仓库 `AGENTS.md` 的「规则与技能位置」段列出路径,并在 meta `AGENTS.md` 的「子仓库规则与技能索引」里能找到;否则只是一堆没人读的文件。
|
||||
- **技能发现机制因 harness 而异。** Pi 递归扫描用户级与项目技能目录(`.pi/skills/`、`.agents/skills/`,后者从工作目录向上,遇到 git 仓库根或工作区根停止);Claude 体系读 `.claude/skills/`;codex / dsh 等未必扫描技能目录。所以 meta `AGENTS.md` 里给出技能路径,让模型按需 `read`,不把「自动发现」当前提。
|
||||
- **meta 会话只自动加载工作目录及父目录的 `AGENTS.md`。** 子仓库的 `AGENTS.md` 靠 meta `AGENTS.md` 的索引与读取协议带出来。不要依赖 `.pi/` 扩展、`.pi/settings.json` 或任何 harness 私有机制做自动注入,换一个入口就失效。
|
||||
|
||||
**维护纪律**:新增或删除子仓库规则/技能时,同一次提交里同步 meta `AGENTS.md` 的子仓库索引(只写路径 + 触发场景,不复制正文);索引里的路径必须真实存在。共有技能不登记进子仓库索引。
|
||||
|
||||
Reference in New Issue
Block a user