Your first repo-shaped setup, start to finish

In Claude Code

A two-file setup is when you create AGENTS.md and put there everything that is common to all agents, and then for each agent create a file like CLAUDE.md and import the content of AGENTS.md:

@AGENTS.md

And add Claude-specific things after this line. This is how CLAUDE.md may look like for example:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

The import paths are resolved relative to the file they appear in, and you can nest up to 4 levels. If you use backticks around the path it's not treated as an import and instead you can refer to AGENTS.md from the content of CLAUDE.md without importing it. Alternatively, if you don't want to have any Claude-specific things in CLAUDE.md you can create a symlink pointing from this file to AGENTS.md with ln -s AGENTS.md CLAUDE.md (on Windows you might need Admin rights or Developer Mode enabled, import is more universal).

Proving it loaded. To check if everything works as intended you can run /context and make sure that there's an entry called CLAUDE.md under Memory files. That's how the docs describe it: "To confirm the file loaded, run /context in a session and check the list under Memory files."

Just to clarify — /memory is something different, listing all possible locations of memory files (including ones that haven't been created yet).

The gotcha. If you use a two-file setup, discovery mechanism looks for the CLAUDE.md file upwards starting from the directory from which you launched the app. So if you were to create packages/api/CLAUDE.md it would be ignored until you either open some file in that directory using the Read tool or you run the app from there (files from parent directories get loaded in full at launch, and files from subdirectories don't — the docs say they load on a Read, "not at launch and not when writing or creating files there."). In other words, if you create packages/api/CLAUDE.md and it seems like it's not working, it probably works exactly as described and you just haven't triggered it.

The last thing to keep in mind is that importing a file doesn't change anything in terms of memory usage, as all imported files get loaded anyway when you launch the app. And the 200-line figure mentioned in the docs is about adhering to the instructions, not about the actual length of CLAUDE.md — everything that's there will be loaded anyway.

In Codex CLI

One AGENTS.md at the repo's root, zero setup, read by Codex before any task is being run.

How it finds and combines files: starts at the ~/.codex directory (configurable via CODEX_HOME env var), then traverses from the project's root down to the current working directory appending contents of every file on the way. The project's root is a closest ancestor directory containing .git (customizable by project_root_markers config option). No more than one file per directory, AGENTS.override.md has precedence over AGENTS.md so if you have an outdated one it will hide AGENTS.md without warning.

To make sure it was loaded: you can't run the /context command so the best verification is to ask about the repo's canary (reply with UNKNOWN if it's not known, single word, no tools usage).

codex exec "What is the canary for this repo? If you do not know, reply exactly: UNKNOWN. Reply with one word and do not use any tools."

Alternatively you can enable logging in a directory by using a config flag and have a look at the TUI log file.

codex -c log_dir=./.codex-log

then read ./.codex-log/codex-tui.log.

The trap: there's a 32 KiB limit for the instruction which is defined by project_doc_max_bytes config option, set for the entire chain of concatenated files (not per file). It gets cut when the limit is reached, with no visible signal — the source comment says larger files are "silently truncated". If there's no more room for the instruction, remaining files are dropped. Dropped files are the deepest and most context-specific ones, which are the closest to the working directory.

Long story short — a big file at the very top isn't just a waste of context but can starve the file that was actually important.

In GitHub Copilot CLI

Copilot CLI supports AGENTS.md by design so the file looks fine here; it has the broadest support of all the tools from this category in terms of supported files:

• .github/copilot-instructions.md

• .github/instructions/**/*.instructions.md (it's path-scoped)

• CLAUDE.md

• GEMINI.md (might be useful if team members use different tools)

But it also becomes a liability during the initial setup phase as Copilot CLI merges all the files it finds and says it "does not define a general precedence order between these files. Avoid conflicting instructions." Given there's no documentation for which one wins, we can skip thinking about it and just keep one file and remove the rest.

Also, copilot init creates .github/copilot-instructions.md so if you run it you'll get another instruction file, not a populated main one.

Proving it loaded.

• /instructions: shows the instruction files found for the current session, you can enable or disable them separately

• /env: lists instruction files together with MCP servers, skills, agents, hooks etc

The gotcha.

There's also a pitfall that changing the file has no effect on an already running session, as per the docs: changes "are not immediately available for use in active CLI sessions." To apply them you need to either quit and run it again using copilot --continue or create a new session using /new.

So if everything seems to work after the first setup, but then you modify the file and stay in the same session, you'll see no change and conclude the file is not working.

In Cursor

There are two mechanisms in Cursor which aim to achieve the same thing but you need to choose one of them when setting it up.

The first one is the AGENTS.md file (located in the project root) which is mentioned in Cursor's docs, and described as "an alternative to .cursor/rules for straightforward use cases". Cursor's CLI docs also say that "the CLI also reads AGENTS.md and CLAUDE.md at the project root (if present)." That's what we'd recommend using if you're getting started with Cursor.

The second mechanism is using the .cursor/rules/*.mdc files which are a kind of "markdown" files with some frontmatter in them, that define when the rule should be applied. If you put there a single file with alwaysApply: true it will work like a memory-file, always being included in the sessions. The following is an example of such a .mdc file:

---
description: Project commands and landmines
alwaysApply: true
---

- Tests: `pnpm test` from the repo root. `pnpm --filter api test` skips the contract tests.

alwaysApply: true property overrides globs and description so this rule gets always included in every session. If you remove the alwaysApply: true property, but keep the globs, it will only get pulled if there's a file in the context that matches the glob. If you remove only the alwaysApply: true property, you'll be left with the description which means it's up to the agent when to use this rule. If you remove both of them, you'll end up with a rule that's included "only when you @-mention the rule in chat" — configured to look at, inert in practice.

Proving it loaded. As of now there's no CLI command that lists all active rules so if you want to make sure they are properly configured, the best way is to go to Customise → Rules page in the editor. From the terminal the canary probe is the practical check:

cursor-agent --trust --mode ask -p "What is the canary for this repo? If you do not know, reply exactly: UNKNOWN. Reply with one word and do not use any tools."

You need --trust the first time in a directory you haven't opened interactively; without it the CLI stops before it even reaches the model.

The gotcha. The extension is load-bearing. Cursor's own docs annotate a .md file sitting inside .cursor/rules/ with the comment "Ignored (wrong extension)" — right directory, right content, does nothing. And as above, the CLI refuses to start in a directory you haven't trusted, which is at least a loud failure rather than a silent one.

In Antigravity CLI

Antigravity CLI — it's an executable called agy, and the documentation says that it reads both GEMINI.md and AGENTS.md files placed in the workspace root directory, parsing them during the startup and using before asking for changes (the doc says: "Create a GEMINI.md or AGENTS.md file at your workspace root... The agent automatically parses these rules on startup and consults them before suggesting changes.").

So you can have a global file under ~/.gemini/GEMINI.md and an CLI settings file under ~/.gemini/antigravity-cli/settings.json.

There are two things not defined in the documentation, so it's best to avoid assuming anything about them:

• How it works if both files (GEMINI.md and AGENTS.md) are placed in the same directory — the precedence or merging logic

• What the relation is between a file in a subdirectory and the one in the root

If you plan to use Antigravity CLI, we'd recommend keeping it simple for now and having just one file in the workspace's root directory, until these things are documented.

For people migrating from Gemini CLI, keep in mind that this context.fileName is a thing specific for the Gemini CLI and is not mentioned among the keys of the Antigravity CLI settings you can find in its documentation; don't use it to set up your config.

Proving it loaded.

What's more… We were wondering if there's any way to check which instruction files are loaded by the model, but couldn't find anything in the docs:

• There's no /memory command

• /context command is described as a way to explore tokens usage, not as an inventory of loaded files

We were thinking we could come up with a canary probe — a print-mode one-word query asking about some repo canary and instructing it what to respond if it's not there (so it always responds UNKNOWN).

agy -p "What is the canary for this repo? If you do not know, reply exactly: UNKNOWN. Reply with one word and do not use any tools."

The gotcha.

But… Actually, we tried this, and the results were negative. We've been using version 1.1.9 of Antigravity CLI, created a new git repository in which we've never been interactively, placed a file under the root directory of this workspace, and ran the probe; neither AGENTS.md nor GEMINI.md files ended up in the model (we checked it in both default and plan modes). Also, asking Antigravity directly whether any project context file was in its instructions returned NONE, so it wasn't the model declining to answer.

But, at least for now, we can't point why this is happening; it could be:

• The settings.json file doesn't have the workspace directory listed in the trustedWorkspaces array

• It might have something to do with the way Antigravity CLI handles projects (which it has its own system for — eg. you can run agy --new-project or agy --project), we weren't in any project in this case

• It could be connected with print mode itself

So if you run into a situation like this, always keep in mind that just because the file is there doesn't mean it's loaded, so if you get UNKNOWN, try to go to the directory interactively once, then ask again before making any conclusions about what's inside the file.

In Kimi Code CLI

The file should be called AGENTS.md (lowercase agents.md works too), and there's also a .kimi-code sub-folder in the project where you can place it instead (there's no KIMI.md).

It looks for this file in 4 places:

• globally in ~/.kimi-code/AGENTS.md (if you haven't configured a data root it falls back to this one)

• globally in ~/.agents/AGENTS.md (shared between tools)

• in every directory from the git work-tree root down to the current one, picking up .kimi-code/AGENTS.md

• same for plain AGENTS.md (no .kimi-code sub-folder here)

If it finds multiple files in these places, they're all merged together without replacing any of them; instead every part is prefixed with the path where it's been found.

Compared to competing solutions this has two more features that are really useful:

• whenever you edit the file it's automatically being reloaded during the session, so there's no need to restart the app

• the 32 KB limit for the merged content is a soft one — you get a visible warning telling you to trim, instead of the content being truncated silently

Proving it loaded.

• There's no documented way to see which files were loaded; if you want to check it you can start a new session from the repo's root and ask the app for some random word defined only within the repo (let it know what to reply if it isn't there, and ask it to respond with a single word without using any tool).

What is the canary for this repo? If you do not know, reply exactly: UNKNOWN.
Reply with one word and do not use any tools.

In the /status command you can see version of the app, model name, current working directory and mode but there's no information about the instructions chain.

The gotcha.

• It doesn't check the git work-tree's parent directories (so if your AGENTS.md is in a directory that is above this one in the file-system it won't be found). If you don't have a git repo created for the project, only the current working directory is being scanned.

• If the file is empty or filled with whitespaces it gets skipped silently.

• If you want to use a symlink to share the same AGENTS.md file across multiple repos make sure you're on 0.28.0 or newer, otherwise the web backend won't follow the symlink.

• We haven't tried this one ourselves as we only had the outdated kimi-cli that's based on Python, not the TypeScript rewrite; the info above is based on the Moonshot docs and the source code from the 0.31.1 release, make sure to verify it.