agents-md-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AGENTS.md / CLAUDE.md Creator

AGENTS.md / CLAUDE.md 创作指南

Create and maintain AI documentation files that help agents understand your project efficiently using progressive disclosure principles.

基于渐进式披露原则创建和维护AI文档，帮助Agent高效理解你的项目。

Core Philosophy: Iron Rule

核心原则：铁则

Never use line count as a metric. Judge by single source of truth (no duplication), cognitive relevance (only task-relevant info), and maintainability (change once, not everywhere).

绝对不要把行数作为衡量指标。判断标准应当是单一信息源（无重复）、认知相关性（仅保留任务相关信息）、可维护性（一处修改即可，无需多处同步）。

Quick Decision Trees

快速决策树

"I want to create AGENTS.md"

"我想要创建AGENTS.md"

Create AGENTS.md?
├─ Detect project structure → references/project_detection.md
├─ Determine if monorepo → Check for apps/, packages/, workspace configs
├─ Extract essential info → README.md, package.json, folder layout
├─ Choose template → references/templates.md
└─ Apply progressive disclosure → references/progressive_disclosure.md

Create AGENTS.md?
├─ Detect project structure → references/project_detection.md
├─ Determine if monorepo → Check for apps/, packages/, workspace configs
├─ Extract essential info → README.md, package.json, folder layout
├─ Choose template → references/templates.md
└─ Apply progressive disclosure → references/progressive_disclosure.md

"My AGENTS.md is too bloated"

"我的AGENTS.md太臃肿了"

Optimize existing AGENTS.md?
├─ Back up file first → cp AGENTS.md AGENTS.md.bak.$(date)
├─ Classify each section → references/progressive_disclosure.md#content-classification
├─ Create Level 2 references → docs/references/ for detailed content
├─ Update Level 1 → Keep only high-frequency, critical info
└─ Verify completeness → Ensure no information is lost

Optimize existing AGENTS.md?
├─ Back up file first → cp AGENTS.md AGENTS.md.bak.$(date)
├─ Classify each section → references/progressive_disclosure.md#content-classification
├─ Create Level 2 references → docs/references/ for detailed content
├─ Update Level 1 → Keep only high-frequency, critical info
└─ Verify completeness → Ensure no information is lost

"I don't know my project structure type"

"我不知道我的项目结构类型"

Detect project structure?
├─ Check for apps/ or packages/ directories → Monorepo
├─ Check for workspace config (pnpm-workspace.yaml, etc.) → Monorepo
├─ Check for lerna.json, turbo.json, nx.json → Monorepo
├─ Single package.json at root → Polyrepo (likely)
└─ Show detection confidence and ask user to confirm

Detect project structure?
├─ Check for apps/ or packages/ directories → Monorepo
├─ Check for workspace config (pnpm-workspace.yaml, etc.) → Monorepo
├─ Check for lerna.json, turbo.json, nx.json → Monorepo
├─ Single package.json at root → Polyrepo (likely)
└─ Show detection confidence and ask user to confirm

Project Structure Detection

项目结构检测

Auto-Detection Indicators

自动检测指标

Indicator	Type	Evidence
`apps/` directory exists	Monorepo	Multiple applications
`packages/` directory exists	Monorepo	Shared libraries
`pnpm-workspace.yaml`	Monorepo	pnpm workspace config
`turbo.json`	Monorepo	Turborepo build system
`lerna.json`	Monorepo	Lerna monorepo
`nx.json`	Monorepo	Nx monorepo
Single `package.json` at root	Polyrepo	Single package
Multiple top-level `src/` dirs	Polyrepo	Multiple projects

指标	类型	依据
存在 `apps/` 目录	Monorepo	多个应用项目
存在 `packages/` 目录	Monorepo	共享依赖库
`pnpm-workspace.yaml`	Monorepo	pnpm工作区配置
`turbo.json`	Monorepo	Turborepo构建系统
`lerna.json`	Monorepo	Lerna monorepo
`nx.json`	Monorepo	Nx monorepo
根目录仅单个 `package.json`	Polyrepo	单包项目
多个顶层 `src/` 目录	Polyrepo	多个独立项目

Detection Confidence Levels

检测置信度等级

