agents-md-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AGENTS.md Generator

AGENTS.md 生成器

Generate hierarchical AGENTS.md structures optimized for AI coding agents with minimal token usage.

为AI编码代理生成优化的层级化AGENTS.md结构，实现令牌使用最小化。

Core Principles

核心原则

Root AGENTS.md is LIGHTWEIGHT - Only universal guidance, links to sub-files (~100-200 lines max)
Nearest-wins hierarchy - Agents read closest AGENTS.md to file being edited
JIT indexing - Provide paths/globs/commands, NOT full content
Token efficiency - Small, actionable guidance over encyclopedic docs
Sub-folder files have MORE detail - Specific patterns, examples, commands

根目录AGENTS.md 需轻量化 - 仅包含通用指引，链接至子文件（最多约100-200行）
就近优先层级 - 代理读取与当前编辑文件最接近的AGENTS.md
即时索引（JIT indexing） - 提供路径/通配符/命令，而非完整内容
令牌效率 - 优先提供简短、可执行的指引，而非百科全书式文档
子文件夹文件需更详细 - 包含特定模式、示例、命令

Workflow

工作流程

Phase 1: Repository Analysis

阶段1：仓库分析

Analyze and report:

Repository type: Monorepo, multi-package, or simple?
Tech stack: Languages, frameworks, key tools

Major directories needing own AGENTS.md:

Apps (
```
apps/web
```
,
```
apps/api
```
,
```
apps/mobile
```
)
Services (
```
services/auth
```
,
```
services/transcribe
```
)
Packages (
```
packages/ui
```
,
```
packages/shared
```
)
Workers (
```
workers/queue
```
,
```
workers/cron
```
)

Build system: pnpm/npm/yarn workspaces? Turborepo? Lerna?
Testing setup: Jest, Vitest, Playwright, pytest?
Key patterns: Organization, conventions, examples, anti-patterns

Present as structured map before generating files.

分析并报告：

仓库类型：单仓库（Monorepo）、多包仓库还是简单仓库？
技术栈：使用的语言、框架、关键工具

需要独立AGENTS.md的主要目录：

应用（
```
apps/web
```
,
```
apps/api
```
,
```
apps/mobile
```
）
服务（
```
services/auth
```
,
```
services/transcribe
```
）
包（
```
packages/ui
```
,
```
packages/shared
```
）
工作进程（
```
workers/queue
```
,
```
workers/cron
```
）

构建系统：pnpm/npm/yarn工作区？Turborepo？Lerna？
测试配置：Jest、Vitest、Playwright、pytest？
关键模式：组织方式、约定、示例、反模式

在生成文件前，以结构化地图形式呈现分析结果。

Phase 2: Root AGENTS.md

阶段2：根目录AGENTS.md

Create lightweight root (~100-200 lines):

markdown

undefined

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

markdown

undefined

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
API:
```
apps/api/
```
-> see apps/api/AGENTS.md

Web UI:
```
apps/web/
```
-> see apps/web/AGENTS.md
API:
```
apps/api/
```
-> see 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

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]

undefined

[3-5 lines: what must pass before PR]

undefined

Phase 3: Sub-Folder AGENTS.md

阶段3：子文件夹AGENTS.md

For each major package, create detailed AGENTS.md:

markdown

undefined

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

markdown

undefined

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

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

[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"
```

[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"

[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

undefined

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

undefined

Phase 4: Special Templates

阶段4：特殊模板

Design System / UI Package

设计系统 / UI 包

markdown

undefined

markdown

undefined

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

undefined

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

undefined

Database / Data Layer

数据库 / 数据层

markdown

undefined

markdown

undefined

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

undefined

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

undefined

API / Backend Service

API / 后端服务

markdown

undefined

markdown

undefined

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

undefined

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

undefined

Testing

测试

markdown

undefined

markdown

undefined

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/**
```

undefined

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

undefined

Output Format

输出格式

Provide files in order:

Analysis Summary
Root AGENTS.md (complete)
Each Sub-Folder AGENTS.md (with file path)

Format:

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

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

按以下顺序提供文件：

分析摘要
根目录AGENTS.md（完整内容）
每个子文件夹AGENTS.md（含文件路径）

格式：

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

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

agents-md-generator

Original

Translation

AGENTS.md Generator

AGENTS.md 生成器

Core Principles

核心原则

Workflow

工作流程

Phase 1: Repository Analysis

阶段1：仓库分析

Phase 2: Root AGENTS.md

阶段2：根目录AGENTS.md

Project Name

Project Name

Project Snapshot

Project Snapshot

Root Setup Commands

Root Setup Commands

Universal Conventions

Universal Conventions

Security & Secrets

Security & Secrets

JIT Index

JIT Index

Package Structure

Package Structure

Quick Find Commands

Quick Find Commands

Definition of Done

Definition of Done

Phase 3: Sub-Folder AGENTS.md

阶段3：子文件夹AGENTS.md

Package Name

Package Name

Package Identity

Package Identity

Setup & Run

Setup & Run

Patterns & Conventions

Patterns & Conventions

Key Files

Key Files

JIT Index Hints

JIT Index Hints

Common Gotchas

Common Gotchas

Pre-PR Checks

Pre-PR Checks

Phase 4: Special Templates

阶段4：特殊模板

Design System / UI Package

设计系统 / UI 包

Design System

Design System

Database / Data Layer

数据库 / 数据层

Database

Database

API / Backend Service

API / 后端服务

API Patterns

API Patterns

Testing

测试

Testing

Testing

Output Format

输出格式

Quality Checklist

质量检查清单