agents-md

AGENTS.md 构建器

目标

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

• 根目录：跨领域指导和模块映射（适用于单体仓库）
• 嵌套目录：各组件/模块的技术专属说明
• 可选：模块级功能映射

指导应简洁明确（使用简短项目符号，尽量少写说明文字）。详细内容请链接到文档。

需要询问的输入（如缺失）

• 这是一个单体仓库（包含多个独立构建的模块），还是单个项目？
• 仓库布局：后端、前端、文档、基础设施分别位于何处；列出主要模块/子项目。
• 需要记录哪些跨领域工作流（例如，前端调用后端 API、认证流程、共享类型、本地开发）。
• 如果需要功能映射：列出排名前 5-15 的面向用户功能（名称）及其所属模块。
• 是否有需要记录在根目录 AGENTS.md 中的 MCP 使用规则（允许使用的服务/工具、安全限制）。
• 是否有硬性规则（禁止修改的内容、必需命令、代码风格规则）。

AGENTS.md 的放置位置（启发式规则）

在以下位置创建 AGENTS.md：

• 仓库根目录（全局规则、模块映射和跨领域工作流）
• 每个主要组件/模块的根目录（例如，backend/、frontend/、docs/、infra/）
• 约定、所有权或风险程度不同的任何子目录（支付、认证、数据迁移）

除非存在明确的边界，否则避免将 AGENTS.md 放得太深；文件过多会造成干扰。

工作流（检查清单）

1. 清点仓库
   • 列出顶层目录和构建文件（Gradle/Maven、Node/Next、文档站点）。
   • 找出自然的“组件根目录”和关键子模块。
2. 起草根目录 AGENTS.md
   • 只说明全局规则（适用于所有位置的规则）。
   • 如果是单体仓库：添加模块/子项目映射（而非功能映射），并链接到各嵌套 AGENTS.md。
   • 不要将技术专属说明放在根目录；应将其放入所属模块的 AGENTS.md。
   • 文档：默认不要打开/读取 docs/；只有在被要求或确有必要时才查阅。
   • 添加跨领域工作流（模块之间的连接方式）：前端 <-> 后端 API、认证/会话、契约位置（OpenAPI/GraphQL）、本地开发时如何“一起运行”。
   • 添加跨仓库验证指南：各模块的运行位置及前置条件；首次运行保持安静；调试时针对失败项缩小范围并使用详细日志重新运行。
3. 为各组件起草嵌套 AGENTS.md
   • 将技术专属说明放在所属模块中：
     • 后端：如何运行、测试、迁移数据库；关键模块和入口点。
     • 前端：如何运行、构建、测试；环境变量；关键路由/区域。
     • 文档：文档结构、添加 ADR/操作手册的位置，以及如何预览/构建文档。
4. 按需构建映射
   • 如果是单体仓库：模块映射放在根目录（使用 references/module-map-format.md）。
   • 功能映射应放在所属模块的 AGENTS.md 中（使用 references/feature-map-format.md）。
5. 验证一致性
   • 确保指导在父级和子级范围之间不存在冲突。
   • 保持每个 AGENTS.md 简短且便于执行；将较长的细节移至 docs/ 下的文档中。

模板

使用以下模板：

• 根目录和模块 AGENTS.md：references/agents-template.md
• 模块映射格式：references/module-map-format.md
• 功能映射表格式（按模块）：references/feature-map-format.md
• 建议的 docs/ 布局（Spring + Next）：references/docs-structure.md

交付内容

提供：

• 根目录 AGENTS.md（如有要求），包含模块映射和跨领域工作流。
• 各组件/模块的嵌套 AGENTS.md，包含技术专属指导。
• 各模块的可选功能映射表（如有要求）。
• 已创建/更新文件列表及任何待解决问题。