agents-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AGENTS.md Generator

AGENTS.md 生成器

Create or update agent instruction files for a codebase:

```
AGENTS.md
```
as the canonical instruction file
```
CLAUDE.md
```
shim pointing to
```
AGENTS.md
```
```
GEMINI.md
```
shim pointing to
```
AGENTS.md
```

Embed the behavioral principles from the public Karpathy-inspired coding guidelines: https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md

Source license: MIT, per the upstream repository.

The full upstream

CLAUDE.md

text is hard-coded in the

AGENTS.md

template below. Use that embedded text when generating

AGENTS.md

为代码库创建或更新Agent指令文件：

```
AGENTS.md
```
作为标准指令文件
```
CLAUDE.md
```
shim文件，指向
```
AGENTS.md
```
```
GEMINI.md
```
shim文件，指向
```
AGENTS.md
```

嵌入源自Karpathy公开编码指南的行为准则： https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md

源许可证：MIT，遵循上游仓库规定。

上游完整的

CLAUDE.md

文本已硬编码在下方的

AGENTS.md

模板中。生成

AGENTS.md

时请使用该嵌入文本。

Non-Negotiable Principles

不可协商的准则

Every generated

AGENTS.md

must include the hard-coded upstream four principles as non-negotiables. The four principles are:

Think Before Coding
Simplicity First
Surgical Changes
Goal-Driven Execution

每个生成的

AGENTS.md

必须包含硬编码的上游四项准则作为不可协商内容。四项准则如下：

编码先思考
简洁优先
精准修改
目标导向执行

Discovery Workflow

发现工作流

Identify the workspace root.
Detect whether this is a VS Code workspace:
- Look for
```
*.code-workspace
```
  in the current directory.
- Look for
```
.vscode/
```
  settings when no
```
.code-workspace
```
  file exists.
If a
```
.code-workspace
```
file exists, parse its
```
folders
```
entries and build the project matrix from those folders.
For VS Code workspace folders, use each folder's
```
name
```
field as the source of truth for the project display name and project code. Do not replace it with the filesystem folder name unless
```
name
```
is missing.
Treat any workspace folder whose
```
path
```
is
```
.
```
as the meta workspace, not a code project. Also mention the
```
.code-workspace
```
file itself, if present, as workspace metadata. Add the meta workspace to
```
AGENTS.md
```
with no tech stack.
If no VS Code workspace is detected, infer projects from repo roots, package files, app folders, and README files.

Detect each project's tech stack from files such as:

package.json

pnpm-workspace.yaml

yarn.lock

vite.config.*

next.config.*

pyproject.toml

requirements.txt

uv.lock

poetry.lock

```
go.mod
```
,
```
Cargo.toml
```
,
```
Gemfile
```
,
```
composer.json
```
```
Dockerfile
```
,
```
docker-compose.yml
```
, Terraform files, mobile app configs

Check whether
```
UBIQUITOUS_LANGUAGE.md
```
exists. If it does, reference it as required domain context. If it does not, still include a note that it should be generated with the
```
ubiquitous-language
```
skill when domain terminology matters.

Use structured parsing when available. For

.code-workspace

, prefer JSON parsing that tolerates comments if the local toolchain supports it. If not, read carefully and avoid corrupting paths.

识别工作区根目录。
检测当前是否为VS Code工作区：
- 在当前目录查找
```
*.code-workspace
```
  文件。
- 当不存在
```
.code-workspace
```
  文件时，查找
```
.vscode/
```
  设置。
如果存在
```
.code-workspace
```
文件，解析其
```
folders
```
条目并从这些文件夹构建项目矩阵。
对于VS Code工作区文件夹，使用每个文件夹的
```
name
```
字段作为项目显示名称和项目编码的可靠来源。除非
```
name
```
字段缺失，否则不要用文件系统文件夹名称替换它。
将任何
```
path
```
为
```
.
```
的工作区文件夹视为元工作区，而非代码项目。如果存在
```
.code-workspace
```
文件本身，也需将其作为工作区元数据提及。将元工作区添加到
```
AGENTS.md
```
中，且不标注技术栈。
如果未检测到VS Code工作区，则从仓库根目录、包文件、应用文件夹和README文件推断项目。

