# Optimize Agents Md

> AGENTS.md 编写与优化指南，遵循渐进式披露原则。当用户创建、修改或重构 AGENTS.md，讨论 AI agent 指令结构、规则放置位置，或提到「渐进式披露」「模块化」「AGENTS.md 最佳实践」时，务必加载此 skill。即使用户只是说「帮我写个 AGENTS.md」「优化一下这个配置文件」「拆分一下规则」，也应该使用此 skill。

- Skill: `cnife/optimize-agents-md` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cnife/optimize-agents-md`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cnife/optimize-agents-md/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: cnife (https://skillmd.com/u/cnife)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cnife/optimize-agents-md

---


# AGENTS.md 编写与优化指南

## 问题诊断

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

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

## 创建 AGENTS.md 时的原则

### 1. 从精简开始

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

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

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

### 2. 按作用域规划

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

```text
这条规则 → 全局生效？ → 是 → 根 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 不得直接修改该文件**）

### 层级结构

```text
~/.config/opencode/AGENTS.md   # 用户全局（所有项目共享）
    ↓ 继承/覆盖
project/AGENTS.md              # 项目根目录（项目级规则）
    ↓ 继承/覆盖
project/src/python/AGENTS.md   # 模块级（特定模块规则）
```

**规则优先级**：模块级 > 项目级 > 用户全局级（更具体的规则覆盖更通用的规则）

### 禁止重复原则

**不同层级的 AGENTS.md 不能有重复内容**，原因：

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

**正确做法**：

| 层级 | 应包含 | 不应包含 |
|------|--------|----------|
| 用户全局 | 跨项目通用规则（语言偏好、Git 规范） | 项目特定规则、模块规则 |
| 项目根目录 | 项目特定规则（项目架构、团队约定） | 已在用户全局定义的规则、模块规则 |
| 模块目录 | 模块特定规则（技术栈规范、文件命名） | 已在上层定义的规则 |

**示例**：

```markdown
# ❌ 错误：项目 AGENTS.md 重复用户全局规则

## 语言

始终用中文回答。 # 已在 ~/.config/opencode/AGENTS.md 定义，重复！

## Git

简短提交信息，不加前缀    # 已在 ~/.config/opencode/AGENTS.md 定义，重复！

## ✅ 正确：项目 AGENTS.md 只包含项目特定规则

## 项目结构

src/ 为源码目录，tests/ 为测试目录。

## 团队约定

PR 必须经过至少一人审核。
```

### 文件放置示例

```text
~/.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. 决策树

```text
这条规则是否每次会话都需要？
├── 是 → 是所有项目都需要的吗？
│   ├── 是 → 建议放到 ~/.config/opencode/AGENTS.md（用户全局；agent 只提供草稿，用户手动应用）
│   └── 否 → 放到项目根目录 AGENTS.md
└── 否 → 是特定模块/文件夹的吗？
    ├── 是 → 放到该文件夹下的 AGENTS.md
    └── 否 → 是项目级文档/架构说明吗？
        ├── 是 → 放到 docs/AGENTS.md
        └── 否 → 是复杂工作流吗？
            ├── 是 → 创建 Skill
            └── 否 → 考虑是否真的需要这条规则
```

## 执行步骤

### 1. 创建新的 AGENTS.md

```text
1. 确认需要哪些全局规则（语言、原则、Git）
2. 判断是否有模块级规则需要单独放置
3. 编写精简的根 AGENTS.md
4. 如有需要，创建子目录 AGENTS.md、docs/AGENTS.md 或 Skill
```

### 2. 分析现有内容

```text
1. 读取现有 AGENTS.md
2. 列出所有规则模块
3. 标记每个模块的作用域（全局/模块/项目文档/任务）
```

### 3. 制定拆分计划

向用户展示：

- 哪些内容保留在根目录
- 哪些内容拆分到子目录 AGENTS.md
- 哪些内容应该放到 docs/AGENTS.md
- 每个新文件的内容概要

### 4. 执行拆分

```text
1. 创建子目录 AGENTS.md、docs/AGENTS.md 或 Skill 文件
2. 迁移相关规则（保持格式和层级）
3. 更新根 AGENTS.md，移除已拆分内容
4. 添加必要的引用说明（可选）
```

### 5. 验证

```text
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 保持精简

```markdown
# 语言

始终用中文回答。

## 核心原则

- 优先简单、可维护的方案
- 不要过度设计

## Git

- 简短提交信息，不加前缀

## 模块规则

Python 项目 → 参考 src/python/AGENTS.md
前端项目 → 参考 src/frontend/AGENTS.md

## 文档

项目架构 → 参考 docs/AGENTS.md
```

### 子目录 AGENTS.md 聚焦单一模块

```markdown
# Python 项目规范

## 工具

依赖管理用 uv，格式化用 ruff。

## 原则

- Fast-fail：外层才用 try-except
- 禁止硬编码凭证
```

### docs/AGENTS.md 用于项目级文档

```markdown
# 项目文档规范

## 架构说明

本项目采用三层架构，详见 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 |