agents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AGENTS.md Generator Skill

AGENTS.md生成器技能

Generate and maintain AGENTS.md files following the public agents.md convention.

AGENTS.md is FOR AGENTS, not humans. Human readability is a convenient side effect, not a design goal. Every section, format choice, and word exists to maximize AI coding agent efficiency. If something helps humans but wastes agent tokens, remove it.

Spec Compliance: This skill follows the official agents.md specification which has no required fields - all sections are recommendations based on best practices from 2,500+ repositories.

遵循公共agents.md规范生成并维护AGENTS.md文件。

AGENTS.md是为Agent设计的，而非人类。 人类可读性只是附带的便利，并非设计目标。每个章节、格式选择和文字的存在都是为了最大化AI编码Agent的效率。如果某项内容对人类有帮助但会浪费Agent的token，请移除它。

规范合规性： 本技能遵循官方agents.md规范，该规范无必填字段——所有章节都是基于2500+个仓库的最佳实践的建议内容。

Language Choice

语言选择

Default to English - AI coding agents perform best with English instructions because:

Programming keywords, libraries, and error messages are English
Zero "semantic friction" between instruction and code (
```
Create user
```
→
```
createUser
```
)
Most token-efficient encoding for technical instructions

Exception: Match your code's naming language. If your codebase uses non-English naming conventions (e.g., German class names like

Rechnungssteller

, French variables like

id_client

), write AGENTS.md in that language to prevent "naming hallucinations" where agents mix languages.

Rule: The language of AGENTS.md must match the language used for domain naming in the code.

默认使用英文——AI编码Agent使用英文指令时表现最佳，原因如下：

编程关键字、库和错误信息均为英文
指令与代码之间无「语义摩擦」（例如
```
Create user
```
→
```
createUser
```
）
技术指令的编码token效率最高

例外情况：匹配代码的命名语言。如果代码库使用非英文命名规范（例如德语类名

Rechnungssteller

、法语变量

id_client

），请使用对应语言编写AGENTS.md，以避免Agent出现「命名幻觉」（混合使用不同语言）。

规则： AGENTS.md的语言必须与代码中领域命名所使用的语言保持一致。

When to Use This Skill

何时使用本技能

When creating new projects, use this skill to establish baseline AGENTS.md structure.

When standardizing existing projects, use this skill to generate consistent agent documentation.

When ensuring multi-repo consistency, use this skill to apply the same standards across repositories.

When checking if AGENTS.md files are up to date, use the freshness checking scripts to compare file timestamps with git commits.

创建新项目时，使用本技能建立基础AGENTS.md结构
标准化现有项目时，使用本技能生成一致的Agent文档
确保多仓库一致性时，使用本技能在各仓库中应用相同标准
检查AGENTS.md文件是否过时，使用新鲜度检查脚本比较文件时间戳与git提交记录

Audit Before Generating

生成前的审计

NEVER generate AGENTS.md blindly. Before running generation scripts, understand the project:

切勿盲目生成AGENTS.md。运行生成脚本前，请先了解项目：

1. Discover Existing Documentation

1. 发现现有文档

bash

undefined

bash

undefined

Find all existing guides and documentation

查找所有现有指南和文档

find . -name "*.md" -type f | head -30 ls -la .github/ .gitlab/ .claude/ .cursor/ 2>/dev/null

Check for existing agent instructions

检查现有Agent指令

cat CLAUDE.md copilot-instructions.md .github/copilot-instructions.md 2>/dev/null

undefined

cat CLAUDE.md copilot-instructions.md .github/copilot-instructions.md 2>/dev/null

undefined

2. Understand Where Work Happens

2. 了解工作核心区域

bash

undefined

bash

undefined

Most active directories (by recent commits)

最近提交最活跃的目录

Largest directories (by file count)

文件数量最多的目录

find . -type f -not -path './.git/*' | cut -d'/' -f2 | sort | uniq -c | sort -rn | head -10

undefined

find . -type f -not -path './.git/*' | cut -d'/' -f2 | sort | uniq -c | sort -rn | head -10

undefined

3. Identify Pain Points

3. 识别痛点

Look for patterns that indicate areas needing explicit guidance:

Repeated review comments - Check PR history for recurring feedback
CI failures - Check recent CI logs for common failure modes
Large files - Files with 500+ lines often need refactoring guidance
Inconsistent naming - Mixed conventions suggest missing style rules

寻找需要明确指导的模式：

重复的评审意见 - 查看PR历史记录中的常见反馈
CI失败 - 查看近期CI日志中的常见失败模式
大文件 - 500行以上的文件通常需要重构指导
不一致的命名 - 混合规范表明缺少样式规则

4. Interview the Codebase

4. 「访谈」代码库

Ask these questions before generating:

Question	Where to Look
What's the primary language?	`package.json` , `composer.json` , `go.mod`
What framework is used?	`composer.json` (TYPO3, Symfony), `package.json` (React, Vue)
How are tests run?	`Makefile` , `package.json scripts` , CI config
What's the deployment target?	`.github/workflows/` , `Dockerfile` , `docker-compose.yml`
Are there existing conventions?	`CONTRIBUTING.md` , `.editorconfig` , linter configs

This audit ensures generated content addresses real needs rather than generic patterns.

生成前请确认以下问题：

