Scaling Context with File References

What You'll Learn

A single CLAUDE.md works great for small projects. But as your conventions grow, testing standards, component patterns, API guidelines, deployment rules, that file gets long and hard to maintain. In this lesson, we split project memory across focused files using the @ import syntax, and introduce a pattern for keeping everything organised.

The Problem with a Single File

After the last lesson, your CLAUDE.md might already have 50+ lines of conventions. Now imagine adding:

• Detailed testing patterns with examples
• Component architecture guidelines
• API design standards
• Database conventions
• Deployment and CI/CD rules

A 300-line CLAUDE.md is hard to read, hard to maintain and hard to review in pull requests. When everything is in one file, a change to your testing conventions shows up in the same diff as your component rules.

File References with @

Claude Code supports an @ syntax inside CLAUDE.md that imports content from other files. The referenced file gets loaded as if its content were inlined at that position.

# CLAUDE.md
 
@AGENTS.md

That single line pulls in the entire contents of AGENTS.md at load time. You can reference multiple files:

# CLAUDE.md
 
@docs/architecture.md
@docs/api-standards.md

How references work:

• Paths are relative to the file containing the @ import
• Home directory paths work too: @~/.claude/personal-prefs.md
• Claude loads them at session start, same as the main CLAUDE.md
• References inside code blocks are ignored, so examples won't trigger imports

The AGENTS.md Standard

AGENTS.md is the universal equivalent of CLAUDE.md. While CLAUDE.md is specific to Claude Code, AGENTS.md is recognised by most AI coding tools including GitHub Copilot, Cursor, Gemini CLI and others.

Claude Code doesn't natively read AGENTS.md yet. It looks for CLAUDE.md. But here's the thing: since Claude Code supports @ file references, we can get the best of both worlds. Keep your CLAUDE.md as a minimal entry point that references AGENTS.md:

# CLAUDE.md
 
@AGENTS.md

Now your project conventions live in AGENTS.md, a file that most AI tools already understand, and Claude Code picks it up through the reference. If a teammate uses Cursor, Copilot or any other agent that supports the standard, they get the same conventions automatically without needing a separate config file for each tool. One file, every agent.

Move the project context that /init generated in the previous lesson into AGENTS.md. This is the same content, just in a different file. Open your CLAUDE.md, cut everything out, and paste it into a new AGENTS.md file. Then update CLAUDE.md to just reference it with @AGENTS.md, as shown above.

Why split it this way?

1. CLAUDE.md stays tiny. It's just the entry point. Easy to see at a glance.
2. AGENTS.md is the real document. It holds the structured project context, and it's where most edits happen.
3. Works across tools. AGENTS.md is recognised by Copilot, Cursor, Gemini CLI, Codex and others. Your conventions aren't locked into one tool.
4. Naming signals intent. AGENTS.md makes it clear this file is for AI agents, not humans reading a README. Anyone browsing the repo understands its purpose immediately.
5. Clean diffs. Changes to project context show up in AGENTS.md commits, separate from other project changes.

In the next lesson, we'll add focused rules for specific areas like testing and UI development.