Claude Code Guide
Stop Re-Explaining Your Codebase Every Session
Persistent context that makes Claude a real teammate
Claude Code Projects let you save instructions, files, and context that persist across conversations — turning Claude from a one-shot tool into a teammate that knows your codebase. Instead of re-explaining your stack, conventions, and architecture every session, you define it once and Claude remembers.
Core Concept
What Are Claude Projects?
A Claude Project is a persistent workspace where you store context that Claude loads automatically at the start of every conversation. Think of it as Claude's long-term memory for a specific codebase, client, or domain.
Projects have three layers of persistence. Project Knowledge is the file layer — upload code files, documentation, specs, or any reference material Claude should understand. Custom Instructions define how Claude should behave — your coding standards, preferred frameworks, tone, and constraints. Conversation History within a project stays accessible, so you can reference past decisions.
In Claude Code (the terminal CLI), this concept maps to CLAUDE.md— a markdown file at your project root that Claude reads on every session start. CLAUDE.md serves the same purpose as project custom instructions: it tells Claude who you are, what you're building, and how you want the code written. The difference is that CLAUDE.md lives in your repo, version-controlled alongside your code.
Step by Step
Setting Up Your First Project
Create a CLAUDE.md in your repo root
This is your project's instruction file. Start with three sections: your tech stack (e.g., "Next.js 15, TypeScript, Supabase, Tailwind"), your key conventions (e.g., "Server Components by default, Client Components only when state is needed"), and your testing requirements (e.g., "All API routes must have integration tests").
Add project knowledge files
In claude.ai, upload files that Claude should reference — your API schema, database ERD, style guide, or architecture docs. In Claude Code, these files are already available since Claude can read your entire project tree. For critical files, reference them explicitly in CLAUDE.md so Claude prioritizes them.
Write custom instructions
Be specific and operational. Instead of "write clean code," say "use explicit return types on all exported functions" or "never use any — use unknown with type narrowing." Claude follows concrete rules more reliably than vague guidance.
Test with a real task
Give Claude a task you've done recently — something where you know what good output looks like. Compare the result with and without project context. If the output misses your conventions, tighten the instructions.
Expert Tips
Best Practices for Claude Projects
Your CLAUDE.md should be a lean reference, not a novel. Include your stack, conventions, file structure overview, and testing requirements. If it exceeds 500 lines, split detail into topic-specific files and reference them.
Include 2-3 files that show your coding style — a well-structured component, a service module, a test file. Claude extrapolates patterns from examples more effectively than from written rules alone.
Negative constraints are powerful. "Never use any type — use unknown + narrowing" or "No string concatenation in SQL" prevents the most common AI missteps. Claude follows explicit prohibitions reliably.
When you make architectural decisions, update your project knowledge. A living context file produces better results than a stale one. Treat project context like documentation — it rots if you ignore it.
Side by Side
Projects vs. Plain Claude
The difference is stark. With a well-configured project, Claude produces code that matches your existing patterns on the first try. Without it, you spend half your session correcting style, conventions, and architecture mismatches.
What a CLAUDE.md looks like
Common Questions
Frequently Asked Questions
What are the file limits for Claude Projects?
Claude Projects can hold up to 200K tokens of project knowledge — roughly equivalent to a 500-page book or a medium-sized codebase. Files are processed when added, so Claude understands their content contextually rather than treating them as raw text.
Can I share a Claude Project with my team?
Yes. On Claude Team and Enterprise plans, projects can be shared across your organization. Team members see the same project knowledge and custom instructions, ensuring consistent AI behavior across the team. On Pro plans, projects are private to your account.
Can I have multiple projects for different codebases?
Absolutely. You can create as many projects as you need — one per repo, one per client, one per feature branch. Each project maintains its own context, instructions, and knowledge base independently.
Do Claude Projects work with the API?
Projects are a feature of claude.ai and the Claude desktop apps. For API usage, you achieve similar persistence through system prompts and the CLAUDE.md file in Claude Code. The ChatGPT Codex CLI automatically loads CLAUDE.md at the start of every session, giving you project-like persistence in terminal workflows.
Master Claude Projects
Your first persistent project. 20 minutes.