问题	查看位置
主要开发语言是什么？	`package.json` , `composer.json` , `go.mod`
使用了什么框架？	`composer.json` （TYPO3, Symfony）、 `package.json` （React, Vue）
如何运行测试？	`Makefile` , `package.json scripts` , CI配置
部署目标是什么？	`.github/workflows/` , `Dockerfile` , `docker-compose.yml`
是否存在现有规范？	`CONTRIBUTING.md` , `.editorconfig` , 代码检查器配置

本次审计可确保生成的内容解决实际需求，而非通用模式。

Prerequisites

前置要求

The generator scripts require:

Requirement	Version	Notes
Bash	4.3+	Required for nameref variables ( `local -n` )
jq	1.5+	JSON processing
git	2.0+	For git history analysis

生成器脚本需要以下依赖：

依赖项	版本	说明
Bash	4.3+	需支持nameref变量（ `local -n` ）
jq	1.5+	JSON处理工具
git	2.0+	用于git历史分析

macOS Users

macOS用户

macOS ships with Bash 3.2 (GPLv2 licensed). Install a newer version:

bash

undefined

macOS默认搭载Bash 3.2（基于GPLv2协议）。请安装更新版本：

bash

undefined

Install Bash 4.4+ via Homebrew

通过Homebrew安装Bash 4.4+

brew install bash

Run scripts with newer bash

使用新版本Bash运行脚本

/opt/homebrew/bin/bash scripts/generate-agents.sh /path/to/project

Or add to PATH (optional)

或添加到PATH（可选）

export PATH="/opt/homebrew/bin:$PATH"


The scripts will detect incompatible Bash versions and exit with a helpful error message.

export PATH="/opt/homebrew/bin:$PATH"


脚本会检测不兼容的Bash版本，并输出友好的错误提示后退出。

CRITICAL: Full Verification Required

关键要求：必须完成完整验证

NEVER trust existing AGENTS.md content as accurate. Always verify documented information against the actual codebase:

切勿默认认为现有AGENTS.md内容准确。请始终对照实际代码库验证文档信息：

Mandatory Verification Steps

强制验证步骤

Extract actual state from source files:
- List all modules/files with their actual docstrings
- List all scripts and their actual purposes
- Extract actual Makefile/package.json commands
- List actual test files and structure
Compare extracted state against documented state:
- Check if documented files actually exist
- Check if documented commands actually work
- Check if module descriptions match actual docstrings
- Check if counts (modules, scripts, tests) are accurate
Identify and fix discrepancies:
- Remove documentation for non-existent files
- Add documentation for undocumented files
- Correct inaccurate descriptions
- Update outdated counts and references
Preserve unverifiable content:
- Keep manually-written context that can't be extracted
- Keep subjective guidance and best practices
- Mark preserved content appropriately

从源文件提取实际状态：
- 列出所有模块/文件及其实际文档字符串
- 列出所有脚本及其实际用途
- 提取实际的Makefile/package.json命令
- 列出实际的测试文件和结构
对比提取状态与文档状态：
- 检查文档中记录的文件是否实际存在
- 检查文档中记录的命令是否可正常运行
- 检查模块描述是否与实际文档字符串匹配
- 检查计数（模块、脚本、测试）是否准确
识别并修复差异：
- 删除不存在文件的文档记录
- 添加未记录文件的文档内容
- 修正不准确的描述
- 更新过时的计数和引用
保留无法验证的内容：
- 保留无法自动提取的人工编写上下文
- 保留主观指导和最佳实践
- 对保留的内容进行适当标记

What to Verify

验证内容清单

Category	Verification Method
Module list	`ls <dir>/*.py` + read docstrings
Script list	`ls scripts/*.sh` + read headers
Commands	`grep` Makefile targets AND run them
Test files	`ls tests/*.py`
Data files	`ls *.json` in project root
Config files	Check actual existence
File names	EXACT match required (not just existence)
Numeric values	PHPStan level, coverage %, etc. from actual configs

类别	验证方法
模块列表	`ls <dir>/*.py` + 读取文档字符串
脚本列表	`ls scripts/*.sh` + 读取头部注释
命令	`grep` Makefile目标并实际运行
测试文件	`ls tests/*.py`
数据文件	项目根目录下的 `ls *.json`
配置文件	检查实际是否存在
文件名	必须完全匹配（不仅是存在）
数值	PHPStan级别、覆盖率等，从实际配置中提取

Critical: Exact Name Matching

关键要求：文件名完全匹配

File names in AGENTS.md must match actual filenames exactly:

Documented	Actual	Status
`CowriterAjaxController.php`	`AjaxController.php`	WRONG - name mismatch
`AjaxController.php`	`AjaxController.php`	Correct

Real-world example from t3x-cowriter review:

AGENTS.md documented
```
Controller/CowriterAjaxController.php
```
Actual file was
```
Controller/AjaxController.php
```
This mismatch confused agents trying to find the file

AGENTS.md中的文件名必须与实际文件名完全一致：

文档记录	实际文件	状态
`CowriterAjaxController.php`	`AjaxController.php`	错误 - 名称不匹配
`AjaxController.php`	`AjaxController.php`	正确

来自t3x-cowriter评审的真实案例：

