Most developers are using Claude Code like a fancy autocomplete. Paste a bug, get a fix, repeat — never building on anything. This guide covers everything that separates that from actually using it: CLAUDE.md setup, plan mode, path-specific rules, CI/CD integration, and the workflow habits that compound over time.

TL;DR

  • Most developers use Claude Code as a one-shot Q&A tool — that’s the wrong mental model
  • CLAUDE.md is the most important file you’re not creating
  • Plan mode vs direct execution is the single biggest workflow unlock
  • Path-specific rules in .claude/rules/ apply conventions automatically across your whole codebase
  • The -p flag is non-negotiable for CI/CD pipelines
  • Custom slash commands turn repetitive prompting into one-liners

I want to tell you something uncomfortable: you’re probably wasting Claude Code.

Not maliciously. Not because you’re lazy. Because nobody told you how it actually works.

The default pattern most developers fall into is paste-and-pray. You drop in a bug. You get a fix. You paste in a feature request. You get some code. One question, one answer, repeat forever, never building on anything. It’s transactional. It’s shallow. And it leaves probably 80% of Claude Code’s actual capability completely untouched.

That’s not a knock — it’s genuinely how most people start. But if you’re still working that way six months in, that’s a problem. Because Claude Code isn’t a code suggestion engine. It’s an autonomous engineering partner that can read your entire codebase, understand your architecture, execute multi-step plans, run your test suite, debug failures, and ship features end to end.

The difference between a casual user and a power user isn’t talent or experience. It’s configuration, workflow, and knowing which features actually move the needle. Let’s go through all of it.

The File You Should Have Created on Day One

There’s a file that sits at the root of your project that will have more impact on your Claude Code results than anything else you do. Most people have never created it.

It’s called CLAUDE.md.

Without it, Claude Code is making educated guesses. It doesn’t know that your team uses camelCase for variables and PascalCase for components. It doesn’t know you prefer functional components over class components. It doesn’t know your API naming convention is verb-first. It doesn’t know you never use any-typed variables and you have strong feelings about it.

With a well-written CLAUDE.md, Claude Code follows your team’s standards automatically. Every file it touches, every function it writes, every test it generates — consistent, without you manually correcting it each time.

Here’s what belongs in yours:

  • Your tech stack and the specific versions that matter
  • Coding conventions and naming patterns your team actually uses
  • File structure — where things go and why
  • Testing requirements and what a “good test” looks like in your context
  • Error handling patterns you’ve standardized on
  • Common pitfalls specific to your codebase (the stuff that only makes sense after you’ve been burned)
  • Hard rules — things Claude should never do in this project

Spend 30 minutes writing this file. Seriously. That investment will save you thousands of manual corrections over the next year and keep a new team member’s Claude Code aligned with yours from day one.

The Three-Level Hierarchy (and Where Most Teams Go Wrong)

CLAUDE.md isn’t one file — it’s a hierarchy, and the level matters.

User-level

lives at ~/.claude/CLAUDE.md. This is personal. Your own preferences, shortcuts, your particular style. It’s not version controlled. Your teammates will never see it. This is the right place for things like “I prefer verbose variable names” or “always add JSDoc comments to exported functions.”

Project-level

lives at .claude/CLAUDE.md in your repo root. This is shared with your entire team through git. Team standards, architectural decisions, universal rules — this is where they live. If it affects how anyone on the team should use Claude Code in this project, it goes here.

Directory-level

lives inside specific directories and only applies when Claude Code is working on files in that location. Useful for sub-projects or modules with genuinely different conventions.

The mistake I see constantly: teams put shared rules in their user-level config, then wonder why the new developer’s Claude Code is producing code that doesn’t match team standards. The fix is always the same — move those rules to project-level and commit them.

Stop Sending Messages. Start Setting Mode.

This is the single change that will most immediately improve your output quality on complex work.

There are two modes:

direct execution

