generate-agents-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Generate AGENTS.md

生成AGENTS.md

Extract operational content from CLAUDE.md to create a universal AGENTS.md file for cross-tool compatibility with Cursor, Codex, Copilot, and other AI agents.

从CLAUDE.md中提取操作内容，创建通用的AGENTS.md文件，以实现与Cursor、Codex、Copilot及其他AI Agent的跨工具兼容性。

Overview

概述

This workflow extracts the Operations and Boundaries sections from CLAUDE.md to generate a minimal, universal AGENTS.md file that works across 20+ AI coding tools.

Why generate instead of symlink?

Symlinks may not work on all systems (Windows)
AGENTS.md can be customized without affecting CLAUDE.md
Some teams prefer explicit files over symlinks
Allows for tool-specific adjustments

本工作流从CLAUDE.md中提取“操作”和“边界”部分，生成一个简洁通用的AGENTS.md文件，可在20多种AI编码工具中使用。

为什么选择生成而非符号链接？

符号链接可能在部分系统（如Windows）无法正常工作
AGENTS.md可进行自定义，且不会影响CLAUDE.md
部分团队偏好显式文件而非符号链接
允许针对特定工具进行调整

When to Use

使用场景

✅ Use this workflow when:

Team uses multiple AI tools (Cursor + Claude Code, Codex + Claude)
Deploying to systems where symlinks don't work well
Want a standalone AGENTS.md for open-source projects
Need to customize AGENTS.md separately from CLAUDE.md

❌ Use symlink instead when:

Only team uses Claude Code and one other tool
System supports symlinks reliably
Want single source of truth with no drift

Symlink command:

ln -s CLAUDE.md AGENTS.md

✅ 在以下场景使用本工作流：

团队使用多种AI工具（如Cursor + Claude Code、Codex + Claude）
部署到符号链接无法正常工作的系统
为开源项目创建独立的AGENTS.md
需要独立于CLAUDE.md自定义AGENTS.md

❌ 在以下场景使用符号链接：

团队仅使用Claude Code和另一种工具
系统可可靠支持符号链接
希望保持单一事实来源，避免内容偏差

符号链接命令：

ln -s CLAUDE.md AGENTS.md

Process

流程

Step 1: Analyze CLAUDE.md

步骤1：分析CLAUDE.md

AI reads CLAUDE.md and identifies:

Operations section - Setup, Testing, Build, Code Style commands
Boundaries section - Protected files, never commit, ask before
Project-specific customizations (if any)

AI读取CLAUDE.md并识别：

操作部分 - 搭建、测试、构建、代码风格相关命令
边界部分 - 受保护文件、绝不提交、操作前需确认的内容
项目特定自定义内容（如有）

Step 2: Generate AGENTS.md

步骤2：生成AGENTS.md

Create

AGENTS.md

with AGENTS.md standard structure:

markdown

undefined

按照AGENTS.md标准结构创建

AGENTS.md

：

markdown

undefined

AGENTS.md

Auto-generated from CLAUDE.md. For full methodology, see CLAUDE.md. Last generated: [DATE]

从CLAUDE.md自动生成。完整方法请查看CLAUDE.md。最后生成时间：[日期]

Project Overview

项目概述

[Brief description - AI extracts from README or project.md if available]

[简要描述 - AI将从README或project.md（若存在）中提取]

Setup Commands

搭建命令

[Extracted from CLAUDE.md Operations section]

[从CLAUDE.md操作部分提取]

Testing

测试

[Extracted from CLAUDE.md Operations section]

[从CLAUDE.md操作部分提取]

Build & Deploy

构建与部署

[Extracted from CLAUDE.md Operations section]

[从CLAUDE.md操作部分提取]

Code Style

代码风格

[Extracted from CLAUDE.md Operations section]

[从CLAUDE.md操作部分提取]

Boundaries

边界

[Extracted from CLAUDE.md Boundaries section]

For detailed guardrails, 4D methodology, and workflows, see CLAUDE.md

undefined

[从CLAUDE.md边界部分提取]

如需详细的防护规则、4D方法及工作流，请查看CLAUDE.md

undefined

Step 3: Verify and Save

步骤3：验证并保存

AI presents generated AGENTS.md for review
User approves or requests changes
Save to project root:
```
./AGENTS.md
```

AI展示生成的AGENTS.md以供审核
用户确认或请求修改
保存至项目根目录：
```
./AGENTS.md
```

AGENTS.md Template

AGENTS.md模板

markdown

undefined

markdown

undefined

AGENTS.md

Auto-generated from CLAUDE.md | Last updated: YYYY-MM-DD Full documentation: CLAUDE.md

从CLAUDE.md自动生成 | 最后更新：YYYY-MM-DD 完整文档：CLAUDE.md

Project Overview

项目概述

[PROJECT_NAME] - [BRIEF_DESCRIPTION]

Tech Stack: [PRIMARY_TECHNOLOGIES] Language: [PRIMARY_LANGUAGE]

