hierarchical-agents

分层 Agent 文档生成器

目的

为代码库创建分层的 AGENTS.md 系统，让 AI 编码 Agent 能够以最少的 Token 高效工作。生成轻量级的根目录文档，并依据“就近优先”原则提供详细的子文件夹指南。

适用场景

• 为新项目创建 AGENTS.md 文档
• 为单体仓库配置 AI Agent 指南
• 优化现有文档以提高 Token 使用效率
• 实施 JIT（即时）索引模式

流程

按顺序执行以下阶段。完整详情请参阅 references/generation-process.md。

阶段 1：分析代码库

分析代码库：

1. 仓库类型（单体仓库、多包、简单项目）
2. 技术栈（语言、框架、工具）
3. 主要目录（应用、服务、包）
4. 构建系统和测试配置
5. 关键模式、约定和反模式

输出：生成任何文件之前，先创建结构化的仓库地图。

阶段 2：生成根目录 AGENTS.md

根目录文档必须轻量：最多约 100-200 行，只包含通用指南。它充当索引和导航中心。Agent 会读取距离正在编辑的文件最近的 AGENTS.md——子文件夹中的文件会覆盖根目录文件（就近优先）。

创建根目录文件，包含以下部分：

1. 项目概览（3-5 行）
   • 仓库类型
   • 主要技术栈
   • 关于子包 AGENTS.md 文件的说明
2. 根目录设置命令（5-10 行）
   • 安装依赖、构建全部内容、检查全部类型、测试全部内容
3. 通用约定（5-10 行）
   • 代码风格（TypeScript 严格模式？Prettier？ESLint？）
   • 提交格式（Conventional Commits？）
   • 分支策略
   • PR 要求
4. 实现规则（2-3 行）——参见下方示例
5. 开发工作流（5-7 行）——参见下方示例
6. 安全与密钥（3-5 行）
   • 切勿提交令牌
   • 密钥的存放位置（.env 模式）
   • PII 处理
7. JIT 索引 - 目录地图（10-20 行）——参见下方示例
   • 按路径引用文件，不要引用文件内容
   • 提供 Agent 可执行的搜索命令
8. 验收标准（3-5 行）
   • PR 前检查清单
   • 必须通过的检查项

实现规则示例：

## Implementation Rules

Before adding ANY external dependency (gems, npm packages, GitHub Actions, Docker images, APIs, CDN links):
- Use WebSearch to verify the latest stable version BEFORE implementation
- Never trust training data for version numbers

JIT 索引示例：

## JIT Index (what to open, not what to paste)

### Package Structure
- Web UI: `apps/web/` -> [see apps/web/AGENTS.md](apps/web/AGENTS.md)
- API: `apps/api/` -> [see apps/api/AGENTS.md](apps/api/AGENTS.md)
- Shared packages: `packages/**/` -> [see packages/README.md]

### Quick Find Commands
- Search function: `rg -n "functionName" apps/** packages/**`
- Find component: `rg -n "export.*ComponentName" apps/web/src`
- Find API routes: `rg -n "export const (GET|POST)" apps/api`

开发工作流示例：

## Development Workflow

- Before coding -> describe approach -> wait for approval
- Ambiguous requirements -> ask first
- If task touches >3 files -> decompose first
- After coding -> list breakage risks + suggest tests
- Bug fix -> write failing test -> fix until green
- When corrected -> add lesson to .agents/lessons/

阶段 3：生成子文件夹 AGENTS.md 文件

子文件夹中的文档应比根目录包含更多细节——具体模式、特定技术的约定，以及代码库中的实际文件示例。

为每个主要包/目录创建详细的 AGENTS.md：

1. 包身份（2-3 行）
2. 设置与运行（5-10 行）
3. 模式与约定（10-20 行）——最重要
4. 关键位置/文件（5-10 行）
5. JIT 索引提示（5-10 行）
6. 常见注意事项（3-5 行）
7. PR 前检查（2-3 行）

关键要求：模式与约定部分必须包含带有“应该做/不应该做”示例的真实文件路径。

阶段 4：特别注意事项

针对特定包类型（设计系统、数据库、API、测试）调整模板。 专用模板请参阅 references/generation-process.md。

目录结构

单体仓库

AGENTS.md                    # Root (lightweight)
apps/
  web/AGENTS.md             # Frontend details
  api/AGENTS.md             # Backend details
packages/
  ui/AGENTS.md              # Design system details
  shared/AGENTS.md          # Shared code details

简单项目

AGENTS.md                    # Root (can be more detailed)
src/
  components/AGENTS.md      # Component patterns
  services/AGENTS.md        # Service patterns

质量检查清单

• 根目录 AGENTS.md 不超过 200 行
• 根目录链接到所有子 AGENTS.md 文件
• 每个子文件都有具体示例（实际文件路径）
• 命令可直接复制粘贴执行
• 根目录与子文件之间没有重复内容
• 每条“应该做”都有真实文件示例
• 每条“不应该做”都引用真实反模式
• 所有路径均为相对路径，且已确认存在
• 只有主要包/领域包含 AGENTS.md——而非每个目录都包含

维护

在以下情况下更新 AGENTS.md：

• 添加新包或主要目录
• 更改构建/测试命令
• 确立新约定
• 重构项目结构

相关资源

• references/generation-process.md - 包含模板的完整分步生成流程