Skip to main content

Project Context Files

Repository-root files that teach coding agents how to work inside a project.

How To Evaluate Entries​

Each entry in this family should make the following points clear:

  • What the convention is.
  • Where the file, URL, or protocol surface normally lives.
  • When a team should use it.
  • Adoption evidence from a public spec, canonical docs, or active ecosystem use.
  • Which example illustrates the convention, if one exists.
  • Related conventions that solve adjacent problems.

Registry Entries​

These files live in a repository root and tell AI coding agents how to behave in that project. Think of them as a README written for agents.

AGENTS.md​

The cross-tool standard for agent context. The Agentic AI Foundation, part of the Linux Foundation, maintains it after OpenAI donated the project in December 2025 alongside Anthropic's MCP and Block's Goose. Claude Code, Cursor, Copilot, Gemini CLI, and other agents can read the same file.

A typical AGENTS.md documents build commands, coding conventions, PR rules, and what the agent must not touch. In monorepos, each subdirectory can have its own AGENTS.md that inherits from the root. Agents read the nearest file in the directory tree.

Claude Code added AGENTS.md support in version 2.1.277. When a project has no CLAUDE.md, Claude Code reads AGENTS.md as its project instructions. Anthropic notes that this fallback is not yet available on Bedrock, Vertex, or Foundry.

CLAUDE.md​

Claude Code's native memory file. Loaded automatically before every session. Anything in it enters the context window without prompting. Supports @imports for referencing other files (up to 5 levels deep), which keeps the main file lean while allowing each team or subdirectory to own its own rules.

CLAUDE.md is Claude-specific. For multi-tool teams, the common pattern is to make it a symlink to AGENTS.md: CLAUDE.md → AGENTS.md.

GEMINI.md​

Gemini CLI's default project context file. It can hold project instructions, coding conventions, and domain context. Gemini CLI loads these files hierarchically from global, workspace, and subdirectory locations, and supports @file.md imports for splitting instructions across files.

GitHub Copilot's cloud agent and CLI also recognize GEMINI.md. Gemini CLI can be configured to look for additional filenames, including AGENTS.md, through context.fileName.

MEMORY.md​

Claude Code's auto-memory file. Written by the agent, not the human. When Claude learns something about your codebase mid-session, it can persist that knowledge here. On next session, the index loads automatically; topic files load on demand. Complements CLAUDE.md: you write the instructions, the agent writes the learnings.

Cursor, Cline, and GitHub Copilot instruction files​

Tool-specific equivalents. Cursor uses YAML-frontmatter scoped rules by glob pattern. GitHub Copilot uses .github/copilot-instructions.md for repo-wide defaults and path-specific .instructions.md files. Open-source agents like Cline and Roo Code use .clinerules or .roorules in the project root to ingest behavior on initialization. For teams using multiple tools, the symlink pattern prevents content from drifting apart across files.

.aiignore​

Tells AI agents which files and folders to skip, much like .gitignore. JetBrains Junie adopted this pattern. It can keep sensitive configuration, large binaries, and generated code outside the agent's context.

Memory Bank (cline_docs/ or .roo/)​

A project state architecture popularized by open-source agents like Cline and Roo Code. The agent maintains context across several Markdown files, such as activeContext.md, productContext.md, and systemArchitecture.md. It updates those files as the project changes across long-running sessions.