You have brief.md and plan.md. They live in your project folder. Now you need Claude to reference them at the right moments without constantly re-reading. The @file reference syntax makes this surgical.

The problem context files solve

Without dedicated context files, you end up

• Pasting chunks of the brief into every prompt
• Re-explaining constraints each time
• Losing track of which rules apply where
• Claude forgetting the shape of the project between sessions

With context files + @file refs, Claude reads the right document at the right time. Cheap + precise.

The 4 standard context files

For a substantial project, this is the typical structure

my-project/ ├── CLAUDE.md ← project-level instructions (Module 02) ├── brief.md ← goal + constraints ├── plan.md ← phases + steps ├── spec.md ← detailed requirements ├── notes.md ← ongoing scratchpad └── (work files)

CLAUDE.md is loaded every session automatically. The others are loaded on demand.

Using @file references

Inside a prompt or inside a CLAUDE.md, you can reference another file like this:

@brief.md

When Claude encounters @brief.md, it reads the file content as if it were written inline. The context is pulled in just for that moment.

Example in a prompt

Let's work on Phase 3 from @plan.md. Make sure anything we build matches the constraints in @brief.md.

Claude reads both files, then executes the task with their content in mind.

Using @file in CLAUDE.md

You can inline context files into CLAUDE.md itself

Project CLAUDE.md

About this project @brief.md

Current plan @plan.md

Specs @spec.md

Every session in this project loads all 3 files as part of CLAUDE.md context. Claude starts fully briefed.

Trade-off: bigger context cost. Only do this for projects where you want the plan loaded constantly. For others, reference on-demand in specific prompts.

What goes in each file

brief.md

Goal, success criteria, constraints, audience. From Module 11 Lesson 2.

plan.md

Phases, steps, dependencies, time estimates, risks. From Module 11 Lesson 3.

spec.md (optional)

Detailed requirements. Usually technical stuff - data schemas, API contracts, exact format specifications. Only needed for projects with complex output requirements.

notes.md

Scratchpad for decisions, learnings, questions, stuck points. Grows as the project evolves. Every significant decision gets a line here.

Example notes.md

Project Notes

2026-04-15

• Confirmed with client: they want a single HTML scroll, not a deck
• Decided to exclude branded search conversions (aligned with client's earlier preference)

2026-04-16

• Discovered the Meta Feb drop is attribution, not real decline - updating Phase 2 analysis
• Added a note to CLAUDE.md: always check attribution before flagging a decline

Becomes a decision log. Invaluable on long projects when you or a teammate asks "why did we do it this way?"

The context-engineering mindset

You are deliberately shaping what Claude knows at each moment:

• CLAUDE.md - always loaded (who you are, project-level rules)
• @brief.md, @plan.md - loaded on-demand (project shape)
• @spec.md - loaded for specific technical work
• @notes.md - loaded when you need historical decisions
• Files in /data - loaded for that specific analysis

This is context engineering. You control the information flow . Better control = better outputs.

Anti-patterns

Putting everything in CLAUDE.md

Makes CLAUDE.md huge, eats tokens on every session, drops adherence. Keep CLAUDE.md lean (Module 02) and use @file refs for project-specific context.

Not maintaining the files

Stale brief.md that doesn't reflect the current project. plan.md still showing Phase 1 when you're actually on Phase 4. Notes.md that hasn't been updated in weeks.

Update as you go. These files are working documents.

Over-splitting into too many files

brief.md + plan.md + spec.md + audience.md + risks.md + stakeholders.md + timeline.md... Too many. Stick to the 4 canonical files unless there's a clear reason to add more.

Power-user tips

• Use @file in CLAUDE.md for static context, @file in prompts for momentary loads - balance between always-loaded and on-demand
• Keep notes.md chronological - date every entry, read top-down when reviewing
• Archive finished project's context files into archive/ folder - searchable later
• Use relative paths - @brief.md not @/Users/...full-path/brief.md - works regardless of where the project lives

Action items

☐ For your next complex project, create brief.md, plan.md, notes.md

☐ Practice using @file refs in prompts: "let's work on Phase 3 from @plan.md"

☐ Update notes.md after every significant decision

☐ Don't let plan.md go stale - update as phases complete

Next lesson: Executing a plan in chunks.

Exercises

1. Review the concepts covered in this lesson: Context files + @file.
2. Write down your key takeaway from this lesson.
3. Practice running any commands or prompts mentioned above inside your terminal.