AGENTS.md中记录了
```
Controller/CowriterAjaxController.php
```
实际文件为
```
Controller/AjaxController.php
```
该不匹配导致Agent无法找到文件

Critical: Command Verification

关键要求：命令验证

Commands documented in AGENTS.md must actually work when run:

bash

undefined

AGENTS.md中记录的命令必须可实际运行：

bash

undefined

BAD: Document without testing

错误做法：未测试就记录

make test-mutation # May not exist!

make test-mutation # 可能不存在！

GOOD: Verify before documenting

正确做法：记录前先验证

make -n test-mutation 2>/dev/null && echo "EXISTS" || echo "MISSING"


**Real-world example from t3x-cowriter review:**
- AGENTS.md documented `make test-mutation` and `make phpstan`
- Neither target existed (actual was `make typecheck`)
- Agents failed when trying to run documented commands

make -n test-mutation 2>/dev/null && echo "存在" || echo "不存在"


**来自t3x-cowriter评审的真实案例：**
- AGENTS.md中记录了`make test-mutation`和`make phpstan`
- 这两个目标均不存在（实际为`make typecheck`）
- Agent尝试运行文档中的命令时失败

Example Verification Commands

验证命令示例

bash

undefined

bash

undefined

Extract actual module docstrings

提取实际模块的文档字符串

for f in cli_audit/*.py; do head -20 "$f" | grep -A5 '"""'; done

List actual scripts

列出实际脚本

ls scripts/*.sh

Extract Makefile targets

提取Makefile目标

grep -E '^[a-z_-]+:' Makefile*

List actual test files

列出实际测试文件

ls tests/.py tests/**/.py

undefined

ls tests/.py tests/**/.py

undefined

Anti-Patterns to Avoid

需避免的反模式

WRONG: Updating only dates and counts based on git commits
WRONG: Trusting that existing AGENTS.md was created correctly
WRONG: Copying file lists without verifying they exist
WRONG: Using extracted command output without running it
RIGHT: Extract → Compare → Fix discrepancies → Validate

错误： 仅基于git提交更新日期和计数
错误： 假设现有AGENTS.md内容创建正确
错误： 复制文件列表而不验证是否存在
错误： 使用提取的命令输出而不实际运行
正确： 提取 → 对比 → 修复差异 → 验证

Agent-Optimized Design

面向Agent优化的设计

This skill generates AGENTS.md files optimized for AI coding agent efficiency based on:

Research showing 16.58% token reduction with good AGENTS.md
GitHub best practices from 2,500+ repositories
Multi-agent collaborative design (Claude + Gemini discussion)

本技能基于以下内容生成面向AI编码Agent效率优化的AGENTS.md文件：

Key Design Principles

核心设计原则

Structured over Prose - Tables and maps parse faster than paragraphs
Verified Commands - Commands that don't work waste 500+ tokens debugging
Pointer Principle - Point to files, don't duplicate content
Time Estimates - Help agents choose appropriate test scope
Golden Samples - One example file beats pages of explanation
Heuristics Tables - Eliminate decision ambiguity

结构化优先于散文式 - 表格和映射比段落解析更快
已验证的命令 - 无法运行的命令会浪费500+ token用于调试
指向原则 - 指向文件，而非重复内容
时间估算 - 帮助Agent选择合适的测试范围
黄金示例 - 一个示例文件胜过数页说明
启发式表格 - 消除决策歧义

Token-Saving Sections

节省Token的章节

Section	Saves	How
Commands (verified)	500+ tokens	No debugging broken commands
File Map	3-5 search cycles	Direct navigation
Golden Samples	Full rewrites	Correct patterns first time
Utilities List	Duplicate code	Reuse existing helpers
Heuristics	User correction cycles	Autonomous decisions
Codebase State	Breaking changes	Avoid legacy/migration code

章节	节省Token数量	实现方式
已验证命令	500+	无需调试无效命令
文件映射	3-5次搜索周期	直接导航
黄金示例	避免重复编写	首次就使用正确模式
工具列表	避免重复代码	重用现有辅助工具
启发式规则	减少用户修正周期	自主决策
代码库状态	避免破坏变更	避开遗留/迁移代码

Capabilities

功能特性

Thin root files (~50 lines) with precedence rules and agent-optimized tables
Scoped files for subsystems (backend/, frontend/, internal/, cmd/)
Auto-extracted commands from Makefile, package.json, composer.json, go.mod
Language-specific templates for Go, PHP, TypeScript, Python, hybrid projects
Freshness checking - Detects if AGENTS.md files are outdated by comparing their "Last updated" date with git commits
Automatic timestamps - All generated files include creation/update dates in the header
Documentation extraction - Parses README.md, CONTRIBUTING.md, SECURITY.md, CHANGELOG.md
Platform file extraction - Parses .github/, .gitlab/ templates, CODEOWNERS, dependabot.yml
IDE settings extraction - Parses .editorconfig, .vscode/, .idea/, .phpstorm/
AI agent config extraction - Parses .cursor/, .claude/, .windsurf/, copilot-instructions.md
Extraction summary - Verbose mode shows all detected settings and their sources

