The `AGENTS.md` file serves as a crucial guide for AI coding agents, providing context and instructions for effective code generation and modification. Best practices for creating and utilizing `AGENTS.md` include: - **Placement and Structure:** - Create `AGENTS.md` at the root of your repository for easy discoverability by agents. - For large monorepos, consider nesting `AGENTS.md` files within subprojects, with the closest file taking precedence for specific instructions. - Use standard Markdown formatting and headings to organize information clearly and logically. - **Comprehensive Context:** - **Project Overview:** Briefly describe the project's purpose, key technologies, and overall architecture. - **Coding Conventions:** Document coding standards, style guidelines, naming conventions, and other practices to ensure generated code integrates seamlessly. - **Build and Test Instructions:** Provide clear commands for building the project, running tests, and any specific testing frameworks or requirements. Include commands for linting. - **Architecture and Design Patterns:** Outline specific design patterns (e.g., MVC, microservices), architectural principles, or frameworks used (e.g., Redux for state management). - **Dependencies and Environment:** Mention crucial dependencies, environment setup tips, and any known quirks or limitations the agent should be aware of. - **Specific Guidelines and Constraints:** - **"Dos" and "Don'ts":** Explicitly list preferred practices and things to avoid. For example, "use MUI v3" or "do not hardcode colors." This can be refined iteratively based on agent output. - **PR Guidelines:** Include instructions for Pull Request messages, formatting, and required information for collaborative environments. - **Security Considerations:** Outline any security concerns or best practices relevant to the project. - **Actionable Information:** - Focus on providing actionable information that directly guides the agent's work. - Include commands for running tests or linters, as agents can execute these and fix failures before completing tasks. - **Maintainability and Iteration:** - Treat `AGENTS.md` as living documentation, updating it as the project evolves or new guidelines emerge. - Refine the content based on the agent's performance and the quality of its generated code. By following these best practices, you can create a robust `AGENTS.md` file that significantly enhances the effectiveness and efficiency of AI coding agents.