CLAUDE.md: your project's memory

A CLAUDE.md file is pulled into context automatically at the start of every session. It is the file that pays back the most, and the one people under-invest in. Put in it what Claude would otherwise rediscover every session: the build and test commands, where the important code lives, the conventions you actually enforce, the project-specific traps.

Claude Code reads CLAUDE.md from the repo root, any parent or child directory of where you launch, and your home folder ((local path)) for cross-project defaults. The newer cross-tool convention is AGENTS.mdas the canonical filename withCLAUDE.mdsymlinked to it, so the same context file works across editors. Nested files compose: aCLAUDE.md` in a subdirectory layers on top of the root one when you work in that subtree.

Two shortcuts pay for themselves. Type /init once to generate a first draft from your codebase. While you work, prefix a message with # and Claude writes that instruction into the relevant CLAUDE.md for you, so the memory grows as you correct it. If you want a worked starting point instead of a blank file, I keep my production-tested CLAUDE.md files and rules open-source in slopless, and a longer write-up on the memory side in I Built a Personal Memory System for Claude.

Permissions: change these defaults first

By default Claude asks before any action that could change your system. That is the right floor, but the per-prompt approvals get tedious fast, and the fix is not to disable them blindly. Open .claude/settings.json (project) or (local path) (global) and set a real permissionspolicy withallow, deny, and ask lists. Allowlist the read-only and obviously-safe commands you run constantly. Keep destructive ones (rm -rf, force-push, curlto arbitrary hosts) ondenyorask`.

Permission modes are the other lever. Press Shift+Tab to cycle between the default (ask), acceptEdits (auto-approve file edits, still prompt for shell), and plan mode. For genuinely untrusted code, /sandbox runs the session in an isolated environment. The realistic threat with a broad allowlist is not a fat-fingered command; it is an injected instruction from a web page or a repo file chaining an allowed command to do something you did not intend. A PreToolUse hook (below) is the deterministic backstop the allowlist alone does not give you.

Skills: the biggest addition since 2025

A skill is a folder under (local path) with a SKILL.mdfile: frontmatter (adescriptionthat tells Claude when to fire it, plus a pinnedmodeloragent) and a body of instructions. When a task matches the description, Claude loads the skill and follows it. You invoke one explicitly with /name`, or Claude reaches for it on its own when the trigger matches.

Skills are how you stop re-explaining the same workflow. A deploy procedure, a house style for commit messages, a research-then-write pipeline, a status report that always pulls the same five sources: each becomes a skill you write once and trigger by name. I run more than fifty of them, and keep a sampling of the real ones (skills, rules, worked examples) public in rundatarun. The discipline that keeps them useful is the same as CLAUDE.md: progressive disclosure. Keep the always-loaded description short, put the heavy how-to in the body that loads only when the skill fires, and prune skills that stop earning their slot.

Subagents: parallelism without the terminal juggling

The old advice was to open three or four terminals and run a Claude in each. That still works, but it is now the manual version of something native. Claude Code can spawn subagents directly through its Task tool, and you can define reusable ones as `(local path) files, each with its own system prompt, tool access, and model.

Two patterns matter. First, fan-out: when a task means reading across many files or searching a codebase several ways, hand it to a parallel explorer agent and keep only the conclusion in your main context, not the raw file dumps. Launch several at once by putting multiple tool calls in a single turn and they run concurrently. Second, model selection per agent: cheap discovery and summarization go to a fast model, voice-sensitive writing and hard reasoning stay on the frontier model. Pinning the model per agent is where a lot of the cost and speed control lives.

The judgment call is when not to delegate. With a large context window, reflexively forking everything is its own failure mode; reasoning-heavy work often belongs inline where you can see and steer each step. Fork for breadth (scan, discover, summarize), stay inline for depth.

Hooks: deterministic automation the model can't skip

Hooks are shell commands the harness runs at fixed points in a session, configured in settings.json. PreToolUse fires before a tool runs and can block it. PostToolUse fires after. SessionStart, UserPromptSubmit, and Stop cover the rest of the lifecycle. The key property is that the harness executes them, not the model, so they are reliable in a way a CLAUDE.md instruction never is. If you need something to happen every single time, it is a hook, not a request.