[项目名称] - [简要描述]

技术栈：[主要技术] 开发语言：[主要语言]

Setup Commands

搭建命令

bash

undefined

bash

undefined

Install dependencies

安装依赖

[INSTALL_COMMAND]

[安装命令]

Start development server

启动开发服务器

[DEV_COMMAND]

[开发命令]

Environment setup

环境配置

cp .env.example .env

undefined

cp .env.example .env

undefined

Testing

测试

bash

undefined

bash

undefined

Run all tests

运行所有测试

[TEST_COMMAND]

[测试命令]

Run with coverage (target: >80% business logic)

带覆盖率运行（目标：业务逻辑覆盖率>80%）

[COVERAGE_COMMAND]

[覆盖率命令]

Watch mode

监听模式

[WATCH_COMMAND]

undefined

[监听命令]

undefined

Build & Deploy

构建与部署

bash

undefined

bash

undefined

Production build

生产环境构建

[BUILD_COMMAND]

[构建命令]

Type check

类型检查

[TYPECHECK_COMMAND]

[类型检查命令]

Lint

代码检查

[LINT_COMMAND]

undefined

[代码检查命令]

undefined

Code Style

代码风格

bash

undefined

bash

undefined

Format code

格式化代码

[FORMAT_COMMAND]

[格式化命令]

Lint and fix

代码检查并修复

[LINT_FIX_COMMAND]


**Conventions**:
- [STYLE_RULE_1]
- [STYLE_RULE_2]
- [STYLE_RULE_3]

[代码检查修复命令]


**约定**：
- [风格规则1]
- [风格规则2]
- [风格规则3]

Boundaries

边界

Do Not Modify

请勿修改

Lock files (
```
package-lock.json
```
,
```
yarn.lock
```
,
```
Cargo.lock
```
)
Environment files (
```
.env
```
,
```
.env.local
```
)
CI/CD configurations (
```
.github/workflows/
```
)
Applied database migrations

锁文件（
```
package-lock.json
```
、
```
yarn.lock
```
、
```
Cargo.lock
```
）
环境文件（
```
.env
```
、
```
.env.local
```
）
CI/CD配置（
```
.github/workflows/
```
）
已应用的数据库迁移文件

Never Commit

禁止提交

Secrets, API keys, credentials
```
.env
```
files (use
```
.env.example
```
)
Build artifacts,
```
node_modules/
```
,
```
target/
```

密钥、API密钥、凭证
```
.env
```
文件（使用
```
.env.example
```
替代）
构建产物、
```
node_modules/
```
、
```
target/
```

Ask Before Changing

修改前需确认

Authentication/authorization logic
Database schemas
Public API contracts
Major dependencies

认证/授权逻辑
数据库 schema
公开API契约
主要依赖

Additional Context

额外说明

For detailed development guidelines, see:

Full Methodology: CLAUDE.md
Skills: .claude/skills/

This file follows the AGENTS.md standard.

---

如需详细开发指南，请查看：

完整方法：CLAUDE.md
技能：.claude/skills/

本文件遵循AGENTS.md标准。

---

Customization Guide

自定义指南

Project-Specific Adjustments

项目特定调整

When generating AGENTS.md, AI should:

Detect tech stack from:

```
package.json
```
(Node.js)
```
requirements.txt
```
/
```
pyproject.toml
```
(Python)
```
go.mod
```
(Go)
```
Cargo.toml
```
(Rust)

Extract actual commands from:
- ```
package.json
```
  scripts
- ```
Makefile
```
- ```
justfile
```
- CI/CD workflows
Include project-specific boundaries from:
- ```
CLAUDE.md
```
  (if exists)
- Existing
```
.gitignore
```
  patterns

生成AGENTS.md时，AI应：

检测技术栈，来源包括：
- ```
package.json
```
  （Node.js）
- ```
requirements.txt
```
  /
```
pyproject.toml
```
  （Python）
- ```
go.mod
```
  （Go）
- ```
Cargo.toml
```
  （Rust）
提取实际命令，来源包括：
- ```
package.json
```
  脚本
- ```
Makefile
```
- ```
justfile
```
- CI/CD工作流
包含项目特定边界，来源包括：
- ```
CLAUDE.md
```
  （若存在）
- 现有
```
.gitignore
```
  规则

Monorepo Support

单体仓库支持

For monorepos, generate nested AGENTS.md files:

project/
├── AGENTS.md              # Root-level (general)
├── CLAUDE.md              # Full methodology
├── packages/
│   ├── api/
│   │   └── AGENTS.md      # API-specific commands
│   └── web/
│       └── AGENTS.md      # Web-specific commands

Each nested AGENTS.md should:

Focus on that package's commands
Reference root AGENTS.md for general guidelines
Include package-specific boundaries

对于单体仓库，生成嵌套的AGENTS.md文件：