从以下文件检测每个项目的技术栈：

package.json

、

pnpm-workspace.yaml

、

yarn.lock

、

vite.config.*

、

next.config.*

pyproject.toml

、

requirements.txt

、

uv.lock

、

poetry.lock

```
go.mod
```
、
```
Cargo.toml
```
、
```
Gemfile
```
、
```
composer.json
```
```
Dockerfile
```
、
```
docker-compose.yml
```
、Terraform文件、移动应用配置

检查
```
UBIQUITOUS_LANGUAGE.md
```
是否存在。如果存在，将其作为必需的领域上下文引用。如果不存在，仍需添加说明：当领域术语重要时，应使用
```
ubiquitous-language
```
技能生成该文件。

在可用情况下使用结构化解析。对于

.code-workspace

文件，如果本地工具链支持，优先使用可容忍注释的JSON解析。如果不支持，则需仔细读取，避免破坏路径。

Project Matrix

项目矩阵

Every

AGENTS.md

must include a project matrix with this exact heading and columns:

markdown

undefined

每个

AGENTS.md

必须包含一个项目矩阵，且必须使用以下精确标题和列：

markdown

undefined

Project Matrix

项目矩阵

Project Name (Code)	Path	Tech Stack
Full Platform Workspace (FULL-PLATFORM-WORKSPACE)	.	Meta workspace, no code
PARTNERS-API (PARTNERS-API)	../partners-apis.example.com	PHP, Laravel


Project code rules:

- Codes are stable identifiers used by feature prompts, discovery, PRDs, issues, and release notes.
- Use uppercase letters, digits, and hyphens only.
- For VS Code workspaces, derive the code from the workspace folder `name`, not from `path`.
- Preserve the workspace folder `name` as the project name, but remove leading emoji/icons and trim whitespace for the display text in `Project Name (Code)`.
- Normalize the code from the cleaned workspace folder name by uppercasing and replacing non-alphanumeric runs with hyphens.
- Example: `🔌 PARTNERS-API` becomes `PARTNERS-API (PARTNERS-API)`.
- Example: `🧩 Full Platform Workspace` with path `.` becomes `Full Platform Workspace (FULL-PLATFORM-WORKSPACE)` and is marked as meta workspace.
- If two projects collide, add a qualifier: `ADMIN-WEB`, `ADMIN-API`.
- Do not rename existing project codes in an existing `AGENTS.md` unless the user asks.
- Mark the VS Code workspace folder with `path: "."` as `Meta workspace, no code`.

项目名称（编码）	路径	技术栈
Full Platform Workspace (FULL-PLATFORM-WORKSPACE)	.	Meta workspace, no code
PARTNERS-API (PARTNERS-API)	../partners-apis.example.com	PHP, Laravel


项目编码规则：

- 编码是功能提示、发现、PRD、问题和发布说明中使用的稳定标识符。
- 仅使用大写字母、数字和连字符。
- 对于VS Code工作区，从工作区文件夹的`name`字段派生编码，而非从`path`字段。
- 保留工作区文件夹的`name`作为项目名称，但在`项目名称（编码）`的显示文本中移除开头的表情符号/图标并修剪空格。
- 通过将清理后的工作区文件夹名称转为大写，并将非字母数字序列替换为连字符，对编码进行规范化。
- 示例：`🔌 PARTNERS-API` 变为 `PARTNERS-API (PARTNERS-API)`。
- 示例：`🧩 Full Platform Workspace` 且路径为`.`时，变为 `Full Platform Workspace (FULL-PLATFORM-WORKSPACE)`，并标记为元工作区。
- 如果两个项目编码冲突，添加限定词：`ADMIN-WEB`、`ADMIN-API`。
- 除非用户要求，否则不要修改现有`AGENTS.md`中的现有项目编码。
- 将`path: "."`的VS Code工作区文件夹标记为`Meta workspace, no code`。