精简根文件（约50行），包含优先级规则和Agent优化表格
作用域文件，针对子系统（backend/、frontend/、internal/、cmd/）
自动提取命令，从Makefile、package.json、composer.json、go.mod中提取
语言特定模板，支持Go、PHP、TypeScript、Python、混合项目
新鲜度检查 - 通过对比「最后更新」日期与git提交记录，检测AGENTS.md文件是否过时
自动时间戳 - 所有生成的文件头部均包含创建/更新日期
文档提取 - 解析README.md、CONTRIBUTING.md、SECURITY.md、CHANGELOG.md
平台文件提取 - 解析.github/、.gitlab/模板、CODEOWNERS、dependabot.yml
IDE设置提取 - 解析.editorconfig、.vscode/、.idea/、.phpstorm/
AI Agent配置提取 - 解析.cursor/、.claude/、.windsurf/、copilot-instructions.md
提取摘要 - 详细模式下显示所有检测到的设置及其来源

Running Scripts

运行脚本

Generating AGENTS.md Files

生成AGENTS.md文件

To generate AGENTS.md files for a project:

bash

scripts/generate-agents.sh /path/to/project

Options:

```
--dry-run
```
- Preview changes without writing files
```
--verbose
```
- Show detailed output
```
--style=thin
```
- Use thin root template (~30 lines, default)
```
--style=verbose
```
- Use verbose root template (~100-200 lines)
```
--update
```
- Update existing files only (preserves human edits outside generated markers)
```
--claude-shim
```
- Generate CLAUDE.md that imports AGENTS.md for Claude Code compatibility
```
--force
```
- Regenerate even if files exist

为项目生成AGENTS.md文件：

bash

scripts/generate-agents.sh /path/to/project

可选参数：

```
--dry-run
```
- 预览变更但不写入文件
```
--verbose
```
- 显示详细输出
```
--style=thin
```
- 使用精简根模板（约30行，默认）
```
--style=verbose
```
- 使用详细根模板（约100-200行）
```
--update
```
- 仅更新现有文件（保留生成标记外的人工编辑内容）
```
--claude-shim
```
- 生成导入AGENTS.md的CLAUDE.md文件，兼容Claude Code
```
--force
```
- 即使文件已存在也重新生成

Validating Structure

验证结构合规性

To validate AGENTS.md structure compliance:

bash

scripts/validate-structure.sh /path/to/project

Options:

```
--check-freshness, -f
```
- Also check if files are up to date with git commits
```
--verbose, -v
```
- Show detailed output

验证AGENTS.md结构是否符合规范：

bash

scripts/validate-structure.sh /path/to/project

可选参数：

```
--check-freshness, -f
```
- 同时检查文件是否与git提交记录同步
```
--verbose, -v
```
- 显示详细输出

Checking Freshness

检查新鲜度

To check if AGENTS.md files are up to date with recent git commits:

bash

scripts/check-freshness.sh /path/to/project

This script:

Extracts the "Last updated" date from the AGENTS.md header
Checks git commits since that date for files in the relevant scope
Reports if there are commits that might require AGENTS.md updates

Options:

```
--verbose, -v
```
- Show commit details and changed files
```
--threshold=DAYS
```
- Days threshold to consider stale (default: 7)

Example with full validation:

bash

scripts/validate-structure.sh /path/to/project --check-freshness --verbose

检查AGENTS.md文件是否与近期git提交记录同步：

bash

scripts/check-freshness.sh /path/to/project

该脚本：

从AGENTS.md头部提取「最后更新」日期
检查该日期之后相关作用域内的git提交记录
报告可能需要更新AGENTS.md的提交

可选参数：

```
--verbose, -v
```
- 显示提交详情和变更文件
```
--threshold=DAYS
```
- 判定为过时的天数阈值（默认：7天）

完整验证示例：

bash

scripts/validate-structure.sh /path/to/project --check-freshness --verbose

Detecting Project Type

检测项目类型

To detect project language, version, and build tools:

bash

scripts/detect-project.sh /path/to/project

检测项目的语言、版本和构建工具：

bash

scripts/detect-project.sh /path/to/project

Detecting Scopes

检测作用域

To identify directories that should have scoped AGENTS.md files:

bash

scripts/detect-scopes.sh /path/to/project

识别需要创建作用域AGENTS.md文件的目录：

bash

scripts/detect-scopes.sh /path/to/project

Extracting Commands

提取命令

To extract build commands from Makefile, package.json, composer.json, or go.mod:

bash

scripts/extract-commands.sh /path/to/project

从Makefile、package.json、composer.json或go.mod中提取构建命令：

bash

scripts/extract-commands.sh /path/to/project

Extracting Documentation

提取文档信息

To extract information from README.md, CONTRIBUTING.md, SECURITY.md, and other documentation:

bash

scripts/extract-documentation.sh /path/to/project

从README.md、CONTRIBUTING.md、SECURITY.md等文档中提取信息：

bash

scripts/extract-documentation.sh /path/to/project

Extracting Platform Files

提取平台文件信息

To extract information from .github/, .gitlab/, CODEOWNERS, dependabot.yml, etc.:

bash

scripts/extract-platform-files.sh /path/to/project

从.github/、.gitlab/、CODEOWNERS、dependabot.yml等文件中提取信息：

bash

scripts/extract-platform-files.sh /path/to/project

Extracting IDE Settings

提取IDE设置信息

To extract information from .editorconfig, .vscode/, .idea/, etc.:

bash

