agents-md-maintenancelisted

# AGENTS.md 维护 ## 核心原则 - `AGENTS.md` 是 agent 每次进入仓库时都会读取的操作指南，不是历史记录仓库。 - 目标是提供足够共享上下文，让 agent 在不浪费上下文窗口的情况下，知道“动手前必须知道什么”。 - 长流程、历史经验、大命令块、环境细节和低频说明放入 `AGENTS.local/` 或其他 topic docs。 - 公开仓库中不要写入 secrets、真实凭据、私有路径、内部主机、私有服务地址或个人本地状态。 - 编辑时保留已有硬规则；如果规则过时，要明确迁移或替换，不要静默删除。 - 每个对话都应该默认知道的项目背景、总览、硬规则和安全边界必须直接写在 `AGENTS.md`，不要拆成 `AGENTS.local/` 中的单独 overview 文件。 - 主 `AGENTS.md` 必须提供整个项目或工作空间的全局描述，让 agent 能从整体角度理解这个仓库是做什么的、核心目标是什么、主要结构如何组织、关键产物和维护边界是什么。 ## 适用范围 - 这个 skill 主要面向 Codex 这类会自动加载 `AGENTS.md` 的智能体操作指南。 - 其他智能体可能使用不同入口文件名，例如 Claude Code 常用 `CLAUDE.md`；文件名不同，但维护逻辑相同。 - 维护非 `AGENTS.md` 入口时，把规则中的 `AGENTS.md` / `AGENTS.local/` 等价替换为对应文件和目录，例如 `CLAUDE.md` / `CLAUDE.local/`。 - 核心目标不是固定文件名，而是在默认加载的入口文件中提供足够全局上下文和硬规则，同时把低频细节拆到 local 目录按需读取，避免默认加载文档浪费上下文窗口。 - 如果采用 `CLAUDE.md`、`CLAUDE.local/` 或其他同类命名，也要同步维护 `.gitignore`、canonical copy、导航表和文件路径引用。 ## 推荐结构 优先采用两层结构，但 `AGENTS.local/` 下的文件不要写死。拆分应由项目实际内容决定，不要套固定模板。 ```text AGENTS.md AGENTS.local/ 01_<detailed-topic>.md 02_<detailed-topic>.md ... ``` 如果入口文件不是 `AGENTS.md`，保持同样结构语义，只替换文件名： ```text CLAUDE.md CLAUDE.local/ 01_<detailed-topic>.md 02_<detailed-topic>.md ... ``` - `AGENTS.md`：中等长度入口，放必须常驻的规则和索引。 - `AGENTS.local/`：详细规则、长工作流、历史教训、命令示例和项目维护笔记。 - `AGENTS.local/` 应该是一组平行的细节章节，不应该包含“总览”“项目概览”这类默认上下文文件。 - 示例中的 `...` 表示按项目实际内容增减文件；不要让模型误以为只能按示例数量或示例命名拆分。 - 复制示例到真实 `AGENTS.md` 时，必须把 `...` 替换成真实文件行或删除，不要把省略行当成实际导航项。 - `AGENTS.local/` 的拆分目标是把语义相同或相近的章节放在一起，并降低常驻上下文压力；不是为了追求固定文件数或固定命名。 - 不要拆得很碎。只有当内容明显属于不同任务场景、单文件过长、或会