Real uses: a PreToolUse guard on Bash that blocks rm -rf and flags injected-looking commands, an auto-formatter on PostToolUse after every edit, a SessionStart hook that injects the current branch and recent context. A memory or preference can ask Claude to do something; only a hook guarantees it.

MCP: connect your own tools

The Model Context Protocol lets Claude Code talk to external tools and data: a database, an internal API, a search index, a browser driver. Add servers with claude mcp add --scope user|project|local <name> -- <command>, or --transport http for a hosted one. User scope makes a server available everywhere; a checked-in .mcp.json shares it with everyone working in the repo. Once connected, the server's tools appear alongside the built-ins. This is how you give Claude access to the systems your work actually lives in, instead of copy-pasting between them.

The core loop: explore, plan, code, commit

The workflow that holds up across almost every problem is still the same four beats, and the first two are the ones people skip:

1. Explore. Have Claude read the relevant files, issues, or docs first. No edits yet.
2. Plan. Ask for a plan before any code. Press Shift+Tab into plan mode and Claude works read-only, then hands you a plan to approve. For harder problems, raise the reasoning with /effort xhigh, or drop the word ultrathink into a single prompt for one deep turn.
3. Code. Now let it implement against the agreed plan.
4. Commit. Have it write the commit and open the PR.

Skip explore and plan and Claude jumps straight to code, which is exactly when it builds the wrong thing confidently. The other durable variants: test-driven (write failing tests, confirm they fail, then code until green) for anything verifiable, and visual-driven (give it a screenshot tool and a mock, let it iterate until they match) for UI.

Context discipline

A long session fills with stale file contents and dead ends, and quality drifts with it. Run /clear between unrelated tasks to reset. Use /compact to summarize a long thread down to what still matters when you want to keep going. Even with a million-token window on the higher plans, more context is not free: past a heavy fill, retrieval gets worse, not better. Keep the working set focused. Reference files precisely with @ and tab-completion so Claude reads the right thing instead of grepping the whole tree.

Headless mode and automation

claude -p "<prompt>" runs non-interactively, which is how Claude Code goes into CI, pre-commit hooks, and scheduled jobs. Add --output-format stream-json for machine-readable output. The Agent SDK wraps the same engine for building your own tools on top. This is the path from "I run Claude in my terminal" to "Claude runs as part of my pipeline": triage incoming issues and label them, review diffs for the things linters miss, regenerate docs on merge. The same harness, no human in the chair.

Dynamic workflows: many agents, with a referee

The most recent capability is orchestration. Claude can write a script that fans work out across parallel subagents and then runs adversarial verifiers before returning an answer, so a finding has to survive a skeptic before you see it. It is gated behind an opt-in setting because it can burn through tokens fast, with hard caps (sixteen agents at once, a backstop ceiling far above any real run). Reach for it on genuine fan-out work: a codebase audit, a framework migration, multi-attempt verification of an uncertain result. For everyday editing, one careful (secret) beats fifty parallel guesses. The skill is knowing which task is which. I wrote up what shipping Opus 4.8 and dynamic workflows on the same day changed about the unit of work in One Careful Pass Is No Longer the Default.

Go deeper: the harness, in the open

Much of the year's work behind this is public, if you want worked examples instead of principles:

• claudelicious: a full Claude Code cookbook, the why and the wiring behind an entire harness (skills, hooks, memory, agents). The direct companion to this article.
• slopless: the production-tested CLAUDE.md files and rules I run to make Claude Code write better, more human code.
• rundatarun: skills, rules, and worked examples pulled straight from production.
• mneme: semantic search over your Claude Code session history, for when the answer is in a conversation you had three weeks ago.

And a few posts that go deeper on individual pieces:

• Three Harnesses, Three Characters: why to choose your harness every six months instead of letting it choose you.
• Syncing Claude Code Configurations Across Machines: keeping one harness consistent across every box you work on.
• The Enterprise Battle for Claude Code: where the tool and its ecosystem are heading.