# 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 应包含的内容

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

- 项目标识和真相源边界；
- 防止直接损害的一行 P0 规则；
- 各领域权威长期参考文档链接；
- 常用工作流必须加载的 skill 名称；
- Secret、破坏性命令、目标工作区和构建禁令的短警告。

- 禁止内容：

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

## 超出内容的分流位置

- 分流顺序：

  - 可复用工作流进入 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`；
  - 双向交叉引用。

## 拆分步骤

1. 识别正在修改或扩展的详细领域。
2. 把详细内容移到权威 skill 或 `docs/reference/*.md`。
3. 用一条简短索引和权威链接替换原详细章节。
4. 在 `AGENTS.md` 保留 P0 损害预防警告，但压缩为一行路由规则。
5. 禁止创建巨大溢出文档：
   - 不得把所有内容移入单个文件；
   - 临时迁移记录仅在立即指向各领域承接文档时可用。
6. 用户未明确要求时：
   - 不为体积预算新增测试、保护代码或预检；
   - 默认控制方式是文档治理和简洁评审。

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

## 交叉引用要求

- 外部索引规则：

  - 每条索引必须注明权威目标；
  - 优先使用 `docs/reference/hwlab.md` 等直接路径；
  - 也可使用 `$unidesk-cicd` 等 skill 名称。

- 规则归属：

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

## Secret 与输出治理

- 指令文件不得包含：

  - Secret、完整 API key 或完整 DSN；
  - base64 载荷或 bearer token；
  - SSH 私钥或可直接复用的凭据。

- 大输出治理：

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

## 当前 UniDesk 路由图

- CLI 行为与输出：`docs/reference/cli.md`。
- YAML-first 配置：`docs/reference/yaml-first-ops.md` 与 `$unidesk-ymalops`。
- 平台基础设施：`docs/reference/platform-infra.md`；涉及 Sub2API 时使用 `$unidesk-sub2api`。
- 分布式现场修复：`$dad-dev` 与 `docs/reference/devops-hygiene.md`。
- CI/CD 与发布：`$unidesk-cicd` 与 `docs/reference/cli.md`。
- GitHub issue 与 PR 写入：`$unidesk-gh`。
- Trans/远端补丁传输：`$unidesk-trans` 与 `docs/reference/cli.md`。
- Web 界面、Workbench 和 web-probe：`$unidesk-webdev`。
- OpenTelemetry 与 Tempo：`$unidesk-otel` 与 `docs/reference/observability.md`。
- HWLAB 节点/通道运维：`docs/reference/hwlab.md`。
- AgentRun：`docs/reference/agentrun.md`。
- Master/D601 开发环境：`docs/reference/dev-environment.md`。
- 秘书工作：`docs/reference/secretary-reference.md`。