optimize-agents-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AGENTS.md 编写与优化指南

Guide for Writing and Optimizing AGENTS.md

问题诊断

Problem Diagnosis

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

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

Split AGENTS.md when it exhibits the following symptoms:

The file exceeds 100 lines and contains rules for multiple unrelated modules
Rules for different tech stacks are mixed (Python + Frontend + Database)
The Agent loads a large amount of irrelevant content in each session
High coupling between rules, making independent maintenance difficult

创建 AGENTS.md 时的原则

Principles for Creating AGENTS.md

1. 从精简开始

1. Start with Simplicity

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

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

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

The root AGENTS.md should only contain rules that are "required in every session":

Language preferences
Core working principles
Global Git specifications
Project entry instructions

Goal: Keep the root AGENTS.md under 50 lines.

2. 按作用域规划

2. Plan by Scope

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

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

Before adding a rule, first determine its scope:

This rule → Global effect? → Yes → Root AGENTS.md
         → Specific module? → Yes → Subdirectory AGENTS.md or Skill
         → Complex workflow? → Yes → Skill
         → Uncertain? → Consider if it's really necessary

3. 避免常见陷阱

3. Avoid Common Pitfalls

陷阱	问题	正确做法
把所有规则塞进一个文件	Context 浪费、Agent 困惑	按作用域拆分
教程式内容（如何使用 X）	每次会话都加载无关内容	放到 Skill 或文档
过于具体的命令示例	规则膨胀、难以维护	只写核心原则
与其他规则冲突	Agent 行为不一致	合并或删除冲突规则

Pitfall	Problem	Correct Approach
Stuffing all rules into one file	Context waste, Agent confusion	Split by scope
Tutorial-style content (how to use X)	Irrelevant content loaded in every session	Place in Skill or documentation
Overly specific command examples	Rule bloat, difficult to maintain	Only write core principles
Conflicts with other rules	Inconsistent Agent behavior	Merge or delete conflicting rules

4. 写作风格

4. Writing Style

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

Concise: Use phrases instead of paragraphs
Clear: Avoid words like "maybe" or "perhaps"; use "should" or "prohibit"
Structured: Use lists and tables for quick scanning
Explain why: Briefly state the importance of each rule

渐进式披露原则

Progressive Disclosure Principle

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

层级	内容	加载时机
1. Metadata	name + description	始终可见
2. SKILL.md body	核心指令	Agent 判断相关时
3. References	详细文档	需要时才读取

好处：

节省 context window
Agent 只看到相关规则
规则更易维护

Core idea: Start simple, add complexity on demand.

Level	Content	Loading Timing
1. Metadata	name + description	Always visible
2. SKILL.md body	Core instructions	Loaded when the Agent judges it relevant
3. References	Detailed documentation	Loaded only when needed

Benefits:

Saves context window space
The Agent only sees relevant rules
Rules are easier to maintain

文件放置规则（重要）

File Placement Rules (Important)

核心原则

Core Principles

与特定文件夹/模块相关的 AGENTS.md → 放在该文件夹下
与整个项目相关的通用文档型 AGENTS.md → 放在
```
docs/
```
目录下
用户全局规则 → 放在
```
~/.config/opencode/AGENTS.md
```
（适用于所有项目）

AGENTS.md related to a specific folder/module → Place in that folder
Project-wide document-type AGENTS.md → Place in the
```
docs/
```
directory
User global rules → Place in
```
~/.config/opencode/AGENTS.md
```
(applies to all projects)

层级结构

Hierarchical Structure

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

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

~/.config/opencode/AGENTS.md   # User global (shared by all projects)
    ↓ Inherit/Override
project/AGENTS.md              # Project root (project-level rules)
    ↓ Inherit/Override
project/src/python/AGENTS.md   # Module-level (specific module rules)

Rule Priority: Module-level > Project-level > User global-level (more specific rules override more general ones)

禁止重复原则

No Duplication Principle

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

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

正确做法：

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

示例：

markdown

undefined

AGENTS.md files at different levels must not contain duplicate content for the following reasons:

Wastes context window space
May cause rule conflicts
Increases maintenance burden

Correct Approach:

Level	Should Contain	Should Not Contain
User global	Cross-project general rules (language preferences, Git specifications)	Project-specific rules, module rules
Project root	Project-specific rules (project architecture, team agreements)	Rules already defined in user global, module rules
Module directory	Module-specific rules (tech stack specifications, file naming)	Rules already defined in upper levels

Example:

markdown

undefined

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

❌ Wrong: Project AGENTS.md duplicates user global rules

语言

Language

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

Always respond in Chinese. # Already defined in ~/.config/opencode/AGENTS.md, duplicate!

Git

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

Short commit messages, no prefix # Already defined in ~/.config/opencode/AGENTS.md, duplicate!

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

✅ Correct: Project AGENTS.md only contains project-specific rules

项目结构

