CLAUDE CODE OS

The file Claude reads every time it opens the project. It is not a README. README is for the human cloning the repo. CLAUDE.md is a briefing for an agent: what the project IS, the voice, the hard constraints, the dangerous commands, the safe shortcuts.

Keep it short. No narration. Point to detailed docs instead of duplicating them. If Claude keeps making the same mistake over and over, a line is missing here.

Concrete tip: start with the monorepo map, the non-negotiable conventions, and the shortcuts that keep you from wiping production. Everything else becomes a link.

A hook is a script that runs on an event: PreToolUse, PostToolUse, SessionStart, Stop. Think middleware. Useful for blocking edits on sensitive files, running lint after a save, firing a notification when a long session ends.

Configured in settings.json. Do not confuse it with Claude's memory. A hook is deterministic, it always runs, without depending on the agent remembering.

In Sapiens, a hook warns whenever an em-dash shows up in a .md file, because the house DNA forbids it. A rule that becomes code, not a preference that becomes wishful thinking.

Every tool (Bash, Edit, Write, MCP) can be allowed, denied or asked. Defined by command pattern. E.g. Bash(git status:*) frees only status, not push.

Move to user settings what is universally safe (ls, git diff, npm test). Move to project settings what is repo-specific (npm run convex:deploy only in this project).

Never free the whole Bash(*). You lose the seat belt and still feel comfortable.

Before every experiment or big change, commit. It becomes a checkpoint you can revert to painlessly.

Direct messages: fix, feat, chore, refactor. No process narration in the body. The diff tells the story.

When Claude is iterating fast on a feature, commit at every green step. If the next attempt breaks, you run git restore with confidence.

Things like: named exports not default, Tailwind before CSS Modules, dates in ISO 8601, no console.log in the final commit.

CLAUDE.md points here. It exists so you do not repeat the same correction 5 times across 5 different sessions.

When you catch yourself saying the same thing for the second time in the same week, open the file and write it down.

A lean ADR. Format: swapped X for Y on DD/MM because Z.

When Claude (or you) tries to revert something three months from now, this file prevents the classic well, there must be a reason, leave it there.

Only write the entry when the decision is non-obvious. Do not document the trivial.

Long sessions pollute the context. Claude starts remembering things that no longer matter and losing focus on what does.

/clear wipes it. Costs nothing, recovers precision.

If you caught yourself re-explaining the same thing twice in the same session, the clear was due one answer earlier.

A subagent is a parallel Claude with its own scope. It does the search (grep, read, web fetch) and comes back with a short report. Your main context does not get clogged with tool results.

Typical cases: exploring a big folder, reading a huge PR, doing code review as an independent second opinion.

Brief it like a colleague who just walked into the room. No assumptions.

Edit the login is vague. Edit src/app/auth/page.tsx:42 is surgical.

When you know where it lives, say where it lives. Saves search tools and prevents Claude from editing the wrong file with the same name.

Also works for functions: paste the exact snippet to change. Big models pick up context better from literal text than from descriptions.

Auto-compact erases parts of the session to fit the context. You do not choose what it summarizes.

/compact lets you ask for the compression explicitly, so you continue with the memory curated the way you want.

Useful before switching phases in a long task: research is done, implementation is next, compact the research into a summary and move on.

Claude trying to pull a screw with a hammer? Stop. Do not sit there cheering that the next attempt will land.

Step back, reformulate the prompt, maybe start a new session carrying the lesson from the previous one.

Insisting costs tokens and degrades the next attempt, because the context fills up with broken tries the model starts treating as precedent.

Shift+Tab enters plan mode. Claude proposes a plan, you approve or adjust before it touches a single file.

For any task past 15 minutes of execution, planning mode pays for itself. You fix in the plan in 30 seconds what would cost 10 minutes of undo.

For tweak this copy, it is overhead. Use judgment.

git worktree add ../proj-foo branch-foo creates a parallel folder pointing at another branch.

Useful when you want to run 2 Claudes in parallel, one on main fixing a bug, another on a feature, without the checkout dance that loses IDE state.

Hardcore, but it solves operating on more than one front.

Bash with run_in_background, or an agent in the background. Claude keeps interacting while the build, the test or the agent runs.

You get notified when it finishes. No watching paint dry.

Combines strongly with subagents: you delegate a big investigation, keep coding something else, receive the report when it is ready.

Inverts classic TDD. You write the assertion (given this input, I expect this output), Claude implements until it passes.

When the test goes green, it is done. No subjectivity.

Works best for pure functions, algorithms, parsers. UI still needs human verification, a green test does not guarantee a working feature.

Claude says done, you read the diff. Especially in UI: type-check passed is not the feature works.

Run the server, click, check the golden path and at least one edge case.

The agent's summary describes the intention, not the result. Verifying is part of the task, not optional.

cat error.log | claude diagnose this. Build output, test logs, production dumps: pipe them straight in.

Do not copy-paste. Pipe is faster, preserves formatting and dodges the clipboard limit.

Works for small files without allocating a read tool. For big files, still use Read, or you blow the context.

System microphone, transcription, paste.

For a long 5-minute briefing you talk as if explaining to a partner. It comes out more natural than typing and Claude picks up context better than from cherry-picked prompts.

Works great in the car, walking, brushing your teeth. Some of this project's best specs came out that way.

A custom line at the bottom of the terminal: current branch, tokens consumed, mode, active session.

Configured via /statusline. It is the vim status bar, but for AI.

A small hack that kills the huh, is it still running or did it hang. One glance and you know.

/quote, /pop-article, /review. Each slash is a skill: a prompt plus tools plus structured instructions.

When you do the same thing 3 times, it becomes a slash. Saves minutes a day and standardizes output.

In Sapiens, the whole editorial flow (generate a quote, review, publish) runs on slashes. That is where the speed comes from.

Double Esc takes you back to before the last exchange.

Useful when Claude took a wrong branch and you want to reformulate without losing the earlier context.

It is not a code undo, it is a prompt undo. To undo a file, git restore remains the way.

alias cl=claude --model opus. alias clc=claude --continue. alias cly=claude --dangerously-skip-permissions (carefully).

Put it in .zshrc or .bashrc.

Every second saved on an operation you do 50 times a day matters. The opposite of glamour, just arithmetic.

Model Context Protocol. A server that exposes tools: Stripe, GitHub, Notion, databases, Convex, your own MCP.

Claude becomes the brain that orchestrates. You connect once per service, use it forever.

In Sapiens, the house MCP exposes the app's API (create a quote, list drafts, publish) for Claude to operate editorially. It is the jump from assistant to operational colleague.

Custom output styles: terse engineer, friendly tutor, editorial blueprint, brutally honest.

It becomes a personality preset. Useful when the same agent serves different cases (debugging demands directness, pair programming demands dialogue).

Combines with slashes: each skill can ship with its own output style built in.

P2P sync. Your home machine and your laptop stay identical without GitHub in the middle.

Good for heavy local work you do not want to push to the remote all the time (big assets, builds, downloads).

It does not replace git, it complements it. Git for versioned code, Syncthing for the machine's raw state.

A skill is a folder with SKILL.md plus scripts plus prompts. Claude reads it when you invoke it.

It is teaching a pattern once and using it forever. The Sapiens skills (/quote, /pop-article, /pipeline) live in skills/ and each one is a specialist agent of the editorial flow.

When you want to distill operational knowledge into a reusable, portable format, a skill is the right container.