上下文文档管理_ai-context

以下为本文档的中文说明

AI 上下文文档技能是一个专门用于创建、更新和维护 AI 辅助编程所需的结构化文档的系统化指南。它的核心功能涵盖 AI 文档文件的结构规范、编写约定和演进指南。该技能定义了一套完整的文件层次结构：根目录的 AGENTS.md 作为根上下文，每次交互时加载，要求保持最小化以节省令牌；CLAUDE.md 是 Claude Code 的入口文件，会加载 AGENTS.md；.github/skills/ 目录下按主题组织的 SKILL.md 文件按需加载；以及包级别和文件夹级别的 AGENTS.md。使用场景覆盖所有使用 AI 编码助手的开发项目。当需要为项目建立 AI 上下文文件时、当需要更新已有文档以反映项目变化时、或当需要维护 AI 技能描述文件时，该技能提供标准化的操作指南。核心特点在于文件层次结构的设计理念和令牌效率的考量，根 AGENTS.md 只需包含最基本的信息，详细上下文放在按需加载的 SKILL.md 中。从技术实现角度来看，该技能采用了业界成熟的最佳实践和设计模式，确保了代码质量和系统稳定性。通过持续的功能迭代和社区反馈收集，它不断优化和完善自身的功能集与用户体验。对于正在寻找同类解决方案的团队来说，这是一个经过验证的可靠选择，

AI Context Documentation

How to write and maintain the structured documentation that AI coding assistants consume.

File Hierarchy

AGENTS.md # Root context — always loaded by agents CLAUDE.md # Required for Claude Code (loads AGENTS.md) .github/skills/<topic>/SKILL.md # On-demand detailed context packages/<name>/AGENTS.md # Package-specific context <any-folder>/AGENTS.md # Folder-specific context

Root Files

AGENTS.md

Always loaded on every interaction. Keep itminimalto save tokens.

Must contain:

  • One-line project description
  • Essential commands (run, test, build)
  • Repository structure overview (top-level dirs only)
  • Skills index table linking to eachSKILL.md
  • Key entry points for common tasks

Mustnotcontain:

  • Detailed explanations (put those in skills)
  • Code examples longer than one line
  • Duplicated content from skills

CLAUDE.md

Required because Claude Code doesn’t loadAGENTS.mdnatively. It bridges Claude Code into the same context system. Contents:

Read [AGENTS.md](AGENTS.md) before starting any task. ## Skills Load these for detailed context on specific topics: | Skill | When to use | |-------|-------------| | [<name>](.github/skills/<name>/SKILL.md) | <description> |

Keep in sync with the skills table inAGENTS.md.

Skills

Creating a Skill

  1. Create.github/skills/<topic>/SKILL.md
  2. Add YAML frontmatter withnameanddescription
  3. Add an entry to the skills table in bothAGENTS.mdandCLAUDE.md

SKILL.md Format

--- name: <topic> description: <when an agent should load this — be specific about triggers> --- # <Title> <One-line summary.> ## <Sections organized by task>

Writing Guidelines

  • Frontmatterdescription: Write it as a trigger — what task or question should cause an agent to load this skill
  • Be concise: Use tables over prose, code snippets over explanations
  • Be specific: File paths, command names, function signatures — not vague descriptions
  • No duplication: If info exists in another skill, reference it instead of repeating
  • Actionable structure: Organize by what the agent needs todo, not by architecture

Package & Folder Context

AddAGENTS.mdinside a package or folder when:

  • The directory has non-obvious conventions agents keep getting wrong
  • There are local commands, patterns, or gotchas not covered by root docs

Keep these files very short — a few lines of context is often enough.

When to Update

TriggerAction
Agent repeatedly asks about a topicCreate a new skill
Agent gets something wrong despite docsRefine the relevant skill
New package/directory with unique patternsAdd a localAGENTS.md
Architecture or tooling changesUpdate affected skills
Skill grows too largeSplit into multiple skills
Skills table changesUpdate bothAGENTS.mdandCLAUDE.md

Principles

  1. Token budget: Root files stay small; details go in skills
  2. Load on demand: Skills are only read when relevant to the task
  3. Living docs: Update when patterns change — stale docs are worse than none
  4. Cross-platform:AGENTS.md+.github/skills/is the shared convention;CLAUDE.mdbridges Claude Code which doesn’t loadAGENTS.mdnatively