Claude Code Best Practices: A Developer's Guide (2026)

On this page · 16 sections▾

One-sentence definition
Why this repo exists
Mental model
Smallest end-to-end example
Deep dive: the six pieces
What I got wrong
Real-world workflow
Common mistakes
Context, cost, and the dumb zone
Who this is for
Community signal
The verdict
The bigger picture
FAQ
Glossary
All sources

One-sentence definition

Claude Code best practices is the discipline of orchestrating Claude through Commands, Agents, Skills, Hooks, MCP servers, and Memory — keeping each context small, each role focused, and the human in the review seat — so the agent ships production code instead of plausible-looking demos.

The shanraisshan/claude-code-best-practice repository is the most-cited consolidation of those patterns today — a curated knowledge base built on top of Anthropic’s docs, Boris Cherny’s tweets, and tips from the dev rel team and community. Stars in the tens of thousands, MIT-licensed, and refreshed almost weekly.

Why this repo exists

Claude Code shipped fast and grew faster. Anthropic’s docs cover what each feature does. Boris Cherny’s X account drops pattern-of-the-week tips. Engineers like Thariq, Cat Wu, and Dex publish their workflows on YouTube and personal blogs. The MLOps Community runs talks. Reddit’s r/ClaudeCode collects field reports. None of these surfaces talk to each other.

A developer trying to answer “how do I actually use Claude Code well?” in early 2026 had to read the docs, scroll Boris’ timeline, watch hour-long talks, and skim Reddit threads — then synthesize. The repo collapses that work into one page. Concepts table, hot features, an orchestration pattern, 82 tips with attribution, comparison of OSS Claude Code workflow methodologies, and a tutorial directory with runnable examples.

It is to Claude Code what the Twelve-Factor App was to web services — not invented by the platform team, but consolidated by a practitioner who got tired of the fragmented state of best practices.

This is a learning resource, not a tool

The repo is markdown-and-examples. Cloning it does not install anything actionable into your project — it gives you a map of what to do. The runnable parts (weather-orchestrator, agent examples, skills) are reference implementations to copy and adapt, not a framework to install. Treat it like the AWS Well-Architected Framework: read it, apply selectively to your project.

Mental model: the named pieces

Six concepts carry most of Claude Code. Once you know these, every doc page is a deeper read of one of them.

        YOU                              CLAUDE CODE SESSION
         │                                       │
         │ /command  ──────── injects prompt ───▶│
         │                                       │
         │                                  ┌────┴─────┐
         │            spawns subagent ─────▶│  AGENT   │ fresh context
         │                                  │          │ own tools
         │                                  │          │ own memory
         │                                  └────┬─────┘
         │                                       │
         │                          loads ──────▶│  SKILL  (just-in-time)
         │                                       │   docs/patterns/rules
         │                                       │
         │                          calls ──────▶│  MCP SERVER
         │                                       │   tools, resources
         │                                       │
         │                          fires ──────▶│  HOOK
         │                                       │   pre/post tool, prompt
         │                                       │
         │                          reads  ─────▶│  MEMORY
         │                                       │   CLAUDE.md + .claude/rules

