optimize-agents-md（优化 AgentMD）

AGENTS.md 编写与优化指南

问题诊断

当 AGENTS.md 出现以下症状时，应该拆分：

• 文件超过 100 行，包含多个不相关模块的规则
• 不同技术栈的规则混在一起（Python + 前端 + 数据库）
• Agent 每次会话都加载大量无关内容
• 规则之间耦合度高，难以独立维护

创建 AGENTS.md 时的原则

1. 从精简开始

根 AGENTS.md 应该只包含「每次会话都需要」的规则：

• 语言偏好
• 核心工作原则
• 全局 Git 规范
• 项目入口说明

目标：根 AGENTS.md 保持在 50 行以内。

2. 按作用域规划

在添加规则前，先判断作用域：

这条规则 → 全局生效？ → 是 → 根 AGENTS.md
         → 特定模块？ → 是 → 子目录 AGENTS.md 或 Skill
         → 复杂工作流？ → 是 → Skill
         → 不确定？ → 考虑是否真的需要

3. 避免常见陷阱

4. 写作风格

• 简洁：用短语而非段落
• 明确：避免「可能」「也许」，用「应该」「禁止」
• 结构化：用列表和表格，便于快速扫描
• 解释原因：简要说明为什么这条规则重要

渐进式披露原则

核心思想：从简单到复杂，按需加载。

好处：

• 节省 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 不能有重复内容，原因：

• 浪费上下文窗口
• 可能导致规则冲突
• 增加维护负担

正确做法：

示例：

# ❌ 错误：项目 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  # 部署工作流（复杂任务）

判断标准

为什么要区分 docs/ 和子目录 AGENTS.md？

• 子目录 AGENTS.md：Agent 进入该目录工作时自动加载，提供即时上下文
• docs/AGENTS.md：项目级说明，需要显式引用或搜索才会加载，避免每次会话都加载大量文档内容

为什么要区分用户全局和项目 AGENTS.md？

• 用户全局 AGENTS.md：一次定义，所有项目共享，避免在每个项目中重复相同的个人偏好
• 项目 AGENTS.md：项目特定规则，只在该项目生效，不影响其他项目

拆分策略

1. 分类规则

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 选择

最佳实践

根 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。

常见错误