Claude Code best practices (learned the hard way)

The first month I used Claude Code, I treated it like a faster autocomplete. I dropped it into a repo, told it to "clean up the auth module," and walked away. It rewrote three files I never asked it to touch, deleted a test I needed, and confidently told me the build passed. The build did not pass. I had not given it a way to check.

That month taught me that Claude Code is not a smarter chatbot, it is an agent that reads files, runs commands, and edits your code on its own. The skill is not prompting. It is building the rails the agent runs on. If you want that rigor written down as reusable skills, Claude Fable 5 wrote six of them during its free-access window. Below are the eight habits I actually use now, and for each one I name the specific failure it prevents, because I hit every one of these failures before I learned the fix. If you want the gentle on-ramp first, my Claude Code 101 guide for knowledge workers covers the basics. This post is the layer above that: what to do once it is installed and you want it to be reliable.

Two quick notes before the practices. Everything here is checked against the official Claude Code docs as of mid-2026, because the tool ships fast and half the advice online is already stale. And pricing is current as of mid-2026 and moves often, so confirm before you commit.

Claude Code best practices: the eight habits that matter

I am ordering these by leverage, not by difficulty. The first three are setup you do once and benefit from forever. The middle three are how you run a session so it stays trustworthy. The last two are guardrails that keep a fast agent from doing something you regret. None of them require you to be an engineer. If you can write a few lines of markdown and read a diff, you can do all eight.

Here is the short version, then the detail.

1. Give Claude a CLAUDE.md it reads every session.
2. Scope the context, do not dump the whole repo.
3. Use plan mode before you let it edit.
4. Fan big, independent work out to subagents.
5. Lock down permissions with allowlists and hooks.
6. Verify, do not trust. Run it, read the diff.
7. Wire up MCP servers for real tools and memory.
8. Practice secret hygiene. Never paste keys.

Practice 1: give Claude a CLAUDE.md it reads every session

The failure it fixes: re-explaining your project at the start of every single session. Without a memory file, Claude starts each conversation with a blank context window. It does not know your stack, your conventions, or the decision you made yesterday. So you re-type it, the agent half-follows it, and you correct the same mistakes again next session.

The fix is a CLAUDE.md file. It is a plain markdown file that Claude reads at the start of every conversation, and it is the single highest-leverage thing you can set up. You can put one at the project root (./CLAUDE.md, checked into git so your team shares it), one in your home folder (~/.claude/CLAUDE.md, applied to every project on your machine), and a private ./CLAUDE.local.md you keep out of version control. They all load at launch.

What goes in it: the commands Claude cannot guess, the code style that differs from defaults, your testing setup, your branch and PR conventions, and the architectural decisions specific to your project. What stays out: anything Claude can figure out by reading the code, standard language conventions, and long tutorials. The official guidance is to keep each file under about 200 lines and to ask of every line, "would removing this cause Claude to make a mistake?" If not, cut it. A bloated CLAUDE.md is worse than a short one, because the important rules get lost in the noise and the agent starts ignoring half of it.

Two shortcuts I lean on. Run /init in a new project and Claude analyzes the codebase and drafts a starter file for you, then you refine it. And modern Claude Code also keeps its own auto memory, notes it writes for itself based on your corrections, stored per-repository, which you can inspect any time with the /memory command. The combination is the loop in the diagram above: the session reads your memory file, does the work, writes back what it learned, and the next session starts smarter than the last. I go deep on building this layer into your daily setup in how to build a second brain in Claude Code, and the same idea powers Iwo's Second Brain as a ready template instead of a blank file.

Practice 2: scope the context, do not dump the whole repo

The failure it fixes: a full context window and a degraded agent. Claude's context window holds the entire conversation, including every file it reads and every command it runs. It fills up faster than you expect, and performance drops as it fills. The classic mistake, and one I made constantly, is telling Claude to "investigate the codebase" with no boundary. It reads two hundred files, the context is now mostly noise, and the actual task suffers.

