| name | optimize-agents-md |
| description | AGENTS.md 编写与优化指南，遵循渐进式披露原则。当用户创建、修改或重构 AGENTS.md，讨论 AI agent 指令结构、规则放置位置，或提到「渐进式披露」「模块化」「AGENTS.md 最佳实践」时，务必加载此 skill。即使用户只是说「帮我写个 AGENTS.md」「优化一下这个配置文件」「拆分一下规则」，也应该使用此 skill。 |
| metadata | {"internal":true} |
AGENTS.md 编写与优化指南
问题诊断
当 AGENTS.md 出现以下症状时，应该拆分：
- 文件超过 100 行，包含多个不相关模块的规则
- 不同技术栈的规则混在一起（Python + 前端 + 数据库）
- Agent 每次会话都加载大量无关内容
- 规则之间耦合度高，难以独立维护
创建 AGENTS.md 时的原则
1. 从精简开始
根 AGENTS.md 应该只包含「每次会话都需要」的规则：
- 语言偏好
- 核心工作原则
- 全局 Git 规范
- 项目入口说明
目标：根 AGENTS.md 保持在 50 行以内。
2. 按作用域规划
在添加规则前，先判断作用域：
这条规则 → 全局生效？ → 是 → 根 AGENTS.md
→ 特定模块？ → 是 → 子目录 AGENTS.md 或 Skill
→ 复杂工作流？ → 是 → Skill
→ 不确定？ → 考虑是否真的需要
3. 避免常见陷阱
| 陷阱 | 问题 | 正确做法 |
|---|
| 把所有规则塞进一个文件 | Context 浪费、Agent 困惑 | 按作用域拆分 |
| 教程式内容（如何使用 X） | 每次会话都加载无关内容 | 放到 Skill 或文档 |
| 过于具体的命令示例 | 规则膨胀、难以维护 | 只写核心原则 |
| 与其他规则冲突 | Agent 行为不一致 | 合并或删除冲突规则 |
4. 写作风格
- 简洁：用短语而非段落
- 明确：避免「可能」「也许」，用「应该」「禁止」
- 结构化：用列表和表格，便于快速扫描
- 解释原因：简要说明为什么这条规则重要
渐进式披露原则
核心思想：从简单到复杂，按需加载。
| 层级 | 内容 | 加载时机 |
|---|
| 1. Metadata | name + description | 始终可见 |
| 2. SKILL.md body | 核心指令 | Agent 判断相关时 |
| 3. References | 详细文档 | 需要时才读取 |
好处：
- 节省 context window
- Agent 只看到相关规则
- 规则更易维护
文件放置规则（重要）
安全边界（必须遵守）
- 禁止：AI agent 不得直接创建/编辑/删除任何“用户全局”的
AGENTS.md（例如 ~/.agents/AGENTS.md、~/.config/**/AGENTS.md、~/.config/opencode/AGENTS.md 等）。
- 允许：当用户需要全局规则时，AI agent 只能给出建议与完整内容草稿（或 diff 文本），并明确说明应由用户自行手动应用到其全局文件中。
- 始终优先：默认只在当前仓库/项目目录内创建或修改
AGENTS.md（项目根、子目录、docs/），避免影响其他项目与环境。
核心原则
- 与特定文件夹/模块相关的 AGENTS.md → 放在该文件夹下
- 与整个项目相关的通用文档型 AGENTS.md → 放在
docs/ 目录下
- 用户全局规则 → 建议放在
~/.config/opencode/AGENTS.md（适用于所有项目；但agent 不得直接修改该文件）
层级结构
~/.config/opencode/AGENTS.md # 用户全局（所有项目共享）
↓ 继承/覆盖
project/AGENTS.md # 项目根目录（项目级规则）
↓ 继承/覆盖
project/src/python/AGENTS.md # 模块级（特定模块规则）
规则优先级：模块级 > 项目级 > 用户全局级（更具体的规则覆盖更通用的规则）
禁止重复原则
不同层级的 AGENTS.md 不能有重复内容，原因：
正确做法：
| 层级 | 应包含 | 不应包含 |
|---|
| 用户全局 | 跨项目通用规则（语言偏好、Git 规范） | 项目特定规则、模块规则 |
| 项目根目录 | 项目特定规则（项目架构、团队约定） | 已在用户全局定义的规则、模块规则 |
| 模块目录 | 模块特定规则（技术栈规范、文件命名） | 已在上层定义的规则 |
示例：
# ❌ 错误：项目 AGENTS.md 重复用户全局规则
## 语言
始终用中文回答。 # 已在 ~/.config/opencode/AGENTS.md 定义，重复！
## Git
简短提交信息，不加前缀 # 已在 ~/.config/opencode/AGENTS.md 定义，重复！
## ✅ 正确：项目 AGENTS.md 只包含项目特定规则
## 项目结构
src/ 为源码目录，tests/ 为测试目录。
## 团队约定
PR 必须经过至少一人审核。
文件放置示例
~/.config/opencode/
└── AGENTS.md # 用户全局规则（所有项目共享）
project/
├── AGENTS.md # 项目全局规则（< 50 行）
├── docs/
│ ├── AGENTS.md # 项目级文档规则、架构说明
│ ├── architecture.md # 架构文档
│ └── api-guide.md # API 使用指南
├── src/
│ ├── python/
│ │ └── AGENTS.md # Python 模块特定规则
│ └── frontend/
│ └── AGENTS.md # 前端模块特定规则
└── .opencode/
└── skills/
└── deploy/SKILL.md # 部署工作流（复杂任务）
判断标准
| 内容类型 | 放置位置 | 示例 |
|---|
| 用户全局约束 | ~/.config/opencode/AGENTS.md（仅建议/草稿，用户手动应用） | 语言偏好、Git 规范、核心原则 |
| 项目全局约束 | 项目根目录 AGENTS.md | 项目架构、团队约定、入口说明 |
| 模块/文件夹规则 | 该文件夹下的 AGENTS.md | Python 规范、前端规范、API 模块规则 |
| 项目级文档说明 | docs/AGENTS.md | 架构说明、文档编写规范、项目指南 |
| 复杂工作流 | Skill | 部署流程、PR 创建流程 |
为什么要区分 docs/ 和子目录 AGENTS.md？
- 子目录 AGENTS.md：Agent 进入该目录工作时自动加载，提供即时上下文
- docs/AGENTS.md：项目级说明，需要显式引用或搜索才会加载，避免每次会话都加载大量文档内容
为什么要区分用户全局和项目 AGENTS.md？
- 用户全局 AGENTS.md：一次定义，所有项目共享，避免在每个项目中重复相同的个人偏好
- 项目 AGENTS.md：项目特定规则，只在该项目生效，不影响其他项目
拆分策略
1. 分类规则
| 规则类型 | 放置位置 | 示例 |
|---|
| 用户全局规则 | ~/.config/opencode/AGENTS.md（仅建议/草稿，用户手动应用） | 语言偏好、Git 规范、核心原则 |
| 项目全局规则 | 项目根 AGENTS.md | 项目架构、团队约定、入口说明 |
| 模块规则 | 子目录 AGENTS.md | Python 规范 → python/AGENTS.md |
| 项目文档规则 | docs/AGENTS.md | 文档编写规范、架构说明 |
| 任务规则 | Skill | 复杂工作流、特定任务指南 |
2. 决策树
这条规则是否每次会话都需要？
├── 是 → 是所有项目都需要的吗？
│ ├── 是 → 建议放到 ~/.config/opencode/AGENTS.md（用户全局；agent 只提供草稿，用户手动应用）
│ └── 否 → 放到项目根目录 AGENTS.md
└── 否 → 是特定模块/文件夹的吗？
├── 是 → 放到该文件夹下的 AGENTS.md
└── 否 → 是项目级文档/架构说明吗？
├── 是 → 放到 docs/AGENTS.md
└── 否 → 是复杂工作流吗？
├── 是 → 创建 Skill
└── 否 → 考虑是否真的需要这条规则
执行步骤
1. 创建新的 AGENTS.md
1. 确认需要哪些全局规则（语言、原则、Git）
2. 判断是否有模块级规则需要单独放置
3. 编写精简的根 AGENTS.md
4. 如有需要，创建子目录 AGENTS.md、docs/AGENTS.md 或 Skill
2. 分析现有内容
1. 读取现有 AGENTS.md
2. 列出所有规则模块
3. 标记每个模块的作用域（全局/模块/项目文档/任务）
3. 制定拆分计划
向用户展示：
- 哪些内容保留在根目录
- 哪些内容拆分到子目录 AGENTS.md
- 哪些内容应该放到 docs/AGENTS.md
- 每个新文件的内容概要
4. 执行拆分
1. 创建子目录 AGENTS.md、docs/AGENTS.md 或 Skill 文件
2. 迁移相关规则（保持格式和层级）
3. 更新根 AGENTS.md，移除已拆分内容
4. 添加必要的引用说明（可选）
5. 验证
1. 检查根 AGENTS.md 是否精简
2. 确认子目录文件内容完整
3. 验证没有规则丢失或重复
4. 确认 docs/AGENTS.md 包含项目级文档规则（如有）
Skill vs AGENTS.md 选择
| 场景 | 推荐 | 原因 |
|---|
| 跨项目个人偏好（语言、Git） | ~/.config/opencode/AGENTS.md（agent 仅提供草稿，用户手动修改） | 所有项目共享 |
| 项目约束（架构、团队约定） | 项目 AGENTS.md | 项目级生效 |
| 技术栈规范（Python、前端） | 子目录 AGENTS.md 或 Skill | 按需加载 |
| 项目文档/架构说明 | docs/AGENTS.md | 需要时加载 |
| 复杂工作流（部署、PR） | Skill | 渐进披露 + 可复用 |
| 团队约定（命名、格式） | 项目 AGENTS.md | 全局约束 |
最佳实践
根 AGENTS.md 保持精简
# 语言
始终用中文回答。
## 核心原则
- 优先简单、可维护的方案
- 不要过度设计
## Git
- 简短提交信息，不加前缀
## 模块规则
Python 项目 → 参考 src/python/AGENTS.md
前端项目 → 参考 src/frontend/AGENTS.md
## 文档
项目架构 → 参考 docs/AGENTS.md
子目录 AGENTS.md 聚焦单一模块
# Python 项目规范
## 工具
依赖管理用 uv，格式化用 ruff。
## 原则
- Fast-fail：外层才用 try-except
- 禁止硬编码凭证
docs/AGENTS.md 用于项目级文档
# 项目文档规范
## 架构说明
本项目采用三层架构，详见 architecture.md。
## API 文档
- REST API 规范 → api-guide.md
- GraphQL Schema → schema.graphql
Skill 用于复杂任务
当规则包含多步骤工作流、需要渐进披露大量内容时，创建 Skill 而非 AGENTS.md。
常见错误
| 错误 | 后果 | 修正 |
|---|
| 根 AGENTS.md 过长 | Context 浪费 | 拆分到子目录、docs/ 或 Skill |
| 规则重复定义 | Agent 困惑 | 每条规则只出现一次 |
| 不同层级内容重复 | Context 浪费、规则冲突 | 每条规则只在最合适的层级定义一次 |
| 拆分粒度过细 | 维护负担 | 合并相关规则 |
| 忘记删除原内容 | 规则冲突 | 拆分后必须删除原文 |
| 模块规则放在根目录 | 不相关规则被加载 | 移到对应子目录 |
| 项目文档规则放在根目录 | Context 膨胀 | 移到 docs/AGENTS.md |
| 项目规则放在用户全局 | 影响其他项目 | 移到项目 AGENTS.md |
