Google’s Gemini CLI shipped with AGENTS.md support, which sounds like straightforward compatibility news until you look at the details. The format is shared, but the interpretation diverges in ways that matter if you’re running both Gemini CLI and Claude Code against the same repository.
This isn’t a “which is better” comparison. It’s a technical breakdown of how each tool reads AGENTS.md, where they agree, where they don’t, and how to write instructions that give good results in both without maintaining two separate files.
What Gemini CLI Actually Reads
Gemini CLI’s AGENTS.md handling follows the same hierarchical resolution as Claude Code: it walks up from the current working directory, collecting all AGENTS.md files it finds, then processes them from root to leaf. Files closer to the working file take precedence when instructions conflict.
The difference is in what it does with the content.
Claude Code treats AGENTS.md as instruction context that gets prepended to the system prompt. Gemini CLI processes it through what Google calls “grounding” — the model is given the file content as context but with a different weighting mechanism that affects how strongly the instructions influence output compared to the user’s immediate query.
In practice, this means:
- High-specificity commands (exact terminal commands, file paths, naming conventions): both tools follow these reliably
- Behavioral instructions (tone, verbosity, decision heuristics): Gemini CLI is more likely to deprioritize these when the user’s query is specific
- Prohibitions (“never do X”): Claude Code treats these as hard constraints; Gemini CLI treats them as strong preferences that can be overridden by explicit user instruction
You don’t need to rewrite your AGENTS.md. But you should test prohibitions explicitly with Gemini CLI before relying on them in automated pipelines.
Section-by-Section Compatibility
Commands Section
## Commands
Build: `npm run build`
Test: `npm test -- --coverage`
Lint: `npm run lint`
Type check: `npx tsc --noEmit`Both tools: full compatibility. This is the most reliable section across all AI coding tools — Gemini CLI, Claude Code, Cursor, Copilot Workspace. Exact commands are low-ambiguity and get followed consistently.
One Gemini CLI quirk: if the Commands section uses backtick formatting but without a code block, Gemini CLI sometimes interprets the backtick content as inline code to display rather than a command to execute. Use full code blocks for multi-step commands:
## Commands
**Build:**
```bash
npm run buildTest:
npm test -- --coverage
Less elegant, but unambiguous.
### Code Style Section
```markdown
## Code Style
- TypeScript strict mode. No `any`.
- Prefer `const` over `let`. Never `var`.
- Error handling: throw typed errors, not generic `new Error('string')`
- Imports: sorted, no barrel re-exports except at package boundariesBoth tools: high compatibility. Style rules in list format with concrete examples get followed well by both. Claude Code is slightly more consistent about maintaining these across a long session (context window usage patterns differ), but the differences are minor for most projects.
Architecture Constraints
## Architecture
- Routes call services. Services call repositories. No direct DB access from routes.
- Never import across package boundaries using relative paths.
- `src/types/` is read-only for AI agents — type changes require human review.Both tools: moderate compatibility. Claude Code treats the “never import” and “read-only” instructions as hard constraints and will explicitly refuse to violate them. Gemini CLI treats them as guidance — it will follow them unless the user explicitly asks otherwise or unless the task seems to require it.
If architectural constraints are load-bearing for your workflow, add rationale:
- Never import across package boundaries using relative paths.
Reason: We have a custom module resolution setup that will silently break if this happens.
The CI check for this is not reliable on Windows.Gemini CLI responds better to constraints when it understands why they exist. Claude Code follows them regardless, but rationale doesn’t hurt.
Prohibited Actions
This is where the tools diverge most significantly.
Claude Code example:
## Prohibited
- Do not run `DROP TABLE` or any destructive database commands.
- Do not modify files in `src/generated/` — these are auto-generated.
- Do not commit directly to `main`.Both tools will follow these during a normal interaction. The difference shows up in two scenarios:
Scenario 1: User explicitly asks to violate the rule
Claude Code: “I can’t do that — my instructions say not to modify src/generated/.”
Gemini CLI: Will often comply with the user’s explicit request, sometimes mentioning the constraint, sometimes not.
Scenario 2: The prohibition is ambiguous
If your prohibition says “don’t modify database schemas” and the user asks for a migration file, Claude Code will flag the ambiguity and ask. Gemini CLI will make a judgment call.
The fix for cross-tool compatibility is specificity:
## Prohibited
- Do not run any SQL that modifies table structure (ALTER TABLE, DROP TABLE, CREATE TABLE).
If a migration is needed, write the migration file but do not execute it.
- Do not modify any file whose path contains `/generated/`.
These files are outputs of `npm run codegen` and will be overwritten on next run.Specific file path patterns and explicit clarifications about what to do instead make prohibitions more robust across both tools.
Writing AGENTS.md for Both Tools
The fundamental rule: write for the less literal tool, test against the stricter one.
Gemini CLI’s tendency to treat instructions as strong preferences rather than hard rules means you need to be explicit about intent. Claude Code’s tendency to treat everything as binding means you shouldn’t add instructions you don’t actually want enforced.
A compatible pattern that works well:
# AGENTS.md
## Project Context
[Short paragraph: what this project is, primary tech stack, who works on it]
## Commands
[Exact commands in code blocks with bash language hint]
## Constraints
[Numbered list, each item with:
1. The constraint in imperative form
2. One-line reason
3. What to do instead if the constraint applies]
## Code Conventions
[Concrete rules with examples. "Use X" not "prefer X".]
## What to Ask a Human
[Explicit list of decision types that should prompt the agent to ask rather than decide]The “What to Ask a Human” section is particularly effective with Gemini CLI. Unlike prohibitions (which Gemini may override), a list of scenarios where the agent should ask creates a clarification-seeking behavior rather than a blocking behavior — and that translates better across both tools.
Practical Testing
Before deploying an AGENTS.md to a repo used by both tools, run these test cases:
# Test 1: Command execution
# Ask each tool: "How do I run the tests for this project?"
# Expected: Both return the exact command from your Commands section
# Test 2: Prohibition enforcement
# Ask each tool: "Can you modify the files in src/generated/?"
# Expected: Both decline or ask for clarification
# Test 3: Architecture constraint
# Ask each tool: "Add a database query directly in the route handler"
# Expected: Both push back or suggest the service layer alternative
# Test 4: Ambiguous instruction
# Write a rule that's slightly ambiguous, then ask something that hits the ambiguity
# Expected: Both ask for clarification rather than guessingFor Test 4, ambiguity is where you’ll see the biggest difference in behavior. Claude Code tends to ask. Gemini CLI tends to interpret. Neither approach is wrong — but if your workflow depends on one behavior or the other, design your instructions accordingly.