The discipline is to give Claude the specific context the task needs and nothing more. Reference exact files with @ instead of describing where code lives. Point it at the one example pattern you want it to follow. Describe the symptom, the likely location, and what "fixed" looks like, rather than a vague "fix the login bug." The official before-and-after is stark: "add tests for foo.py" becomes "write a test for foo.py covering the case where the user is logged out, avoid mocks." The second prompt produces a usable result on the first try.

Two habits keep context clean across a longer session. Use /clear between unrelated tasks so old context does not bleed into new work. And when the agent has gone down a wrong path twice, do not keep correcting, clear and restart with a sharper prompt that folds in what you learned. A fresh session with a better prompt almost always beats a long session full of failed attempts. This idea, that the files and context you load are the real instruction, is the thread running through my whole approach to AI productivity systems for 2026.

Practice 3: use plan mode before you let it edit

The failure it fixes: Claude solving the wrong problem at full speed. Letting the agent jump straight to editing is how you get a plausible-looking change that misses the point, or a refactor that touches files you never wanted touched. By the time you notice, it has already written to disk.

Plan mode is the guardrail. In plan mode Claude reads files and proposes a written plan but makes no edits, because the write tools are physically unavailable. It is a hard read-only sandbox enforced at the tool level, not a polite suggestion. You toggle into it with Shift+Tab, review the plan it produces, and only switch out and approve when the approach is right. You can even open the plan in your editor to tweak it before the agent proceeds.

The workflow Anthropic recommends is explore, then plan, then code. First, in plan mode, ask Claude to read the relevant code and explain how it works. Then ask it to produce a detailed implementation plan: which files change, what the flow is, what could break. Then switch out of plan mode and let it implement against that plan. The planning step forces the agent to surface dependencies before it touches anything, which is exactly where the "wrong problem" failures get caught.

When to skip it: small, obvious changes. If you could describe the diff in one sentence, like fixing a typo or adding a log line, planning is just overhead, so ask Claude to do it directly. Plan mode earns its cost when the change spans multiple files, when you are unsure of the approach, or when you are working in code you do not know well. For more of these session-level moves, the engineers on my list will get more from Claude Code advanced tips for engineers.

Practice 4: fan big, independent work out to subagents

The failure it fixes: one agent trying to hold a huge job in one context window, and losing the thread halfway through. When a task means reading dozens of files or running several independent investigations, doing it all in your main conversation floods the context with material you will never reference again, and the quality drops.

Subagents are the answer. Each subagent runs in its own separate context window, with its own tools and permissions, does its piece of work, and reports back only a summary. The exploration never clutters your main conversation. Claude Code ships with built-in ones (an Explore agent for fast read-only search, a Plan agent, and a general-purpose agent), and you can define your own in .claude/agents/ as small markdown files. The simplest way to use them is to just say so: "use subagents to investigate how our auth handles token refresh," or "use a subagent to review this code for edge cases."

The pattern in the diagram above, one lead delegating out and collecting results, is also how you handle big batch jobs without melting a single session. For a large migration, you have Claude list every file that needs changing, then loop a non-interactive command over the list, one invocation per file, each scoped with an allowlist so it can only do the safe operations. The official shape is a shell loop calling claude -p "migrate $file..." --allowedTools "Edit,Bash(git commit *)". Test it on two or three files, refine the prompt, then run it across all of them. This is the frontier of getting real work out of agents without writing the code yourself, which I cover more broadly in my guide to coding agents for knowledge workers.

Practice 5: lock down permissions with allowlists and hooks

The failure it fixes: two opposite problems at once. Either you are clicking "approve" on every single action until you stop actually reading them, or you have handed the agent broad permission and it runs something destructive unattended. Both are bad. The goal is fewer prompts AND tighter control, and you get both with the same tools.

By default Claude asks permission before anything that could modify your system. To cut the noise without losing the safety, use /permissions to allowlist the specific commands you already trust, like npm run lint or git commit. For the things that must NEVER happen, deny them outright. And for batch or unattended runs, the --allowedTools flag restricts exactly what the agent can do, which is the difference between a safe overnight job and a scary one.

