How Many Tools Should an MCP Server Expose?
If you are building a server for the Model Context Protocol (MCP), the right number of tools depends on what a client…
Categories
How to Share Project Instructions Across Claude Code, Codex, and Cursor
When you use Claude Code, Codex, and Cursor on the same code repository, each tool needs the same basic information: how to build and test the code. It also needs to know where important parts are and which changes to avoid. Each tool can read project instruction files: Markdown documents that guide AI coding tools as they work.
Start by putting guidance that applies to all three tools in an AGENTS.md file at the repository’s top level. Add a short CLAUDE.md only if Claude Code’s configuration needs that file to load the shared instructions. This avoids copying the same instructions into multiple files, but the tools do not all find or use instruction files the same way. Check which files each tool loads.
Keep shared guidance in AGENTS.md
The AGENTS.md project describes a plain Markdown format with no required fields or set headings. Use the file to keep guidance that applies across tools, such as project commands and coding conventions. It should also point agents to key parts of the code and set specific limits on what they should change.
For example, a root file might look like this:
# Project instructions
## Project
Describe the main components and where to find them.
## Commands
- Build: provide the project's build command.
- Test: provide the relevant test command.
- Lint: provide the project's lint command.
## Conventions
Record project-specific choices that affect code changes.
## Safety boundaries
Identify files that should not be edited and actions that require approval.Replace the descriptions with accurate details about the repository. Give enough detail to guide a code change. “Run the relevant tests” gives less direction than naming the test command and the code it covers.
Markdown instructions give an agent context, but they do not control its permissions or stop it from taking an action. Use permissions, hooks, tests, or other technical controls to enforce a rule.
Add CLAUDE.md only when Claude Code needs it
Claude Code uses CLAUDE.md for project instructions and can import other files. A short file can point Claude Code to the shared instructions:
@AGENTS.mdAnthropic documents this import syntax and explains how Claude Code can load AGENTS.md through its Project instructions setting in the memory documentation. If the setting already loads the root AGENTS.md, you do not need a separate wrapper. Check the setting and confirm Claude Code loads the shared guidance before keeping two copies.
Put Claude-specific guidance in CLAUDE.md and avoid repeating shared rules there. Anthropic’s Claude context guidance recommends keeping instructions concise and up to date. Anthropic’s advice covers CLAUDE.md and sets no file-size limit for all three tools.
Check how each tool finds instructions
The tools do not handle a shared filename the same way. Each has its own rules for finding files, using instructions in subdirectories, and combining guidance.
| Tool | What the documented behavior supports | What to verify |
|---|---|---|
| Codex | The Codex prompting guide describes Codex CLI discovering instruction files along the path from its home directory through the repository to the working directory. | Check the documentation for the installed version before relying on a particular precedence or override rule. |
| Cursor | Cursor’s Rules documentation describes root-level AGENTS.md as a plain-Markdown option for project instructions, alongside Project Rules in .cursor/rules. |
The page describes AGENTS.md as root-only and says nested support was planned. Verify current behavior before depending on nested files. |
| Claude Code | Claude Code documents CLAUDE.md, imports, and AGENTS.md through its Project instructions setting. |
Check the setting and confirm which files the current configuration loads. |
To make the setup work across the tools, keep essential shared instructions at the repository root until you have tested nested files with the versions and settings you use. Add Cursor Project Rules when you need Cursor-specific behavior or limits on where instructions apply.
Keep instructions useful and current
Write down details an agent cannot reliably work out from the code. Include the actual build, test, and lint commands. Add a short guide to the main parts of the code, and spell out specific limits, such as generated files that should not be edited. For tasks that need more detail, point to the relevant project document instead of asking agents to read every document for every change.
Update the instructions when commands, conventions, or project structure change. Remove outdated guidance and check that AGENTS.md, CLAUDE.md, and Cursor rules do not conflict. One shared source helps keep the guidance consistent. A short compatibility file lets a tool load it when its configuration requires one.
What I'm buildingDelegate tasks. Get software.
Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.
Take a look at vroni.com