Command — a slash command (/foo) that injects a prompt template into the current context. Cheap, simple, user-invoked.
Agent (subagent) — an autonomous actor spawned in a fresh isolated context with its own tools, permissions, and persistent identity. Use when work would pollute your main context.
Skill — a markdown file at .claude/skills/<name>/SKILL.md with YAML frontmatter. Auto-discoverable, progressively disclosed, loads only when relevant.
Hook — a user-defined handler that fires on events (PreToolUse, PostToolUse, UserPromptSubmit). Runs outside the agent loop — the place to put deterministic guardrails like “block all writes outside src/”.
MCP server — an external process that exposes tools and data over JSON-RPC. The “everything-else” layer that lets Claude touch databases, APIs, and services it doesn’t know about natively. (See our deep-dive at /blog/what-is-mcp.)
Memory — CLAUDE.md at the project root, plus .claude/rules/*.md files that auto-load. The instruction set Claude reads at every session start.

Smallest end-to-end example

The repo’s flagship example is a weather-orchestrator that shows the Command → Agent → Skill pattern end-to-end:

# Clone and explore
git clone https://github.com/shanraisshan/claude-code-best-practice
cd claude-code-best-practice

# Inspect the three files that compose the workflow
ls .claude/commands/weather-orchestrator.md   # the slash command
ls .claude/agents/weather-agent.md            # the subagent
ls .claude/skills/weather-fetcher/SKILL.md    # the skill

# Run it
claude
> /weather-orchestrator

# What happens:
# 1. Slash command injects a prompt template into your session
# 2. Template tells Claude to spawn the weather-agent subagent
# 3. Subagent spawns in a fresh context with its own tools
# 4. Subagent loads the weather-fetcher skill on demand
# 5. Subagent fetches weather, returns a summary to your main context
# 6. Your main context stays clean — only the final answer flows back

Reading the three markdown files takes about ten minutes. That ten minutes will teach you more about Claude Code than a day of reading the official docs, because you see the pieces in context, talking to each other.

Deep dive: the six pieces

Commands

A command is markdown at .claude/commands/<name>.md with optional YAML frontmatter. Invoke it with /<name>. The contents become a prompt template injected into your current session. Variables, conditional logic, and $ARGUMENTS placeholders are supported.

Opinion: use commands as workflow entry points, not for domain knowledge. If your command file is a wall of technical instructions, you wanted a skill. Commands should be short — “research the topic, plan, then dispatch agents X and Y” — and let skills carry the depth.

Agents (subagents)

Defined at .claude/agents/<name>.md. Each agent gets a fresh context window, can declare its own tool allowlist, model, and permissions. Boris Cherny’s rule of thumb: feature-specific subagents beat general “qa” or “backend engineer” agents. Specificity buys you better tool selection and tighter context.

Opinion: spawn an agent the moment a task would pollute your main context. The classic mistake is doing 20 file reads and 12 greps in your main session, then trying to plan with the noise still loaded. Spawn a research subagent, get a report back, plan with a clean context.

Skills

Skills live at .claude/skills/<name>/SKILL.md. The frontmatter has name, description, optional argument-hint, and an optional tools allowlist. Claude auto-discovers them and loads only the ones whose description matches the current task — progressive disclosure.

Skills are how you teach Claude project-specific patterns without bloating CLAUDE.md. Put your “here’s how we handle migrations” or “here’s our accessibility checklist” into skills, not CLAUDE.md, and they only load when relevant.

Opinion: write skills for any non-trivial repeated workflow. If you ever wrote the same instructions to Claude twice, that should have been a skill the first time.

Hooks

Hooks are user-defined handlers that fire on events: PreToolUse, PostToolUse, UserPromptSubmit, Notification, and more. They run outside the agent loop, so they’re the right place for deterministic guardrails — block writes outside the workspace, run a linter after every Edit, send notifications when long tasks finish.

Opinion: don’t put rules in CLAUDE.md that you can express as a hook. As davila7 put it: if you can make it deterministic via settings.json attribution or a hook, do — never write “NEVER add Co-Authored-By” in CLAUDE.md and hope for compliance.

MCP servers

MCP is the protocol Claude Code speaks to reach external tools. Configure servers in .mcp.json (project) or ~/.claude.json (global). Once registered, their tools appear to Claude as native callables. The repo treats MCP as a first-class concept, not an afterthought — see the best-practice file at best-practice/claude-mcp.md.

Opinion: scope MCP servers per-project, not global, unless they’re truly universal. A Linear MCP server makes sense globally; a custom internal API server belongs in .mcp.json next to the code that uses it. Every server in your global config consumes context tokens even when unused.

Memory

CLAUDE.md at project root is the canonical memory. .claude/rules/*.md auto-load too — use paths: in the frontmatter to lazy-load only when Claude touches matching files. The repo’s tip set is opinionated:

Boris: keep CLAUDE.md under 200 lines. Beyond that, the model deprioritizes parts of it.
HumanLayer’s production CLAUDE.md is 60 lines — and even that’s not 100% reliable.
Wrap critical rules in <important if="..."> tags so the model treats them as conditional must-follows, not background.

Opinion: any developer should be able to clone the repo, run claude, and have it work first try. If that fails, your CLAUDE.md is missing setup commands. That’s the test Dex Horthy uses.

What I got wrong

Three things I assumed about Claude Code and was burned by.

1. I thought one big CLAUDE.md was a feature, not a liability. I packed everything I knew about my project into 800 lines of CLAUDE.md and was surprised when Claude ignored half of it. The model deprioritizes long context. Splitting into .claude/rules/*.md with paths: globs and trimming CLAUDE.md to a 60-line spine made the model behave dramatically better on the same project.

2. I treated subagents as “Claude with extra steps.” Spawning subagents felt slower and more ceremony than just asking Claude directly. It is — and that is the point. The 20 file reads and 12 greps the subagent does stay in the subagent’s context, not yours. Your main context stays at 30% utilization for the whole session and the model stays sharp. Once I started spawning agents proactively for any research-heavy task, the dumb zone stopped being a regular visitor.

3. I thought “vibe coding” was the future. Just describe it, Claude builds it, ship it. It works for prototypes and falls apart at any scale where code review, type safety, and tests matter. Russ Poldrack’s “limits of vibe coding” piece is the most measured contrarian take I’ve read on this. Karpathy now uses “agentic engineering” for a reason: the human is oversight, not typist, but oversight is still the job.

Real-world workflow

Vibe-coding loop

Open Claude Code
“Add a feature that does X”
Watch it run, see broken output
“Fix it”
Repeat 4 until tests pass or you give up

Agentic loop

Research — spawn a subagent to read the relevant files and summarize. Main context stays clean.
Plan — start in plan mode. Have Claude propose phases with tests per phase.
Execute — let the agent run; subagents for any side quest.
Review — second Claude (or /codex review) on the diff.
Ship — open a PR; let GitHub Actions Code Review weigh in.

The Research → Plan → Execute → Review → Ship pattern is not novel. The repo’s contribution is showing how every Claude Code feature maps onto one of those stages. Plan mode for plan, subagents for research and review, hooks for guardrails during execute, scheduled tasks for long-running ship steps.

Common mistakes

CLAUDE.md grew past 200 lines

Root cause: every project quirk got dumped in. Fix: split into .claude/rules/*.md with paths: globs so each rule loads only when relevant. Boris and the HumanLayer team both push for ~60 lines as the target.

Babysitting the agent

Root cause: micromanaging implementation when Claude can just figure it out. Boris’ rule: “paste the bug, say fix, don’t micromanage how.” The repo’s 🚫👶 emoji flags the “do not babysit” tips.

Letting auto-compact fire

Root cause: ignoring context until it auto-compacts. The model is at its least intelligent point during auto-compact (already past the dumb zone). Fix: /compact manually with a hint earlier, or /clear + brief.

Correcting instead of rewinding

Root cause: when Claude takes a wrong turn, people add a correction prompt. Now both the failed attempt and the correction pollute context. Fix: double-Esc or /rewind to before the failure, re-prompt with what you learned. Thariq calls this “rewind > correct.”

One general “backend engineer” subagent

Root cause: agents are configured like job titles. Fix: feature-specific agents (one for migrations, one for the API layer) load smaller, more relevant context and pick better tools.

Context, cost, and the dumb zone

Claude Code performance is a context game. Concrete numbers from community measurements:

Dumb zone starts ~40% context. Dex’s rule of thumb: keep newcomer sessions under 40%, wrap up by 60%. Experienced users push under 30% aggressively, only let it climb to 60% on simple tasks.
Context rot ~300–400k tokens on the 1M model. Even the long-context model degrades materially past this band. Don’t let intelligence-sensitive work drift past.
Auto-compact is the worst point to compact. The model is already in the dumb zone when it fires. Pre-empt with manual /compact <hint> or /clear.
Subagents amortize tokens. 20 file reads + 12 greps in a subagent stay in the subagent — your main session sees only the final report. This is the single highest-leverage move for keeping main contexts small.
Skills load lazily. A repo with 50 skills only pays the token cost of the ones whose description matches the current task. Compose freely.

Who this is for, who it isn’t

Read this if

You use Claude Code daily and want the next 20%.
You’ve hit the dumb zone and want it explained.
You’re building team-shared workflows in .claude/.
You’re evaluating Claude Code vs Cursor / Codex.

Skip if

You’re only writing prototypes (vibe coding works fine there).
You haven’t installed Claude Code yet — start with the official docs first.
You want a copy-paste framework — this is patterns, not a kit.

Community signal

The repo trends regularly on GitHub. The Hacker News thread on Claude Code best practices pulled 600+ points and several hundred comments — most of the tips in the repo started life there or on Boris’ X timeline. Every Boris Cherny tweet on the topic is cited in the repo with the actual link, which makes it auditable rather than folkloric.

Andrej Karpathy’s observation that ~80% of his code is now agent-written gave the “agentic engineering” framing a serious bump. The repo runs with that — every workflow is opinionated about the human staying in oversight, not typist, mode.

The contrarian voice worth taking seriously is Russ Poldrack’s piece on the limits of vibe coding: AI-generated code is statistically “dirty” (unnecessary loops, conceptual errors that pass type checks), and the bug taxonomy has shifted from syntax-level to subtle conceptual. SonarSource’s 2026 benchmark has Opus 4.5 Thinking solving 83.6% of real engineering tasks — but the unsolved 16% trends toward the kind of bug a human review catches and an AI doesn’t.

The verdict

Our take

Read this repo. If you use Claude Code seriously, the Command → Agent → Skill orchestration pattern alone is worth the time, and the 82 attributed tips will save you weeks of trial-and-error.

Don’t mistake it for a framework — it’s a map. Adopt selectively: pick the patterns that match your team’s scale, and ignore the rest. The strongest move on day one is to apply the “CLAUDE.md ≤ 200 lines” rule, set up .claude/rules/*.md with paths: globs, and write your first skill for any workflow you’ve repeated twice.

The bigger picture

The shift from vibe coding to agentic engineering is the bigger story underneath this repo. In 2025, the question was “can AI write working code?” and the answer was “yes, small things, sometimes.” In 2026 the question is “how do you orchestrate AI to ship production code?” — and the answer is converging on a pattern most workflow methodologies (Superpowers, gstack, BMAD-METHOD, OpenSpec, Spec Kit, all linked from the repo) reinvent independently: research → plan → execute → review → ship, with the human as oversight at each gate.

Claude Code is the platform that exposes the right primitives to do this without rolling your own framework. The repo is the field manual for using those primitives well. Both will evolve fast — Anthropic ships features weekly, and the community ships consolidations like this one in response. Bet on the pattern, not on any specific tool.

Frequently asked questions

What is Claude Code, in one sentence?

Claude Code is Anthropic's terminal-based agentic coding tool — a CLI that reads your codebase, runs commands, edits files, opens PRs, and loops on failures, with a configurable workspace under .claude/ that scopes its memory, tools, and permissions to your project.

What is the difference between a Command, an Agent, and a Skill?

Commands are user-invoked prompt templates that inject context into the current session. Agents (subagents) are autonomous actors that run in a fresh, isolated context with their own tools and permissions. Skills are progressively-disclosed knowledge packs that load only when relevant. Use commands to start workflows, agents to fork work that needs context isolation, and skills to teach Claude domain-specific patterns on demand.

Why does Claude ignore my CLAUDE.md instructions?

CLAUDE.md grows past 200 lines and the model deprioritizes parts of it. Three fixes: keep CLAUDE.md under 200 lines, wrap critical rules in <important if="..."> tags, and split long instructions into .claude/rules/*.md with paths frontmatter so they only load when matching files are touched.

When should I start a new session vs. /compact the current one?

New session for genuinely new tasks — the dumb zone starts around 40% context use, and the 1M context model degrades around 300–400k tokens. /compact with a hint ("focus on auth refactor, drop test debugging") for mid-task continuation. /clear + a brief is more work but you control exactly what carries forward — use it before high-stakes next steps.

What is the Command → Agent → Skill orchestration pattern?

A workflow architecture where a slash command kicks off a job, dispatches one or more subagents that run in isolated contexts, and each subagent loads relevant skills on demand. The pattern keeps your main session clean (subagents absorb the noisy work), maximizes per-context intelligence (small focused contexts beat one bloated one), and makes workflows reusable across projects.

Are Claude Code Skills the same as MCP servers?

No. Skills are markdown instruction files in .claude/skills/<name>/SKILL.md that Claude reads as guidance — they tell the model what to do. MCP servers are executable processes Claude calls over JSON-RPC to actually do things (query a database, post to Slack). Skills are knowledge; MCP is action. They compose: a skill can instruct Claude to invoke MCP tools.

What is vibe coding, and why is it being replaced by agentic engineering?

Vibe coding is one-shot prompting with no plan, no review, no tests — "just describe it and ship." It works for prototypes and breaks at production scale. Agentic engineering, the term Karpathy and others now prefer, is orchestrating agents through a research → plan → execute → review → ship loop, with the human as oversight rather than typist. The shift maps to Claude Code's actual feature set: plan mode, subagents for review, hooks for automated checks, scheduled tasks for long-running loops.

Glossary

Claude Code

Anthropic's terminal-based agentic coding CLI.

Command

Slash-invoked prompt template at .claude/commands/<name>.md.

Subagent / Agent

Autonomous actor in fresh context at .claude/agents/<name>.md.

Skill

Auto-discovered knowledge pack at .claude/skills/<name>/SKILL.md.

Hook

Event handler that runs outside the agent loop (PreToolUse, etc.).

MCP server

External JSON-RPC server exposing tools to Claude Code.

CLAUDE.md

Project-root memory file auto-loaded every session.

.claude/rules/

Lazily-loaded rule files with paths globs.

Plan mode

Claude proposes a plan and waits for approval before executing.

Dumb zone

Performance degradation band starting around 40% context use.

Context rot

Quality drop on the 1M model past ~300–400k tokens.

Vibe coding

One-shot prompting with no plan or review — works for prototypes only.

Agentic engineering

Orchestrating agents through plan-execute-review with the human as oversight.

All sources

Primary

shanraisshan/claude-code-best-practice — the repository itself, MIT-licensed.
code.claude.com/docs — official Anthropic Claude Code documentation.
Boris Cherny on X — Anthropic engineer behind Claude Code; source of most workflow tips in the repo.
Andrej Karpathy on agentic engineering — the “80% of my code” tweet that named the era.
anthropics/claude-code — the underlying CLI itself.

Community

Critical / contrarian

Internal

What is MCP? A developer’s map (2026) — for the MCP layer of the Claude Code stack.
Browse agent skills on MCP.Directory
Claude Code client guide
Browse 3,000+ MCP servers
Best MCP servers for Claude Code

Claude Code Best Practices: From Vibe Coding to Agentic Engineering (2026)