Hooks are the deterministic layer on top. A hook is a shell command Claude Code runs automatically at a fixed point in its lifecycle, configured in .claude/settings.json. Unlike a CLAUDE.md rule, which the model may or may not follow, a hook always fires. A PreToolUse hook can block an action before it runs, for example blocking any write to your migrations/ folder. A PostToolUse hook can run a formatter or linter automatically after every edit. You can even ask Claude to write the hook for you. The whole point: the rules you cannot afford to have the model "forget" should be code, not advice. This combination of allowlists, deny rules, and hooks is what makes a fast agent something you can leave running.

Practice 6: verify, do not trust. Run it, read the diff

The failure it fixes: the trust-then-verify gap. Claude produces a clean-looking implementation, tells you it works, and the edge case it missed ships to production. This was my very first mistake, the auth cleanup that "passed" a build it never ran. An agent stops when the work LOOKS done, and without a check it can run, "looks done" is the only signal it has.

The fix is to give Claude something that returns a pass or fail it can read: a test suite, a build exit code, a linter, or a screenshot to compare against a design. Once that check exists, the loop closes on its own. The agent does the work, runs the check, reads the result, and keeps iterating until it passes, instead of waiting for you to catch every mistake. Bake the criteria right into the prompt: not "implement email validation," but "write a validateEmail function, here are the test cases, run the tests after implementing and fix any failures."

Two stronger versions for work you did not watch. A Stop hook can run your check as a script and refuse to let the turn end until it passes. And for a real second opinion, have a fresh subagent review the diff: because it sees only the change and your criteria, not the reasoning that produced it, it grades the result on its own terms. Claude Code even ships a /code-review command that does exactly this. Whichever you use, ask the agent to show evidence (the test output, the command it ran, the screenshot) rather than just asserting success. The rule I hold onto: if you cannot verify it, do not ship it.

Practice 7: wire up MCP servers for real tools and memory

The failure it fixes: copy-pasting data into the chat from every other tool you use. If you find yourself pasting an issue from your tracker, a row from your database, or a design spec into Claude by hand, you are doing work the agent could do directly, and you are introducing errors every time you paste.

MCP, the Model Context Protocol, is how Claude Code connects to your other tools. With a server connected, the agent can read and act on that system itself: pull a ticket from your issue tracker and open a PR, query your Postgres database, check a monitoring dashboard, or pull a design from Figma. You add one with claude mcp add, and servers come in a few transports (a remote HTTP server is the recommended default, with local stdio servers for tools that run on your machine). They can expose tools the agent calls, resources it reads, and prompts it reuses.

One caution that matters: only connect servers you trust, because a server that pulls in external content can expose you to prompt-injection risk. Start with one server that removes a real copy-paste loop in your day, then add more. Wired up well, MCP is also how you give the agent durable, queryable memory beyond a flat file. That persistent-memory layer is what Iwo's MemoryOS provides over MCP, so your context follows you across sessions instead of resetting each time.

Practice 8: practice secret hygiene. Never paste keys

The failure it fixes: a leaked credential. This is the one with no undo button. Paste an API key into a chat, hardcode a token so the agent can "test" something, or let a key sit committed in a file, and you have created a security incident. An agent that reads and writes files and runs shell commands raises the stakes, because by default it can read your .env file, your SSH keys, and anything you exported into your shell.

The hygiene is the same hygiene good engineers already follow, applied with the agent in mind. Never paste a raw key into the conversation. Keep secrets in environment variables, not in code. Add your .env file to .gitignore so it is never committed. And use the permission tools from Practice 5 to deny the agent access to sensitive paths: block reads of .env and credential files, and block commands like curl on any project that holds production credentials. For higher-stakes work, Claude Code can run in an OS-level sandbox that restricts filesystem and network access, so the agent works freely inside a boundary you defined rather than across your whole machine.

The mindset shift is simple. You would not give a new contractor your root password on day one. Treat the agent the same way: useful access, scoped tightly, secrets kept out of reach.

How to start this week

You do not adopt all eight at once. Here is the order I would start in, smallest effort first.

1. Write one CLAUDE.md. Run /init in your main project, then trim it to the commands, conventions, and decisions Claude cannot guess. This alone removes most of the re-explaining.
2. Make plan mode your default for anything non-trivial. Get in the habit of Shift+Tab before you let it edit, and reading the plan before you approve.
3. Add one verification check. Pick a task type you run often and start ending the prompt with "run the tests and fix failures." Let the loop close itself.
4. Set two permission rules. One allowlist for a command you approve constantly, one deny rule for something that must never happen.
5. Connect one MCP server. Whichever tool you copy-paste from most. Remove that loop.