Project Structure

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

src/ is the source code directory, tests/ is the test directory.

团队约定

Team Agreement

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

undefined

PRs must be reviewed by at least one person.

undefined

文件放置示例

File Placement Example

~/.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                # User global rules (shared by all projects)

project/
├── AGENTS.md                # Project global rules (< 50 lines)
├── docs/
│   ├── AGENTS.md            # Project-level documentation rules, architecture descriptions
│   ├── architecture.md      # Architecture documentation
│   └── api-guide.md         # API usage guide
├── src/
│   ├── python/
│   │   └── AGENTS.md        # Python module-specific rules
│   └── frontend/
│       └── AGENTS.md        # Frontend module-specific rules
└── .opencode/
    └── skills/
        └── deploy/SKILL.md  # Deployment workflow (complex task)

判断标准

Judgment Criteria

内容类型	放置位置	示例
用户全局约束	`~/.config/opencode/AGENTS.md`	语言偏好、Git 规范、核心原则
项目全局约束	项目根目录 AGENTS.md	项目架构、团队约定、入口说明
模块/文件夹规则	该文件夹下的 AGENTS.md	Python 规范、前端规范、API 模块规则
项目级文档说明	`docs/AGENTS.md`	架构说明、文档编写规范、项目指南
复杂工作流	Skill	部署流程、PR 创建流程

Content Type	Placement	Example
User global constraints	`~/.config/opencode/AGENTS.md`	Language preferences, Git specifications, core principles
Project global constraints	Project root AGENTS.md	Project architecture, team agreements, entry instructions
Module/folder rules	AGENTS.md in that folder	Python specifications, frontend specifications, API module rules
Project-level documentation instructions	`docs/AGENTS.md`	Architecture descriptions, documentation writing specifications, project guides
Complex workflows	Skill	Deployment processes, PR creation processes

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

Why Distinguish Between docs/ and Subdirectory AGENTS.md?

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

Subdirectory AGENTS.md: Automatically loaded when the Agent works in that directory, providing immediate context
docs/AGENTS.md: Project-level instructions, loaded only when explicitly referenced or searched, avoiding loading large amounts of documentation content in every session

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

Why Distinguish Between User Global and Project AGENTS.md?

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

User global AGENTS.md: Define once, shared by all projects, avoiding repeating the same personal preferences in each project
Project AGENTS.md: Project-specific rules, only effective in this project, without affecting other projects

拆分策略

Split Strategy

1. 分类规则

1. Categorize Rules

规则类型	放置位置	示例
用户全局规则	`~/.config/opencode/AGENTS.md`	语言偏好、Git 规范、核心原则
项目全局规则	项目根 AGENTS.md	项目架构、团队约定、入口说明
模块规则	子目录 AGENTS.md	Python 规范 → `python/AGENTS.md`
项目文档规则	`docs/AGENTS.md`	文档编写规范、架构说明
任务规则	Skill	复杂工作流、特定任务指南

Rule Type	Placement	Example
User global rules	`~/.config/opencode/AGENTS.md`	Language preferences, Git specifications, core principles
Project global rules	Project root AGENTS.md	Project architecture, team agreements, entry instructions
Module rules	Subdirectory AGENTS.md	Python specifications → `python/AGENTS.md`
Project documentation rules	`docs/AGENTS.md`	Documentation writing specifications, architecture descriptions
Task rules	Skill	Complex workflows, specific task guides

2. 决策树

2. Decision Tree

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

Is this rule needed in every session?
├── Yes → Is it needed for all projects?
│   ├── Yes → Place in ~/.config/opencode/AGENTS.md (user global)
│   └── No → Place in project root AGENTS.md
└── No → Is it for a specific module/folder?
    ├── Yes → Place in AGENTS.md under that folder
    └── No → Is it project-level documentation/architecture description?
        ├── Yes → Place in docs/AGENTS.md
        └── No → Is it a complex workflow?
            ├── Yes → Create a Skill
            └── No → Consider if this rule is really necessary

执行步骤

Execution Steps

1. 创建新的 AGENTS.md

1. Create a New AGENTS.md

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

1. Confirm which global rules are needed (language, principles, Git)
2. Determine if module-level rules need to be placed separately
3. Write a concise root AGENTS.md
4. If needed, create subdirectory AGENTS.md, docs/AGENTS.md or Skill

2. 分析现有内容

2. Analyze Existing Content

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

1. Read the existing AGENTS.md
2. List all rule modules
3. Mark the scope of each module (global/module/project documentation/task)

3. 制定拆分计划

3. Develop a Split Plan

向用户展示：

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

Show users:

Which content remains in the root directory
Which content is split into subdirectory AGENTS.md
Which content should be placed in docs/AGENTS.md
A content summary for each new file

4. 执行拆分

4. Execute the Split

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