High confidence (≥3 indicators): Proceed without asking
Medium confidence (1-2 indicators): Show findings, ask user to confirm
No clear indicators: Ask user directly

高置信度（≥3个匹配指标）：无需询问直接执行
中置信度（1-2个匹配指标）：展示检测结果，询问用户确认
无明确指标：直接询问用户

Progressive Disclosure Architecture

渐进式披露架构

Three-Level Loading System

三级加载体系

Level 1 (AGENTS.md) - Always loaded
├── One-line project description
├── Essential commands (run, test, build)
├── Repository structure (top-level dirs only)
├── Reference index tables (multi-entry)
└── Key entry points

Level 2 (docs/references/) - On-demand
├── Detailed SOP flows
├── Edge case handling
├── Complete config examples
└── Historical decisions

Level 3 (Project files) - As needed
├── README.md
├── package.json files
└── Config files

Level 1 (AGENTS.md) - 始终加载
├── 项目一句话描述
├── 核心命令（运行、测试、构建）
├── 仓库结构（仅顶层目录）
├── 参考索引表（多入口）
└── 关键入口点

Level 2 (docs/references/) - 按需加载
├── 详细SOP流程
├── 边缘 case 处理
├── 完整配置示例
└── 历史决策记录

Level 3 (项目文件) - 按需要取
├── README.md
├── package.json文件
└── 配置文件

Multi-Entry Principle

多入口原则

The same Level 2 resource can have multiple entry points for different discovery paths:

Entry	Location	Trigger Scenario	User Mindset
Reference index	Start	"I have an error/problem"	"What doc has the answer?"
Before-change table	Middle	"About to modify code"	"What should I know first?"
Trigger index	End	"Long conversation, need to re-orient"	"Which doc was that again?"

This is NOT duplication. It's like a book having a table of contents, an index, and quick reference cards.

同一个Level 2资源可以针对不同查找路径设置多个入口点：

入口	位置	触发场景	用户心态
参考索引	文档开头	"我遇到了报错/问题"	"哪份文档有答案？"
修改前检查表	文档中间	"即将修改代码"	"我需要先知道什么？"
触发索引	文档末尾	"长对话后需要重新梳理上下文"	"之前提到的文档是哪个来着？"

这不是内容重复，就像一本书同时有目录、索引和快速参考卡一样。

AGENTS.md vs CLAUDE.md

AGENTS.md 与 CLAUDE.md 的区别

File Relationship

文件关系

AGENTS.md # Root context - always loaded by agents
CLAUDE.md # Required for Claude Code - loads AGENTS.md

AGENTS.md # 根上下文 - Agent始终加载
CLAUDE.md # Claude Code 专用文件 - 加载AGENTS.md

CLAUDE.md Contents (Minimal Bridge)

CLAUDE.md 内容（极简桥接）

markdown

Read [AGENTS.md](AGENTS.md) before starting any task.

CLAUDE.md exists only because Claude Code doesn't load AGENTS.md natively. Keep it minimal.

markdown

Read [AGENTS.md](AGENTS.md) before starting any task.

CLAUDE.md存在的唯一原因是Claude Code不会原生加载AGENTS.md，保持内容极简即可。

AGENTS.md Essential Structure

AGENTS.md 核心结构

Required Sections (Level 1)

必选章节（Level 1）

Section	Purpose	Keep Minimal
Project description	One-line summary	✅
Essential commands	run, test, build	✅
Repository structure	Top-level directories only	✅
Reference index	Pointers to detailed docs	✅
Key entry points	Common task starting points	✅

章节	用途	保持精简
项目描述	一句话总结	✅
核心命令	运行、测试、构建	✅
仓库结构	仅顶层目录	✅
参考索引	指向详细文档的链接	✅
关键入口点	常见任务的起始位置	✅

Never Include in AGENTS.md (Level 1)

绝对不要放在AGENTS.md（Level 1）的内容

Content	Why	Where Instead
Detailed explanations	Bloats context	Level 2 references
Code examples >1 line	Can be looked up	Level 2 references
Duplicated content	Maintenance burden	Single source
Historical decisions	Low frequency	Level 2 references

内容	原因	替代存放位置
详细说明	占用过多上下文	Level 2参考文档
超过1行的代码示例	可按需查询	Level 2参考文档
重复内容	增加维护成本	单一信息源
历史决策记录	使用频率低	Level 2参考文档

