CLAUDE.md and AGENTS.md: Optimizing AI Code with Precision

The CLAUDE.md and AGENTS.md files have become essential tools for improving the quality of code generated by AI agents. The AGENTS.md file, launched by OpenAI, has now become an almost universal standard adopted by most code agents on the market, such as Codex, Cursor, Aider, Jules, and Factory. These files allow for the adaptation of the produced code to the specific needs of each project by defining precise coding standards.

For users of Claude Code, the CLAUDE.md file is indispensable. It should be written in natural language, concise and structured, to avoid overwhelming the agent with unnecessary information. The guidelines should be general and applicable to the entire project, while specific rules should be reserved for nested files at the relevant subfolder levels. Although these recommendations primarily apply to CLAUDE.md, they are also valid for AGENTS.md.

Anthropic, the publisher of Claude Code, emphasizes the importance of writing precise and unambiguous instructions. If certain directives are not followed, it may be due to a file that is too long or poorly formulated instructions. It is advisable to use emphasis markers to prioritize critical instructions, such as "VERY IMPORTANT". Additionally, CLAUDE.md should be treated like code: modify, test, and iterate to achieve the best results.

Instructions to Avoid and Include

It is crucial to avoid instructions that Claude can deduce on its own, such as standard coding conventions or details of a well-documented API. Information that is likely to change during the project should also be avoided to prevent it from becoming outdated. Notably, avoid purely rhetorical prescriptive formulations such as "Write clean code" or "make no mistakes."

On the other hand, the CLAUDE.md file should include directives that the AI cannot guess, such as specific bash commands, company-specific coding conventions, or internal security requirements. Also mention the development environment if it is atypical, and add instructions to correct recurring errors from Claude.

Finally, CLAUDE.md can contain references to local files or online resources, allowing Claude to consult internal documentation before each conversation.

Practical Tips

To maximize the effectiveness of CLAUDE.md, it is recommended to include elements such as the graphic charter, documentation choices, and the development of unit tests and UX. An audit by sub-agents of the produced structural code is also advisable, as well as version management practices for personal projects.

This model should be adapted to the specific needs of each project, and it is important to review it regularly, especially during model version changes at Anthropic. Context engineering and prompt engineering are key skills to make the most of Claude Code.