/ Blog
Home Blog Contact Buddy Ads Builder Audit Engine

The Complete Guide to Claude Code V2: CLAUDE.md ...

Claude & Anthropic

Claude Code V2 with a well-structured CLAUDE.md file, a curated MCP server stack, and custom slash commands is one of the most capable AI-assisted development setups available. CLAUDE.md acts as persistent project memory loaded at every session; MCP servers extend Claude's reach to files, databases, and live documentation; and custom commands encode repeatable workflows so they run consistently without drift.

Key takeaways

  • CLAUDE.md is a markdown file at your project root that loads automatically into context every session — treat it as a persistent system prompt, not aspirational documentation.
  • Context7 is the highest-priority MCP server to install first because it fetches live library documentation, eliminating hallucinated method signatures from stale training data.
  • Custom slash commands in .claude/commands/ make repeatable workflows consistent across every developer and agent on the project — human or AI.
  • Multi-agent orchestrator-subagent patterns require explicit inter-agent handoff formats from the start; vague handoffs are the most common reason these systems break down.
  • Treat CLAUDE.md and your .claude/commands/ directory as engineering infrastructure: version-control them, review them like code, and update them as the project evolves.
Key terms
CLAUDE.md
A markdown file at the root of a Claude Code project that loads automatically into context every session, acting as persistent project memory and a system prompt.
MCP Server
An external process Claude Code connects to via the Model Context Protocol, giving Claude capabilities like file access, web search, and live documentation retrieval beyond text generation.
Custom Slash Command
A named, repeatable workflow defined in a markdown file inside .claude/commands/ that Claude Code executes consistently every time it is invoked.
Orchestrator-Subagent Pattern
A multi-agent architecture where one Claude Code instance plans and delegates tasks to specialized subagents that each handle a distinct part of the workflow.
Context Window
The maximum amount of text (tokens) a language model can process in a single session; managing what gets passed between agents is critical to avoiding degraded outputs.

What is CLAUDE.md and why does it matter for Claude Code?

CLAUDE.md is Claude Code's project memory file — a markdown document that sits at the root of your project and is automatically loaded into context at the start of every session. [1] Without it, Claude Code starts cold every time. With a well-crafted one, it starts as a senior engineer who already knows your stack, your conventions, your constraints, and your current goals.

A practical question that came up in the r/ClaudeAI community thread on this topic is how much to put in CLAUDE.md versus handling through in-session prompting. The answer practitioners have landed on: anything you'd need to re-explain more than once goes into CLAUDE.md; anything you'd say once in a session stays in the session. That mental model keeps the file lean and genuinely useful.

Common Mistake: Writing CLAUDE.md for what your project will eventually be rather than what it is today. Files with hundreds of words of aspirational architecture that don't reflect the actual codebase cause Claude to diverge from your real code. Keep it honest and update it as the project evolves.

The anatomy of a production CLAUDE.md

A production CLAUDE.md is structured information Claude can parse quickly, not a wall of text. Here are the sections worth including:

Key Insight: The "Current Sprint" section is the most underused element of CLAUDE.md. A three-sentence summary of your active work takes 60 seconds to update and eliminates the 5–10 minutes of re-orientation that otherwise happens at the start of every session. Over a week, that's 30 or more minutes returned.

Extra sections for AI agent projects

For agent-focused projects — like Buddy, the open-source Google Ads agent — the CLAUDE.md needs sections most tutorials skip:

Which MCP servers should you actually install?

MCP servers are external processes that Claude Code connects to, giving it capabilities beyond text generation — reading files, querying databases, browsing documentation, calling APIs, and manipulating browser state. [2] The value depends entirely on which servers you configure and how. Think of them as Claude's hands: without them, it can think and write; with them, it can act.

For a deeper look at how these pieces fit together, see what's the difference between Claude Code and MCP.