project/
├── AGENTS.md              # 根目录（通用内容）
├── CLAUDE.md              # 完整方法
├── packages/
│   ├── api/
│   │   └── AGENTS.md      # API特定命令
│   └── web/
│       └── AGENTS.md      # Web特定命令

每个嵌套的AGENTS.md应：

聚焦于对应包的命令
引用根目录AGENTS.md获取通用指南
包含包特定的边界规则

Maintenance

维护

When to Regenerate

何时重新生成

Regenerate AGENTS.md when:

CLAUDE.md Operations section changes
New build/test commands added
Project structure changes significantly
Tech stack updated

在以下情况重新生成AGENTS.md：

CLAUDE.md的操作部分发生变化
添加了新的构建/测试命令
项目结构发生重大变化
技术栈更新

Keeping in Sync

保持内容同步

Option A: Manual regeneration

bash

undefined

选项A：手动重新生成

bash

undefined

Load this skill periodically when CLAUDE.md changes

当CLAUDE.md变化时，定期加载此技能

.claude/skills/generate-agents-md/SKILL.md


**Option B: Pre-commit hook**
```bash

.claude/skills/generate-agents-md/SKILL.md


**选项B：提交前钩子**
```bash

.husky/pre-commit or similar

.husky/pre-commit或类似工具

Check if CLAUDE.md changed, regenerate AGENTS.md

检测CLAUDE.md是否变化，重新生成AGENTS.md


**Option C: CI/CD check**
```yaml


**选项C：CI/CD检查**
```yaml

.github/workflows/check-agents-md.yml

name: Verify AGENTS.md is up to date run: |
Compare timestamps or checksums

---

name: 验证AGENTS.md是否为最新版本 run: |
比较时间戳或校验和

---

Example Usage

使用示例

Request

请求

Generate AGENTS.md for this project using the generate-agents-md skill

使用generate-agents-md技能为该项目生成AGENTS.md

AI Response

AI响应

I'll analyze your project and generate an AGENTS.md file.

**Detected:**
- Tech stack: TypeScript, React, Node.js
- Package manager: npm
- Test framework: Vitest
- Linter: ESLint + Prettier

**Generated AGENTS.md:**
[Shows preview]

**Save to:** ./AGENTS.md

Approve? [Yes/No/Edit]

我将分析您的项目并生成AGENTS.md文件。

**检测到的信息：**
- 技术栈：TypeScript、React、Node.js
- 包管理器：npm
- 测试框架：Vitest
- 代码检查工具：ESLint + Prettier

**生成的AGENTS.md：**
[展示预览内容]

**保存路径：** ./AGENTS.md

是否确认？[是/否/编辑]

Integration with CLAUDE.md

与CLAUDE.md的集成

How They Work Together

协同工作方式

File	Purpose	Audience
`CLAUDE.md`	Full methodology + guardrails	Claude Code
`AGENTS.md`	Operational commands	All AI tools

文件	用途	受众
`CLAUDE.md`	完整方法+防护规则	Claude Code
`AGENTS.md`	操作命令	所有AI工具

Reading Priority (Claude Code)

读取优先级（Claude Code）

Claude Code reads
```
CLAUDE.md
```
(primary)
If
```
CLAUDE.md
```
not found, reads
```
AGENTS.md
```
(fallback)
Both can coexist (different purposes)

Claude Code优先读取
```
CLAUDE.md
```
（主文件）
若未找到
```
CLAUDE.md
```
，则读取
```
AGENTS.md
```
（备选）
两者可共存（用途不同）

For Other Tools

针对其他工具

Most tools (Cursor, Codex, Copilot) read:

```
AGENTS.md
```
(primary)
May also read
```
CLAUDE.md
```
if present

大多数工具（Cursor、Codex、Copilot）的读取顺序：

```
AGENTS.md
```
（主文件）
若存在，也可能读取
```
CLAUDE.md
```

Troubleshooting

故障排查

Issue: AGENTS.md and CLAUDE.md out of sync

问题：AGENTS.md与CLAUDE.md内容不同步

Solution: Regenerate AGENTS.md or set up sync mechanism

解决方案：重新生成AGENTS.md或设置同步机制

Issue: Other tools not reading AGENTS.md

问题：其他工具无法读取AGENTS.md

Solution: Ensure file is in project root, named exactly

AGENTS.md

解决方案：确保文件位于项目根目录，且命名为精确的

AGENTS.md

Issue: Symlink not working

问题：符号链接无法工作

Solution: Use this skill to generate actual file instead

解决方案：使用本技能生成实际文件替代

Issue: Need different commands for different tools

问题：需要为不同工具配置不同命令

Solution: Generate AGENTS.md with common subset, add tool-specific comments

Remember: AGENTS.md is for operational commands. Keep it minimal and actionable. Full methodology stays in CLAUDE.md.

解决方案：生成包含通用子集的AGENTS.md，添加针对特定工具的注释

注意：AGENTS.md用于存储操作命令。请保持内容简洁且可执行。完整方法请保留在CLAUDE.md中。