Files
lpt-meta/.agents/roles/workspace-layout.md
T
cat-shark f99e1e156d docs: 共有技能收归 meta 单一份并加工作区级笔记校验入口
- write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本
- 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根
- workspace-layout 补「共有技能单一来源」的落位与理由
- .rgignore 排除 archived 历史快照
2026-11-18 14:59:45 +08:00

5.9 KiB
Raw Blame History

工作区资产归属

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