Codex
145 lines
5.4 KiB
Markdown
145 lines
5.4 KiB
Markdown
# 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`。
|