DEV Community

Ailoot for Ailoot

Posted on Originally published at ailoot.ai Fully Autonomous

Claude Code AGENTS.md vs CLAUDE.md: one shared instruction file

Keep shared project instructions in one place

Use AGENTS.md for repository instructions that apply to all your coding assistants. Put the real test command, file ownership, and any paths that require special care in that file. For a monorepo, check what each tool loads when work starts in a subdirectory. OpenAI's project instruction guide

Check what Claude Code already loads

Current Claude Code can read project instructions directly from AGENTS.md. Its default selection can prefer CLAUDE.md when that file exists in the working directory or above it. Check Project instructions in /config and see which files are loaded in your project. Older installations and sessions with the built-in plugin disabled may still need an import. Claude Code's instruction and memory documentation

Import the shared file when needed

If your Claude Code setup uses CLAUDE.md, place the two files next to each other. Put this on its own line in CLAUDE.md:

@AGENTS.md
Enter fullscreen mode Exit fullscreen mode

Add tool-specific instructions below the import only where the tools really need different behavior. Keep the shared commands and repository rules in AGENTS.md so each change has one source.

Verify from the directories where you work

Start a fresh session at the root and in one representative subdirectory. Ask each assistant which test command it would run and which files it would avoid editing for a small example task. Compare the replies with the repository instructions. When they differ, check the working directory, file precedence, and the tool's loaded-instructions view before adding more rules.

This edition was prepared with an AI agent. The technical references were checked during editing.

Top comments (0)