agents-md-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AGENTS.MD Generator

AGENTS.MD 生成工具

Generate comprehensive AGENTS.md documentation for backend projects following the AGENTS.md/CLAUDE.md symlink pattern.

遵循AGENTS.md/CLAUDE.md软链接模式，为后端项目生成全面的AGENTS.md文档。

Core Workflow

核心工作流程

1. Understand the Scope

1. 明确范围

Ask the user to clarify:

Target module: Root directory, specific module (mcp, teamo_code, etc.), or multiple modules
Source materials: Existing CLAUDE.md, API route files, technical design docs
API count: How many interfaces need documentation (affects detail level)
Content to preserve: Existing business rules, specs, or guidelines to keep
Content to remove: Deprecated features, unused patterns (e.g., Ralph Loop)

请用户明确以下信息：

目标模块：根目录、特定模块（mcp、teamo_code等）或多个模块
源材料：现有CLAUDE.md、API路由文件、技术设计文档
API数量：需要文档化的接口数量（会影响详细程度）
需保留内容：现有业务规则、规范或指南
需移除内容：已废弃功能、未使用的模式（如Ralph Loop）

2. Read Source Materials

2. 读取源材料

Read all relevant source files:

Existing CLAUDE.md or AGENTS.md (if exists)
API route files (e.g.,
```
clawdbot.py
```
,
```
router.py
```
)
Related business spec documents
Data model definitions

Use Read tool to load files into context. For large codebases, use Grep to find specific patterns first.

读取所有相关源文件：

现有CLAUDE.md或AGENTS.md（若存在）
API路由文件（如
```
clawdbot.py
```
、
```
router.py
```
）
相关业务规范文档
数据模型定义

使用Read工具将文件加载到上下文环境中。对于大型代码库，先使用Grep工具查找特定模式。

3. Generate AGENTS.md Content

3. 生成AGENTS.md内容

Follow the template structure in

references/agents_template.md

Required Sections:

Module Overview - Responsibilities, main features, core collections
Business Specifications - Domain-specific rules, workflows, special mechanisms
API Interface Documentation - Complete interface specs (see
```
references/api_doc_template.md
```
)
Data Models - MongoDB collections, PostgreSQL tables, Redis keys
External Integrations - Third-party APIs, external services
Complete Data Flows - End-to-end process diagrams (see
```
references/data_flow_template.md
```
)

Content Priorities:

Completeness over brevity: Include all interfaces, all fields, all business rules
Accuracy over idealism: Document actual behavior, not desired behavior
Concrete examples: Provide JSON request/response samples for every interface
Chinese + English: Chinese labels (接口、功能、请求体) with English technical terms

遵循

references/agents_template.md

中的模板结构：

必填章节:

模块概述 - 职责、主要功能、核心集合
业务规范 - 领域特定规则、工作流程、特殊机制
API接口文档 - 完整接口规范（参考
```
references/api_doc_template.md
```
）
数据模型 - MongoDB集合、PostgreSQL表、Redis键
外部集成 - 第三方API、外部服务
完整数据流 - 端到端流程示意图（参考
```
references/data_flow_template.md
```
）

内容优先级:

完整性优先于简洁性：包含所有接口、所有字段、所有业务规则
准确性优先于理想化：记录实际行为，而非期望行为
提供具体示例：为每个接口提供JSON请求/响应示例
中英混合：中文标签（接口、功能、请求体）搭配英文技术术语

4. Create Symlink Structure

4. 创建软链接结构

After creating AGENTS.md:

Backup:
```
cp CLAUDE.md CLAUDE.md.backup
```
Delete:
```
rm CLAUDE.md
```
Symlink:
```
ln -s AGENTS.md CLAUDE.md
```
Verify:
```
ls -la CLAUDE.md
```
should show
```
CLAUDE.md -> AGENTS.md
```

Use the Bash tool for these operations.

创建AGENTS.md后执行以下步骤：

备份：
```
cp CLAUDE.md CLAUDE.md.backup
```
删除原文件：
```
rm CLAUDE.md
```
创建软链接：
```
ln -s AGENTS.md CLAUDE.md
```
验证：执行
```
ls -la CLAUDE.md
```
应显示
```
CLAUDE.md -> AGENTS.md
```

使用Bash工具执行上述操作。

5. Validate and Test

5. 验证与测试

Structure Validation:

✅ YAML frontmatter removed (AGENTS.md uses standard Markdown)
✅ All code blocks properly fenced with language tags
✅ All tables properly formatted
✅ All internal links work (e.g.,
```
[Section](#section)
```
)

Content Validation:

✅ Every API interface has request/response models
✅ Every data model has field descriptions and indexes
✅ Every external integration has API endpoints and auth
✅ Every data flow has clear start and end points

Symlink Validation:

bash

undefined

结构验证:

✅ 移除YAML前置内容（AGENTS.md使用标准Markdown）
✅ 所有代码块正确添加语言标签围栏
✅ 所有表格格式正确
✅ 所有内部链接可正常跳转（如
```
[Section](#section)
```
）

内容验证:

