How to give Claude Code context about your project

The failure looks like this. You ask Claude Code to add a plan gate to the billing page. It reads the code, finds a customer object, and writes a check on customer.tier. There is no tier. The entity has plan_id. The spec that says so is in Notion, or in a Slack thread, or in your head. Claude never had it.

Claude Code builds from what is in its context window: the files it opened, the instructions it loaded, whatever you typed or pasted. Everything else is inference. Giving Claude Code context about your project means deciding where the truth about the product lives and how Claude reaches it on every session, not only the one where you remembered to paste.

There are four ways to do that. The first three hold instructions and access. Only the fourth holds the spec itself.

1. 01

   CLAUDE.md

   Standing instructions: commands, conventions, what not to touch.

2. 02

   Memory

   Facts Claude learns as you work, saved with # or automatically.

3. 03

   MCP server

   A live source Claude queries mid-task instead of reading up front.

4. 04

   ContextsBase over MCP

   The spec, data model, and test cases themselves, published.

CLAUDE.md is the file Claude Code reads before it does anything else. Put one at the repository root and it loads at the start of every session in that project. Claude Code also checks parent directories, and ~/.claude/CLAUDE.md for instructions you want in every project. Run /init inside Claude Code to scaffold a first version from your codebase.

# Project
Next.js 14 app router, TypeScript, Tailwind. Package manager is pnpm.

# Commands
- pnpm dev        starts the app on :3000
- pnpm test       unit tests
- pnpm e2e        Playwright, run before every PR

# Conventions
- Server components by default. Add "use client" only for event handlers.
- Never edit src/generated. Regenerate with pnpm codegen.

# Where things live
- Auth: src/lib/auth.ts   Billing: src/lib/stripe.ts
- Product specs: pulled from the contextsbase MCP server, not this file.

@docs/architecture.md

Nested CLAUDE.md files

A CLAUDE.md inside src/billing/ or packages/api/ is loaded when Claude starts reading or editing files in that folder. Use nested files for rules that only apply there. Keep the root file about the whole repo. For personal notes that should not be committed, use CLAUDE.local.md, which Claude Code reads alongside the shared file.

# src/billing
- Plans are free and premium. The column is users.plan_id.
  There is no tier field. Do not add one.
- Never call Stripe from a component. Go through lib/billing.
- Money is integer cents. Never a float.

Start any message with # and Claude Code treats it as something to remember rather than an instruction for the current task. It asks which memory file the note belongs in, so a repo convention lands in the shared CLAUDE.md and a personal preference lands in your own notes.

you › # We use pnpm, never npm. Playwright tests live in e2e/, not tests/.

  Where should this be saved?
  › Project memory (./CLAUDE.md)         shared with the team
    Local project memory (./CLAUDE.local.md)   just you, gitignored
    User memory (~/.claude/CLAUDE.md)     every project on this machine

✓ Saved to ./CLAUDE.md

Claude Code also keeps an auto-memory directory per project under ~/.claude/projects/. As you work, it writes down facts it learns, one file per fact, with a MEMORY.md index that loads at the start of each session. You can read and edit these files directly. They are plain markdown.

Model Context Protocol (MCP) is how Claude Code talks to outside systems. An MCP server exposes tools Claude can call mid-task. Instead of reading a description of your project up front, Claude asks a question at the moment it needs the answer. Adding a remote server over HTTP is one command:

claude mcp add --transport http contextsbase https://app.contextsbase.com/api/v1/mcp \
  --header "Authorization: Bearer mcp_live_••••••••••••••••••••••••"

By default the server is saved for you in this project only. Add --scope project to write it into a shared .mcp.json at the repository root, which is what you want for a team. Claude Code expands environment variables in that file, so the token never touches git:

{
  "mcpServers": {
    "contextsbase": {
      "type": "http",
      "url": "https://app.contextsbase.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${CONTEXTSBASE_TOKEN}" }
    }
  }
}

What a generic MCP server gives you

Most MCP servers are adapters: a Postgres server, a Notion server, a GitHub server, a filesystem server. They give Claude access to a system it could not otherwise reach. That is real progress over pasting, but access is not structure. Claude can now search your Notion. It still has to work out which of the four pages called “Password reset” is the current one.

Method 4 is method 3 with the right thing on the other end. ContextsBase is an MCP server whose contents are the spec itself: features with business rules, entities with fields and foreign keys, flows, and test cases written as Given / When / Then, ordered into iterations. You publish them once. Claude Code pulls exactly the one it is working on, builds it, runs the tests, and records what it did against which version of the spec. It connects with the same claude mcp add command from method 3.

• Publish a feature, its entities, and its tests. Functionality, business rules, edge cases. The entities it touches with their fields. Test cases as Given / When / Then. Claude only ever reads published features, so drafts stay invisible. F-3 ResetToken T-7, T-8
• Queue it in an iteration. An ordered list of features. Claude claims them one at a time, so two agents never take the same item. I-1
• Create an MCP token and add the server. Tokens carry scopes for read, write, and records. Run the command above, or commit the .mcp.json with the token in an environment variable.
• Give Claude one instruction. Implement iteration I-1. It calls the tools in order and reports each record back.

One instruction. Claude claims F-3, pulls the spec and tests, builds, and records the result over MCP.

Five tools do the work: list_iterations, next_iteration_item, get_feature_spec, record_test_automation, and record_feature_implementation. Each implementation record carries a fingerprint of the spec it was built from. Edit the feature later and the record turns Outdated, so the drift a markdown file hides is visible in one place. Keep your CLAUDE.md for conventions. Delete the spec you pasted into it.

CLAUDE.md is the right place for how to work in a repo. Teams get into trouble when they also use it as the product spec. The same three failures show up every time, and none of them is fixed by writing a longer file.

A spec has shape. Entities have fields. Rules have test cases. Features have a status that says whether they are ready to build. Markdown flattens all of that into paragraphs, and Claude does what any reader does with paragraphs: it interprets them. A knowledge base over MCP hands Claude the shape, one feature at a time.

“Loaded” is when the context enters the conversation. “Knows what was built” means the method records the outcome, not only the instructions.

Keep them layered. CLAUDE.md for how you code. Memory for what you keep correcting. ContextsBase for what you are building. A raw MCP server for data only the database knows. The same four methods exist for Cursor, with .cursor/rules in place of CLAUDE.md and .cursor/mcp.json in place of .mcp.json. That guide is How to give Cursor context about your project.