Context is King: How Project Files and Templates Keep Claude on Track

#claudecode #ai #productivity #beginners

Part 6 of 7 · Series: Building Your AI Developer Handbook · GitHub

The Context Problem

Every developer switches between projects. Each project has its own setup, ongoing decisions, deadlines, and "why did we do it this way" history.

"Imagine a consultant who works with five different clients. Every Monday they need a full briefing — 'who are you, what are we building, why did you make that decision last week?' — before they can do anything useful. Now imagine if that briefing happened every single day."

That's Claude without project context files.

Project files and reference files give Claude the backstory before it starts. Not the code — Claude can read the code. The context behind the code.

The Project Context File

---
name: project_auth_rewrite
type: project
---

Auth system rewrite in progress. Deadline: 2026-06-20.

**Why:** Legal flagged session token storage as non-compliant
with new data regulations.

**How to apply:** Scope decisions favor compliance over
ergonomics until the audit is complete.

Every project file has three parts:

The fact — what happened or what was decided
The why — motivation (deadline, constraint, stakeholder, incident)
How to apply — what should change about Claude's behavior

"A sign that says 'do not open this door' is easy to ignore. A sign that says 'do not open this door — last person who did triggered the fire suppression system' is not."

The Why is what lets Claude judge edge cases. Without it, rules are followed blindly. With it, Claude can ask: "does this new situation actually trigger the same concern?"

What Goes in a Project File

Good content:

Architectural decisions and the trade-offs that led to them
Ongoing work — who is doing what, by when (use absolute dates, not "next Thursday")
Why a particular library was chosen over alternatives
A constraint not obvious from the code (legal, performance, security)

Bad content — don't memorize these:

Already exists	Don't put in project file
Code patterns	Read the code
File structure	Read the filesystem
Git history	Run `git log`
Things that change daily	Too stale too fast

"A map is useful. A map from three years ago of a city that's been rebuilt is worse than no map — it gives you false confidence."

Project files decay. The Why field tells you whether a memory is still load-bearing or just historical noise.

When Project Files Shine

Without a project file:

Session start:
"So just to re-explain the context — we're mid-sprint on auth,
there's a compliance deadline, the approach was chosen because..."

With a project file:

[Claude reads: auth rewrite, deadline 2026-06-20,
compliance is the priority, no ergonomics shortcuts]

You: "should we add a caching layer to the token check?"
Claude: "Given the compliance requirement, caching token validation
would complicate the audit trail — skip it until after the audit."

Claude makes the right call without being told why. That's context working.

The Reference File

---
name: reference_template_location
type: reference
---

Template path: ~/.claude/templates/ts-react-project.md

Usage: at new repo init, copy to .claude/CLAUDE.md.
Fill in [Project Name] and Architecture section.

Note: verify library versions at each project init — they drift.

Reference files are simple: where to find things that live outside the project.

Where bugs are tracked (Linear, Jira, GitHub Issues)
Where design assets live (Figma, Storybook)
Where dashboards are (Grafana, Datadog)
Where templates live (local filesystem paths)

"A good assistant knows where the filing cabinet is. They don't memorize every document inside it — they just know where to look."

The Template System

The reference file above points to a template: ~/.claude/templates/ts-react-project.md.

This is a complete project-level CLAUDE.md for TypeScript/React projects. New repo workflow:

mkdir -p .claude
cp ~/.claude/templates/ts-react-project.md .claude/CLAUDE.md
# Fill in: [Project Name], Architecture section

Instantly Claude knows: TypeScript project, pnpm, Zod for validation, TanStack Query for server state, Zustand for client state. All project-level rules in place before you write a single line.

"A chef's mise en place — everything in its place before cooking starts. Setup done right means execution can be clean."

The warning: "Verify library versions are still current at each project init — they drift." A template from six months ago might reference a library that's had a major version bump. Always check.

The Full Context Hierarchy

When Claude starts a session, it reads context in layers:

1. Global CLAUDE.md       ← who you are, universal rules
2. Project CLAUDE.md      ← this stack, this project's rules
3. Memory files (index)   ← lessons, preferences, project context
4. The code itself        ← what's actually been built

"General law → company policy → department rules → today's meeting agenda. Each layer is more specific than the last."

Writing Your First Project File

You don't write project files upfront. Write them when you notice you're re-explaining context.

Trigger: You find yourself starting a session with "so just to re-explain the context..."

Action: Stop. Write a project file:

---
name: project_[feature_name]
type: project
---

[What's being built, current status]

**Why:** [The motivation — constraint, deadline, stakeholder ask]

**How to apply:** [What Claude should do differently because of this]