scripts/extract-ide-settings.sh /path/to/project

从.editorconfig、.vscode/、.idea/等文件中提取信息：

bash

scripts/extract-ide-settings.sh /path/to/project

Extracting AI Agent Configs

提取AI Agent配置信息

To extract information from .cursor/, .claude/, copilot-instructions.md, etc.:

bash

scripts/extract-agent-configs.sh /path/to/project

从.cursor/、.claude/、copilot-instructions.md等文件中提取信息：

bash

scripts/extract-agent-configs.sh /path/to/project

Verifying Content Accuracy

验证内容准确性

CRITICAL: Always run this before considering AGENTS.md files complete.

To verify that AGENTS.md content matches actual codebase state:

bash

scripts/verify-content.sh /path/to/project

This script:

Checks if documented files actually exist
Verifies Makefile targets are real
Compares module/script counts against actual files
Reports undocumented files that should be added
Reports documented files that don't exist

Options:

```
--verbose, -v
```
- Show detailed verification output
```
--fix
```
- Suggest fixes for common issues

This verification step is MANDATORY when updating existing AGENTS.md files.

关键要求：在确认AGENTS.md文件完成前必须运行此脚本。

验证AGENTS.md内容是否与实际代码库状态匹配：

bash

scripts/verify-content.sh /path/to/project

该脚本：

检查文档中记录的文件是否实际存在
验证Makefile目标是否真实存在
对比模块/脚本计数与实际文件
报告应添加的未记录文件
报告不存在的已记录文件

可选参数：

```
--verbose, -v
```
- 显示详细验证输出
```
--fix
```
- 针对常见问题建议修复方案

更新现有AGENTS.md文件时，此验证步骤为强制要求。

Verifying Commands Work

验证命令可运行性

To prevent "command rot" (documented commands that no longer work):

bash

scripts/verify-commands.sh /path/to/project

This script:

Extracts commands from AGENTS.md tables and code blocks
Verifies npm/yarn scripts exist in package.json
Verifies make targets exist in Makefile
Verifies composer scripts exist in composer.json
Updates "Last verified" timestamp on success

Options:

```
VERBOSE=true
```
- Show detailed output
```
DRY_RUN=true
```
- Don't update timestamp

Why this matters: Research shows broken commands waste 500+ tokens as agents debug non-existent commands. Verified commands enable confident execution.

防止「命令失效」（文档中记录的命令已无法运行）：

bash

scripts/verify-commands.sh /path/to/project

该脚本：

从AGENTS.md表格和代码块中提取命令
验证npm/yarn脚本是否存在于package.json
验证make目标是否存在于Makefile
验证composer脚本是否存在于composer.json
验证成功时更新「最后验证」时间戳

可选参数：

```
VERBOSE=true
```
- 显示详细输出
```
DRY_RUN=true
```
- 不更新时间戳

重要性：研究表明，无效命令会导致Agent浪费500+ token用于调试。已验证的命令可确保Agent自信执行。

Post-Generation Validation Checklist

生成后验证清单

After generating AGENTS.md files, ALWAYS validate the output:

bash

undefined

生成AGENTS.md文件后，请始终验证输出内容：

bash

undefined

1. Run structure validation

1. 运行结构验证

scripts/validate-structure.sh /path/to/project --verbose

2. Verify content accuracy

2. 验证内容准确性

scripts/verify-content.sh /path/to/project

3. Verify commands work

3. 验证命令可运行性

scripts/verify-commands.sh /path/to/project


**Validation criteria:**

| Check | Pass Criteria | Common Issues |
|-------|---------------|---------------|
| **Thin root** | Root AGENTS.md ≤ 80 lines | Duplicated scope content in root |
| **All scopes covered** | Every major directory has AGENTS.md | Missing `Tests/`, `Configuration/` |
| **No duplication** | Content appears in ONE location | Commands duplicated in root + scope |
| **Commands verified** | All documented commands execute | Typos, renamed targets |
| **Files exist** | All referenced files are real | Hallucinated paths |
| **Links valid** | All cross-references resolve | Broken relative paths |

**Example validation output:**

✓ Root AGENTS.md: 47 lines (thin) ✓ Scopes found: Classes/, Tests/, Configuration/ ✓ No duplicate commands between root and scopes ✗ Missing: Resources/Private/Templates/ (no AGENTS.md) ✗ Command "make phpstan" not found (actual: "make typecheck")


**Never consider generation complete until all checks pass.**

scripts/verify-commands.sh /path/to/project


**验证标准：**

| 检查项 | 通过标准 | 常见问题 |
|-------|---------------|---------------|
| **精简根文件** | 根AGENTS.md ≤ 80行 | 根文件中重复了作用域内容 |
| **覆盖所有作用域** | 每个主要目录均有AGENTS.md | 缺少`Tests/`、`Configuration/`目录的文件 |
| **无重复内容** | 内容仅出现在一个位置 | 命令在根文件和作用域文件中重复 |
| **命令已验证** | 所有文档中的命令均可执行 | 拼写错误、目标重命名 |
| **文件存在** | 所有引用的文件均真实存在 | 虚构的路径 |
| **链接有效** | 所有交叉引用均可解析 | 无效的相对路径 |

**验证输出示例：**

