agents-md-generator

AGENTS.md 生成器

生成分层的 AGENTS.md 结构，以尽可能少的 token 优化 AI 编码 Agent 的使用体验。

核心原则

1. 根目录 AGENTS.md 保持轻量——仅包含通用指导和指向子文件的链接（最多约 100–200 行）
2. 就近优先的层级结构——Agent 会读取距离待编辑文件最近的 AGENTS.md
3. 即时索引——提供路径、glob 模式和命令，而非完整内容
4. 提高 token 使用效率——提供精简、可执行的指导，而非百科全书式文档
5. 子文件夹中的文件包含更多细节——具体模式、示例和命令

工作流

阶段 1：仓库分析

分析并报告：

1. 仓库类型：单体仓库、多包仓库，还是简单仓库？
2. 技术栈：语言、框架、关键工具
3. 需要单独创建 AGENTS.md 的主要目录：
   • 应用（apps/web、apps/api、apps/mobile）
   • 服务（services/auth、services/transcribe）
   • 包（packages/ui、packages/shared）
   • Worker（workers/queue、workers/cron）
4. 构建系统：pnpm/npm/yarn 工作区？Turborepo？Lerna？
5. 测试配置：Jest、Vitest、Playwright、pytest？
6. 关键模式：组织方式、约定、示例、反模式

生成文件之前，先以结构化映射的形式呈现。

阶段 2：根目录 AGENTS.md

创建轻量的根目录文件（约 100–200 行）：

# Project Name

## Project Snapshot
[3-5 lines: repo type, tech stack, note about sub-AGENTS.md files]

## Root Setup Commands
[5-10 lines: install, build all, typecheck all, test all]

## Universal Conventions
[5-10 lines: code style, commit format, branch strategy, PR requirements]

## Security & Secrets
[3-5 lines: never commit tokens, .env patterns, PII handling]

## JIT Index
### 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)

### 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`

## Definition of Done
[3-5 lines: what must pass before PR]

阶段 3：子文件夹 AGENTS.md

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

# Package Name

## Package Identity
[2-3 lines: what it does, primary tech]

## Setup & Run
[5-10 lines: install, dev, build, test, lint commands]

## Patterns & Conventions
[10-20 lines - MOST IMPORTANT SECTION]
- File organization rules
- Naming conventions
- Examples with actual file paths:
  - DO: Use pattern from `src/components/Button.tsx`
  - DON'T: Class components like `src/legacy/OldButton.tsx`
  - Forms: Copy `src/components/forms/ContactForm.tsx`
  - API calls: See `src/hooks/useUser.ts`

## Key Files
[5-10 lines: important files to understand package]
- Auth: `src/auth/provider.tsx`
- API client: `src/lib/api.ts`
- Types: `src/types/index.ts`

## JIT Index Hints
[5-10 lines: search commands for this package]
- Find component: `rg -n "export function .*" src/components`
- Find hook: `rg -n "export const use" src/hooks`
- Find tests: `find . -name "*.test.ts"`

## Common Gotchas
[3-5 lines if applicable]
- "Auth requires NEXT_PUBLIC_ prefix for client-side"
- "Always use @/ imports for absolute paths"

## Pre-PR Checks
[2-3 lines: copy-paste command]
pnpm --filter @repo/web typecheck && pnpm --filter @repo/web test

阶段 4：特殊模板

设计系统 / UI 包

## Design System
- Components: `packages/ui/src/components/**`
- Use design tokens from `packages/ui/src/tokens.ts`
- Component gallery: `pnpm --filter @repo/ui storybook`
- Examples:
  - Buttons: `packages/ui/src/components/Button/Button.tsx`
  - Forms: `packages/ui/src/components/Input/Input.tsx`

数据库 / 数据层

## Database
- ORM: Prisma / Drizzle / TypeORM
- Schema: `prisma/schema.prisma`
- Migrations: `pnpm db:migrate`
- Connection: via `src/lib/db.ts` singleton
- NEVER run migrations in tests

API / 后端服务

## API Patterns
- REST routes: `src/routes/**/*.ts`
- Auth middleware: `src/middleware/auth.ts`
- Validation: Zod schemas in `src/schemas/**`
- Errors: `ApiError` from `src/lib/errors.ts`
- Example: `src/routes/users/get.ts`

测试

## Testing
- Unit: `*.test.ts` colocated
- Integration: `tests/integration/**`
- E2E: `tests/e2e/**` (Playwright)
- Single test: `pnpm test -- path/to/file.test.ts`
- Mocks: `src/test/mocks/**`

输出格式

按以下顺序提供文件：

1. 分析摘要
2. 根目录 AGENTS.md（完整内容）
3. 每个子文件夹的 AGENTS.md（注明文件路径）

格式：

---
File: `AGENTS.md` (root)
---
[content]

---
File: `apps/web/AGENTS.md`
---
[content]

质量检查清单

生成之前，请确认：

• 根目录 AGENTS.md 少于 200 行
• 根目录文件链接到所有子 AGENTS.md 文件
• 每个子文件都有具体示例（实际路径）
• 命令可直接复制粘贴运行
• 根目录文件和子文件之间没有重复内容
• 即时索引提示使用实际模式（ripgrep、find、glob）
• 每条“DO”都包含实际文件示例
• 每条“DON'T”都引用实际反模式
• PR 前检查均为单条命令