Skip to content
Lesson 4 of 12

Context Is Everything — CLAUDE.md and Project Setup

7 min read

Why Context Determines Quality

AI is a mirror of the context you provide. Give it vague, incomplete context and you get vague, incomplete code. Give it precise, structured context and you get code that follows your conventions, matches your patterns, and integrates seamlessly with your existing codebase. The difference between a 2x developer and a 5.7x developer often comes down to context engineering -- the skill of giving AI exactly the right information to work autonomously.

Think of it this way: when you onboard a new developer to your team, you do not hand them a laptop and say "build features." You give them documentation, explain the architecture, show them the coding conventions, and walk them through the deployment process. CLAUDE.md is that onboarding document for AI.

Anatomy of an Effective CLAUDE.md

CLAUDE.md is a markdown file at the root of your project that Claude Code reads automatically at the start of every session. It serves as persistent project memory. Here is the structure that works best:

# Project: SkyVanguard Web

## Tech Stack
- Next.js 14 with App Router
- TypeScript in strict mode
- Tailwind CSS with custom theme
- MDX for content pages
- Deployed on Vercel

## Directory Structure
- /src/app/ — Pages and API routes (App Router)
- /src/components/ — Reusable UI components
- /src/content/ — MDX content files (courses, blog posts)
- /src/lib/ — Utility functions and shared logic
- /src/styles/ — Global styles and Tailwind config
- /public/ — Static assets

## Coding Conventions
- Use ES modules (import/export), never CommonJS
- Prefer server components by default, use "use client" only when needed
- Name components in PascalCase, utilities in camelCase
- Use conventional commits: feat:, fix:, refactor:, docs:, test:, chore:
- All content supports i18n with .en.mdx and .es.mdx file pairs

## Commands
- `npm run dev` — Start development server
- `npm run build` — Production build
- `npm run lint` — Run ESLint
- `npm test` — Run Vitest test suite

## Deployment
- Push to main triggers Vercel deployment
- Preview deployments on pull requests
- Environment variables in Vercel dashboard

## Content Structure
- Courses live in /src/content/courses/{course-name}/
- Each course has _meta.en.mdx and _meta.es.mdx for metadata
- Lessons are numbered: 01-lesson-name.en.mdx, 01-lesson-name.es.mdx
- Frontmatter includes: title, description, date, tags, category, order, course

This file is approximately 40 lines and takes 5 minutes to write. It saves hours of corrections and back-and-forth on every session.

The 80/20 of Context

Not all context is equally valuable. Here is where 20% of the information drives 80% of the quality:

Must Have (the 20% that matters most)

  1. Tech stack with versions -- "Next.js 14" not just "Next.js"
  2. Directory structure -- Where things live and naming patterns
  3. Coding conventions -- The patterns AI should follow
  4. Key commands -- How to build, test, and deploy

Nice to Have

  1. Architecture decisions -- Why you chose certain patterns
  2. Known issues -- Things AI should work around
  3. Third-party integrations -- APIs and services in use

Usually Not Needed

  1. Full API documentation -- AI can read the code
  2. Detailed business logic explanations -- Better handled per-task
  3. Historical decisions -- Relevant context goes in task prompts

Overloading CLAUDE.md with too much information can actually hurt performance. Keep it focused on what AI needs to write correct code on the first try.

Directory-Scoped Context

For large projects, a single root CLAUDE.md may not be enough. Claude Code supports nested CLAUDE.md files that provide context specific to a subdirectory:

project/
  CLAUDE.md              # Global project context
  src/
    api/
      CLAUDE.md          # API-specific patterns and conventions
    components/
      CLAUDE.md          # Component library guidelines
    content/
      CLAUDE.md          # Content formatting rules

Example of a directory-scoped CLAUDE.md for an API directory:

# API Routes

## Patterns
- All routes export GET, POST, PUT, DELETE as named functions
- Use zod schemas for request validation
- Return NextResponse.json() with consistent error format
- Include rate limiting middleware on mutation endpoints

## Error Format
{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE",
  "status": 400
}

## Authentication
- Use getServerSession() from next-auth
- Protect all routes except /api/public/*

When Claude Code works in the src/api/ directory, it reads both the root CLAUDE.md and the local one. This gives it general project knowledge plus specific API conventions.

Keeping Context Fresh

A stale CLAUDE.md is worse than no CLAUDE.md because it teaches AI outdated patterns. Build the habit of updating it:

Update triggers:

  • After adding a new major dependency
  • After changing directory structure
  • After establishing a new convention
  • After changing build or deployment process
  • After resolving a recurring issue caused by outdated context

A practical approach is to add CLAUDE.md updates to your definition of done for major features. Shipped a new API pattern? Update the API conventions. Migrated the database? Update the commands section.

# Make CLAUDE.md updates part of your workflow
claude "We just migrated from Prisma to Drizzle ORM. Update CLAUDE.md
       to reflect the new database tooling, commands, and patterns."

The Context Window: Understanding Limits

Claude Code has a context window that holds the entire conversation plus project files it reads. As sessions grow long, older context gets compressed or dropped. Understanding this helps you work more effectively:

Managing long sessions:

# When context gets large, compact the conversation
/compact

# This summarizes the conversation history, freeing up
# context space for new work while preserving key decisions

Strategies for context efficiency:

  • Keep CLAUDE.md concise -- it is read on every interaction
  • Use /compact after completing a major feature before starting the next
  • For very long sessions, consider starting a new session with a clear description of what was already accomplished
  • Reference specific files by path rather than pasting their contents into the conversation

Real Example: A Production CLAUDE.md

Here is a condensed version of a CLAUDE.md that enables Claude to work autonomously on a real Next.js project with internationalization, dark mode, and content management:

# SkyVanguard Web

## Stack
Next.js 14, TypeScript strict, Tailwind CSS, MDX, Vercel

## Structure
/src/app/[locale]/ — i18n routes (en, es)
/src/components/ — Shared components
/src/content/courses/ — Course MDX files
/src/content/blog/ — Blog MDX files
/src/lib/i18n.ts — Translation utilities
/src/styles/globals.css — Tailwind base + custom styles

## Conventions
- Server components default, "use client" when needed
- ES modules only, async/await only
- Conventional commits (feat:, fix:, refactor:)
- All content bilingual: .en.mdx + .es.mdx pairs
- Tailwind dark: variant for dark mode (next-themes)

## Content Frontmatter
Courses: title, description, date, tags, category, order, course
Blog: title, description, date, tags, category
Meta: title, description, date, tags, category, level

## Commands
dev: npm run dev
build: npm run build
lint: npm run lint

This is 25 lines. It gives Claude everything it needs to create new courses, add features, fix bugs, and maintain consistency across the project. When you see a developer shipping 12 projects in a week, this kind of context setup is the invisible infrastructure making it possible.

Practical Exercise

Before moving to the next lesson, create or update your CLAUDE.md:

  1. Start with your tech stack and versions
  2. Document your directory structure
  3. List your 3-5 most important coding conventions
  4. Add the commands for build, test, and deploy
  5. Include any content or file naming patterns

Test it by starting a new Claude Code session and asking it to create a small feature. If it gets the conventions right on the first try, your context is working. If it needs corrections, add those corrections to CLAUDE.md so they do not happen again.