# 工作区资产归属 - **功能**:规定各类文档与产物放在哪个仓库/目录,避免重复、错位与正文复制。 - **何时用**:新增或修改文档时;决定某段说明该写进哪个仓库时;处理优化清单时;判断某个文件是否该出现在 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` 的「规则与技能位置」段列出路径,并在 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` 的子仓库索引(只写路径 + 触发场景,不复制正文);索引里的路径必须真实存在。共有技能不登记进子仓库索引。