Agent 指令治理

本文范围：
- 目标：保持自动加载的 Agent 指令文件精简、可导航且稳定；
- 适用对象：本地和远端 AGENTS.md、CLAUDE.md 类别名；
- 扩展范围：所有自动注入 Agent 上下文的仓库级指令文件。

体积预算

体积定义：
- AGENTS.md 是索引，不是知识库；
- 本地或远端 AGENTS.md 的硬上限均为 10 KiB；
- 使用 wc -c AGENTS.md 按字节计量。

AGENTS.md 已超过 10 KiB 时：

不得继续追加详细规则；
必须先拆分；
只向 AGENTS.md 回填一行索引。
修改会导致 AGENTS.md 超过 10 KiB 时：
- 把新内容分流到 skill 或 docs/reference/*.md；
- 保持 AGENTS.md 为短索引。
加载或输出 AGENTS.md 触发 CLI 输出转储或上下文膨胀时：
- 将其视为可见性缺陷；
- 将其视为指令治理缺陷；
- 通过拆分文件修复；
- 不得提高输出上限；
- 不得要求 Agent 绕过转储读取。

AGENTS.md 只保留始终需要的路由信息：

分流顺序：
- 可复用工作流进入 skill SKILL.md，例如：
  - $dad-dev、$unidesk-cicd、$unidesk-gh；
  - $unidesk-trans、$unidesk-otel、$unidesk-webdev；
  - $unidesk-ymalops。
- 稳定项目约束、工作区规则、架构边界和验收标准进入 docs/reference/*.md。
- CLI 相关内容：
  - 形态、输出样式、路由语法和操作体验进入 docs/reference/cli.md；
  - 已有更具体参考文档时进入具体文档。
- 部署治理、固定仓库边界和真相源规则进入 docs/reference/devops-hygiene.md。
- HWLAB 节点/通道规则进入 docs/reference/hwlab.md 和目标仓库自身参考文档。
- AgentRun 真相源和部署通道规则进入 docs/reference/agentrun.md。
- 平台基础设施和 YAML-first 运维：
  - 进入 docs/reference/platform-infra.md；
  - 同时由 docs/reference/yaml-first-ops.md 约束。
- 过程材料：
  - 过程记录、临时发现和带日期调查日志进入 GitHub issue、PR 评论或过程记录；
  - 进入长期参考前必须蒸馏。
规则既能跨项目复用、又依赖 UniDesk 当前目录或服务时：
- 把可复用流程放入 skill；
- 把 UniDesk 特定路径、通道名和验收边界放入 docs/reference/*.md；
- 双向交叉引用。

外部索引规则：
- 每条索引必须注明权威目标；
- 优先使用 docs/reference/hwlab.md 等直接路径；
- 也可使用 $unidesk-cicd 等 skill 名称。
规则归属：
- 不得在 AGENTS.md、skill 和长期参考之间重复完整规则；
- AGENTS.md 可以保留摘要；
- 参考文档拥有细节；
- 两个参考文档冲突时，更新职责更具体的文档；
- 冲突处理后只保留一个权威版本。

指令文件不得包含：
- Secret、完整 API key 或完整 DSN；
- base64 载荷或 bearer token；
- SSH 私钥或可直接复用的凭据。
大输出治理：
- 不得把大段 CLI 输出粘贴进 AGENTS.md；
- 不得粘贴 OTel trace 转储、JSON 数组或浏览器记录；
- 大输出证明可复用规则时，只保留规则摘要；
- 摘要必须链接到拥有完整结论的 issue 或参考文档。