AGENTS.md
AGENTS.md is a conventional document file placed in the root directory of open-source software projects. It is used to declare interaction rules, contribution norms, and operational constraints to AI coding assistants or automated agents. Its core function is to provide AI agents with project context guidance and specify the boundaries of permitted and prohibited operations, ensuring that automated tools conform to project maintainers' expected behavioral standards when participating in code generation, review, or modification.
Core Facts
AGENTS.md is a common naming convention that has emerged in the AI programming tools ecosystem, and tools such as OpenAI Codex and Cursor also recognize this file to varying degrees.
AGENTS.md是一种新兴实践，开发者通过在项目根目录放置Markdown文件向AI编码代理传达编码规范、架构偏好和工作流程要求
Typical AGENTS.md content includes a project architecture overview, a list of core files that must not be modified, test run commands, code style conventions, and change approval processes.
Timeline (last 90 days)
Huntley believes AGENTS.md still has value as background description, but it should not be used as a constraint; constraints need determinism, while descriptions can be vague.
The problem with AGENTS.md has the same origin as the system prompt: the model may not read it, may forget it after reading it, and after forgetting may still act according to its default habits from training, so its effectiveness is probabilistic.
AGENTS.md is a convention file placed in Markdown form at the repository root or in subdirectories, used to describe to the agent the project structure, coding standards, common commands, and prohibited matters.
Huntley believes that continuously adding rules to AGENTS.md cannot constrain agent behavior, because a gap always exists between the rules and the agent's actual behavior and will widen as the codebase evolves.
Files such as AGENTS.md represent a simple way of configuring an Agent, describing the Agent's capability boundaries and behavioral norms in natural language; it is sufficient for personal projects or small teams, but far from sufficient in an enterprise environment.
OpenCode V2 only reads AGENTS.md and is completely incompatible with CLAUDE.md; even putting CLAUDE.md into the instructions setting will not cause it to be loaded.
A shadowed AGENTS.md refers to a same-named rules file in a subdirectory that may override or block the parent file due to path resolution order, causing the intended rules to never be read.
By applying community-verified specification templates (such as .cursorrules or AGENTS.md), common issues such as inconsistent AI-generated styles, inconsistent technology choices, or missing security boundaries can be avoided.
Maintainer cliffhall promoted an 'Agentic Software Factory' engineering system, using AGENTS.md as the absolute rules file and removing the old CLAUDE.md.
Codex adopts the SDD (Specification-Driven Development) philosophy, establishing structured inputs through AGENTS.md and skill documents.
40 more timeline events
All Facts (20)
AGENTS.md is a common naming convention that has emerged in the AI programming tools ecosystem, and tools such as OpenAI Codex and Cursor also recognize this file to varying degrees.
80%VerifiedAGENTS.md是一种新兴实践，开发者通过在项目根目录放置Markdown文件向AI编码代理传达编码规范、架构偏好和工作流程要求
70%VerifiedTypical AGENTS.md content includes a project architecture overview, a list of core files that must not be modified, test run commands, code style conventions, and change approval processes.
65%Verified执行 claude -v 可查看 Claude Code 版本，教程演示版本为 2.1.207
65%Verified优化上下文注入策略可能比更换更便宜的模型更能有效降低AI编程开支
65%VerifiedOpenAI officially integrated Codex into the ChatGPT ecosystem.
70%UnverifiedAGENTS.md类似于传统的CONTRIBUTING.md，但专门面向AI代理而非人类贡献者
85%UnverifiedAGENTS.md的实践与'上下文工程'（Context Engineering）的理念密切相关，代表了从提示工程到上下文工程的演进
85%Unverified编码规则的价值不在于让AI写出超越自身能力的代码，而在于减少探索和决策过程中的浪费
85%UnverifiedAGENTS.md是用于描述业务逻辑上下文的配置文件，包含技术栈使用方式、文件组织映射和业务逻辑说明
85%UnverifiedAGENTS.md是一种新兴的项目级AI配置文件规范，最早由Google在其内部工程实践中推广
70%Partially VerifiedWhen a CLAUDE.md file is not present in a folder, Claude automatically looks for and uses AGENTS.md as the source of project instructions.
65%UnverifiedThe concept of AGENTS.md was originally shaped by OpenAI Codex and community practices.
60%UnverifiedClaude Code's compatibility strategy is to read CLAUDE.md first and fall back to AGENTS.md when it is absent.
60%UnverifiedAn AI tool reading a context configuration file at startup is equivalent to injecting a project-level system prompt into the model before each conversation, thereby reducing low-quality modifications caused by a lack of background knowledge.
60%Unverifiedagents.md and CLAUDE.md are configuration files supported by Claude Code and similar tools; AI agents automatically read them at startup and inject them into the conversation context as system prompts.
60%UnverifiedAGENTS.md is a convention file placed in Markdown form at the repository root or in subdirectories, used to describe to the agent the project structure, coding standards, common commands, and prohibited matters.
50%UnverifiedHuntley believes that continuously adding rules to AGENTS.md cannot constrain agent behavior, because a gap always exists between the rules and the agent's actual behavior and will widen as the codebase evolves.
50%UnverifiedThe problem with AGENTS.md has the same origin as the system prompt: the model may not read it, may forget it after reading it, and after forgetting may still act according to its default habits from training, so its effectiveness is probabilistic.
50%UnverifiedHuntley believes AGENTS.md still has value as background description, but it should not be used as a constraint; constraints need determinism, while descriptions can be vague.
50%