AGENTS.md Structure

AGENTS.md 结构

Generate

AGENTS.md

with this structure:

markdown

undefined

按以下结构生成

AGENTS.md

：

markdown

undefined

Agent Instructions

Agent 指令

Read First

必读内容

```
AGENTS.md
```
is the canonical instruction file for agents in this workspace.
```
CLAUDE.md
```
and
```
GEMINI.md
```
are shims that point here.
Read
```
UBIQUITOUS_LANGUAGE.md
```
when it exists before making domain decisions.
Use the project codes in the Project Matrix when referring to projects in prompts, PRDs, issues, release notes, and discovery reports.

```
AGENTS.md
```
是此工作区中Agent的标准指令文件。
```
CLAUDE.md
```
和
```
GEMINI.md
```
是指向此处的shim文件。
当
```
UBIQUITOUS_LANGUAGE.md
```
存在时，在做出领域决策前请先阅读该文件。
在提示词、PRD、问题、发布说明和发现报告中引用项目时，请使用项目矩阵中的项目编码。

Non-Negotiable Principles

不可协商的准则

Source: https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md

Upstream license: MIT.

来源： https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md

上游许可证：MIT。

CLAUDE.md

Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.

减少常见LLM编码错误的行为指南。必要时可与项目特定指令合并。

权衡： 这些指南偏向谨慎而非速度。对于琐碎任务，请自行判断。

1. Think Before Coding

1. 编码先思考

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

State your assumptions explicitly. If uncertain, ask.
If multiple interpretations exist, present them - don't pick silently.
If a simpler approach exists, say so. Push back when warranted.
If something is unclear, stop. Name what's confusing. Ask.

不要假设。不要隐藏困惑。明确权衡。

在实现前：

明确陈述你的假设。如有不确定，请提问。
如果存在多种解释，请列出所有解释——不要默默选择。
如果存在更简单的方法，请说明。必要时提出异议。
如果有不清楚的地方，请停止。指出困惑之处并提问。

2. Simplicity First

2. 简洁优先

Minimum code that solves the problem. Nothing speculative.

No features beyond what was asked.
No abstractions for single-use code.
No "flexibility" or "configurability" that wasn't requested.
No error handling for impossible scenarios.
If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

用最少的代码解决问题。不做任何投机性内容。

不添加超出需求的功能。
不为单次使用的代码添加抽象。
不添加未被要求的“灵活性”或“可配置性”。
不为不可能的场景添加错误处理。
如果你写了200行代码但本可以用50行完成，请重写。

问问自己：“资深工程师会认为这过于复杂吗？”如果是，请简化。

3. Surgical Changes

3. 精准修改

Touch only what you must. Clean up only your own mess.

When editing existing code:

Don't "improve" adjacent code, comments, or formatting.
Don't refactor things that aren't broken.
Match existing style, even if you'd do it differently.
If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:

Remove imports/variables/functions that YOUR changes made unused.
Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

只修改必须修改的内容。只清理自己造成的混乱。

编辑现有代码时：

不要“改进”无关的代码、注释或格式。
不要重构未损坏的内容。
匹配现有风格，即使你会用不同的方式做。
如果发现无关的死代码，请提及它——不要删除。

当你的修改产生无用内容时：

删除因你的修改而变得无用的导入/变量/函数。
除非被要求，否则不要删除预先存在的死代码。

检验标准：每一行修改都应直接追溯到用户的需求。

4. Goal-Driven Execution

4. 目标导向执行

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

"Add validation" → "Write tests for invalid inputs, then make them pass"
"Fix the bug" → "Write a test that reproduces it, then make it pass"
"Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

定义成功标准。循环直到验证通过。

将任务转化为可验证的目标：

“添加验证” → “为无效输入编写测试，然后让测试通过”
“修复bug” → “编写复现bug的测试，然后让测试通过”
“重构X” → “确保重构前后测试都通过”