and plan mode. Most people default to direct execution for everything. That’s wrong.

Direct execution makes sense for tasks with clear, limited scope. Fix this specific bug. Add this validation. Rename this variable across the codebase. When the scope is narrow and the risk is contained, just let Claude Code work.

Plan mode is for everything bigger. Refactoring a module. Adding a feature that touches multiple files. Migrating from one pattern to another. Restructuring your test suite. Anything with architectural decisions baked into it.

In plan mode, Claude Code first creates a plan. It outlines what files it will touch, what changes it will make, and in what order. You review that plan before a single line of code is written. You can adjust steps, remove something you disagree with, or catch a misunderstanding before it propagates across a dozen files.

The rule I use: if the task touches more than two files or requires any architectural decision, plan mode. If you skip this on complex tasks, you will spend more time undoing things than you saved by starting fast.

Built-In Tools You’re Probably Not Using Correctly

Claude Code ships with a set of tools that most people either don’t know exist or misuse constantly.

Grep vs Glob

— these are not interchangeable. Grep searches file contents. Glob matches file paths. If you’re looking for where a function is called, use Grep. If you’re looking for all test files in a project, use Glob. Using the wrong one wastes time and produces confusing results. This distinction matters more than it looks.

Read, Write, Edit

— Edit is for targeted modifications using unique text matching. It’s fast and precise. When Edit fails because the text match isn’t unique enough, you fall back to Read plus Write — read the full file, then write the complete modified version. Know when each is appropriate. Reaching for Write when Edit would work is wasteful; reaching for Edit when the match is ambiguous causes silent bugs.

The /memory command

— this shows which memory files Claude Code has loaded into the current session. If Claude Code is behaving inconsistently or ignoring rules you’ve set, run /memory before assuming anything else. Nine times out of ten, the right context simply isn’t loaded.

Custom Slash Commands: Stop Prompting the Same Thing Twice

If you’ve typed the same prompt more than three times, you should have a slash command for it.

Create them in .claude/commands/ for shared team commands or ~/.claude/commands/ for personal ones.

A /review command that runs your team’s code review checklist. A /test command that generates tests following your specific patterns and coverage requirements. A /deploy-check command that verifies everything is ready before you push to production.

These take about 10 minutes to create per command. The return on that time is measured in hours per month of prompting you never have to do again. And because they’re in .claude/commands/, your whole team benefits from them automatically.

Skills vs CLAUDE.md: Context Engineering Done Right

There’s a distinction that trips up most intermediate Claude Code users.

CLAUDE.md is always loaded. Every session, every task, no exceptions. Universal standards go here.

Skills

are on-demand. They activate when invoked. Task-specific workflows belong here.

The mistake: loading task-specific procedures into CLAUDE.md. Your CLAUDE.md gets bloated. Claude Code gets confused by irrelevant context. You burn tokens on instructions that don’t apply to the current task.

The rule is clean: if it applies to every task, it belongs in CLAUDE.md. If it applies to a specific type of work — “here’s how we generate database migrations” or “here’s the process for writing integration tests” — make it a skill.

Path-Specific Rules: The Feature Teams Discover and Never Go Back From

This one consistently surprises developers who’ve been using Claude Code for months.

Create rule files in .claude/rules/ with YAML frontmatter specifying glob patterns:

--- paths: ["**/*.test.tsx"] --- All tests must use the arrange-act-assert pattern. Never mock the database layer directly. Use factory functions for test data, never inline object literals.

Those rules load automatically, and only when Claude Code is editing files that match the pattern. Every test file in your entire codebase — regardless of which directory it lives in — gets the same testing conventions applied without you having to do anything.

This is dramatically more powerful than directory-level CLAUDE.md because it works based on what the file is, not where it lives. You write the rule once and it applies everywhere the pattern matches.

CI/CD Integration: Automating the Work That Shouldn’t Be Manual

