Project Context
There is something called "project context" — usually saved in a file named AGENTS.md at the root of your repository. AGENTS.md is an open format for project instructions that works across many AI coding agents. Some products may have their own vendor-specific files, such as CLAUDE.md in Claude Code.
This file is loaded into the agent's memory at the start of every session, giving it the background it needs to work effectively in your project without you having to re-explain things each time.
Some agentic tools offer a built-in command to generate the project context file for you by scanning your project:
# Many agents provide an initialization command
/init # generates a project context file such as AGENTS.md or CLAUDE.md
Review and edit the output — the auto-generated version is a starting point, not a finished product.
A good project context file answers:
- What does this project do, and what is the tech stack?
- What are the build, test, and lint commands?
- What conventions should the agent follow (branch naming, PR format, file structure)?
- What should the agent not do without asking first?
Repository context
The repository-level context file lives in the root of your project and is committed to version control so the whole team shares the same baseline.
Use AGENTS.md — it is vendor-neutral and read by all major AI coding agents. Claude Code reads CLAUDE.md by default, but can import AGENTS.md (see below).
The AGENTS.md standard does not define any override feature yet, but some agents support user-level and local override files that take precedence over the repository-level file.
User-level override
For reusable preferences across all your projects, you can have a user-level context file that applies to every project you open:
| Tool | Path |
|---|---|
| Claude Code | ~/.claude/CLAUDE.md |
| Opencode | ~/.config/opencode/AGENTS.md |
| Codex | ~/.codex/AGENTS.md — also supports cross-project reusable preferences at this path |
AGENTS.md support discussion thread: https://github.com/agentsmd/agents.md/issues/91
Local override
Some agents support local override files for AGENTS.md (or CLAUDE.md) in the project directory, which take precedence over the repository-level file. Use this for personal preferences that you don't want to share with teammates.
AGENTS.local.md— supported by Opencode, Codex, and othersCLAUDE.local.md— supported by Claude Code
Add these to .gitignore so they stay on your machine only.
AGENTS.md support discussion threads: - https://github.com/agentsmd/agents.md/issues/13 - https://github.com/agentsmd/agents.md/issues/72
Hierarchy of project context
When multiple context files exist, most agents apply them in the following priority order:
- Local override (
AGENTS.local.mdorCLAUDE.local.md) - Repository context (
AGENTS.mdorCLAUDE.md) - User-level (
~/.claude/CLAUDE.md,~/.config/opencode/AGENTS.md, etc.)
Refer to your specific agent's documentation for exact behavior, as some may not support all three levels or may have different override rules.
Claude Code and AGENTS.md
Claude Code reads CLAUDE.md natively, not AGENTS.md. To keep a single source of truth in the open-standard AGENTS.md, create a CLAUDE.md that imports it:
<!-- CLAUDE.md -->
@AGENTS.md
Claude Code supports the @ import directive, which expands the referenced file at session start. You can also add Claude-specific instructions below the import if needed.
This avoids duplicating project context across two files and keeps AGENTS.md as the canonical, vendor-neutral source.