对于多步骤任务，简要说明计划：

1. [步骤] → 验证：[检查项]
2. [步骤] → 验证：[检查项]
3. [步骤] → 验证：[检查项]

明确的成功标准让你可以独立循环执行。模糊的标准（“让它工作”）需要不断澄清。

当以下情况发生时，说明这些指南有效： diff中的不必要修改减少，因过于复杂而导致的重写减少，澄清问题在实现前提出而非在错误发生后。

Project Matrix

项目矩阵

Project Name (Code)	Path	Tech Stack
...	...	...

项目名称（编码）	路径	技术栈
...	...	...

Domain Context

领域上下文

Read
```
UBIQUITOUS_LANGUAGE.md
```
before domain-heavy work.
If the file does not exist and terminology is unclear, generate it with the
```
ubiquitous-language
```
skill.

在处理领域相关工作前，请阅读
```
UBIQUITOUS_LANGUAGE.md
```
。
如果该文件不存在且术语不明确，请使用
```
ubiquitous-language
```
技能生成它。

Workspace Notes

工作区说明

[VS Code workspace detection result.]
[Meta workspace entry explanation, including the workspace folder with path
```
.
```
and the
```
.code-workspace
```
file if present.]

[VS Code工作区检测结果。]
[元工作区条目说明，包括路径为
```
.
```
的工作区文件夹，以及（如果存在的话）
```
.code-workspace
```
文件。]

Operating Rules

操作规则

Preserve unrelated user changes.
Prefer existing project patterns over new abstractions.
Keep generated plans tied to project codes.
Run targeted validation for changed behavior.

保留用户的无关修改。
优先使用现有项目模式而非新的抽象。
保持生成的计划与项目编码关联。
对修改后的行为进行针对性验证。

Source Notes

来源说明

Behavioral principles are copied verbatim from the Karpathy-inspired guidelines by forrestchang: https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md
Upstream license: MIT.


Preserve any useful existing local instructions when updating `AGENTS.md`, but reorganize duplicated content into this structure.

行为准则逐字复制自forrestchang基于Karpathy的指南： https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md
上游许可证：MIT。


更新`AGENTS.md`时，请保留任何有用的现有本地指令，但需将重复内容重组为上述结构。

Shim Files

Shim文件

Create or update

CLAUDE.md

and

GEMINI.md

as shims.

Use this content unless the project already has important tool-specific instructions:

markdown

undefined

创建或更新

CLAUDE.md

和

GEMINI.md

作为shim文件。

除非项目已有重要的工具特定指令，否则使用以下内容：

markdown

undefined

Agent Instructions

Agent 指令

Read

AGENTS.md

first. It is the canonical instruction file for this workspace.

This file is a shim for tool compatibility.


If an existing shim contains valuable tool-specific rules, keep them under:

```markdown

请先阅读

AGENTS.md

。它是此工作区的标准指令文件。

本文件是为了工具兼容性而创建的shim文件。


如果现有shim文件包含有价值的工具特定规则，请将其保留在：

```markdown

Tool-Specific Notes

工具特定说明


Do not duplicate the full `AGENTS.md` content into shims.


不要将`AGENTS.md`的完整内容复制到shim文件中。

Final Response

最终响应

After writing files, respond with:

markdown

Generated agent instructions.

Files:
- `AGENTS.md`
- `CLAUDE.md`
- `GEMINI.md`

Project codes:
- `CODE` - Project Name

Notes:
- [VS Code workspace detected / not detected.]
- [UBIQUITOUS_LANGUAGE.md referenced / missing but referenced as recommended context.]

写入文件后，请回复：

markdown

生成Agent指令完成。

文件：
- `AGENTS.md`
- `CLAUDE.md`
- `GEMINI.md`

项目编码：
- `CODE` - 项目名称

说明：
- [检测到VS Code工作区 / 未检测到VS Code工作区。]
- [已引用UBIQUITOUS_LANGUAGE.md / 文件缺失，但已作为推荐上下文引用。]