✓ 根AGENTS.md：47行（精简格式） ✓ 检测到的作用域：Classes/、Tests/、Configuration/ ✓ 根文件与作用域文件之间无重复命令 ✗ 缺失：Resources/Private/Templates/（无AGENTS.md） ✗ 命令"make phpstan"不存在（实际为"make typecheck"）


**所有检查通过前，请勿认为生成已完成。**

Using Reference Documentation

使用参考文档

AGENTS.md Analysis

AGENTS.md分析

When understanding best practices and patterns, consult

references/analysis.md

for analysis of 21 real-world AGENTS.md files.

了解最佳实践和模式时，请参考

references/analysis.md

，其中包含对21个真实AGENTS.md文件的分析。

Directory Coverage

目录覆盖范围

When determining which directories need AGENTS.md files, consult

references/directory-coverage.md

for guidance on PHP/TYPO3, Go, and TypeScript project structures.

确定哪些目录需要AGENTS.md文件时，请参考

references/directory-coverage.md

，其中包含PHP/TYPO3、Go和TypeScript项目结构的指导。

Real-World Examples

真实示例

When needing concrete examples of AGENTS.md files, consult

references/examples/

Project	Files	Description
`coding-agent-cli/`	Root + scripts scope	CLI tool example
`ldap-selfservice/`	Root + internal scopes	Go web app with multiple scopes
`simple-ldap-go/`	Root + examples scope	Go library example
`t3x-rte-ckeditor-image/`	Root + Classes scope	TYPO3 extension example

需要AGENTS.md文件的具体示例时，请参考

references/examples/

：

项目	文件	描述
`coding-agent-cli/`	根文件 + 脚本作用域	CLI工具示例
`ldap-selfservice/`	根文件 + 内部作用域	包含多个作用域的Go Web应用
`simple-ldap-go/`	根文件 + 示例作用域	Go库示例
`t3x-rte-ckeditor-image/`	根文件 + Classes作用域	TYPO3扩展示例

Using Asset Templates

使用资产模板

Root Templates

根模板

When generating root AGENTS.md files, the scripts use these templates:

```
assets/root-thin.md
```
- Minimal root template (~30 lines) with precedence rules and scope index
```
assets/root-verbose.md
```
- Detailed root template (~100 lines) with architecture overview and examples

生成根AGENTS.md文件时，脚本使用以下模板：

```
assets/root-thin.md
```
- 极简根模板（约30行），包含优先级规则和作用域索引
```
assets/root-verbose.md
```
- 详细根模板（约100行），包含架构概述和示例

Scoped Templates

作用域模板

When generating scoped AGENTS.md files, the scripts use language-specific templates:

```
assets/scoped/backend-go.md
```
- Go backend patterns (packages, error handling, testing)
```
assets/scoped/backend-php.md
```
- PHP backend patterns (PSR, DI, security)
```
assets/scoped/typo3.md
```
- TYPO3 extension patterns (TCA, Extbase, Fluid, TYPO3 CGL)
```
assets/scoped/oro.md
```
- Oro bundle patterns (datagrids, workflows, ACL, message queue)
```
assets/scoped/cli.md
```
- CLI patterns (flags, output, error codes)
```
assets/scoped/frontend-typescript.md
```
- TypeScript frontend patterns (components, state, testing)

生成作用域AGENTS.md文件时，脚本使用语言特定模板：

```
assets/scoped/backend-go.md
```
- Go后端模式（包、错误处理、测试）
```
assets/scoped/backend-php.md
```
- PHP后端模式（PSR、DI、安全）
```
assets/scoped/typo3.md
```
- TYPO3扩展模式（TCA、Extbase、Fluid、TYPO3 CGL）
```
assets/scoped/oro.md
```
- Oro Bundle模式（数据网格、工作流、ACL、消息队列）
```
assets/scoped/cli.md
```
- CLI模式（标志、输出、错误代码）
```
assets/scoped/frontend-typescript.md
```
- TypeScript前端模式（组件、状态、测试）

Supported Project Types

支持的项目类型

Language	Project Types
Go	Libraries, web apps (Fiber/Echo/Gin), CLI (Cobra/urfave)
PHP	Composer packages, Laravel/Symfony
PHP/TYPO3	TYPO3 extensions (auto-detected via `ext_emconf.php` )
PHP/Oro	OroCommerce, OroPlatform, OroCRM bundles
TypeScript	React, Next.js, Vue, Node.js
Python	pip, poetry, Django, Flask, FastAPI
Hybrid	Multi-language projects (auto-creates scoped files per stack)

语言	项目类型
Go	库、Web应用（Fiber/Echo/Gin）、CLI（Cobra/urfave）
PHP	Composer包、Laravel/Symfony
PHP/TYPO3	TYPO3扩展（通过 `ext_emconf.php` 自动检测）
PHP/Oro	OroCommerce、OroPlatform、OroCRM Bundle
TypeScript	React、Next.js、Vue、Node.js
Python	pip、poetry、Django、Flask、FastAPI
混合	多语言项目（自动为每个技术栈创建作用域文件）

Output Structure

输出结构

Root File

根文件

Root AGENTS.md (~50-80 lines) contains agent-optimized sections:

Section	Purpose	Format
Commands (verified)	Executable commands with time estimates	Table with ~Time column
File Map	Directory purposes for navigation	`dir/ → purpose` format
Golden Samples	Canonical patterns to follow	Table: For / Reference / Key patterns
Utilities List	Existing helpers to reuse	Table: Need / Use / Location
Heuristics	Quick decision rules	Table: When / Do
Boundaries	Always/Ask/Never rules	Three-tier list
Codebase State	Migrations, tech debt, known issues	Bullet list
Terminology	Domain-specific terms	Table: Term / Means
Scope Index	Links to scoped files	List with descriptions

根AGENTS.md（约50-80行）包含面向Agent优化的章节：

章节	用途	格式
已验证命令	带时间估算的可执行命令	包含~Time列的表格
文件映射	用于导航的目录用途说明	`dir/ → 用途` 格式
黄金示例	需遵循的标准模式	表格：场景 / 参考文件 / 核心模式
工具列表	可重用的现有辅助工具	表格：需求 / 用途 / 位置
启发式规则	快速决策规则	表格：场景 / 操作
边界规则	始终执行/需询问/禁止操作规则	三级列表
代码库状态	迁移、技术债务、已知问题	项目符号列表
术语表	领域特定术语	表格：术语 / 含义
作用域索引	指向作用域文件的链接	带描述的列表

Scoped Files

作用域文件

Scoped AGENTS.md files cover six core areas (per GitHub best practices):

Commands - Executable build, test, lint commands
Testing - Test conventions and execution
Project Structure - Architecture and key files
Code Style - Formatting and conventions
Git Workflow - Commit/PR guidelines
Boundaries - Always do / Ask first / Never do

Additional recommended sections:

Overview
Setup/Prerequisites
Security
Good vs Bad examples
When stuck
House Rules (for scoped overrides)

作用域AGENTS.md文件涵盖六个核心领域（基于GitHub最佳实践）：

命令 - 可执行的构建、测试、代码检查命令
测试 - 测试规范与执行方式
项目结构 - 架构与核心文件
代码风格 - 格式与规范
Git工作流 - 提交/PR指南
边界规则 - 始终执行/需询问/禁止操作规则

推荐的额外章节：

概述
安装/前置要求
安全
优劣示例
遇到问题时的处理方式
本地规则（用于覆盖根文件规则）

AI Tool Compatibility

AI工具兼容性

Claude Code

Claude Code centers on CLAUDE.md files. For compatibility, use the

--claude-shim

flag to generate a CLAUDE.md that imports AGENTS.md:

bash

scripts/generate-agents.sh /path/to/project --claude-shim

This creates a minimal CLAUDE.md:

markdown

<!-- Auto-generated shim for Claude Code compatibility -->
@import AGENTS.md

This ensures AGENTS.md remains the source of truth while Claude Code can access it.

Claude Code以CLAUDE.md文件为核心。为确保兼容性，请使用

--claude-shim

标志生成导入AGENTS.md的CLAUDE.md文件：

bash

scripts/generate-agents.sh /path/to/project --claude-shim

这将创建一个极简的CLAUDE.md文件：

markdown

<!-- 为Claude Code兼容性自动生成的垫片 -->
@import AGENTS.md

这样可确保AGENTS.md始终为事实来源，同时Claude Code可访问其内容。

OpenAI Codex

Codex uses stacking semantics with AGENTS.override.md for per-directory overrides:

Concatenation order:
```
~/.codex/AGENTS.md
```
→ root → nested directories → current dir
Override files: Place
```
AGENTS.override.md
```
in directories to add/override rules
Size limit: Default 32 KiB cap - keep root AGENTS.md lean so nested files aren't crowded out

Best practices for Codex:

Keep root AGENTS.md under 4 KiB (leaves room for 7+ nested files)
Use
```
--style=thin
```
template for optimal Codex compatibility
Move detailed rules to scoped AGENTS.md files in subdirectories
Use AGENTS.override.md for directory-specific behavior changes

Example override structure:

project/
├── AGENTS.md                    # Thin root (~2 KiB)
├── src/
│   ├── AGENTS.md               # Source patterns
│   └── AGENTS.override.md      # Override root rules for src/
└── tests/
    ├── AGENTS.md               # Test patterns
    └── AGENTS.override.md      # Allow larger PRs in tests/

Codex使用堆叠语义，通过AGENTS.override.md实现按目录覆盖：

拼接顺序：
```
~/.codex/AGENTS.md
```
→ 根文件 → 嵌套目录 → 当前目录
覆盖文件： 在目录中放置
```
AGENTS.override.md
```
以添加/覆盖规则
大小限制： 默认32 KiB上限 - 保持根AGENTS.md精简，避免嵌套文件超出限制

Codex最佳实践：

保持根AGENTS.md小于4 KiB（为7+个嵌套文件预留空间）
使用
```
--style=thin
```
模板以获得最佳兼容性
将详细规则移至子目录的作用域AGENTS.md文件
使用AGENTS.override.md实现目录特定行为变更

覆盖结构示例：

project/
├── AGENTS.md                    # 精简根文件（约2 KiB）
├── src/
│   ├── AGENTS.md               # 源码模式
│   └── AGENTS.override.md      # 覆盖src/目录的根文件规则
└── tests/
    ├── AGENTS.md               # 测试模式
    └── AGENTS.override.md      # 允许测试目录中的PR更大

GitHub Copilot