MCP Server What It Does Best For Priority
Context7 Fetches live documentation for libraries & frameworks Any project using actively-updated dependencies Essential
Filesystem Read/write files outside the working directory Multi-repo work, config management Essential
Brave Search Real-time web search from within Claude Code Research, error diagnosis, checking current APIs High
GitHub PR creation, issue management, repo operations Teams, open-source projects High
Puppeteer / Playwright Browser automation & scraping Testing, data collection, UI validation Medium
PostgreSQL / SQLite Direct database querying Data-heavy applications Project-specific

Why Context7 deserves to be your first install

AI coding assistants have a training data cutoff, and libraries like the Google Ads API, LangChain, or Next.js change fast enough that hallucinated method signatures and deprecated patterns are a recurring problem. [3] Context7 solves this by fetching up-to-date documentation dynamically when Claude needs it, rather than relying on potentially stale training data.

In practice — working on Google Ads API integrations — this has meaningfully reduced debugging cycles on dependencies that change quarterly. I'd estimate 40–60% fewer "why isn't this method working" cycles on fast-moving libraries, based on my own project experience.

Best Practice: After installing Context7, add an explicit instruction to your CLAUDE.md: "Before implementing any third-party library functionality, use Context7 to fetch current documentation rather than relying on training data." This creates a consistent retrieval habit across all sessions without needing to re-prompt it each time.

For step-by-step MCP configuration guidance, setting up MCP servers in Claude Code covers the installation ritual in detail.

How do custom slash commands work in Claude Code?

Custom slash commands let you define repeatable workflows as named commands that Claude executes consistently — every time, without drift. [1] Commands live in .claude/commands/ at your project root, or ~/.claude/commands/ for global commands. Each command is a markdown file: the filename becomes the command name, and the content is the instruction set Claude follows.

A file at .claude/commands/review-pr.md becomes /project:review-pr in your Claude Code session.

Commands that deliver real workflow value

Key Insight: The value of custom commands isn't just convenience — it's consistency. When every developer on the team (human or AI) follows the same /project:test-and-fix process, you get predictable, auditable behavior instead of improvised solutions. This matters most in agentic workflows.

Command design principles

For more on building durable Claude Code workflows, see my best workflow for working with Claude Code.

How do multi-agent patterns work with Claude Code?

Once CLAUDE.md and MCP servers are in place, the next level is orchestrating multiple Claude Code instances as specialized agents that hand work off to each other. The most reliable pattern is one orchestrator instance that plans and delegates, paired with specialized subagents that execute. [1]

The orchestrator-subagent pattern

In the Buddy Google Ads agent specifically, this pattern runs as: a planning agent that interprets campaign performance data and decides what optimizations to propose, an implementation agent that writes the API calls [4], and a validation agent that checks proposed changes against account rules before anything reaches a human approval queue.

Best Practice: Give each subagent a separate CLAUDE.md or append agent-specific instructions to the shared one under clearly labeled headers. An agent that only reviews code should know it has no write permissions — and that constraint should live in its context, not just in your workflow design.

Where multi-agent setups break down

Common Mistake: Building multi-agent systems without explicit handoff formats. When your orchestrator passes a task to a builder agent, the output format must be structured and predictable. Define JSON schemas or markdown templates for inter-agent communication from the start — not as an afterthought when things break.

Context window management is the other common failure mode. Each agent in a long chain accumulates context, and without active management you'll hit limits or get degraded outputs. The practical fix: summarize outputs before passing them forward. Don't pass 2,000 tokens of test output to the next agent — pass a 200-token structured summary with the full output stored to a file the agent can reference if needed.

For more on dynamic handoff patterns, see dynamic workflows in Claude Code.

How does this apply to marketing and advertising workflows?

Claude Code V2 configured this way isn't only a developer tool — it's infrastructure for building the custom AI tooling that marketing campaigns actually need. Generic AI tools are built for median use cases. Your Google Ads account structure, your creative testing methodology, your attribution model — none of that is median.

A marketing technologist or technical account manager with this setup can build:

The CLAUDE.md for a marketing-focused project should include your attribution model, your KPI hierarchy (ROAS, CPA, impression share — whichever drives decisions), your account structure conventions, and references to the platform API documentation your agents will need. [4] MCP servers like a Google Ads API integration or a custom reporting database connector become your agent's data access layer.

