- write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本 - 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根 - workspace-layout 补「共有技能单一来源」的落位与理由 - .rgignore 排除 archived 历史快照
5.9 KiB
5.9 KiB
工作区资产归属
- 功能:规定各类文档与产物放在哪个仓库/目录,避免重复、错位与正文复制。
- 何时用:新增或修改文档时;决定某段说明该写进哪个仓库时;处理优化清单时;判断某个文件是否该出现在 meta 仓库时;放规则或技能时。
规则
文档归属
- 所有系统文档统一在
lpt-docs仓库维护,代码仓库不保留 README、docs/等文档文件。 lpt-docs只维护系统概念描述和设计思路,不保存开发记录、系统中间态和开发过程产物。- 跨仓库的实现优化清单记录在 meta 仓库
OPTIMIZATION_BACKLOG.md(只放待办、依据与验收标准);概念与设计仍归lpt-docs。 - 修改
lpt-docs后,如需在 meta 仓库补充说明,保持 meta 仓库不复制文档正文。
meta 仓库的维护边界
- 本 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/。
规则与技能的落位
规则和技能都收在 .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的「规则与技能位置」段列出路径,并在 metaAGENTS.md的「子仓库规则与技能索引」里能找到;否则只是一堆没人读的文件。- 技能发现机制因 harness 而异。 Pi 递归扫描用户级与项目技能目录(
.pi/skills/、.agents/skills/,后者从工作目录向上,遇到 git 仓库根或工作区根停止);Claude 体系读.claude/skills/;codex / dsh 等未必扫描技能目录。所以 metaAGENTS.md里给出技能路径,让模型按需read,不把「自动发现」当前提。 - meta 会话只自动加载工作目录及父目录的
AGENTS.md。 子仓库的AGENTS.md靠 metaAGENTS.md的索引与读取协议带出来。不要依赖.pi/扩展、.pi/settings.json或任何 harness 私有机制做自动注入,换一个入口就失效。
维护纪律:新增或删除子仓库规则/技能时,同一次提交里同步 meta AGENTS.md 的子仓库索引(只写路径 + 触发场景,不复制正文);索引里的路径必须真实存在。共有技能不登记进子仓库索引。