✅ 每个API接口都有请求/响应模型
✅ 每个数据模型都有字段描述和索引
✅ 每个外部集成都有API端点和认证信息
✅ 每个数据流都有清晰的起始和结束节点

软链接验证:

bash

undefined

Verify symlink

验证软链接

ls -la CLAUDE.md

Verify content match

验证内容一致性

diff CLAUDE.md AGENTS.md

Expected: No output (files are identical via symlink)

预期结果：无输出（通过软链接，两个文件内容完全一致）

undefined

undefined

6. Git Commit

6. Git提交

Follow the project's Git commit standards:

bash

git add AGENTS.md CLAUDE.md CLAUDE.md.backup
git commit -m "docs: 创建 <模块名称> AGENTS.md 并设置 CLAUDE.md 软链接

- 创建 AGENTS.md (完整的模块规范文档)
- 包含 <X> 个接口的完整文档
- 包含业务规范 (<业务规范名称>)
- 包含数据模型和外部集成说明
- 创建软链接 CLAUDE.md -> AGENTS.md
- 备份原 CLAUDE.md 为 CLAUDE.md.backup

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"

遵循项目的Git提交规范：

bash

git add AGENTS.md CLAUDE.md CLAUDE.md.backup
git commit -m "docs: 创建 <模块名称> AGENTS.md 并设置 CLAUDE.md 软链接

- 创建 AGENTS.md (完整的模块规范文档)
- 包含 <X> 个接口的完整文档
- 包含业务规范 (<业务规范名称>)
- 包含数据模型和外部集成说明
- 创建软链接 CLAUDE.md -> AGENTS.md
- 备份原 CLAUDE.md 为 CLAUDE.md.backup

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"

API Documentation Standards

API文档规范

Interface Template

接口模板

For each API interface, document:

Basic Info:

HTTP method and path
Functionality description (Chinese)
Authentication requirements

Request:

Request model name and fields
Field types, constraints, required/optional
Request example (JSON)

Response:

Response model name and fields
Field types and descriptions
Success response example (JSON)
Error response examples (JSON)

Business Logic (if complex):

Step-by-step flow
Validation rules
Side effects

See

references/api_doc_template.md

for detailed examples.

每个API接口需记录以下内容：

基本信息:

HTTP方法和路径
功能描述（中文）
认证要求

请求:

请求模型名称和字段
字段类型、约束、必填/可选
请求示例（JSON格式）

响应:

响应模型名称和字段
字段类型和描述
成功响应示例（JSON格式）
错误响应示例（JSON格式）

业务逻辑（若复杂）:

分步流程
验证规则
副作用

详细示例请参考

references/api_doc_template.md

。

Data Flow Documentation

数据流文档

Use ASCII diagrams with clear stages:

用户操作
    ↓
API 调用 (接口名称)
    ├─ Step 1: 验证 (描述)
    ├─ Step 2: 数据库操作 (描述)
    │   ├─ 查询 xxx
    │   └─ 更新 yyy
    ├─ Step 3: 外部服务调用 (描述)
    └─ Step 4: 返回响应

For complex flows, break into multiple sub-diagrams. See

references/data_flow_template.md

for examples.

使用ASCII示意图展示清晰的阶段：

用户操作
    ↓
API 调用 (接口名称)
    ├─ Step 1: 验证 (描述)
    ├─ Step 2: 数据库操作 (描述)
    │   ├─ 查询 xxx
    │   └─ 更新 yyy
    ├─ Step 3: 外部服务调用 (描述)
    └─ Step 4: 返回响应

对于复杂流程，可拆分为多个子示意图。示例请参考

references/data_flow_template.md

。

Best Practices

最佳实践

Progressive Disclosure

渐进式披露

Root AGENTS.md: Global specs, cross-module patterns, project overview Module AGENTS.md: Module-specific specs, API docs, detailed flows

Reference module docs from root:

markdown

请参考对应模块的文档获取详细的开发指南:
- **MCP 模块**: `wowchat/mcp/AGENTS.md`
- **Teamo Code 模块**: `wowchat/teamo_code/AGENTS.md`

根目录AGENTS.md：全局规范、跨模块模式、项目概述 模块级AGENTS.md：模块专属规范、API文档、详细流程

在根目录文档中引用模块文档：

markdown

请参考对应模块的文档获取详细的开发指南:
- **MCP 模块**: `wowchat/mcp/AGENTS.md`
- **Teamo Code 模块**: `wowchat/teamo_code/AGENTS.md`

Spec Auto-Deposition

规范自动提交

Update Spec auto-deposition mechanism to use AGENTS.md:

markdown

