Instruction & Memory Files

This content was generated with the assistance of AI and should be verified against the official documentation of each tool and framework before being relied on in production.

This section’s bibliography lists the reference material consulted while preparing these pages.

Examples on this page target the Claude Code CLI 2.1.283, VS Code 1.139 with the GitHub Copilot Chat extension, and the GitHub Copilot CLI 1.0.88, checked against the official Claude Code and GitHub/VS Code documentation as of 2026-09-28. ai-catalog excerpts are pinned to commit 58fb709. The running example is the same DocsAssistant API Spring Boot + Python sample used across the AI-Assisted Development sub-section, with its controller at src/main/java/com/example/docsassistant/DocsController.java.

Instruction and memory files are the always-on layer: unlike a skill or a prompt file, they load automatically at the start of a session rather than waiting to be invoked. That makes them the right place for facts every turn needs — build commands, conventions, layout — and the wrong place for anything only some tasks need.

CLAUDE.md: locations and precedence

Claude Code loads CLAUDE.md (and CLAUDE.local.md) from four scopes, concatenated rather than overridden, in this order from broadest to most specific:

Scope Location Purpose

Managed policy

macOS /Library/Application Support/ClaudeCode/CLAUDE.md; Linux/WSL /etc/claude-code/CLAUDE.md; Windows C:\Program Files\ClaudeCode\CLAUDE.md

Organization-wide instructions deployed by IT/DevOps; cannot be excluded by individual settings.

User instructions

~/.claude/CLAUDE.md

Personal preferences that apply to every project on your machine.

Project instructions

./CLAUDE.md or ./.claude/CLAUDE.md

Team-shared instructions, checked into source control.

Local instructions

./CLAUDE.local.md

Personal, project-specific preferences; add it to .gitignore yourself so it isn’t committed.

CLAUDE.md and CLAUDE.local.md from the working directory and every directory above it load at launch; content is ordered from the filesystem root down to the working directory, so instructions closer to where you launched Claude are read last, with CLAUDE.local.md appended after CLAUDE.md at each level. Being read last is not an override: if two files contradict each other Claude may follow either, so keep them consistent. Files in subdirectories below the working directory are not loaded at launch — they load on demand, the moment Claude reads a file in that subtree, which is how a monorepo module keeps its own conventions out of context everywhere else. Run /context in a session to confirm which memory files actually loaded. See Claude Code — How Claude remembers your project.

A minimal project CLAUDE.md for the DocsAssistant API repository:

CLAUDE.md
# DocsAssistant API

Spring Boot 3 + Java 21 backend under `src/main/java/com/example/docsassistant/`, with a Python
ingestion pipeline under `ingest/`. Run `mvn test` before proposing any change as done.

- The REST controller is `src/main/java/com/example/docsassistant/DocsController.java`.
- Use 2-space indentation in the Python ingestion scripts.

Anthropic’s own guidance is to keep this under 200 lines: a longer file costs more context on every turn and, in practice, reduces how consistently Claude follows it. When a project’s instructions outgrow that budget, split them into path-scoped rule files (below) or a skill instead of one long CLAUDE.md.

@path imports

A CLAUDE.md can pull in other files with @path/to/file syntax; both relative and absolute paths work, relative paths resolve against the file that contains the import (not the working directory), and an import can itself import further files up to four hops deep. Import parsing skips fenced code blocks and inline code spans, so wrapping a path in backticks —  @README  — mentions it as plain text instead of importing it.

CLAUDE.md
See @README for project overview and @package.json for the available npm commands.

# Additional instructions
- Git workflow: @docs/git-instructions.md

An import that resolves outside the current working directory — for example @~/.claude/my-team-notes.md inside a project file — is an external import. The first time Claude Code encounters one in a project it shows an approval dialog listing the files; declining leaves the import disabled without asking again. See Claude Code — How Claude remembers your project.

Rules directories

For larger projects, .claude/rules/ holds one topic per file (testing.md, security.md, …​), discovered recursively, so instructions stay modular instead of piling into one CLAUDE.md. A rule with no paths frontmatter loads unconditionally, at the same priority as ./.claude/CLAUDE.md. A rule scoped with paths: glob patterns in its YAML frontmatter loads only when Claude reads a matching file — for example:

.claude/rules/api-design.md
---
paths:
  - "src/main/java/com/example/docsassistant/**/*Controller.java"
---

# API design rules

- Every endpoint validates its input before touching the repository layer.
- Return 404, not 500, when a requested id doesn't exist.

~/.claude/rules/ holds personal rules that apply across every project on the machine, loaded before project rules. See Claude Code — How Claude remembers your project.

Auto memory

Alongside CLAUDE.md, Claude Code maintains auto memory: notes Claude writes itself, without you editing a file, from corrections and preferences you give it in conversation. It records one of four kinds per note — user, feedback, project, reference — and skips anything it can already derive from the codebase or that an existing CLAUDE.md already says. Storage is per-project at ~/.claude/projects/<project>/memory/, holding a MEMORY.md index (only its first 200 lines or 25KB load at session start) plus one topic file per memory; it is machine-local, shared across worktrees and subdirectories of the same repository but not across machines. Auto memory is on by default and toggles from /memory or the autoMemoryEnabled setting. Browse or edit it with /memory at any time. A typical index, one line per memory:

~/.claude/projects/<project>/memory/MEMORY.md
- [Testing preference](feedback_testing.md) -- run `mvn test -pl api` rather than the full build while iterating
- [Release freeze](project_release_freeze.md) -- no merges to `main` until the 2.0 tag is cut
- [Issue tracker](reference_tracker.md) -- bugs live in the GitHub project board, not Jira

To keep a machine-local project from writing auto memory at all, turn it off in that project’s settings:

.claude/settings.local.json
{
  "autoMemoryEnabled": false
}

See Claude Code — How Claude remembers your project.

AGENTS.md and path-specific Copilot instructions

AGENTS.md

AGENTS.md is an open, tool-agnostic Markdown format — described by its own site as "a README for agents" — for the build/test/convention context an AI coding agent needs, kept separate from the human-facing README.md. It supports nesting: a subdirectory’s own AGENTS.md takes priority for work inside that subtree, letting a monorepo give each package tailored instructions. It has no required fields — it is plain Markdown with whatever headings help. As of 2026-09-28 its site lists a broad set of supporting tools, including GitHub Copilot, OpenAI Codex, Google Jules and Gemini CLI, Cursor, Aider, Zed, Amp and VS Code. Claude Code is not on that list but also reads it, as described below.

AGENTS.md
# DocsAssistant API

## Build and test
- `mvn test` runs the Java test suite; `pytest ingest/` runs the Python ingestion tests.

## Conventions
- The REST controller is `src/main/java/com/example/docsassistant/DocsController.java`.
- Use 2-space indentation in the Python ingestion scripts.

Claude Code (v2.1.277+) reads a repository’s AGENTS.md directly as project instructions, on its own when the repository has no CLAUDE.md/CLAUDE.local.md on the working-directory path, or alongside CLAUDE.md when the Project instructions setting (/config) is set to read both. See Claude Code — How Claude remembers your project for the precedence table and its per-tool caveats. On the Copilot side, GitHub’s docs state that the nearest AGENTS.md in the directory tree takes precedence, and VS Code reads it when the chat.useAgentsMdFile setting is on (nested AGENTS.md files are experimental there and off by default) — see VS Code — Custom instructions.

.github/copilot-instructions.md

GitHub Copilot’s repository-wide instructions file is plain Markdown at a fixed path, applied to every request made in the context of the repository on the Copilot surfaces that support repository custom instructions (for example Copilot on GitHub.com, including code review, and Copilot in the IDE):

.github/copilot-instructions.md
# Project Overview
DocsAssistant API: a Spring Boot 3 + Java 21 backend under `src/main/java/com/example/docsassistant/`.

## Testing
Run `mvn test`. Tests must pass before a change is considered complete.

See GitHub — Adding repository custom instructions for GitHub Copilot.

Path-specific *.instructions.md

Copilot also supports instructions scoped to matching files: a Markdown file under .github/instructions/ (subdirectories are allowed), named <name>.instructions.md, whose YAML frontmatter applyTo key gives a glob pattern (or a comma-separated list of patterns) relative to the workspace root. GitHub.com uses these files only for Copilot cloud agent and Copilot code review, and its setup steps always include applyTo. In VS Code applyTo is optional: a file with a description instead is loaded on demand when the description matches the task:

.github/instructions/api-design.instructions.md
---
applyTo: "src/main/java/com/example/docsassistant/**/*Controller.java"
---

- Every endpoint validates its input before touching the repository layer.
- Return 404, not 500, when a requested id doesn't exist.

This is Copilot’s counterpart to a Claude Code path-scoped .claude/rules/*.md file above: both load only when work touches a matching path, instead of on every turn. See VS Code — Custom instructions and GitHub — Adding repository custom instructions for GitHub Copilot.

Portability across tools

Maintaining separate CLAUDE.md, AGENTS.md and .github/copilot-instructions.md files with the same content invites drift. Two ways to keep one source of truth:

In Claude Code
@AGENTS.md

## Claude Code
Use plan mode for changes under `src/main/java/com/example/docsassistant/billing/`.

Placing this in CLAUDE.md next to AGENTS.md makes Claude read the imported file first, then any Claude-specific addenda below it — useful when a project also needs a CLAUDE.md for content that doesn’t belong in the shared file. Where a CLAUDE.md isn’t needed at all, a symlink works too:

$ ln -s AGENTS.md CLAUDE.md

In GitHub Copilot, no import or symlink is needed: Copilot reads AGENTS.md directly (in VS Code while chat.useAgentsMdFile is on), and so does Claude Code 2.1.277+ when no CLAUDE.md exists. A repository that keeps a single AGENTS.md at its root, with no CLAUDE.md or .github/copilot-instructions.md, is therefore read as-is by both tools. Add a .github/copilot-instructions.md alongside it only for Copilot-surface content (such as code-review-specific guidance) that shouldn’t reach Claude Code.

Whichever approach is used, keep instructions short, avoid stating the obvious, and prefer a runnable command over a paragraph of prose:

Do Don’t

"Run mvn test before proposing a change as done."

"Make sure your code is properly tested."

"The REST controller is src/main/java/com/example/docsassistant/DocsController.java."

"Keep the code organized."

A path-scoped rule for a subtree’s own convention

One giant file with every team’s rules mixed together

A concrete command, path or pattern an assistant can act on directly

A restatement of something derivable from the codebase (directory layout, dependency list)

Facts every session needs

A multi-step procedure — move that to a skill instead

See The CLAUDE.md file, Managing Context and Context Engineering for the broader context-budget reasoning behind keeping these files small.

Related pages

References