Fix
CLAUDE.md vs AGENTS.md for Claude Code
Answer
Claude Code reads CLAUDE.md files, including a nested CLAUDE.md in a subfolder, and .claude/rules/. It does not read AGENTS.md on its own, root or nested. Put stack-specific rules in a nested CLAUDE.md in that subfolder or .claude/rules/, not a second copy of the root CLAUDE.md. If you want one shared file, CLAUDE.md can import it with an @AGENTS.md line. Put AGENTS.md in the project root for agents that read it, including Codex and Cursor.
- Scope Tool-agnostic. Written against Cursor project rules (.mdc), Claude Code CLAUDE.md, AGENTS.md, and GitHub Copilot repository instructions as documented on 2026-10-15.
Last verified 2026-10-15
Agents still paste one long CLAUDE.md, or they drop a nested AGENTS.md and expect Claude Code to read it. The Vibe Coder Starter pack is the tool-agnostic file set. Its pinned scope is: Tool-agnostic. Written against Cursor project rules (.mdc), Claude Code CLAUDE.md, AGENTS.md, and GitHub Copilot repository instructions as documented on 2026-10-15. Claude Code reads CLAUDE.md in the project root as project memory on the next session. It also reads a nested CLAUDE.md in a subfolder, and markdown files in .claude/rules/. Copy CLAUDE.md into the project root.
Keep this file short. Put stack-specific rules in a nested CLAUDE.md in that subfolder or .claude/rules/, not a second copy of this file. Claude Code does not read AGENTS.md on its own, root or nested. If you want one shared file, import it with an @AGENTS.md line. Those lines are in the pack's CLAUDE.md. They are not repeated in AGENTS.md, the Cursor .mdc rule, or the Copilot instructions. A nested AGENTS.md does not replace the root CLAUDE.md.
Put AGENTS.md in the project root for agents that read AGENTS.md, including Codex and Cursor. That root file is the shared rule set in this pack. Claude Code uses it when CLAUDE.md imports it with an @AGENTS.md line. Cursor project rules in this pack are .mdc files in .cursor/rules, with description, globs, and alwaysApply frontmatter. A plain .md file in that directory is ignored. That trap is /fixes/cursor-mdc-rule-frontmatter. GitHub Copilot reads .github/copilot-instructions.md.
Do not spawn extra agents for a one-file edit. Use them only when the user asked for parallel work. That line is also only in the pack's CLAUDE.md. The shared rules still apply in every format. Never read, print, or commit secrets: .env, .env.* (except *.example), keys, tokens, or credential files. Do not run git commit, git push, git reset, or force-push unless the user asked for that exact action.
Last verified 2026-10-15. doc-verified.
Vibe Coder Starter pack — Safe defaults for any AI coding agent, in any stack.
doc-verified
Sources in the pack
Questions
- What is the difference between CLAUDE.md and AGENTS.md?
- Claude Code reads CLAUDE.md files, including a nested CLAUDE.md in a subfolder, and .claude/rules/. It does not read AGENTS.md on its own, root or nested. Put stack-specific rules in a nested CLAUDE.md in that subfolder or .claude/rules/, not a second copy of the root CLAUDE.md. If you want one shared file, CLAUDE.md can import it with an @AGENTS.md line. Put AGENTS.md in the project root for agents that read it, including Codex and Cursor.
- Where do stack-specific Claude Code rules go?
- Put stack-specific rules in a nested CLAUDE.md in that subfolder or .claude/rules/. Claude Code reads those files. It does not read AGENTS.md on its own, root or nested. If you want one shared file, CLAUDE.md can import it with an @AGENTS.md line.
- Does a root AGENTS.md replace CLAUDE.md?
- No. Claude Code does not read AGENTS.md on its own, root or nested. Put AGENTS.md in the project root for agents that read it, including Codex and Cursor. If you want one shared file, CLAUDE.md can import it with an @AGENTS.md line.
- When was this Claude Code file rule last checked?
- Last verified 2026-10-15. doc-verified.