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 只保留始终需要的路由信息：

不得放入长示例、命令记录、JSON 输出、issue 时间线、架构长文、provider 特定调试日志或一次性事故分析。

拆分 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，并双向交叉引用。

Agent 发现本地或远端 AGENTS.md 超过 10 KiB 时：

大型旧文件按领域逐步拆分。每次编辑都应让涉及领域更精简、引用更清晰。

AGENTS.md 中指向外部的每条索引必须注明权威目标。优先使用 docs/reference/hwlab.md 等直接路径或 $unidesk-cicd 等 skill 名称。

不得在 AGENTS.md、skill 和长期参考之间重复完整规则。AGENTS.md 可以摘要，参考文档拥有细节。两个参考文档冲突时，更新职责更具体的文档，并只保留一个权威版本。

指令文件不得包含 Secret、完整 API key、完整 DSN、base64 载荷、bearer token、SSH 私钥或可直接复用的凭据。

不得把大段 CLI 输出、OTel trace 转储、JSON 数组或浏览器记录粘贴进 AGENTS.md。大输出证明可复用规则时，只保留规则摘要，并链接到拥有完整结论的 issue 或参考文档。