Loading...
Loading...
Compare original and translation side by side
这条规则 → 全局生效？ → 是 → 根 AGENTS.md
→ 特定模块？ → 是 → 子目录 AGENTS.md 或 Skill
→ 复杂工作流？ → 是 → Skill
→ 不确定？ → 考虑是否真的需要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| 陷阱 | 问题 | 正确做法 |
|---|---|---|
| 把所有规则塞进一个文件 | 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 |
| 层级 | 内容 | 加载时机 |
|---|---|---|
| 1. Metadata | name + description | 始终可见 |
| 2. SKILL.md body | 核心指令 | Agent 判断相关时 |
| 3. References | 详细文档 | 需要时才读取 |
| 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 |
docs/~/.config/opencode/AGENTS.mddocs/~/.config/opencode/AGENTS.md~/.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)| 层级 | 应包含 | 不应包含 |
|---|---|---|
| 用户全局 | 跨项目通用规则（语言偏好、Git 规范） | 项目特定规则、模块规则 |
| 项目根目录 | 项目特定规则（项目架构、团队约定） | 已在用户全局定义的规则、模块规则 |
| 模块目录 | 模块特定规则（技术栈规范、文件命名） | 已在上层定义的规则 |
undefined| 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 |
undefinedundefinedundefined~/.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)| 内容类型 | 放置位置 | 示例 |
|---|---|---|
| 用户全局约束 | | 语言偏好、Git 规范、核心原则 |
| 项目全局约束 | 项目根目录 AGENTS.md | 项目架构、团队约定、入口说明 |
| 模块/文件夹规则 | 该文件夹下的 AGENTS.md | Python 规范、前端规范、API 模块规则 |
| 项目级文档说明 | | 架构说明、文档编写规范、项目指南 |
| 复杂工作流 | Skill | 部署流程、PR 创建流程 |
| Content Type | Placement | Example |
|---|---|---|
| User global constraints | | 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 | | Architecture descriptions, documentation writing specifications, project guides |
| Complex workflows | Skill | Deployment processes, PR creation processes |
| 规则类型 | 放置位置 | 示例 |
|---|---|---|
| 用户全局规则 | | 语言偏好、Git 规范、核心原则 |
| 项目全局规则 | 项目根 AGENTS.md | 项目架构、团队约定、入口说明 |
| 模块规则 | 子目录 AGENTS.md | Python 规范 → |
| 项目文档规则 | | 文档编写规范、架构说明 |
| 任务规则 | Skill | 复杂工作流、特定任务指南 |
| Rule Type | Placement | Example |
|---|---|---|
| User global rules | | 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 → |
| Project documentation rules | | Documentation writing specifications, architecture descriptions |
| Task rules | Skill | Complex workflows, specific task guides |
这条规则是否每次会话都需要？
├── 是 → 是所有项目都需要的吗？
│ ├── 是 → 放到 ~/.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 necessary1. 确认需要哪些全局规则（语言、原则、Git）
2. 判断是否有模块级规则需要单独放置
3. 编写精简的根 AGENTS.md
4. 如有需要，创建子目录 AGENTS.md、docs/AGENTS.md 或 Skill1. 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 Skill1. 读取现有 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)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)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)| 场景 | 推荐 | 原因 |
|---|---|---|
| 跨项目个人偏好（语言、Git） | | 所有项目共享 |
| 项目约束（架构、团队约定） | 项目 AGENTS.md | 项目级生效 |
| 技术栈规范（Python、前端） | 子目录 AGENTS.md 或 Skill | 按需加载 |
| 项目文档/架构说明 | | 需要时加载 |
| 复杂工作流（部署、PR） | Skill | 渐进披露 + 可复用 |
| 团队约定（命名、格式） | 项目 AGENTS.md | 全局约束 |
| Scenario | Recommendation | Reason |
|---|---|---|
| Cross-project personal preferences (language, Git) | | 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 | | Loaded when needed |
| Complex workflows (deployment, PR) | Skill | Progressive disclosure + reusable |
| Team agreements (naming, formatting) | Project AGENTS.md | Global constraints |
undefinedundefinedundefinedundefinedundefinedundefinedundefinedundefinedundefinedundefinedundefinedundefined| 错误 | 后果 | 修正 |
|---|---|---|
| 根 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 |