This post started because I wanted to give a presentation to our developers about Claude Code. Not "here's a cool AI tool," but something practical — so they'd know how to actually use it on our Sitecore projects instead of just throwing "fix this bug" at it and hoping for the best.
And as I was preparing, I realized the core message was simple: Claude inside your project is like an intern. A very fast, very well-read intern — but still an intern. You need to teach it. You need to guide it. You need to command it. If you don't give it context, conventions, and clear direction, it will produce work that's technically plausible but doesn't fit your project. Just like a new hire who hasn't been onboarded.
I've been using Claude Code for a while now — on this blog, on Sitecore XM Cloud projects, on PowerShell scripts, on Next.js components. And I've reached a point where I can say: the tool is genuinely useful, but only if you set it up properly. Otherwise you get inconsistent results that feel almost random — sometimes brilliant, sometimes frustrating. This post is about the practices that made the difference for me.
Stop treating it like a search engine
The mindset shift matters more than any feature. Claude isn't a smarter Google. It's closer to a pair programmer who has read your codebase — a reviewer who knows your conventions, an explainer who can walk you through unfamiliar code at your level. That changes how you use it.
You don't ask "how do I do X in React." You say "here's my component, here's the pattern we use, add a loading state." You give it context, conventions, and a concrete goal. The more it knows about your work, the more useful it becomes. I noticed this immediately on my Sitecore projects — the moment I stopped asking generic questions and started giving Claude the actual component code, the Sitecore wrapper, the serialization YAML, the answers went from "technically correct but useless" to "exactly what I needed."
Which surface for what
Claude ships across three surfaces, and using the wrong one is a common source of friction.
Claude.ai is the chat interface. Great for one-off questions, drafting, exploring ideas — anything that doesn't need your codebase. It doesn't see your files unless you paste them in. I use it when I'm brainstorming a blog post or thinking through an architecture decision before I touch the code.
Claude Code is the CLI and IDE extension. This is where the real development work lives. It can read files, run commands, search your codebase, edit code, and execute scripts. If you're doing anything that involves your repo — a Sitecore XM Cloud project, a Next.js app, PowerShell migration scripts — Claude Code is the right surface. Most developers should be here most of the time.
The API is for when you're building something on top of Claude — an internal tool, a pipeline, an agent. You get full programmatic control. This is the surface I used when I built my RAG-based Sitecore component assistant — the one where PMs can ask "which component do I use for the heading?" and get an answer from the actual documentation instead of pinging me.
Choosing the right model
Claude ships in three tiers: Haiku, Sonnet, and Opus. Picking the right one is about matching cost and capability to the task.
Haiku is fast and cheap. Use it for high-volume, lower-stakes tasks — summarizing logs, generating boilerplate, quick lookups. If you're building something with the API and running thousands of calls, Haiku is where you start.
Sonnet is the default for most work. It handles complex reasoning, large codebases, multi-step tasks, and nuanced instructions. For most Claude Code sessions — writing components, debugging Sitecore issues, reviewing serialization files — Sonnet is the right choice.
Opus is the most capable model. Use it when accuracy matters more than speed — thorough code reviews, architectural decisions, debugging subtle issues like those CSP frame-ancestors problems I wrote about. It's slower and more expensive, so don't reach for it by default. Escalate when the task warrants it.
The practical rule: start with Sonnet, escalate to Opus when you're not getting the quality you need.
The core loop: Plan → Context → Ask → Iterate
A good Claude Code session follows a simple pattern, and I've learned this the hard way — by wasting time when I skipped steps.
Plan first. Before you start editing code, use /plan or just describe what you're trying to accomplish. Claude can draft an approach, identify files it needs to read, and surface decisions you'll need to make. On a Sitecore project this is especially valuable — there are so many moving parts (the React component, the Sitecore wrapper, the component-map registration, the serialization module, the YAML files) that jumping straight to code usually means you'll miss something.
Set context. Claude's context window is finite. What you put in it determines what it can work with. The better your context — the right files, the right conventions, the right constraints — the better the output. When I'm working on a Sitecore component, I make sure Claude has seen the component, the wrapper, and at least one example of a similar component that follows our patterns.
Ask precisely. Vague prompts produce vague results. "Fix the bug" is less useful than "the modal closes before the API call resolves; here's the handler, here's the component." Specificity isn't about being pedantic — it's about giving Claude what it needs to be accurate.
Iterate. Claude Code is built for conversation. If the first output isn't right, don't start over — redirect. "That's close, but keep the existing error handling pattern" is a valid next message. Treat it like working with a colleague.
CLAUDE.md: your project's instruction set
CLAUDE.md is a markdown file Claude reads at the start of every session. Think of it as the onboarding doc you wish new teammates always read — conventions, commands, gotchas, and constraints that apply to this specific project.
What to put in it:
- Build and run commands.
npm run dev,yarn test, the script that seeds the database. Anything Claude might need to execute. - Coding conventions. File naming patterns, import order, the component structure your team has agreed on. On Sitecore XM Cloud projects this matters a lot — if your project uses a specific pattern for field rendering or variant files, say so explicitly.
- Known gotchas. Things that aren't obvious from the code. A workaround that looks wrong but is intentional. An edge case that's been handled and shouldn't be "fixed."
- What Claude shouldn't do. If there are refactors, patterns, or files that are off-limits, say so. Don't rely on Claude inferring restraint.
What to leave out:
- Everything that's already obvious from the codebase itself. CLAUDE.md isn't a README.
- Lengthy architectural explanations. Keep it actionable. Long files dilute the signal.
- Secrets, credentials, or environment variables. This file gets committed.
A good CLAUDE.md is short and specific. If yours is 500 lines, it's too long.
And here's the thing people miss: CLAUDE.md isn't a one-time setup. It's a living document — a work in progress. You write it once, and then you keep updating it as your project evolves, as you discover new gotchas, as your conventions change. Just like the intern analogy — you don't onboard someone on day one and never speak to them again. The intern becomes a junior, the junior becomes mid-level, and the guidance you give them changes over time. Same with Claude. The more you refine your CLAUDE.md, the sharper Claude gets on your project. Every correction, every added convention, every removed outdated rule makes the next session better than the last.
CLAUDE.md in subfolders: keep context scoped
One thing I learned quickly: a single root-level CLAUDE.md that tries to cover everything gets long and noisy. On a Sitecore XM Cloud project you've got React components, Sitecore wrappers, serialization YAML, PowerShell scripts — each with their own conventions and patterns. Putting all of that in one file means Claude loads everything every time, even when you're only working in one area.
The better approach: put a CLAUDE.md in each subfolder that needs specific guidance. When Claude reads and writes files in that folder, it picks up the local CLAUDE.md automatically — so it gets only the context that matters for the files it's touching. The root CLAUDE.md stays short with just the project-wide basics: build commands, high-level architecture, universal conventions. The subfolder files handle the specifics.
For example, in a Sitecore project you might have a CLAUDE.md in the serialization folder explaining the YAML structure and which GUIDs correspond to which template types. Another in the components folder describing the wrapper pattern and field rendering conventions. Another in the scripts folder with PowerShell-specific rules. Each one is small, focused, and only loaded when Claude is actually working in that area. Your intern gets exactly the right onboarding doc for the task at hand — not the entire employee handbook.
Context hygiene: keeping Claude sharp
Claude's context window fills up. When it does, early context gets compressed or dropped, and performance degrades. Managing context actively is one of the highest-leverage things you can do.
/clear resets the conversation entirely. Use it when you're switching tasks or starting something unrelated. A fresh context is often better than a bloated one.
/compact summarizes the conversation and compresses it, preserving the gist while freeing space. Use it mid-task when the conversation is long but you want to keep continuity.
/rewind rolls back the conversation to a previous state. Useful when a sequence of edits went sideways.
Subagents offload work without polluting your main context. When Claude spawns a subagent for a complex subtask, that work happens in a separate context window. The result comes back, but the intermediate thinking doesn't bloat your session.
The general principle: shorter, focused sessions outperform long sprawling ones. Reset early and often.
Power features worth knowing
Slash commands let you define reusable prompts for tasks you run repeatedly. They live in .claude/commands/ and surface as /command-name in the session. If you find yourself typing the same setup instructions repeatedly, make it a command.
Hooks are shell commands that run automatically on Claude Code events — before a tool call, after a file edit, when the session ends. They're configured in settings.json. Common uses: running a linter after every file save, enforcing a check before Claude runs a destructive command.
MCP (Model Context Protocol) lets Claude connect to external tools and data sources — databases, APIs, internal services. If your team has data Claude needs to reason about that isn't in the repo, MCP is the integration layer.
What this looks like on a real Sitecore project
Theory is fine. Let me show you what some of these practices produced on an actual Sitecore XM Cloud + Next.js project — a headless implementation with a component library, serialization pipelines, and a content team publishing regularly.
Scaffolding a complete component in minutes instead of hours
The biggest time sink in a Sitecore project is the ceremony around creating a new component: a React component, a Sitecore wrapper that maps CMS fields to props, a serialization module, and a dozen YAML files defining templates, renderings, and folder structure. The component-map registration happens during build, so that's not something you wire up manually — but everything else is on you.
We encoded all of that into a single /create-component command. A developer types the component name and a one-line description, answers two yes/no questions about interactivity and whether to generate the serialization now, and gets back a fully scaffolded, standards-compliant component — every file, correct GUIDs, correct field types inferred from the description.
What used to take the better part of an hour of copy-pasting and cross-referencing internal docs takes about 10 minutes. The key was encoding which system template GUIDs are correct for each file type (there are four, and using the wrong one silently creates the wrong item type in Sitecore) directly into the tooling, so developers can't get it wrong.
Three parallel code reviewers before every merge
We built a /review-branch command that diffs the current branch against develop, classifies every changed file into one of three categories — React components, Sitecore wrappers, or YAML serialization files — and spawns a specialist review agent for each category simultaneously.
Each agent checks against a different set of rules. The React reviewer flags things like using physical CSS properties (height) instead of logical ones (block-size), missing pointer-events: none on overlay elements, or SCSS class names in the wrong case. The Sitecore reviewer checks field rendering patterns and conditional logic. The YAML reviewer validates scope values and operation types.
All three run in parallel and return a prioritised list of violations. The whole review finishes in about two minutes on average, catches things that would slip through manual PR review, and consistently applies rules that used to live only in the most senior developer's head.
Classifying a hundred content articles automatically
The project publishes a large library of resources — whitepapers, case studies, blog posts, technical guides — each needing four taxonomy fields assigned (Type, Industry, Topic, Solution) for filtering to work. Each field is a Sitecore GUID, not a display label.
We built an agent that reads a resource's YAML file, infers the correct taxonomy from the title and content using domain-specific classification rules, and writes the correct GUIDs into the file. The rules encode real editorial decisions: a Case Study requires a named customer identifiable in the content; a Blog post expresses perspective or opinion, not research.
Running it across a hundred articles takes a couple of minutes. What would have been a week of manual work for a content editor became an afternoon.
Blocking .env reads at the harness level
We added a pre-tool hook in settings.json that intercepts any attempt to read a .env* file before the tool executes. If Claude tries to read one — during a debugging session, following an import chain, anything — the hook blocks it and logs the attempt.
It's four lines of shell script and a single settings entry. The protection runs at the tool invocation layer — before Claude even sees the file. .claudeignore would have been the intuitive place to put this. It would not have been the right one.
These aren't demos. They're the parts of the tooling that get used on every feature, every PR, every sprint.
Always human in the loop
This is the part I stress the most when I talk to other developers about Claude: you can never rely on everything being done correctly. Never. Not once. No matter how good the output looks, no matter how confident Claude sounds — you review everything. You are the senior developer in this relationship. Claude is the intern who writes fast and knows a lot of theory, but doesn't understand your project the way you do.
That means the human in the loop needs to actually be senior — someone who knows the codebase, knows the patterns, knows what right looks like. Someone who can glance at a diff and spot that Claude used the wrong field rendering approach, or generated a serialization file with an incorrect scope, or quietly introduced a pattern your team moved away from six months ago. If you can't easily correct what Claude produces, you shouldn't be letting it produce it unsupervised.
I've seen it go wrong both ways. Developers who blindly accept everything and ship bugs they would have caught with a 30-second review. And developers who don't trust it at all and spend more time second-guessing than they would have spent writing it themselves. The sweet spot is treating it like any other code review — you read it, you understand it, you approve or correct it. The speed gain comes from Claude writing the first draft, not from you skipping the review.
Common pitfalls
- Vague prompts. "Make this better" tells Claude nothing. Say what better means in this context.
- Bloated CLAUDE.md. More is not more. A 50-line CLAUDE.md that Claude actually reads beats a 500-line one that dilutes the important instructions.
- Letting context balloon. Long sessions with switching tasks and accumulated context produce worse results. Clear aggressively.
- Not using /plan. Jumping straight to implementation without a plan wastes tokens and produces code you'll rewrite. Plan first, especially for anything non-trivial.
- No CLAUDE.md at all. Without it, Claude starts every session from zero — guessing your conventions, your patterns, your project structure. Five minutes of setup saves hours of corrections.
- Accepting without reading. Claude writes confident-looking code that can be subtly wrong — a field rendered with the wrong helper, a YAML file with an incorrect scope. If you don't review the diff, you ship the bug.
- One giant conversation for everything. Switching from a React component to a PowerShell script to a serialization fix in the same session means Claude is carrying context from all three. Start a new session for unrelated tasks.
Closing thought
Claude Code rewards the developers who invest a small amount of setup. A good CLAUDE.md, disciplined context management, and a habit of planning before implementing — that's the difference between a tool that occasionally impresses you and one that becomes a genuine force multiplier.
The practices here aren't theoretical. They're the ones that hold up under real Sitecore development workloads — the same projects where I'm dealing with serialization conflicts, component library sprawl, and content teams that need answers yesterday.
Start with your CLAUDE.md. Keep it short and honest. Run /plan before your next feature. Clear context when you switch tasks. The rest follows.