每次修改 AGENTS.md 后,必须在回复尾部单独一行输出(前后空行):
\`\`\`
喵 ฅ՞•ﻌ•՞ฅ 已完成xxx相关的spec,更新/删除AGENTS.md文件中相关内容。
\`\`\`

For module-level updates:

markdown

喵 ฅ՞•ﻌ•՞ฅ 已完成xxx相关的spec,更新/删除<模块路径>/AGENTS.md文件中相关内容。

更新规范自动提交机制以适配AGENTS.md：

markdown

每次修改 AGENTS.md 后,必须在回复尾部单独一行输出(前后空行):
\\`\\`\\`
喵 ฅ՞•ﻌ•՞ฅ 已完成xxx相关的spec,更新/删除AGENTS.md文件中相关内容。
\\`\\`\\`

模块级更新格式：

markdown

喵 ฅ՞•ﻌ•՞ฅ 已完成xxx相关的spec,更新/删除<模块路径>/AGENTS.md文件中相关内容。

Content Removal

内容清理

When migrating from CLAUDE.md to AGENTS.md, remove:

❌ Deprecated features (e.g., Ralph Loop if not used)
❌ Experiment-only code patterns
❌ Duplicate specifications across files

Preserve:

✅ All core business rules
✅ All active API specifications
✅ All data model definitions
✅ All integration patterns

从CLAUDE.md迁移至AGENTS.md时，需移除以下内容：

❌ 已废弃功能（如未使用的Ralph Loop）
❌ 仅用于实验的代码模式
❌ 跨文件重复的规范

需保留以下内容：

✅ 所有核心业务规则
✅ 所有活跃API规范
✅ 所有数据模型定义
✅ 所有集成模式

Common Patterns

常见模式

Multi-Module Documentation

多模块文档结构

For projects with multiple modules, create hierarchy:

/AGENTS.md (root - global specs)
/CLAUDE.md -> AGENTS.md (symlink)

/wowchat/mcp/AGENTS.md (module specs)
/wowchat/mcp/CLAUDE.md -> AGENTS.md (symlink)

/wowchat/teamo_code/AGENTS.md (module specs)
/wowchat/teamo_code/CLAUDE.md -> AGENTS.md (symlink)

对于包含多个模块的项目，创建层级结构：

/AGENTS.md (根目录 - 全局规范)
/CLAUDE.md -> AGENTS.md (软链接)

/wowchat/mcp/AGENTS.md (模块规范)
/wowchat/mcp/CLAUDE.md -> AGENTS.md (软链接)

/wowchat/teamo_code/AGENTS.md (模块规范)
/wowchat/teamo_code/CLAUDE.md -> AGENTS.md (软链接)

API Count Guidelines

API数量指南

< 10 interfaces: Include all details in main AGENTS.md
10-30 interfaces: Group by function, use interface overview table
> 30 interfaces: Consider splitting into multiple module AGENTS.md files

< 10个接口：在主AGENTS.md中包含所有详细内容
10-30个接口：按功能分组，使用接口概览表格
> 30个接口：考虑拆分为多个模块级AGENTS.md文件

External Integration Documentation

外部集成文档

For each external service, document:

Base URL and API endpoints table
Authentication method (API Key, OAuth, etc.)
Request/response format examples
Timeout settings
Error handling patterns

See MCP module example for Lighthouse, Feishu, Alipay integrations.

每个外部服务需记录以下内容：

Base URL和API端点表格
认证方式（API Key、OAuth等）
请求/响应格式示例
超时设置
错误处理模式

可参考MCP模块中Lighthouse、飞书、支付宝集成的示例。

Error Prevention

错误预防

Common Mistakes:

❌ Forgetting to backup CLAUDE.md before creating symlink
❌ Including YAML frontmatter (only needed in SKILL.md, not AGENTS.md)
❌ Incomplete API documentation (missing request/response models)
❌ Missing data flow diagrams for complex processes
❌ Not testing symlinks with
```
ls -la
```

Validation Checklist:

AGENTS.md created with all required sections
CLAUDE.md.backup exists
CLAUDE.md symlink verified (
```
ls -la CLAUDE.md
```
shows
```
-> AGENTS.md
```
)
```
cat CLAUDE.md
```
shows AGENTS.md content
All API interfaces documented
All data models documented
All data flows documented
Git committed with proper message

常见错误:

❌ 创建软链接前忘记备份CLAUDE.md
❌ 包含YAML前置内容（仅SKILL.md需要，AGENTS.md不需要）
❌ API文档不完整（缺少请求/响应模型）
❌ 复杂流程缺少数据流示意图
❌ 未使用
```
ls -la
```
测试软链接

验证清单:

已创建包含所有必填章节的AGENTS.md
存在CLAUDE.md.backup备份文件
已验证CLAUDE.md软链接（
```
ls -la CLAUDE.md
```
显示
```
-> AGENTS.md
```
）
执行
```
cat CLAUDE.md
```
可查看AGENTS.md内容
所有API接口已文档化
所有数据模型已文档化
所有数据流已文档化
已使用规范的提交信息完成Git提交

References

参考资料

Template Structure: See
```
references/agents_template.md
```
API Documentation: See
```
references/api_doc_template.md
```
Data Flow Diagrams: See
```
references/data_flow_template.md
```
Complete Example: See
```
assets/example_mcp_agents.md
```

模板结构: 参考
```
references/agents_template.md
```
API文档: 参考
```
references/api_doc_template.md
```
数据流示意图: 参考
```
references/data_flow_template.md
```
完整示例: 参考
```
assets/example_mcp_agents.md
```
",