At some point, Claude Code stops being a tool you use and starts being infrastructure that runs without you.

The key flag is -p. This runs Claude Code in non-interactive mode. Without it, your CI job hangs forever waiting for input that will never come. If you’re integrating Claude Code into any pipeline, this flag is not optional.

Pair it with --output-format json and --json-schema to get machine-parseable structured output. Your CI system can then post findings as inline PR comments automatically — no human in the loop.

One important principle here: the same Claude Code session that generated the code is less effective at reviewing it. It carries reasoning context that creates bias toward its own decisions. For code review in CI, always use an independent review instance. This isn’t a quirk — it’s a meaningful quality difference.

What does this look like in practice? Automated security review on every PR. Test generation for code paths that aren’t covered. Documentation updates that happen automatically when the implementation changes. All posted as comments, reviewable by your team, without anyone having to remember to run anything.

What a Power User Day Actually Looks Like

Morning: you open your terminal. Claude Code loads your CLAUDE.md and the relevant path-specific rules automatically. You describe the first feature in plain English. Claude Code creates a plan. You review it, adjust one step, approve. It executes across eight files, writes tests, runs them, fixes two failures, and commits.

Afternoon: you’re reviewing a PR. Instead of reading every line yourself, you run /review. Claude Code checks against your team’s standards, flags three issues, explains why each matters. You address the one real issue and approve the rest.

End of day: your CI pipeline runs Claude Code with the -p flag on every new PR. The review happens automatically. PR comments appear. Your team sees them in the morning.

That’s not a vision of the future. That’s what developers who’ve done this setup are running today.

The Bottom Line

Claude Code is one of the most capable developer tools available right now. It’s also one of the most underused — not because of its limitations, but because of how most people approach it.

The gap between using it casually and using it like a power user isn’t months of learning. It’s a few days of intentional setup and practice.

Configure your CLAUDE.md. Learn plan mode. Build custom commands. Use path-specific rules. Integrate it into CI. Those five things will compound.

Most developers will keep pasting one-off questions and getting one-off answers. The ones who build a real system around it will be operating at a completely different level within 30 days.

FAQ

What is CLAUDE.md and why does it matter?


CLAUDE.md is a configuration file that sits at your project root and tells Claude Code about your codebase conventions, patterns, and rules. Without it, Claude Code makes generic assumptions. With a well-written one, it follows your team’s standards automatically across every file it touches.

What’s the difference between plan mode and direct execution in Claude Code?


Direct execution is for narrow, well-defined tasks like fixing a specific bug. Plan mode first generates a step-by-step plan for you to review before any code is written. Use plan mode any time a task touches more than two files or involves architectural decisions.

How do path-specific rules work in Claude Code?


You create rule files in .claude/rules/ with YAML frontmatter containing glob patterns. Rules in those files automatically load whenever Claude Code edits a file matching the pattern — across your entire codebase, regardless of directory structure.

What is the -p flag in Claude Code?


The -p flag runs Claude Code in non-interactive (headless) mode. It’s required for CI/CD pipeline integration — without it, automated jobs hang indefinitely waiting for user input.

Should I use CLAUDE.md or skills for task-specific workflows?


Use CLAUDE.md for universal rules that apply to every task in the project. Use skills for specific workflows — like how to generate migrations or write integration tests — that only apply in certain contexts. Mixing these up leads to a bloated CLAUDE.md and confused output.

Can Claude Code review its own code in CI?


Technically yes, but it’s less effective. A Claude Code session retains reasoning context from code it generated, which introduces bias. For CI code review, always use an independent instance that has no context from the generation session.

Claude Code Official Docs

— https://code.claude.com/docs/en/overview

Claude Code GitHub Repo

— https://github.com/anthropics/claude-code

  • Claude Code Releases (GitHub)

    — https://github.com/anthropics/claude-code/releases

  • Anthropic API Docs

    — https://platform.claude.com/docs/en/home