Content Classification Decision Tree

内容分类决策树

For each section, ask:

Is this high-frequency use?
├─ Yes → Level 1 (AGENTS.md)
└─ No → ↓

Is the violation consequence severe?
├─ Yes → Level 1 (AGENTS.md)
└─ No → ↓

Is there a code pattern to copy directly?
├─ Yes → Level 1 keep the pattern
└─ No → ↓

Is there a clear trigger condition?
├─ Yes → Level 2 + trigger condition
└─ No → Consider deleting

针对每个章节，询问：

是否是高频使用内容？
├─ 是 → Level 1（AGENTS.md）
└─ 否 → ↓

违反规则的后果是否严重？
├─ 是 → Level 1（AGENTS.md）
└─ 否 → ↓

是否有可直接复制的代码模式？
├─ 是 → Level 1保留该模式
└─ 否 → ↓

是否有明确的触发条件？
├─ 是 → Level 2 + 触发条件
└─ 否 → 考虑删除

Reference Index Format

参考索引格式

At Start (Problem-Oriented)

文档开头（问题导向）

markdown

undefined

markdown

undefined

Reference Index (When you encounter problems)

参考索引（遇到问题时查看）

Trigger scenario	Document	Core content
Build fails after dependency change	`docs/references/build-sop.md`	Dependency order, clean build
Test environment variables not loading	`docs/references/env-setup.md`	.env files, globalEnv config
Cache not invalidating	`docs/references/caching.md`	outputs, inputs, env keys

undefined

触发场景	文档	核心内容
依赖变更后构建失败	`docs/references/build-sop.md`	依赖顺序、干净构建
测试环境变量不加载	`docs/references/env-setup.md`	.env文件、globalEnv配置
缓存不失效	`docs/references/caching.md`	输出、输入、环境变量key

undefined

At Middle (Task-Oriented)

文档中间（任务导向）

markdown

undefined

markdown

undefined

Before Modifying Code

修改代码前须知

What you're changing	Read this first	Key gotchas
Build configuration	`docs/references/build-sop.md`	dependsOn order matters
Environment setup	`docs/references/env-setup.md`	globalEnv affects all tasks
Cache behavior	`docs/references/caching.md`	outputs required for file-producing tasks

undefined

你要修改的内容	先读这份文档	关键注意事项
构建配置	`docs/references/build-sop.md`	dependsOn顺序很重要
环境配置	`docs/references/env-setup.md`	globalEnv影响所有任务
缓存行为	`docs/references/caching.md`	生成文件的任务必须配置outputs

undefined

At End (Re-Orientation)

文档末尾（重定向导向）

markdown

undefined

markdown

undefined

Reference Trigger Index

参考触发索引

When to read	Document	What you'll find
Build fails	`docs/references/build-sop.md`	Dependency troubleshooting
Env issues	`docs/references/env-setup.md`	.env and variable setup
Cache problems	`docs/references/caching.md`	Hash input debugging

undefined

什么时候需要读	文档	你能找到的内容
构建失败	`docs/references/build-sop.md`	依赖问题排查
环境变量问题	`docs/references/env-setup.md`	.env和变量配置
缓存问题	`docs/references/caching.md`	哈希输入调试

undefined

Anti-Patterns to Avoid

需要避免的反模式

Anti-Pattern	Wrong	Right
Line count as goal	"Reduced from 2000 to 500 lines"	Assess by duplication and relevance, not line count
References without triggers	`See build-sop.md for details`	Include trigger conditions: "When build fails after dependency changes"
Moving code patterns to Level 2	Move frequently-used code examples	Keep copyable patterns in Level 1
Deleting instead of moving	Delete "unimportant" sections	Move to Level 2, keep trigger in Level 1
Moving while simplifying	Move and edit content simultaneously	Move verbatim first, simplify separately with confirmation

反模式	错误做法	正确做法
以行数为优化目标	"从2000行精简到了500行"	按重复度和相关性评估，不看行数
无触发条件的引用	`详见build-sop.md`	加上触发条件："当依赖变更后构建失败时查看"
把代码模式移到Level 2	迁移高频使用的代码示例	把可直接复制的模式保留在Level 1
直接删除而非迁移	删除"不重要"的章节	迁移到Level 2，在Level 1保留触发入口
迁移同时修改内容	移动内容的同时编辑简化	先原样迁移，确认后再单独做简化