If you're exploring what production advertising agents look like end-to-end, getting started with Buddy walks through a real example built on exactly this stack.

What to do next

  1. Create your CLAUDE.md today. Even a rough draft covering your stack, conventions, and current focus is dramatically better than nothing. Block 20 minutes, write it, commit it, and refine it next week.
  2. Install Context7 as your first MCP server. Configure it, add the retrieval instruction to your CLAUDE.md, and spend one session testing it on a real library you're actively working with.
  3. Build three custom commands for your most repeated workflows. Look at what you re-explain to Claude most often — that's your command backlog. Start with those three and add them to version control immediately.
  4. Design one multi-agent workflow on paper before automating it. Map the orchestrator and subagent roles, define the handoff formats, then implement. The planning phase catches the majority of problems that kill multi-agent projects.
  5. Treat the whole setup as engineering infrastructure. CLAUDE.md, your .claude/commands/ directory, and your MCP configuration should all live in your repo, be reviewed like code, and evolve deliberately alongside the project.

Frequently asked questions

How long should a CLAUDE.md file be?

There is no fixed limit, but production CLAUDE.md files typically run 300–600 words. The goal is structured information Claude can parse quickly, not comprehensive documentation. If a section wouldn't change how Claude behaves in a session, it probably doesn't belong in the file. Err on the side of shorter and accurate over longer and aspirational.

Do MCP servers increase Claude API costs?

MCP servers themselves don't directly add to Claude API costs — they're external processes that supply information. However, the data they return (fetched documentation, search results, file contents) gets added to your context window, which does consume tokens. In agentic workflows where token costs matter, this is worth tracking and is exactly why a "cost-estimate" custom command is worth building early.

Can custom commands be shared across projects?

Yes. Commands placed in ~/.claude/commands/ are available globally across all your Claude Code projects. Commands in .claude/commands/ at the project root are project-specific. A practical approach is to keep generic commands (security checks, changelog generation) global, and keep project-specific workflow commands (API audits, agent-specific steps) local to the repo.

How do you prevent a subagent from taking actions it shouldn't?

The most reliable approach is layered constraints: encode the agent's boundaries explicitly in its CLAUDE.md context, design MCP server access so it only has the permissions it needs (a reviewer agent shouldn't have GitHub write access), and define human-in-the-loop triggers as a named list in the agent's instructions. Constraints that live only in workflow design — not in context — tend to erode over long sessions.

Is Claude Code V2 suitable for non-developers, like marketing managers?

A technical marketing manager or marketing technologist comfortable with code editors can absolutely use Claude Code V2 effectively. The CLAUDE.md and custom command setup does require some initial configuration, but once in place the day-to-day experience is closer to directing an engineer than writing code. For purely non-technical users, a purpose-built agent interface is likely a better starting point than raw Claude Code.

How often should CLAUDE.md be updated?

The "Current Sprint / Active Context" section should be updated weekly at minimum — it has the highest decay rate. Tech stack and convention sections change less often but should be reviewed at the start of any new project phase. A practical habit: make updating CLAUDE.md part of your sprint planning or weekly review, the same way you'd update a README after a significant architectural decision.

References

  1. Anthropic. “Claude Code overview.” Accessed Nov 2, 2026.
  2. Model Context Protocol. “What is the Model Context Protocol (MCP)?.” Accessed Nov 2, 2026.
  3. Wikipedia. “Large language model.” Accessed Nov 2, 2026.
  4. Google for Developers. “Introduction to the Google Ads API.” Accessed Nov 2, 2026.
  5. Original community discussion: r/ClaudeAI thread on Reddit.

Related Reading

AI Disclosure: This article was generated with AI assistance based on a community discussion on Reddit r/ClaudeAI. Expert analysis and practitioner perspective by John Williams, Founder, AHMEEGO · Google Ads Practitioner with $350M+ in managed Google Ads spend. AI was used to draft and structure the content; all strategic recommendations reflect real campaign experience.