文章探讨了将 Claude Code 作为日常开发工具的实践，重点介绍了其核心配置文件 Claude.md、技能系统、子代理功能、插件扩展以及通过 MCP（模型上下文协议）进行集成的方法，旨在提升开发者的工作流效率。
原文 · 未翻译
Claude Code Beyond the Basics
The .claude Directory, Properly Understood
CLAUDE.md, The Way Boris Writes It3.1 The Real CLAUDE.md From the Claude Code Team3.2 Popular CLAUDE.md Files Worth Studying
3.1 The Real CLAUDE.md From the Claude Code Team
3.2 Popular CLAUDE.md Files Worth Studying
CLAUDE.local.md as a Daily Driver
Skills, In Depth5.1 What Skills Actually Are5.2 Writing a Real Skill: Go API Conventions5.3 Popular Skills Worth Installing
5.1 What Skills Actually Are
5.2 Writing a Real Skill: Go API Conventions
5.3 Popular Skills Worth Installing
Building Custom Subagents6.1 Walking Through a /pr-review Agent6.2 Popular Subagents Worth Stealing
6.1 Walking Through a /pr-review Agent
6.2 Popular Subagents Worth Stealing
Plugins and the Marketplace
Underused Claude Code Commands8.1 /goal, the Ralph Loop Built In
8.1 /goal, the Ralph Loop Built In
MCPs as Power Tools9.1 A Real Obsidian Workflow
9.1 A Real Obsidian Workflow
Optimizing Your Daily Workflow
Tips From the Anthropic Team
Resources
Closing Notes
I burned forty minutes on a refactor claude could’ve shipped in four, and the gap wasn’t the model. It was everything around it. The casual user types prompts, takes the first suggestion, and treats claude like dressed-up autocomplete. I run it as a programmable agent: persistent memory, custom commands, parallel sessions spawning across worktrees, and a project layout that gets sharper every week I touch it. This guide assumes you’ve already typed claude into a terminal and seen what happens. We’re going past that…
claude
claude
claude
Now the fun part.
Claude Code Beyond the Basics#
Stop treating Claude Code like a prompt-and-wait chatbot. Treat it like an autonomous agent that needs guardrails, and your whole workflow shifts. The core principle from Boris Cherny and the Anthropic team is simple, and it’s to give Claude a way to verify its own work. Without that loop, you’re the only feedback signal. With it, Claude iterates until the code actually runs. Boris pegs this single move at a 2-3x quality bump.
A few patterns that shift how you operate day to day.
文章探讨了将 Claude Code 作为日常开发工具的实践，重点介绍了其核心配置文件 Claude.md、技能系统、子代理功能、插件扩展以及通过 MCP（模型上下文协议）进行集成的方法，旨在提升开发者的工作流效率。
原文 · 保持原样，未翻译
Claude Code Beyond the Basics
The .claude Directory, Properly Understood
CLAUDE.md, The Way Boris Writes It3.1 The Real CLAUDE.md From the Claude Code Team3.2 Popular CLAUDE.md Files Worth Studying
3.1 The Real CLAUDE.md From the Claude Code Team
3.2 Popular CLAUDE.md Files Worth Studying
CLAUDE.local.md as a Daily Driver
Skills, In Depth5.1 What Skills Actually Are5.2 Writing a Real Skill: Go API Conventions5.3 Popular Skills Worth Installing
5.1 What Skills Actually Are
5.2 Writing a Real Skill: Go API Conventions
5.3 Popular Skills Worth Installing
Building Custom Subagents6.1 Walking Through a /pr-review Agent6.2 Popular Subagents Worth Stealing
Explore, then plan, then code. Hit Shift+Tab twice to drop into plan mode, which is read-only. Let Claude read files, trace flows, map the data model. Get a plan back. Then execute. Skip planning for small fixes. Use it the moment a change touches more than one file.
Shift+Tab
Treat plan mode like a design doc. Have one Claude write the plan. Spin up a second Claude in a fresh session and ask it to review the plan as a staff engineer, no context bias, so it actually catches gaps. If the implementation goes sideways, go back to plan mode and re-plan with verification steps baked in.
Reference, don’t describe. Skip “look at the auth module” and type @src/auth/login.py. Skip pasting an error and pipe it instead with cat error.log | claude. Exact context beats approximate description every single time.
@src/auth/login.py
cat error.log | claude
Delegate, don’t pair-program. Cat Wu (Claude Code team) puts it plainly: “The model performs best if you treat it like an engineer you’re delegating to, not a pair programmer you’re guiding line by line.” Write a crisp brief upfront. Then let it run.
: Press Ctrl+G to open Claude’s plan in your editor and tweak it before Claude proceeds. The plan is just text, so shape it before it becomes code.
: Press Ctrl+G to open Claude’s plan in your editor and tweak it before Claude proceeds. The plan is just text, so shape it before it becomes code.
Ctrl+G
: When Claude makes a mistake, end your prompt with “Update CLAUDE.md so you don’t repeat this.” Boris calls Claude “eerily good at writing rules for itself” from its own failures. Do note, this one habit compounds harder than anything else in this guide.
: When Claude makes a mistake, end your prompt with “Update CLAUDE.md so you don’t repeat this.” Boris calls Claude “eerily good at writing rules for itself” from its own failures. Do note, this one habit compounds harder than anything else in this guide.
The .claude Directory, Properly Understood#
Most folks crack open .claude/, spot CLAUDE.md, and bounce. It’s a layered config system underneath.
.claude/
CLAUDE.md
Two scopes. Project scope sits in .claude/ inside the repo, committed so the team shares it. Global scope sits in ~/.claude/ and rides along on every project on your box.
.claude/
~/.claude/
Mental model. Project files describe the project, global files describe you.
FileScopeCommitWhat it doesCLAUDE.mdProject and globalYesInstructions loaded every sessionCLAUDE.local.mdProject onlyNo, gitignore itYour private project notessettings.jsonProject and globalYesPermissions, hooks, env vars, model defaultssettings.local.jsonProject onlyNoPersonal overrides, auto-gitignored.mcp.jsonProject onlyYesTeam-shared MCP serversskills//SKILL.mdProject and globalYesReusable prompts invoked with /namecommands/*.mdProject and globalYesSingle-file slash commandsagents/*.mdProject and globalYesSubagent definitionsrules/*.mdProject and globalYesTopic-scoped instructions, optionally path-gated
CLAUDE.md files cascade. In a monorepo, both root/CLAUDE.md and root/services/billing/CLAUDE.md load while you’re working the billing service. Handy when folder conventions diverge.
CLAUDE.md
root/CLAUDE.md
root/services/billing/CLAUDE.md
rules/*.md is path-gated. Guidance specific to your migrations folder shouldn’t bloat every session through CLAUDE.md, rather it belongs in .claude/rules/migrations.md with a glob.
rules/*.md
CLAUDE.md
.claude/rules/migrations.md
Skills beat commands. Both .claude/commands/*.md and .claude/skills//SKILL.md register slash commands, but skills carry supporting files, disable-model-invocation, allowed tools, and agent overrides. I shipped a chunk of repo automation as loose commands/*.md last year and had to port the whole lot to skills/ once supporting files were needed. New work goes in skills/.
.claude/commands/*.md
.claude/skills//SKILL.md
disable-model-invocation
commands/*.md
skills/
skills/
: Run claude project purge ~/path/to/repo --dry-run to see exactly what local state Claude holds for a project, handy before handing off a laptop.
: Run claude project purge ~/path/to/repo --dry-run to see exactly what local state Claude holds for a project, handy before handing off a laptop.
claude project purge ~/path/to/repo --dry-run
CLAUDE.md, The Way Boris Writes It#
CLAUDE.md loads at the start of every session. Get it wrong, Claude keeps tripping on the same rake. Get it right, the same prompt suddenly produces output you’d actually ship.
CLAUDE.md
Boris cares about two things here, and the rest is noise once you’ve got these down. I spent a month writing increasingly elaborate context files before I came back around to his framing, and the elaborate versions were worse in every measurable way…
Keep it short. Long files bury the rules that actually matter. For every line you write, run it through Boris’s filter and ask, “Would removing this cause Claude to make a mistake?” If the answer is no, cut it. Be ruthless. The file isn’t a knowledge base, it’s a guardrail.
Let Claude write rules for itself. Any time Claude does something wrong, tell it to “Update CLAUDE.md so you don’t repeat this.” Claude is surprisingly good at distilling its own mistakes into precise rules. Do this for a couple of weeks and the file turns into a curated list of every gotcha your project has accumulated, written in the exact phrasing the model responds to. You stop guessing what to put in there because the model tells you.
3.1 The Real CLAUDE.md From the Claude Code Team#
In one of his talks, Boris walked through the actual CLAUDE.md the Claude Code team checks into their own repo. The whole team contributes to it multiple times a week.
CLAUDE.md
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 # Development Workflow Always use `bun`, not `npm`. # 1. Make changes # 2. Typecheck (fast) bun run typecheck # 3. Run tests bun run test -- -t "test name" # Single suite bun run test:file -- "glob" # Specific files # 4. Lint before committing bun run lint:file -- "file1.ts" bun run lint # 5. Before creating PR bun run lint:claude && bun run test
Development Workflow Always use `bun`, not `npm`. # 1. Make changes # 2. Typecheck (fast) bun run typecheck # 3. Run tests bun run test -- -t "test name" # Single suite bun run test:file -- "glob" # Specific files # 4. Lint before committing bun run lint:file -- "file1.ts" bun run lint # 5. Before creating PR bun run lint:claude && bun run test
Development Workflow Always use `bun`, not `npm`. # 1. Make changes # 2. Typecheck (fast) bun run typecheck # 3. Run tests bun run test -- -t "test name" # Single suite bun run test:file -- "glob" # Specific files # 4. Lint before committing bun run lint:file -- "file1.ts" bun run lint # 5. Before creating PR bun run lint:claude && bun run test
Read it again. Build commands Claude can’t guess, the exact order to run things, single-test invocations, the pre-PR ritual. No style preferences, no codebase tours, no platitudes.
Boris also uses @claude in PR comments to have Claude commit a rule directly:
@claude
1 2 nit: use a string literal, not a ts enum @claude add to CLAUDE.md to never use enums, always prefer literal unions
1 2
1 2
nit: use a string literal, not a ts enum @claude add to CLAUDE.md to never use enums, always prefer literal unions
nit: use a string literal, not a ts enum @claude add to CLAUDE.md to never use enums, always prefer literal unions
He calls this “Compounding Engineering,” where every PR review becomes a CLAUDE.md improvement. The reviewer catches a mistake once, and Claude never repeats it.
CLAUDE.md
Here’s a fleshed-out template following the same philosophy:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 # Code style - Use ES modules (import/export), not CommonJS (require) # Workflow - Always use bun, not npm - Run bun run typecheck before claiming done - Never push to main directly. Always open a PR. # Architecture - All API routes go through src/api/middleware/auth.ts - New database queries go in src/db/queries/. No inline raw SQL. # Gotchas - User and UserRecord are distinct types. UserRecord is the DB row, User is the runtime object. - formatCurrency assumes USD. For international use formatCurrencyByLocale.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
Code style - Use ES modules (import/export), not CommonJS (require) # Workflow - Always use bun, not npm - Run bun run typecheck before claiming done - Never push to main directly. Always open a PR. # Architecture - All API routes go through src/api/middleware/auth.ts - New database queries go in src/db/queries/. No inline raw SQL. # Gotchas - User and UserRecord are distinct types. UserRecord is the DB row, User is the runtime object. - formatCurrency assumes USD. For international use formatCurrencyByLocale.
Code style - Use ES modules (import/export), not CommonJS (require) # Workflow - Always use bun, not npm - Run bun run typecheck before claiming done - Never push to main directly. Always open a PR. # Architecture - All API routes go through src/api/middleware/auth.ts - New database queries go in src/db/queries/. No inline raw SQL. # Gotchas - User and UserRecord are distinct types. UserRecord is the DB row, User is the runtime object. - formatCurrency assumes USD. For international use formatCurrencyByLocale.
Pay attention to the “Gotchas” section. Every entry there started as a real mistake Claude made on a real PR, captured the moment it happened. That sinking moment when you realize the model just shipped USD formatting to a French user? You write it down once, and it never happens again.
Skip these in CLAUDE.md: standard language conventions, file-by-file codebase descriptions, long tutorials, API docs, anything that changes frequently.
CLAUDE.md
: Words like IMPORTANT or YOU MUST improve adherence. Use them sparingly so they carry weight.
: Words like IMPORTANT or YOU MUST improve adherence. Use them sparingly so they carry weight.
IMPORTANT
YOU MUST
You can import other files using @path syntax to keep CLAUDE.md short while pulling in details on demand:
@path
CLAUDE.md
1 2 See @README.md for project overview and @package.json for scripts. @~/.claude/my-preferences.md
1 2
1 2
See @README.md for project overview and @package.json for scripts. @~/.claude/my-preferences.md
See @README.md for project overview and @package.json for scripts. @~/.claude/my-preferences.md
Short file, huge payoff. Keep it tight.
3.2 Popular CLAUDE.md Files Worth Studying#
Steal from people who’ve already done the work. These four are the ones I keep coming back to.
mattpocock/skills CLAUDE.md : conventions for how skills should be written and tested
anthropics/claude-code-action : Anthropic’s own repo, treated the same as internal tools
awesome-claude-code : links to dozens of public CLAUDE.md files across language ecosystems
CLAUDE.md
claudelog.com : community-curated examples organized by stack
Read three, then write yours.
CLAUDE.local.md as a Daily Driver#
CLAUDE.local.md sits next to CLAUDE.md, loads the same way, and never leaves my machine. It goes straight into .gitignore.
CLAUDE.local.md
CLAUDE.md
.gitignore
Here’s how I run it. After every PR, reviewers drop comments. Instead of trying to hold them in my head, I paste them into CLAUDE.local.md the second I read them. Over a few weeks it turns into a personal rule file tuned to the exact feedback I keep getting.
CLAUDE.local.md
1 2 3 4 5 6 7 8 9 10 11 12 13 # Personal review notes (private) # From PR feedback - New SQS consumers need a DLQ and alarms in the same PR - Use Optional over null returns - Tests for new endpoints must include the auth-failure case - Prefer named tuples over plain dicts for return types with 3+ fields # My own quirks to correct - Stop using console.log; use the project logger instead - Always update the OpenAPI spec when adding endpoints
1 2 3 4 5 6 7 8 9 10 11 12 13
1 2 3 4 5 6 7 8 9 10 11 12 13
Personal review notes (private) # From PR feedback - New SQS consumers need a DLQ and alarms in the same PR - Use Optional over null returns - Tests for new endpoints must include the auth-failure case - Prefer named tuples over plain dicts for return types with 3+ fields # My own quirks to correct - Stop using console.log; use the project logger instead - Always update the OpenAPI spec when adding endpoints
Personal review notes (private) # From PR feedback - New SQS consumers need a DLQ and alarms in the same PR - Use Optional over null returns - Tests for new endpoints must include the auth-failure case - Prefer named tuples over plain dicts for return types with 3+ fields # My own quirks to correct - Stop using console.log; use the project logger instead - Always update the OpenAPI spec when adding endpoints
Loaded every session. Claude now includes the auth-failure test and updates the OpenAPI spec without me asking. Nitpick comments on my PRs dropped within two weeks.
: Keep two sections clearly separated: project-specific feedback and personal habits to correct. Mixing them makes the file harder to prune later.
: Keep two sections clearly separated: project-specific feedback and personal habits to correct. Mixing them makes the file harder to prune later.
: Prune after a few weeks. Anything that’s become muscle memory can go. The file should capture what’s still in flux; the stuff that runs on autopilot can go.
: Prune after a few weeks. Anything that’s become muscle memory can go. The file should capture what’s still in flux; the stuff that runs on autopilot can go.
Skills, In Depth#
Skills are how you take Claude Code from “agent that can do anything” to “agent that does the three specific things your project actually needs, done the way your team does them.” They’re the unit of reusable expertise you’ll keep reaching for once you’ve written one or two…
5.1 What Skills Actually Are#
Last Tuesday I needed Claude to summarize my uncommitted diff the same way every time, so I dropped a folder into ~/.claude/skills/ and walked away. That folder is the skill. Inside lives a SKILL.md carrying frontmatter and instructions, and the folder name itself becomes the slash command you type at the prompt. Project-scoped ones sit under .claude/skills//, global ones under ~/.claude/skills//.
~/.claude/skills/
SKILL.md
.claude/skills//
~/.claude/skills//
Here’s the smallest version that earns its keep:
1 2 3 4 5 6 7 8 9 10 11 --- description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff. --- ## Current changes !git diff HEAD ## Instructions Summarize the changes in two or three bullet points, then list any risks: missing error handling, hardcoded values, tests that need updating.
1 2 3 4 5 6 7 8 9 10 11
1 2 3 4 5 6 7 8 9 10 11
--- description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff. --- ## Current changes !git diff HEAD ## Instructions Summarize the changes in two or three bullet points, then list any risks: missing error handling, hardcoded values, tests that need updating.
--- description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff. --- ## Current changes !git diff HEAD ## Instructions Summarize the changes in two or three bullet points, then list any risks: missing error handling, hardcoded values, tests that need updating.
Save that to ~/.claude/skills/summarize-changes/SKILL.md and /summarize-changes shows up in every session you open after.
~/.claude/skills/summarize-changes/SKILL.md
/summarize-changes
Three things that make Skills powerful:
Progressive disclosure. At session start Claude only reads the frontmatter descriptions, roughly 100 tokens apiece. The full SKILL.md and any helper files don’t get pulled in until the skill actually fires.
SKILL.md
Each skill lives as its own folder, so you can drop a templates/ directory alongside the SKILL.md, stash reference docs next to it, and keep scripts in the same tree. The SKILL.md is just the entry point you hand to Claude.
templates/
SKILL.md
SKILL.md
Inline shell. Any line starting with ! runs the command at invocation time and splices the output straight into the prompt.
!
The frontmatter itself carries a good amount of optional knobs:
1 2 3 4 5 6 7 --- name: my-skill description: When to use this skill disable-model-invocation: true # only runs when user explicitly types /my-skill allowed-tools: Read, Grep, Bash agent: read-only ---
1 2 3 4 5 6 7
1 2 3 4 5 6 7
--- name: my-skill description: When to use this skill disable-model-invocation: true # only runs when user explicitly types /my-skill allowed-tools: Read, Grep, Bash agent: read-only ---
--- name: my-skill description: When to use this skill disable-model-invocation: true # only runs when user explicitly types /my-skill allowed-tools: Read, Grep, Bash agent: read-only ---
: Use disable-model-invocation: true for skills with side effects. You want /ship to deploy only when explicitly typed, not when Claude decides it’s relevant.
: Use disable-model-invocation: true for skills with side effects. You want /ship to deploy only when explicitly typed, not when Claude decides it’s relevant.
disable-model-invocation: true
/ship
Set it once. Forget it forever.
5.2 Writing a Real Skill: Go API Conventions#
Here’s a complete skill for a Go service team. It carries the conventions, the gotchas, and scaffolding for a fresh HTTP handler.
Underused Claude Code Commands8.1 /goal, the Ralph Loop Built In
8.1 /goal, the Ralph Loop Built In
MCPs as Power Tools9.1 A Real Obsidian Workflow
9.1 A Real Obsidian Workflow
Optimizing Your Daily Workflow
Tips From the Anthropic Team
Resources
Closing Notes
I burned forty minutes on a refactor claude could’ve shipped in four, and the gap wasn’t the model. It was everything around it. The casual user types prompts, takes the first suggestion, and treats claude like dressed-up autocomplete. I run it as a programmable agent: persistent memory, custom commands, parallel sessions spawning across worktrees, and a project layout that gets sharper every week I touch it. This guide assumes you’ve already typed claude into a terminal and seen what happens. We’re going past that…
claude
claude
claude
Now the fun part.
Claude Code Beyond the Basics#
Stop treating Claude Code like a prompt-and-wait chatbot. Treat it like an autonomous agent that needs guardrails, and your whole workflow shifts. The core principle from Boris Cherny and the Anthropic team is simple, and it’s to give Claude a way to verify its own work. Without that loop, you’re the only feedback signal. With it, Claude iterates until the code actually runs. Boris pegs this single move at a 2-3x quality bump.
A few patterns that shift how you operate day to day.
Explore, then plan, then code. Hit Shift+Tab twice to drop into plan mode, which is read-only. Let Claude read files, trace flows, map the data model. Get a plan back. Then execute. Skip planning for small fixes. Use it the moment a change touches more than one file.
Shift+Tab
Treat plan mode like a design doc. Have one Claude write the plan. Spin up a second Claude in a fresh session and ask it to review the plan as a staff engineer, no context bias, so it actually catches gaps. If the implementation goes sideways, go back to plan mode and re-plan with verification steps baked in.
Reference, don’t describe. Skip “look at the auth module” and type @src/auth/login.py. Skip pasting an error and pipe it instead with cat error.log | claude. Exact context beats approximate description every single time.
@src/auth/login.py
cat error.log | claude
Delegate, don’t pair-program. Cat Wu (Claude Code team) puts it plainly: “The model performs best if you treat it like an engineer you’re delegating to, not a pair programmer you’re guiding line by line.” Write a crisp brief upfront. Then let it run.
: Press Ctrl+G to open Claude’s plan in your editor and tweak it before Claude proceeds. The plan is just text, so shape it before it becomes code.
: Press Ctrl+G to open Claude’s plan in your editor and tweak it before Claude proceeds. The plan is just text, so shape it before it becomes code.
Ctrl+G
: When Claude makes a mistake, end your prompt with “Update CLAUDE.md so you don’t repeat this.” Boris calls Claude “eerily good at writing rules for itself” from its own failures. Do note, this one habit compounds harder than anything else in this guide.
: When Claude makes a mistake, end your prompt with “Update CLAUDE.md so you don’t repeat this.” Boris calls Claude “eerily good at writing rules for itself” from its own failures. Do note, this one habit compounds harder than anything else in this guide.
The .claude Directory, Properly Understood#
Most folks crack open .claude/, spot CLAUDE.md, and bounce. It’s a layered config system underneath.
.claude/
CLAUDE.md
Two scopes. Project scope sits in .claude/ inside the repo, committed so the team shares it. Global scope sits in ~/.claude/ and rides along on every project on your box.
.claude/
~/.claude/
Mental model. Project files describe the project, global files describe you.
FileScopeCommitWhat it doesCLAUDE.mdProject and globalYesInstructions loaded every sessionCLAUDE.local.mdProject onlyNo, gitignore itYour private project notessettings.jsonProject and globalYesPermissions, hooks, env vars, model defaultssettings.local.jsonProject onlyNoPersonal overrides, auto-gitignored.mcp.jsonProject onlyYesTeam-shared MCP serversskills//SKILL.mdProject and globalYesReusable prompts invoked with /namecommands/*.mdProject and globalYesSingle-file slash commandsagents/*.mdProject and globalYesSubagent definitionsrules/*.mdProject and globalYesTopic-scoped instructions, optionally path-gated
CLAUDE.md files cascade. In a monorepo, both root/CLAUDE.md and root/services/billing/CLAUDE.md load while you’re working the billing service. Handy when folder conventions diverge.
CLAUDE.md
root/CLAUDE.md
root/services/billing/CLAUDE.md
rules/*.md is path-gated. Guidance specific to your migrations folder shouldn’t bloat every session through CLAUDE.md, rather it belongs in .claude/rules/migrations.md with a glob.
rules/*.md
CLAUDE.md
.claude/rules/migrations.md
Skills beat commands. Both .claude/commands/*.md and .claude/skills//SKILL.md register slash commands, but skills carry supporting files, disable-model-invocation, allowed tools, and agent overrides. I shipped a chunk of repo automation as loose commands/*.md last year and had to port the whole lot to skills/ once supporting files were needed. New work goes in skills/.
.claude/commands/*.md
.claude/skills//SKILL.md
disable-model-invocation
commands/*.md
skills/
skills/
: Run claude project purge ~/path/to/repo --dry-run to see exactly what local state Claude holds for a project, handy before handing off a laptop.
: Run claude project purge ~/path/to/repo --dry-run to see exactly what local state Claude holds for a project, handy before handing off a laptop.
claude project purge ~/path/to/repo --dry-run
CLAUDE.md, The Way Boris Writes It#
CLAUDE.md loads at the start of every session. Get it wrong, Claude keeps tripping on the same rake. Get it right, the same prompt suddenly produces output you’d actually ship.
CLAUDE.md
Boris cares about two things here, and the rest is noise once you’ve got these down. I spent a month writing increasingly elaborate context files before I came back around to his framing, and the elaborate versions were worse in every measurable way…
Keep it short. Long files bury the rules that actually matter. For every line you write, run it through Boris’s filter and ask, “Would removing this cause Claude to make a mistake?” If the answer is no, cut it. Be ruthless. The file isn’t a knowledge base, it’s a guardrail.
Let Claude write rules for itself. Any time Claude does something wrong, tell it to “Update CLAUDE.md so you don’t repeat this.” Claude is surprisingly good at distilling its own mistakes into precise rules. Do this for a couple of weeks and the file turns into a curated list of every gotcha your project has accumulated, written in the exact phrasing the model responds to. You stop guessing what to put in there because the model tells you.
3.1 The Real CLAUDE.md From the Claude Code Team#
In one of his talks, Boris walked through the actual CLAUDE.md the Claude Code team checks into their own repo. The whole team contributes to it multiple times a week.
CLAUDE.md
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 # Development Workflow Always use `bun`, not `npm`. # 1. Make changes # 2. Typecheck (fast) bun run typecheck # 3. Run tests bun run test -- -t "test name" # Single suite bun run test:file -- "glob" # Specific files # 4. Lint before committing bun run lint:file -- "file1.ts" bun run lint # 5. Before creating PR bun run lint:claude && bun run test
Development Workflow Always use `bun`, not `npm`. # 1. Make changes # 2. Typecheck (fast) bun run typecheck # 3. Run tests bun run test -- -t "test name" # Single suite bun run test:file -- "glob" # Specific files # 4. Lint before committing bun run lint:file -- "file1.ts" bun run lint # 5. Before creating PR bun run lint:claude && bun run test
Development Workflow Always use `bun`, not `npm`. # 1. Make changes # 2. Typecheck (fast) bun run typecheck # 3. Run tests bun run test -- -t "test name" # Single suite bun run test:file -- "glob" # Specific files # 4. Lint before committing bun run lint:file -- "file1.ts" bun run lint # 5. Before creating PR bun run lint:claude && bun run test
Read it again. Build commands Claude can’t guess, the exact order to run things, single-test invocations, the pre-PR ritual. No style preferences, no codebase tours, no platitudes.
Boris also uses @claude in PR comments to have Claude commit a rule directly:
@claude
1 2 nit: use a string literal, not a ts enum @claude add to CLAUDE.md to never use enums, always prefer literal unions
1 2
1 2
nit: use a string literal, not a ts enum @claude add to CLAUDE.md to never use enums, always prefer literal unions
nit: use a string literal, not a ts enum @claude add to CLAUDE.md to never use enums, always prefer literal unions
He calls this “Compounding Engineering,” where every PR review becomes a CLAUDE.md improvement. The reviewer catches a mistake once, and Claude never repeats it.
CLAUDE.md
Here’s a fleshed-out template following the same philosophy:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 # Code style - Use ES modules (import/export), not CommonJS (require) # Workflow - Always use bun, not npm - Run bun run typecheck before claiming done - Never push to main directly. Always open a PR. # Architecture - All API routes go through src/api/middleware/auth.ts - New database queries go in src/db/queries/. No inline raw SQL. # Gotchas - User and UserRecord are distinct types. UserRecord is the DB row, User is the runtime object. - formatCurrency assumes USD. For international use formatCurrencyByLocale.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
Code style - Use ES modules (import/export), not CommonJS (require) # Workflow - Always use bun, not npm - Run bun run typecheck before claiming done - Never push to main directly. Always open a PR. # Architecture - All API routes go through src/api/middleware/auth.ts - New database queries go in src/db/queries/. No inline raw SQL. # Gotchas - User and UserRecord are distinct types. UserRecord is the DB row, User is the runtime object. - formatCurrency assumes USD. For international use formatCurrencyByLocale.
Code style - Use ES modules (import/export), not CommonJS (require) # Workflow - Always use bun, not npm - Run bun run typecheck before claiming done - Never push to main directly. Always open a PR. # Architecture - All API routes go through src/api/middleware/auth.ts - New database queries go in src/db/queries/. No inline raw SQL. # Gotchas - User and UserRecord are distinct types. UserRecord is the DB row, User is the runtime object. - formatCurrency assumes USD. For international use formatCurrencyByLocale.
Pay attention to the “Gotchas” section. Every entry there started as a real mistake Claude made on a real PR, captured the moment it happened. That sinking moment when you realize the model just shipped USD formatting to a French user? You write it down once, and it never happens again.
Skip these in CLAUDE.md: standard language conventions, file-by-file codebase descriptions, long tutorials, API docs, anything that changes frequently.
CLAUDE.md
: Words like IMPORTANT or YOU MUST improve adherence. Use them sparingly so they carry weight.
: Words like IMPORTANT or YOU MUST improve adherence. Use them sparingly so they carry weight.
IMPORTANT
YOU MUST
You can import other files using @path syntax to keep CLAUDE.md short while pulling in details on demand:
@path
CLAUDE.md
1 2 See @README.md for project overview and @package.json for scripts. @~/.claude/my-preferences.md
1 2
1 2
See @README.md for project overview and @package.json for scripts. @~/.claude/my-preferences.md
See @README.md for project overview and @package.json for scripts. @~/.claude/my-preferences.md
Short file, huge payoff. Keep it tight.
3.2 Popular CLAUDE.md Files Worth Studying#
Steal from people who’ve already done the work. These four are the ones I keep coming back to.
mattpocock/skills CLAUDE.md : conventions for how skills should be written and tested
anthropics/claude-code-action : Anthropic’s own repo, treated the same as internal tools
awesome-claude-code : links to dozens of public CLAUDE.md files across language ecosystems
CLAUDE.md
claudelog.com : community-curated examples organized by stack
Read three, then write yours.
CLAUDE.local.md as a Daily Driver#
CLAUDE.local.md sits next to CLAUDE.md, loads the same way, and never leaves my machine. It goes straight into .gitignore.
CLAUDE.local.md
CLAUDE.md
.gitignore
Here’s how I run it. After every PR, reviewers drop comments. Instead of trying to hold them in my head, I paste them into CLAUDE.local.md the second I read them. Over a few weeks it turns into a personal rule file tuned to the exact feedback I keep getting.
CLAUDE.local.md
1 2 3 4 5 6 7 8 9 10 11 12 13 # Personal review notes (private) # From PR feedback - New SQS consumers need a DLQ and alarms in the same PR - Use Optional over null returns - Tests for new endpoints must include the auth-failure case - Prefer named tuples over plain dicts for return types with 3+ fields # My own quirks to correct - Stop using console.log; use the project logger instead - Always update the OpenAPI spec when adding endpoints
1 2 3 4 5 6 7 8 9 10 11 12 13
1 2 3 4 5 6 7 8 9 10 11 12 13
Personal review notes (private) # From PR feedback - New SQS consumers need a DLQ and alarms in the same PR - Use Optional over null returns - Tests for new endpoints must include the auth-failure case - Prefer named tuples over plain dicts for return types with 3+ fields # My own quirks to correct - Stop using console.log; use the project logger instead - Always update the OpenAPI spec when adding endpoints
Personal review notes (private) # From PR feedback - New SQS consumers need a DLQ and alarms in the same PR - Use Optional over null returns - Tests for new endpoints must include the auth-failure case - Prefer named tuples over plain dicts for return types with 3+ fields # My own quirks to correct - Stop using console.log; use the project logger instead - Always update the OpenAPI spec when adding endpoints
Loaded every session. Claude now includes the auth-failure test and updates the OpenAPI spec without me asking. Nitpick comments on my PRs dropped within two weeks.
: Keep two sections clearly separated: project-specific feedback and personal habits to correct. Mixing them makes the file harder to prune later.
: Keep two sections clearly separated: project-specific feedback and personal habits to correct. Mixing them makes the file harder to prune later.
: Prune after a few weeks. Anything that’s become muscle memory can go. The file should capture what’s still in flux; the stuff that runs on autopilot can go.
: Prune after a few weeks. Anything that’s become muscle memory can go. The file should capture what’s still in flux; the stuff that runs on autopilot can go.
Skills, In Depth#
Skills are how you take Claude Code from “agent that can do anything” to “agent that does the three specific things your project actually needs, done the way your team does them.” They’re the unit of reusable expertise you’ll keep reaching for once you’ve written one or two…
5.1 What Skills Actually Are#
Last Tuesday I needed Claude to summarize my uncommitted diff the same way every time, so I dropped a folder into ~/.claude/skills/ and walked away. That folder is the skill. Inside lives a SKILL.md carrying frontmatter and instructions, and the folder name itself becomes the slash command you type at the prompt. Project-scoped ones sit under .claude/skills//, global ones under ~/.claude/skills//.
~/.claude/skills/
SKILL.md
.claude/skills//
~/.claude/skills//
Here’s the smallest version that earns its keep:
1 2 3 4 5 6 7 8 9 10 11 --- description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff. --- ## Current changes !git diff HEAD ## Instructions Summarize the changes in two or three bullet points, then list any risks: missing error handling, hardcoded values, tests that need updating.
1 2 3 4 5 6 7 8 9 10 11
1 2 3 4 5 6 7 8 9 10 11
--- description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff. --- ## Current changes !git diff HEAD ## Instructions Summarize the changes in two or three bullet points, then list any risks: missing error handling, hardcoded values, tests that need updating.
--- description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff. --- ## Current changes !git diff HEAD ## Instructions Summarize the changes in two or three bullet points, then list any risks: missing error handling, hardcoded values, tests that need updating.
Save that to ~/.claude/skills/summarize-changes/SKILL.md and /summarize-changes shows up in every session you open after.
~/.claude/skills/summarize-changes/SKILL.md
/summarize-changes
Three things that make Skills powerful:
Progressive disclosure. At session start Claude only reads the frontmatter descriptions, roughly 100 tokens apiece. The full SKILL.md and any helper files don’t get pulled in until the skill actually fires.
SKILL.md
Each skill lives as its own folder, so you can drop a templates/ directory alongside the SKILL.md, stash reference docs next to it, and keep scripts in the same tree. The SKILL.md is just the entry point you hand to Claude.
templates/
SKILL.md
SKILL.md
Inline shell. Any line starting with ! runs the command at invocation time and splices the output straight into the prompt.
!
The frontmatter itself carries a good amount of optional knobs:
1 2 3 4 5 6 7 --- name: my-skill description: When to use this skill disable-model-invocation: true # only runs when user explicitly types /my-skill allowed-tools: Read, Grep, Bash agent: read-only ---
1 2 3 4 5 6 7
1 2 3 4 5 6 7
--- name: my-skill description: When to use this skill disable-model-invocation: true # only runs when user explicitly types /my-skill allowed-tools: Read, Grep, Bash agent: read-only ---
--- name: my-skill description: When to use this skill disable-model-invocation: true # only runs when user explicitly types /my-skill allowed-tools: Read, Grep, Bash agent: read-only ---
: Use disable-model-invocation: true for skills with side effects. You want /ship to deploy only when explicitly typed, not when Claude decides it’s relevant.
: Use disable-model-invocation: true for skills with side effects. You want /ship to deploy only when explicitly typed, not when Claude decides it’s relevant.
disable-model-invocation: true
/ship
Set it once. Forget it forever.
5.2 Writing a Real Skill: Go API Conventions#
Here’s a complete skill for a Go service team. It carries the conventions, the gotchas, and scaffolding for a fresh HTTP handler.