Monorepo-Specific Considerations

Monorepo 专属注意事项

Additional Detection for Monorepos

Monorepo额外检测项

When a monorepo is detected, also extract:

Information	Source	Purpose
Package names	`apps//package.json` , `packages//package.json`	Understanding modules
Package purposes	package.json `description` field, README files	What each package does
Internal dependencies	workspace:* references	Dependency graph
Build system	turbo.json, nx.json, lerna.json	Task orchestration
Shared patterns	across packages/	Common conventions

检测到是monorepo时，额外提取以下信息：

信息	来源	用途
包名称	`apps//package.json` 、 `packages//package.json`	理解模块结构
包用途	package.json的 `description` 字段、README文件	每个包的功能说明
内部依赖	workspace:*引用	依赖关系图
构建系统	turbo.json、nx.json、lerna.json	任务编排规则
共享规范	跨packages的通用约定	统一开发规范

Package Name Detection

包名称检测

Package naming varies significantly across monorepos. Detect actual package names from:

Directory patterns:
- ```
apps/*
```
  → Application packages
- ```
packages/*
```
  → Library packages
- ```
services/*
```
  → Backend services
Package naming conventions:
- Scoped:
```
@repo/*
```
  ,
```
@company/*
```
  ,
```
@project/*
```
- Unscoped:
```
backend
```
  ,
```
frontend
```
  ,
```
api
```
  ,
```
web
```
- Mixed: Both scoped and unscoped in same repo

Common backend package names:

```
@repo/api
```
,
```
@repo/backend
```
,
```
@repo/server
```
```
apps/api
```
,
```
apps/backend
```
,
```
apps/server
```
```
services/api
```
,
```
services/backend
```

Common frontend package names:

```
@repo/web
```
,
```
@repo/frontend
```
,
```
@repo/app
```
```
apps/web
```
,
```
apps/frontend
```
,
```
apps/app
```
```
apps/admin
```
,
```
apps/dashboard
```

不同monorepo的包命名差异很大，从以下位置检测实际包名：

目录模式：
- ```
apps/*
```
  → 应用包
- ```
packages/*
```
  → 库包
- ```
services/*
```
  → 后端服务包
包命名约定：
- 作用域包：
```
@repo/*
```
  、
```
@company/*
```
  、
```
@project/*
```
- 非作用域包：
```
backend
```
  、
```
frontend
```
  、
```
api
```
  、
```
web
```
- 混合模式：同一个仓库同时存在作用域和非作用域包

常见后端包名：

```
@repo/api
```
、
```
@repo/backend
```
、
```
@repo/server
```
```
apps/api
```
、
```
apps/backend
```
、
```
apps/server
```
```
services/api
```
、
```
services/backend
```

常见前端包名：

```
@repo/web
```
、
```
@repo/frontend
```
、
```
@repo/app
```
```
apps/web
```
、
```
apps/frontend
```
、
```
apps/app
```
```
apps/admin
```
、
```
apps/dashboard
```

Monorepo AGENTS.md Additions

Monorepo AGENTS.md 额外内容

Generate the package table dynamically based on actual project structure:

markdown

undefined

基于实际项目结构动态生成包信息表：

markdown

undefined

Monorepo Structure

Monorepo结构

Package	Location	Purpose	Key commands
`backend`	apps/backend	REST API server	`turbo run dev --filter=backend`
`frontend`	apps/web	Next.js web app	`turbo run dev --filter=frontend`
`ui`	packages/ui	Shared React components	`turbo run build --filter=ui`

包名	位置	用途	核心命令
`backend`	apps/backend	REST API服务	`turbo run dev --filter=backend`
`frontend`	apps/web	Next.js web应用	`turbo run dev --filter=frontend`
`ui`	packages/ui	共享React组件	`turbo run build --filter=ui`

Working with Packages

包操作指南

Run task in specific package:

turbo run <task> --filter=<package-name>

Run only changed packages:
```
turbo run <task> --affected
```

Include dependents:

turbo run <task> --filter=...<package-name>

Run by directory:
```
turbo run <task> --filter=./apps/*
```


**Key guidelines for package tables:**

1. **Use actual package names** from package.json `name` field
2. **Infer purpose** from description field or directory name
3. **Group by type** (apps vs packages) if helpful
4. **Keep it concise** — focus on most commonly used packages
5. **Reference detailed docs** for complete package list

运行指定包的任务：

turbo run <task> --filter=<package-name>

仅运行有变更的包：
```
turbo run <task> --affected
```

包含依赖包：

turbo run <task> --filter=...<package-name>

按目录运行：
```
turbo run <task> --filter=./apps/*
```


**包信息表核心规则：**

1. **使用package.json`name`字段的实际包名**
2. **从description字段或目录名推断包用途**
3. **有帮助的话按类型分组（apps vs packages）**
4. **保持精简** — 重点展示最常用的包
5. **完整包列表参考详细文档**

Verification Checklist

验证清单

After creating or modifying AGENTS.md, verify:

创建或修改AGENTS.md后，验证以下内容：

Information Completeness (Most Important)

信息完整性（最重要）

Every section from original has a home (in Level 1, Level 2, or has canonical source)
Level 2 files match original content exactly (no "simplification" during move)
No content was silently deleted
No line count statistics were mentioned

原文档的每个章节都有归宿（在Level 1、Level 2，或有权威来源）
Level 2文件和原内容完全一致（迁移过程中没有"简化"）
没有内容被静默删除
没有提到行数统计相关内容

Structure Quality

结构质量

Information Recording Principles

信息记录原则

Add this to AGENTS.md after project description to prevent future bloat:

markdown

undefined

在AGENTS.md的项目描述后面添加这段内容，避免后续文档臃肿：

markdown

undefined

Information Recording Principles (Agents Must Read)

信息记录原则（Agent必须阅读）

This document uses progressive disclosure to optimize agent effectiveness.

本文档采用渐进式披露优化Agent工作效率。

Level 1 (This file) contains only

Level 1（本文档）仅包含

Type	Example
Core commands	`npm run dev` , `npm test`
Iron rules/prohibitions	Must use lazy loading
Common error diagnostics	Symptom → cause → fix (complete flow)
Code patterns	Directly copyable code blocks
Directory navigation	Function → file mapping
Trigger index tables	Pointers to Level 2

类型	示例
核心命令	`npm run dev` 、 `npm test`
铁则/禁止规则	必须使用懒加载
常见错误排查	症状 → 原因 → 修复（完整流程）
代码模式	可直接复制的代码块
目录导航	功能 → 文件映射
触发索引表	指向Level 2的链接

Level 2 (docs/references/) contains

Level 2（docs/references/）包含

Type	Example
Detailed SOP flows	Complete 20-step guides
Edge case handling	Rare error diagnostics
Complete config examples	All parameter descriptions
Historical decisions	Why it was designed this way

类型	示例
详细SOP流程	完整的20步操作指南
边缘 case 处理	罕见错误排查
完整配置示例	所有参数说明
历史决策记录	为什么这么设计的原因

When recording information

记录信息时

Assess frequency: High frequency → Level 1, otherwise Level 2
Level 1 references Level 2 must include:
- Trigger condition (when to read)
- Content summary (what you'll find)
Never:
- Place low-frequency detailed flows in Level 1
- Reference Level 2 without trigger conditions

undefined

评估使用频率： 高频 → Level 1，其他 → Level 2
Level 1引用Level 2必须包含：
- 触发条件（什么时候需要读）
- 内容摘要（你能找到什么）
绝对不要：
- 把低频的详细流程放在Level 1
- 引用Level 2时不附带触发条件

undefined

Reference Files

参考文件

File	Purpose
references/project_detection.md	Detailed project structure detection
references/templates.md	AGENTS.md templates for different project types
references/progressive_disclosure.md	Progressive disclosure deep dive
references/anti_patterns.md	Common anti-patterns with examples

文件	用途
references/project_detection.md	详细项目结构检测规则
references/templates.md	不同项目类型的AGENTS.md模板
references/progressive_disclosure.md	渐进式披露深度说明
references/anti_patterns.md	常见反模式及示例