agents-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AGENTS.md builder

AGENTS.md 构建器

Goal

目标

Add lightweight, scoped guidance for an AI agent (and humans) by placing AGENTS.md files at key directory boundaries:

root: cross-domain guidance + a module map (for monorepos)
nested: tech-specific instructions for each component/module
optional: feature maps at the module level

Optimize for concise and precise instructions (short bullets, minimal prose). Link to docs for depth.

通过在关键目录边界放置AGENTS.md文件，为AI Agent（以及人类开发者）提供轻量、范围明确的指引：

根目录：跨领域指引 + monorepo模块映射
嵌套目录：针对每个组件/模块的技术专属说明
可选：模块层级的功能映射

优先使用简洁精准的说明（短列表、最少化散文式描述），深度内容可链接到对应文档。

Inputs to ask for (if missing)

需要询问的输入项（信息缺失时）

Is this a monorepo (multiple independently-built modules) or a single project?
Repo layout: where backend, frontend, docs, infra live; list the major modules/subprojects.
Cross-domain workflows to document (e.g., frontend calling backend API, auth flow, shared types, local dev).
If you want feature maps: top 5-15 user-facing features (names) and which module owns them.
Any rules about MCP usage to capture in root AGENTS.md (allowed servers/tools, safety constraints).
Any hard rules (do not touch X, required commands, style rules).

当前是monorepo（包含多个可独立构建的模块）还是单项目？
仓库结构：后端、前端、文档、基础设施的存放位置；列出主要模块/子项目。
需要记录的跨域工作流（例如前端调用后端API、鉴权流程、共享类型、本地开发流程）。
如果需要功能映射：排名前5-15的面向用户功能（名称）以及所属的模块。
需要记录在根目录AGENTS.md中的MCP使用规则（允许的服务/工具、安全约束）。
所有硬性规则（禁止修改的内容、必须执行的命令、风格规范）。

Where to put AGENTS.md (heuristics)

AGENTS.md存放位置（参考规则）

Create AGENTS.md at:

repo root (global rules + module map + cross-domain workflows)
each major component/module root (e.g.,
```
backend/
```
,
```
frontend/
```
,
```
docs/
```
,
```
infra/
```
)
any subdirectory that has different conventions, ownership, or high risk (payments, auth, data migrations)

Avoid placing AGENTS.md too deep unless there is a real boundary; too many files become noise.

在以下位置创建AGENTS.md：

仓库根目录（全局规则 + 模块映射 + 跨域工作流）
每个主要组件/模块的根目录（例如
```
backend/
```
、
```
frontend/
```
、
```
docs/
```
、
```
infra/
```
）
存在特殊约定、专属负责人或高风险的子目录（支付、鉴权、数据迁移相关目录）

避免将AGENTS.md放置在过深的层级，除非确实存在明显的边界；过多的文件反而会变成无效噪音。

Workflow (checklist)

工作流（检查清单）

Inventory the repo
- List top-level directories and build files (Gradle/Maven, Node/Next, docs site).
- Identify the natural "component roots" and any critical submodules.
Draft root
```
AGENTS.md
```
- State global rules only (things that apply everywhere).
- If monorepo: add a module/subproject map (not a feature map) and links to each nested AGENTS.md.
- Keep tech-specific instructions out of root; push them into the owning module's AGENTS.md.
- Docs: do not open/read
```
docs/
```
  by default; consult only when asked or required.
- Add cross-domain workflows (how modules connect): frontend <-> backend API, auth/session, contract location (OpenAPI/GraphQL), "run together" local dev.
- Add cross-repo verification guidance: where to run per module + prereqs; quiet first run; re-run narrowed failures with verbose logs when debugging.
Draft nested AGENTS.md per component
- Put tech-specific instructions in the module that owns them:
  - Backend: how to run, test, migrate DB; key modules and entrypoints.
  - Frontend: how to run, build, test; env vars; key routes/areas.
  - Docs: docs structure, where to add ADRs/runbooks, how to preview/build docs.
Build maps (as needed)
- If monorepo: module map goes in root (use
```
references/module-map-format.md
```
  ).
- Feature maps should live in the owning module AGENTS.md (use
```
references/feature-map-format.md
```
  ).
Verify consistency
- Ensure guidance does not conflict between parent/child scopes.
- Keep each AGENTS.md short and actionable; move long detail into docs under
```
docs/
```
  .

盘点仓库
- 列出顶级目录和构建文件（Gradle/Maven、Node/Next、文档站点）。
- 识别天然的“组件根目录”和所有关键子模块。
编写根目录
```
AGENTS.md
```
- 仅记录全局规则（适用于所有场景的规则）。
- 如果是monorepo：添加模块/子项目映射（不是功能映射）以及指向每个嵌套AGENTS.md的链接。
- 根目录不要放置技术专属说明，将这类内容放到对应所属模块的AGENTS.md中。
- 文档相关规则：默认不要打开/读取
```
docs/
```
  目录内容，仅在用户要求或必要时查阅。
- 添加跨域工作流（模块之间的连接方式）：前端 <-> 后端API、鉴权/会话、契约存放位置（OpenAPI/GraphQL）、“联动运行”本地开发流程。
- 添加跨仓库校验指引：各模块的运行位置 + 前置依赖；首次运行使用静默模式；调试时使用详细日志重新运行缩小范围后的失败项。
为每个组件编写嵌套AGENTS.md
- 将技术专属说明放到对应所属的模块中：
  - 后端：运行、测试、数据库迁移方式；核心模块和入口点。
  - 前端：运行、构建、测试方式；环境变量；核心路由/功能区域。
  - 文档：文档结构、ADR/运行手册的添加位置、预览/构建文档的方式。
构建映射（按需）
- 如果是monorepo：模块映射放在根目录（使用
```
references/module-map-format.md
```
  模板）。
- 功能映射应该存放在所属模块的AGENTS.md中（使用
```
references/feature-map-format.md
```
  模板）。
校验一致性
- 确保父子层级的指引不存在冲突。
- 保持每个AGENTS.md简短、可执行；将冗长的细节移到
```
docs/
```
  目录下的文档中。

Templates

模板

Use these templates:

Root + module AGENTS.md:
```
references/agents-template.md
```
Module map format:
```
references/module-map-format.md
```
Feature map table format (per module):
```
references/feature-map-format.md
```
Suggested
```
docs/
```
layout (Spring + Next):
```
references/docs-structure.md
```

使用以下模板：

根目录+模块AGENTS.md：
```
references/agents-template.md
```
模块映射格式：
```
references/module-map-format.md
```
功能映射表格格式（每个模块）：
```
references/feature-map-format.md
```
推荐的
```
docs/
```
目录结构（Spring + Next）：
```
references/docs-structure.md
```

Deliverable

交付物

Provide:

Root
```
AGENTS.md
```
(if requested) with module map and cross-domain workflows.
Nested
```
AGENTS.md
```
per component/module with tech-specific guidance.
Optional feature map tables per module (if requested).
A list of files created/updated and any open questions.

提供：

根目录
```
AGENTS.md
```
（如果有要求），包含模块映射和跨域工作流。
每个组件/模块的嵌套
```
AGENTS.md
```
，包含技术专属指引。
可选的每个模块的功能映射表格（如果有要求）。
创建/更新的文件列表以及所有未解决的问题。