Back to Details

create-agents-md

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create AGENTS.md

创建AGENTS.md

Guide for creating AGENTS.md files for project-specific inline rules.
为创建项目专属内嵌规则的AGENTS.md文件提供指南。

When to Use AGENTS.md

何时使用AGENTS.md

  • Small, project-specific instructions that should be committed in the repo
  • Folder-scoped rules for specific directories
  • Package-specific instructions in monorepos
  • Test-specific guidance in test directories
  • 应提交到代码仓库的小型、项目专属说明
  • 针对特定目录的文件夹级规则
  • 单体仓库中针对特定包的说明
  • 测试目录中针对测试的专属指南

When NOT to Use AGENTS.md

何时不使用AGENTS.md

  • Reusable knowledge across projects → Use skills
  • Large documentation → Use skills with references
  • Complex workflows → Use skills with scripts
  • 跨项目可复用的知识 → 使用Skills
  • 大型文档 → 使用带引用的Skills
  • 复杂工作流 → 使用带脚本的Skills

AGENTS.md Structure

AGENTS.md 文件结构

AGENTS.md is a simple markdown file without metadata:
markdown
undefined
AGENTS.md是一个无元数据的简单Markdown文件：
markdown
undefined

Project Instructions

项目说明

Code Style

代码风格

  • Use TypeScript for all new files
  • Prefer functional components in React
  • Use snake_case for database columns
  • 所有新文件均使用TypeScript
  • React中优先使用函数式组件
  • 数据库列使用snake_case命名

Architecture

架构

  • Follow the repository pattern
  • Keep business logic in service layers
undefined
  • 遵循仓库模式
  • 业务逻辑置于服务层
undefined

Location

存放位置

  • Project root: 
    AGENTS.md
    – Primary, inline instructions and references for the whole project (commands, tech stack, testing, code style, architecture, safety boundaries).
  • Subdirectories: 
    subdirectory/AGENTS.md
    – Folder- or package-scoped instructions when local behavior meaningfully diverges from the root (e.g., a specific package, service, or test tree).
  • Nested support: Agents typically combine instructions from the closest 
    AGENTS.md
    with parent ones; keep root general and use nested 
    AGENTS.md
    only where you truly need more specific rules.
  • 项目根目录：
    AGENTS.md
    —— 整个项目的主要内嵌说明和参考（命令、技术栈、测试、代码风格、架构、安全边界）。
  • 子目录：
    subdirectory/AGENTS.md
    —— 当本地行为与根目录规则存在显著差异时，使用文件夹或包级别的说明（例如特定包、服务或测试目录树）。
  • 嵌套支持：Agent通常会合并最近的
    AGENTS.md
    与上级的说明；根目录文件保持通用，仅在确实需要更具体规则时使用嵌套的
    AGENTS.md
    。

Best Practices

最佳实践

  • Keep AGENTS.md files small and focused
  • Use for project-specific conventions
  • Prefer short, concrete references over long prose:
    • Link to project docs, specs, and runbooks
    • Point to example files or directories (e.g., 
      see src/api/users.ts for canonical pattern
      )
    • Include the most important commands with exact CLI invocations
  • Reference existing code examples when possible
  • Update as project evolves
  • 保持AGENTS.md文件精简且聚焦
  • 用于记录项目专属约定
  • 优先使用简短、具体的参考内容而非冗长文字：
    • 链接到项目文档、规格说明和运行手册
    • 指向示例文件或目录（例如：
      参见src/api/users.ts获取标准范式
      ）
    • 包含最重要的命令及其完整CLI调用方式
  • 尽可能参考现有代码示例
  • 随项目演进更新内容

References

参考资料

For detailed best practices, see 
references/best-practices.md
.
如需详细最佳实践，请参阅
references/best-practices.md
。