GitHub Copilot uses

.github/copilot-instructions.md

for repository-wide instructions. This skill extracts existing Copilot instructions and can coexist with AGENTS.md files.

GitHub Copilot使用

.github/copilot-instructions.md

存储仓库级指令。本技能可提取现有Copilot指令，并与AGENTS.md文件共存。

When to Customize vs Auto-Generate

自定义与自动生成的适用场景

Not all sections should be auto-generated. Understanding which sections benefit from manual curation vs automation prevents wasted effort and preserves valuable human insight.

并非所有章节都适合自动生成。了解哪些章节适合人工整理、哪些适合自动化，可避免浪费精力并保留有价值的人类见解。

Auto-Generate These Sections

适合自动生成的章节

These sections are factual and extractable - let scripts handle them:

Section	Why Auto-Generate
Commands	Extract from Makefile/package.json - always accurate
File Map	Directory listing is objective
Scope Index	Detectable from filesystem structure
Language/Framework	Detectable from config files
Test Commands	Extract from CI config

这些章节基于事实且可自动提取 - 请让脚本处理：

章节	自动生成原因
命令	从Makefile/package.json提取 - 始终准确
文件映射	目录列表是客观信息
作用域索引	可从文件系统结构检测
语言/框架	可从配置文件检测
测试命令	从CI配置提取

Manually Curate These Sections

适合人工整理的章节

These sections require human judgment - preserve them during updates:

Section	Why Manual
Golden Samples	Requires taste - which file exemplifies good patterns?
Heuristics	Decision rules come from team experience
Boundaries	Always/Ask/Never rules reflect team policy
Codebase State	Tech debt awareness requires context
Terminology	Domain knowledge is human insight
Architecture Decisions	Why choices were made isn't extractable

这些章节需要人类判断 - 更新时请保留：

章节	人工整理原因
黄金示例	需要筛选 - 哪个文件可作为优质模式的典范？
启发式规则	决策规则来自团队经验
边界规则	始终执行/需询问/禁止操作规则反映团队政策
代码库状态	技术债务认知需要上下文
术语表	领域知识是人类见解
架构决策	无法从文件中提取选择背后的原因

Override Best Practices

覆盖最佳实践

When updating existing AGENTS.md files, preserve custom content:

1. Use
--update
flag:

bash

scripts/generate-agents.sh /path/to/project --update

This preserves content outside

<!-- GENERATED:START -->

<!-- GENERATED:END -->

markers.

2. Place custom content outside markers:

markdown

<!-- GENERATED:START -->

更新现有AGENTS.md文件时，请保留自定义内容：

1. 使用
--update
标志：

bash

scripts/generate-agents.sh /path/to/project --update

此参数会保留

<!-- GENERATED:START -->

<!-- GENERATED:END -->

标记外的内容。

2. 将自定义内容放在标记外：

markdown

<!-- GENERATED:START -->

Commands (auto-generated)

已验证命令（自动生成）

Command	Purpose
`make test`	Run tests

命令	用途
`make test`	运行测试

Custom Heuristics (preserved)

自定义启发式规则（保留内容）

When	Do
Adding endpoint	Create OpenAPI spec first


**3. Use scoped overrides for exceptions:**

project/ ├── AGENTS.md # Global rules └── legacy/ └── AGENTS.md # "Ignore linting in this directory"


**4. Review diffs before committing:**
```bash

场景	操作
添加端点时	先创建OpenAPI规范


**3. 使用作用域覆盖处理例外情况：**

project/ ├── AGENTS.md # 全局规则 └── legacy/ └── AGENTS.md # "忽略此目录的代码检查"


**4. 提交前查看差异：**
```bash

After regenerating

重新生成后

git diff AGENTS.md

Ensure custom sections weren't overwritten

确保自定义章节未被覆盖


**Anti-patterns:**
- **WRONG:** Running generation without `--update`, losing all custom content
- **WRONG:** Duplicating auto-generated content with manual edits (causes drift)
- **WRONG:** Putting custom heuristics inside generated markers (will be overwritten)
- **RIGHT:** Custom content outside markers, auto-content inside markers


**反模式：**
- **错误：** 未使用`--update`标志运行生成，丢失所有自定义内容
- **错误：** 手动编辑自动生成的内容（会导致内容漂移）
- **错误：** 将自定义启发式规则放在生成标记内（会被覆盖）
- **正确：** 自定义内容放在标记外，自动生成内容放在标记内

Directory Coverage

目录覆盖范围

When creating AGENTS.md files, create them in ALL key directories:

Directory	Purpose
Root	Precedence, architecture overview
`Classes/` or `src/`	Source code patterns
`Configuration/` or `config/`	Framework config
`Documentation/` or `docs/`	Doc standards
`Resources/` or `assets/`	Templates, assets
`Tests/`	Testing patterns

Contributing: https://github.com/netresearch/agents-skill

创建AGENTS.md文件时，请为所有关键目录创建：

目录	用途
根目录	优先级规则、架构概述
`Classes/` 或 `src/`	源码模式
`Configuration/` 或 `config/`	框架配置
`Documentation/` 或 `docs/`	文档标准
`Resources/` 或 `assets/`	模板、资源文件
`Tests/`	测试模式

贡献指南： https://github.com/netresearch/agents-skill