1. Create subdirectory AGENTS.md, docs/AGENTS.md or Skill files
2. Migrate relevant rules (maintain format and hierarchy)
3. Update the root AGENTS.md, removing split content
4. Add necessary reference notes (optional)

5. 验证

5. Verification

1. 检查根 AGENTS.md 是否精简
2. 确认子目录文件内容完整
3. 验证没有规则丢失或重复
4. 确认 docs/AGENTS.md 包含项目级文档规则（如有）

1. Check if the root AGENTS.md is concise
2. Confirm that subdirectory files have complete content
3. Verify no rules are lost or duplicated
4. Confirm docs/AGENTS.md contains project-level documentation rules (if applicable)

Skill vs AGENTS.md 选择

Skill vs AGENTS.md Selection

场景	推荐	原因
跨项目个人偏好（语言、Git）	`~/.config/opencode/AGENTS.md`	所有项目共享
项目约束（架构、团队约定）	项目 AGENTS.md	项目级生效
技术栈规范（Python、前端）	子目录 AGENTS.md 或 Skill	按需加载
项目文档/架构说明	`docs/AGENTS.md`	需要时加载
复杂工作流（部署、PR）	Skill	渐进披露 + 可复用
团队约定（命名、格式）	项目 AGENTS.md	全局约束

Scenario	Recommendation	Reason
Cross-project personal preferences (language, Git)	`~/.config/opencode/AGENTS.md`	Shared by all projects
Project constraints (architecture, team agreements)	Project AGENTS.md	Effective at project level
Tech stack specifications (Python, frontend)	Subdirectory AGENTS.md or Skill	Loaded on demand
Project documentation/architecture descriptions	`docs/AGENTS.md`	Loaded when needed
Complex workflows (deployment, PR)	Skill	Progressive disclosure + reusable
Team agreements (naming, formatting)	Project AGENTS.md	Global constraints

最佳实践

Best Practices

根 AGENTS.md 保持精简

Keep Root AGENTS.md Concise

markdown

undefined

markdown

undefined

语言

Language

始终用中文回答。

Always respond in Chinese.

核心原则

Core Principles

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

Prioritize simple, maintainable solutions
Avoid over-engineering

Git

简短提交信息，不加前缀

Short commit messages, no prefix

模块规则

Module Rules

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

Python projects → Refer to src/python/AGENTS.md Frontend projects → Refer to src/frontend/AGENTS.md

文档

Documentation

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

undefined

Project architecture → Refer to docs/AGENTS.md

undefined

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

Subdirectory AGENTS.md Focuses on a Single Module

markdown

undefined

markdown

undefined

Python 项目规范

Python Project Specifications

工具

Tools

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

Use uv for dependency management, ruff for formatting.

原则

Principles

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

undefined

Fast-fail: Only use try-except at the outer layer
Prohibit hard-coded credentials

undefined

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

docs/AGENTS.md for Project-level Documentation

markdown

undefined

markdown

undefined

项目文档规范

Project Documentation Specifications

架构说明

Architecture Description

本项目采用三层架构，详见 architecture.md。

This project uses a three-tier architecture, see architecture.md for details.

API 文档

API Documentation

REST API 规范 → api-guide.md
GraphQL Schema → schema.graphql

undefined

REST API specifications → api-guide.md
GraphQL Schema → schema.graphql

undefined

Skill 用于复杂任务

Skill for Complex Tasks

当规则包含多步骤工作流、需要渐进披露大量内容时，创建 Skill 而非 AGENTS.md。

When rules involve multi-step workflows or require progressive disclosure of large amounts of content, create a Skill instead of AGENTS.md.

常见错误

Common Mistakes

错误	后果	修正
根 AGENTS.md 过长	Context 浪费	拆分到子目录、docs/ 或 Skill
规则重复定义	Agent 困惑	每条规则只出现一次
不同层级内容重复	Context 浪费、规则冲突	每条规则只在最合适的层级定义一次
拆分粒度过细	维护负担	合并相关规则
忘记删除原内容	规则冲突	拆分后必须删除原文
模块规则放在根目录	不相关规则被加载	移到对应子目录
项目文档规则放在根目录	Context 膨胀	移到 docs/AGENTS.md
项目规则放在用户全局	影响其他项目	移到项目 AGENTS.md

Mistake	Consequence	Correction
Overly long root AGENTS.md	Context waste	Split into subdirectories, docs/ or Skill
Duplicate rule definitions	Agent confusion	Each rule appears only once
Duplicate content across levels	Context waste, rule conflicts	Define each rule only at the most appropriate level
Overly fine-grained splitting	Maintenance burden	Merge related rules
Forgetting to delete original content	Rule conflicts	Must delete original content after splitting
Module rules placed in root directory	Irrelevant rules loaded	Move to corresponding subdirectory
Project documentation rules placed in root directory	Context bloat	Move to docs/AGENTS.md
Project rules placed in user global	Affects other projects	Move to project AGENTS.md