{
  "id": 226640,
  "title": "CLAUDE.md and AGENTS.md in the same project - how to avoid maintaining two files",
  "url": "https://urgent.news/2026/08/06/claude-md-and-agents-md-in-the-same-project-how-to-avoid-maintaining",
  "topic": "culture",
  "section": "Culture",
  "published": "2026-08-06T16:04:57.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/hassekf/claudemd-and-agentsmd-in-the-same-project-how-to-avoid-maintaining-two-files-4k9"
  },
  "original_language": "en",
  "account": "Two files, CLAUDE.md and AGENTS.md, appeared in the same project containing conflicting information about how to work with the code. This situation arose due to agents following different instructions from each file. The primary issue was that the AIs did not consistently adhere to the same set of rules, which led to errors and confusion. When adding new guidelines to one file, the other file was often ignored, leading to mistakes and wasted time.\n\nTo avoid duplicating instructions, a three-line AGENTS.md file can be created that points to the primary file, CLAUDE.md. Both tools read the repository files on demand, so when the AGENTS.md file is pointed to CLAUDE.md, the AI agent will follow the instructions from that file. This approach simplifies the process, as there is only one place to edit the project instructions, eliminating the need to decide which of the two files is correct.\n\nFor teams using Unix systems, a symbolic link (symlink) can be used for the leanest option by running `ln -s CLAUDE.md AGENTS.md`. However, on Windows, symlinks may require special configuration due to permissions, potentially causing the file to become a one-line text path that could be misinterpreted by AI agents. Instead, a text pointer file is recommended, as it does not carry the risks associated with symlinks on Windows.\n\nThe content of the primary file should focus on key aspects that impact outcomes, such as what should not be edited and the commands necessary to complete tasks. Providing clear instructions on how to isolate work, especially when multiple agents are involved, is crucial to prevent conflicts and ensure all agents are working with the most up-to-date information.\n\nIn cases where the rules genuinely differ between tools, it is acceptable to have separate files, but the shared rules should be pointed to in one location, with any tool-specific instructions added below it. To confirm that both files are being read correctly, ask the AI agent directly which instructions it is following. This practice simplifies the process and helps prevent potential errors caused by misreading the wrong file.",
  "summary": "I spent two weeks with a CLAUDE.md and an AGENTS.md saying different things about the same repository. I found out the worst way: an agent did exactly what the rule forbade, and the rule was there. In the other file. (abertura sugerida: confira se bate com a sua memória e ajuste para a sua voz antes de postar) Claude Code reads CLAUDE.md . Codex reads AGENTS.md . Use both in one project and you…",
  "key_points": [],
  "editors_take": "Pointing one file to another eliminates duplicated instructions, allowing edits in a single location and reducing errors from conflicting information, especially when using AI agents that read repository files on demand.",
  "illustration": "https://urgent.news/ill/226640.png",
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}