Each step compounds. By the time you reach subagents and hooks, the agent is already something you trust to run, not something you babysit.

Mistakes and anti-patterns to avoid

I have made all of these. Naming them is faster than re-living them.

• The kitchen-sink session. Starting one task, asking something unrelated, then going back. The context fills with noise and quality drops. Fix: /clear between unrelated tasks.
• Correcting on a loop. The agent gets it wrong, you correct, it is still wrong, you correct again. The context is now polluted with failed approaches. Fix: after two failed corrections, clear and write a better prompt.
• The over-stuffed CLAUDE.md. A memory file so long the agent ignores half of it. Fix: prune ruthlessly, and convert "must always happen" rules into hooks.
• Trust without verify. Shipping a plausible-looking change you never ran. Fix: always give the agent a check, and read the diff yourself.
• Unbounded "go investigate." Asking the agent to explore with no scope, so it reads hundreds of files and floods the context. Fix: scope it narrowly, or hand it to a subagent.
• Broad, casual permissions on a sensitive repo. Letting an agent run freely where production credentials live. Fix: deny rules, allowlists, and a sandbox before you let it loose.

FAQ

What are the most important Claude Code best practices in 2026?

Start with a CLAUDE.md memory file the agent reads every session, scope the context instead of dumping the whole repo, and use plan mode before you let it edit. Those three fix the most common failures. Then add verification (give it a test or build it can run), tight permissions with hooks, subagents for big jobs, MCP servers for your tools, and strict secret hygiene. The pattern across all of them is the same: build the rails, then let the agent run.

Do I need to be a developer to follow these?

No. Writing a CLAUDE.md is writing markdown, plan mode and /clear are single keystrokes, and connecting an MCP server is one command. The one skill that helps is being able to read a diff so you can verify what changed. If you are brand new, my Claude Code 101 guide covers the setup before these habits.

What is the difference between CLAUDE.md and auto memory?

You write CLAUDE.md. It holds your instructions and conventions, and Claude reads it at the start of every session. Auto memory is what Claude writes for itself, notes about build commands, debugging insights, and your preferences, stored per repository and loaded automatically. Use CLAUDE.md to guide behavior on purpose, and let auto memory accumulate the things the agent discovers. You can inspect both with the /memory command.

When should I use plan mode versus just letting Claude code?

Use plan mode when the change spans multiple files, when you are unsure of the approach, or when you are working in code you do not know well, because the planning step catches "wrong problem" mistakes before anything is written. Skip it for small, obvious edits you could describe in one sentence, like a typo fix or a renamed variable, where planning is just overhead.

How do I stop Claude Code from doing something dangerous?

Layer your controls. Use /permissions to allowlist commands you trust and deny ones that must never run, use the --allowedTools flag to scope unattended runs, and use hooks for hard rules, since a PreToolUse hook can block an action deterministically where a written rule only advises. For sensitive repos, run it in an OS-level sandbox so its filesystem and network access are boxed in.

How much does Claude Code cost?

Claude Code is included with the paid Claude subscriptions, not the free tier. As of mid-2026 the Pro plan is around 20 dollars a month (less if you pay annually), and the Max plans start at roughly 100 dollars a month for the lower tier and around 200 for the higher tier, which mainly buy you larger usage limits rather than different models. Teams use a per-seat plan. Pricing is current as of mid-2026 and moves often, so confirm before you commit. If cost is your main constraint, cheaper agents like Z.ai's ZCode on GLM-5.2 undercut Claude Code by a wide margin, though they share its lack of built-in memory across sessions.

---

Good Claude Code use is not about clever prompts, it is about the rails you build: a memory file, scoped context, a plan before edits, and a check the agent can run. If you want that memory layer as a ready template instead of a blank file, Iwo's Second Brain ships it, on Iwo's MemoryOS for persistent recall across every session. For the full build inside the terminal, read how to build a second brain in Claude Code.