optimize-agents-md

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