Claude Code: Does It Use Intent.md for Project Setup?

Yes, Claude Code can use an intent.md file to create project instructions, but it is not automatic—you have to explicitly tell it to read that file, and the file itself must be written in a way Claude Code understands. In practice, most users rely on CLAUDE.md as the standard instruction file, while intent.md is a newer, more structured alternative that some teams adopt for better consistency.

What Is intent.md and How Does It Differ from CLAUDE.md?

CLAUDE.md is the conventional memory file for Claude Code. When you place it in your project root (or in ~/.claude/ for global settings), Claude Code automatically reads it at the start of every session. It contains free-form instructions, coding style preferences, and project-specific context.

intent.md is a proposed convention that aims to make those instructions more explicit and machine-readable. Instead of a loose paragraph like “Use async/await and avoid callbacks,” an intent.md file might list specific rules in a structured format, such as YAML or markdown tables, with clear “do” and “don’t” sections. The idea is that a structured file is easier for Claude Code to parse consistently, reducing ambiguity and improving adherence to your preferences.

However, as of now, Claude Code does not automatically detect intent.md. You must either rename it to CLAUDE.md or explicitly reference it in your session, for example by typing “Read intent.md and follow its instructions.” Some teams use a hybrid approach: they keep CLAUDE.md for general context and intent.md for detailed, structured rules, then tell Claude Code to read both at the start of each session.

How to Make Claude Code Use intent.md

If you want to use intent.md as your instruction file, you have a few practical options:

• Rename it: Simply rename intent.md to CLAUDE.md in your project root. This is the simplest way to ensure it is loaded automatically.
• Symlink or copy: Create a symlink from CLAUDE.md to intent.md, or copy the content. This works if you want to keep the filename intent.md for other tools but still have Claude Code read it.
• Explicitly reference it: At the start of each session, type something like “Read intent.md and follow all instructions in it.” This works but requires repeating the command each session.
• Use a startup script: Some users create a shell alias or a script that launches Claude Code with a preloaded prompt that includes the contents of intent.md.

The most robust approach is to keep CLAUDE.md as the primary file and put a short note in it that says “Also read intent.md for detailed rules.” Then Claude Code will automatically read CLAUDE.md and, following your instruction, also read intent.md.

Why Use intent.md Instead of Just CLAUDE.md?

The main reason to use intent.md is to separate high-level project goals from detailed coding conventions. CLAUDE.md can become bloated with everything from “use tabs for indentation” to “the API key is in .env.” By splitting these into a concise CLAUDE.md (what the project is, key commands) and a detailed intent.md (style rules, testing requirements, architectural patterns), you make both easier to maintain.

Another benefit is that intent.md can be shared across different AI coding tools. While CLAUDE.md is specific to Claude Code, intent.md is a more generic name that other tools might recognize in the future. For teams that use multiple AI assistants, having a single structured instruction file can be more portable.

However, this portability is not yet standard. As of now, only CLAUDE.md is officially documented as the memory file for Claude Code. intent.md is a community convention that is gaining traction but has no official support.

Common Problems and Misconceptions

A frequent misconception is that Claude Code will read any markdown file in the root. It does not. Only CLAUDE.md (in the project root or ~/.claude/) is read automatically. Other files like intent.md, AGENTS.md, or PROJECT.md are ignored unless you explicitly ask Claude Code to read them.

Another issue is that users write intent.md in a highly structured format that Claude Code does not fully understand. For example, using YAML with complex nested objects might be parsed incorrectly. The safest approach is to write instructions in plain, simple markdown with short sentences and bullet points. Claude Code is good at following natural language, so overly complex structures can backfire.

A common mistake is forgetting to update intent.md when project conventions change. Because it is not automatically loaded, you might think you updated the instructions, but Claude Code is still using an old cached version. Always check that your session actually loaded the latest content.

How to Choose Between intent.md and CLAUDE.md

The choice depends on your workflow and team preferences:

• Use CLAUDE.md alone if you are the only developer or if you want zero extra steps. It is the official, supported method.
• Use both files if you have a large project with many rules. Keep CLAUDE.md short (what the project is, how to run tests) and put the detailed style guide in intent.md.
• Use intent.md alone if you prefer a structured format and are willing to rename or symlink it to CLAUDE.md. This gives you the structured benefits while keeping automatic loading.

For teams, the most effective pattern is to have a CLAUDE.md that includes a pointer to intent.md. That way, every developer gets consistent behavior without needing to remember to manually load the file.

Best Practices for Writing Effective Instructions

Whether you use intent.md or CLAUDE.md, the quality of your instructions matters more than the filename. Here are practical tips:

• Be specific: Instead of “Write clean code,” say “Use descriptive variable names, keep functions under 20 lines, and add JSDoc comments to all exported functions.”
• Use examples: Show a good and bad example for style rules. For instance, “Use single quotes in JavaScript, not double quotes. Example: const name = 'John'.”
• Prioritize: Put the most important rules first. Claude Code tends to follow instructions in order, so putting critical constraints at the top reduces the chance of them being overlooked.
• Keep it updated: Review the file whenever you change your coding style or project structure. Outdated instructions can cause more harm than no instructions.
• Test it: After writing or updating your instruction file, start a new Claude Code session and ask it to summarize the key rules. This verifies that it parsed the file correctly.

Frequently Asked Questions

Does Claude Code automatically read intent.md?

No, it does not. Only CLAUDE.md is read automatically. To use intent.md, you must rename it, symlink it, or explicitly tell Claude Code to read it each session.

Can I have both CLAUDE.md and intent.md in the same project?

Yes, you can. Claude Code will read CLAUDE.md automatically. If you want it to also read intent.md, add a line in CLAUDE.md like “Read intent.md for detailed coding rules.”

What is the best format for intent.md?

Plain markdown with short bullet points and clear headings works best. Avoid complex YAML or JSON structures, as Claude Code may not parse them reliably. Use simple language and concrete examples.

Does intent.md work with other AI tools like GitHub Copilot?

Not automatically. intent.md is a community convention, not a standard. Other tools have their own instruction files, such as AGENTS.md for some agents. You would need to adapt the content for each tool.

What happens if I have both CLAUDE.md and intent.md but they conflict?

Claude Code will follow CLAUDE.md first, since it is loaded automatically. If you explicitly ask it to read intent.md later, the later instructions may override earlier ones. To avoid confusion, keep them consistent or use one as the source of truth.

Is intent.md a replacement for CLAUDE.md?

It can be, if you rename it. But the official memory file is CLAUDE.md. intent.md is just a filename convention; the content is what matters.

Related

• Prompt Engineering Best Practices for Better AI Outputs
• Long-Haul AI Agents: Runtime Essentials
• Don’t Starve Together: Survive Your First Winter