🔥 shanraisshan/claude-code-best-practice

practice makes claude perfect

= Agents · = Commands · = Skills

Boris Cherny on X (tweet 1 · tweet 2 · tweet 3)

🧠 CONCEPTS

Feature Location Description

Subagents .claude/agents/.md Autonomous actor in fresh isolated context — custom tools, permissions, model, memory, and persistent identity

Commands .claude/commands/.md Knowledge injected into existing context — simple user-invoked prompt templates for workflow orchestration

Skills .claude/skills//SKILL.md Knowledge injected into existing context — configurable, preloadable, auto-discoverable, with context forking and progressive disclosure · Official Skills

Workflows .claude/commands/weather-orchestrator.md

Hooks .claude/hooks/ User-defined handlers (scripts, HTTP, prompts, agents) that run outside the agentic loop on specific events · Guide

MCP Servers .claude/settings.json, .mcp.json Model Context Protocol connections to external tools, databases, and APIs

Plugins distributable packages Bundles of skills, subagents, hooks, MCP servers, and LSP servers · Marketplaces · Create Marketplaces

Settings .claude/settings.json Hierarchical configuration system · Permissions · Model Config · Output Styles · Sandboxing · Keybindings · Fast Mode

Status Line .claude/settings.json Customizable status bar showing context usage, model, cost, and session info

Memory CLAUDE.md, .claude/rules/, ~/.claude/rules/, ~/.claude/projects//memory/ Persistent context via CLAUDE.md files and @path imports · Auto Memory · Rules

Checkpointing automatic (git-based) Automatic tracking of file edits with rewind (Esc Esc or /rewind) and targeted summarization

CLI Startup Flags claude [flags] Command-line flags, subcommands, and environment variables for launching Claude Code · Interactive Mode

AI Terms

Agentic Engineering · Context Engineering · Vibe Coding

Best Practices

Official best practices · Prompt Engineering · Extend Claude Code

🔥 Hot

Feature Location Description

Auto Mode --permission-mode auto Background safety classifier replaces manual permission prompts — Claude decides what's safe while blocking prompt injection and risky escalations · Blog

Channels --channels, plugin-based Push events from Telegram, Discord, or webhooks into a running session — Claude reacts while you're away · Reference

Slack @Claude in Slack Mention @Claude in team chat with a coding task — routes to Claude Code web sessions for bug fixes, code reviews, and parallel task execution

Code Review GitHub App (managed) Multi-agent PR analysis that catches bugs, security vulnerabilities, and regressions · Blog

GitHub Actions .github/workflows/ Automate PR reviews, issue triage, and code generation in CI/CD pipelines · GitLab CI/CD

Chrome --chrome, extension Browser automation via Claude in Chrome — test web apps, debug with console, automate forms, extract data from pages

Scheduled Tasks /loop, /schedule, cron tools /loop runs prompts locally on a recurring schedule (up to 3 days) · /schedule runs prompts in the cloud on Anthropic infrastructure — works even when your machine is off · Announcement

Voice Dictation /voice Push-to-talk speech input for prompts with 20-language support and rebindable activation key

Simplify & Batch /simplify, /batch Built-in skills for code quality and bulk operations — simplify refactors for reuse and efficiency, batch runs commands across files

Agent Teams built-in (env var) Multiple agents working in parallel on the same codebase with shared task coordination

Remote Control /remote-control, /rc Continue local sessions from any device — phone, tablet, or browser · Headless Mode

Git Worktrees built-in Isolated git branches for parallel development — each agent gets its own working copy

Ralph Wiggum Loop plugin Autonomous development loop for long-running tasks — iterates until completion

See orchestration-workflow for implementation details of Command → Agent → Skill pattern.

claude /weather-orchestrator

claude /weather-orchestrator

⚙️ DEVELOPMENT WORKFLOWS

All major workflows converge on the same architectural pattern: Research → Plan → Execute → Review → Ship

Name ★ Uniqueness Plan

Superpowers 122k

writing-plans 5 3 14

Everything Claude Code 116k

planner 30 63 135

Spec Kit 83k

speckit.plan 0 9+ 0

gstack 55k

autoplan 0 0 28

Get Shit Done 44k

gsd-planner 18 57 0

BMAD-METHOD 43k

bmad-create-prd 0 0 40

OpenSpec 35k

opsx:propose 0 11 0

Compound Engineering 12k

ce-plan 48 4 42

HumanLayer 10k

create_plan 6 27 0

Others

💡 TIPS AND TRICKS (86)

🚫👶 = do not babysit

Prompting · Planning · CLAUDE.md · Agents · Commands · Skills · Hooks · Workflows · Advanced · Git / PR · Debugging · Utilities · Daily

■ Prompting (3)

Tip Source

challenge Claude — "grill me on these changes and don't make a PR until I pass your test." or "prove to me this works" and have Claude diff between main and your branch 🚫👶

after a mediocre fix — "knowing everything you know now, scrap this and implement the elegant solution" 🚫👶

Claude fixes most bugs by itself — paste the bug, say "fix", don't micromanage how 🚫👶

■ Planning/Specs (6)

Tip Source

always start with plan mode

start with a minimal spec or prompt and ask Claude to interview you using AskUserQuestion tool, then make a new session to execute the spec

always make a phase-wise gated plan, with each phase having multiple tests (unit, automation, integration)

spin up a second Claude to review your plan as a staff engineer, or use cross-model for review

write detailed specs and reduce ambiguity before handing work off — the more specific you are, the better the output

prototype > PRD — build 20-30 versions instead of writing specs, the cost of building is low so take many shots

■ CLAUDE.md (7)

Tip Source

CLAUDE.md should target under 200 lines per file. 60 lines in humanlayer (still not 100% guaranteed)

wrap domain-specific CLAUDE.md rules in tags to stop Claude from ignoring them as files grow longer

use multiple CLAUDE.md for monorepos — ancestor + descendant loading

use .claude/rules/ to split large instructions

memory.md, constitution.md does not guarantee anything

any developer should be able to launch Claude, say "run the tests" and it works on the first try — if it doesn't, your CLAUDE.md is missing essential setup/build/test commands

keep codebases clean and finish migrations — partially migrated frameworks confuse models that might pick the wrong pattern

use settings.json for harness-enforced behavior (attribution, permissions, model) — don't put "NEVER add Co-Authored-By" in CLAUDE.md when attribution.commit: "" is deterministic

Agents (4)

Tip Source

have feature specific sub-agents (extra context) with skills (progressive disclosure) instead of general qa, backend engineer

say "use subagents" to throw more compute at a problem — offload tasks to keep your main context clean and focused 🚫👶

agent teams with tmux and git worktrees for parallel development

use test time compute — separate context windows make results better; one agent can cause bugs and another (same model) can find them

Commands (3)

Tip Source

use commands for your workflows instead of sub-agents

use slash commands for every "inner loop" workflow you do many times a day — saves repeated prompting, commands live in .claude/commands/ and are checked into git

if you do something more than once a day, turn it into a skill or command — build /techdebt, context-dump, or analytics commands

Skills (9)

Tip Source

use context: fork to run a skill in an isolated subagent — main context only sees the final result, not intermediate tool calls. The agent field lets you set the subagent type

use skills in subfolders for monorepos

skills are folders, not files — use references/, scripts/, examples/ subdirectories for progressive disclosure

build a Gotchas section in every skill — highest-signal content, add Claude's failure points over time

skill description field is a trigger, not a summary — write it for the model ("when should I fire?")

don't state the obvious in skills — focus on what pushes Claude out of its default behavior 🚫👶

don't railroad Claude in skills — give goals and constraints, not prescriptive step-by-step instructions 🚫👶

include scripts and libraries in skills so Claude composes rather than reconstructs boilerplate

embed !command`` in SKILL.md to inject dynamic shell output into the prompt — Claude runs it on invocation and the model only sees the result

■ Hooks (5)

Tip Source

use on-demand hooks in skills — /careful blocks destructive commands, /freeze blocks edits outside a directory

measure skill usage with a PreToolUse hook to find popular or undertriggering skills

use a PostToolUse hook to auto-format code — Claude generates well-formatted code, the hook handles the last 10% to avoid CI failures

route permission requests to Opus via a hook — let it scan for attacks and auto-approve safe ones 🚫👶

use a Stop hook to nudge Claude to keep going or verify its work at the end of a turn

■ Workflows (7)

Tip Source

avoid agent dumb zone, do manual /compact at max 50%. Use /clear to reset context mid-session if switching to a new task

vanilla cc is better than any workflows with smaller tasks

use /model to select model and reasoning, /context to see context usage, /usage to check plan limits, /extra-usage to configure overflow billing, /config to configure settings — use Opus for plan mode and Sonnet for code to get the best of both

always use thinking mode true (to see reasoning) and Output Style Explanatory (to see detailed output with ★ Insight boxes) in /config for better understanding of Claude's decisions

use ultrathink keyword in prompts for high effort reasoning

/rename important sessions (e.g. [TODO - refactor task]) and /resume them later — label each instance when running multiple Claudes simultaneously

use Esc Esc or /rewind to undo when Claude goes off-track instead of trying to fix it in the same context

■ Workflows Advanced (6)

Tip Source

use ASCII diagrams a lot to understand your architecture

use /loop for local recurring monitoring (up to 3 days) · use /schedule for cloud-based recurring tasks that run even when your machine is off

use Ralph Wiggum plugin for long-running autonomous tasks

/permissions with wildcard syntax (Bash(npm run ), Edit(/docs/)) instead of dangerously-skip-permissions

/sandbox to reduce permission prompts with file and network isolation — 84% reduction internally

invest in product verification skills (signup-flow-driver, checkout-verifier) — worth spending a week to perfect

■ Git / PR (5)

Tip Source

keep PRs small and focused — p50 of 118 lines (141 PRs, 45K lines changed in a day), one feature per PR, easier to review and revert

always squash merge PRs — clean linear history, one commit per feature, easy git revert and git bisect

commit often — try to commit at least once per hour, as soon as task is completed, commit

tag @claude on a coworker's PR to auto-generate lint rules for recurring review feedback — automate yourself out of code review 🚫👶

use /code-review for multi-agent PR analysis — catches bugs, security vulnerabilities, and regressions before merge

■ Debugging (7)

Tip Source

make it a habit to take screenshots and share with Claude whenever you are stuck with any issue

use mcp (Claude in Chrome, Playwright, Chrome DevTools) to let claude see chrome console logs on its own

always ask claude to run the terminal (you want to see logs of) as a background task for better debugging

/doctor to diagnose installation, authentication, and configuration issues

error during compaction can be resolved by using /model to select a 1M token model, then running /compact

use a cross-model for QA — e.g. Codex for plan and implementation review

agentic search (glob + grep) beats RAG — Claude Code tried and discarded vector databases because code drifts out of sync and permissions are complex

■ Utilities (5)

Tip Source

iTerm/Ghostty/tmux terminals instead of IDE (VS Code/Cursor)

Wispr Flow for voice prompting (10x productivity)

claude-code-hooks for claude feedback

status line for context awareness and fast compacting

explore settings.json features like Plans Directory, Spinner Verbs for a personalized experience

■ Daily (3)

Tip Source

update Claude Code daily and start your day by reading the changelog

follow r/ClaudeAI, r/ClaudeCode

follow Boris, Thariq, Cat, Lydia, Noah, Anthony, Alex, Kenneth, Claude

Article / Tweet Source

15 Hidden & Under-Utilized Features in Claude Code (Boris) | 30/Mar/26 Tweet

Squash Merging & PR Size Distribution (Boris) | 25/Mar/26 Tweet

Lessons from Building Claude Code: How We Use Skills (Thariq) | 17/Mar/26 Article

Code Review & Test Time Compute (Boris) | 10/Mar/26 Tweet

/loop — schedule recurring tasks for up to 3 days (Boris) | 07 Mar 2026 Tweet

AskUserQuestion + ASCII Markdowns (Thariq) | 28 Feb 2026 Tweet

Seeing like an Agent - lessons from building Claude Code (Thariq) | 28 Feb 2026 Article

Git Worktrees - 5 ways how boris is using | 21 Feb 2026 Tweet

Lessons from Building Claude Code: Prompt Caching Is Everything (Thariq) | 20 Feb 2026 Article

12 ways how people are customizing their claudes (Boris) | 12/Feb/26 Tweet

10 tips for using Claude Code from the team (Boris) | 01/Feb/26 Tweet

How I use Claude Code — 13 tips from my surprisingly vanilla setup (Boris) | 03/Jan/26 Tweet

Ask Claude to interview you using AskUserQuestion tool (Thariq) | 28/Dec/25 Tweet

Always use plan mode, give Claude a way to verify, use /code-review (Boris) | 27/Dec/25 Tweet

Video / Podcast YouTube

Building Claude Code with Boris Cherny (Boris) | 04 Mar 2026 | The Pragmatic Engineer YouTube

Head of Claude Code: What happens after coding is solved (Boris) | 19 Feb 2026 | Lenny's Podcast YouTube

Inside Claude Code With Its Creator Boris Cherny (Boris) | 17 Feb 2026 | Y Combinator YouTube

Boris Cherny (Creator of Claude Code) On What Grew His Career (Boris) | 15 Dec 2025 | Ryan Peterman YouTube

The Secrets of Claude Code From the Engineers Who Built It (Cat) | 29 Oct 2025 | Every YouTube

☠️ STARTUPS / BUSINESSES

Claude Replaced

Code Review Greptile, CodeRabbit, Devin Review, OpenDiff, Cursor BugBot

Voice Dictation Wispr Flow, SuperWhisper

Remote Control OpenClaw

Cowork OpenAI Operator, AgentShadow

Tasks Beads

Plan Mode Agent OS

Skills / Plugins YC AI wrapper startups (reddit)

If you have answers, do let me know at [email protected]

Memory & Instructions (4)

• What exactly should you put inside your CLAUDE.md — and what should you leave out?

• If you already have a CLAUDE.md, is a separate constitution.md or rules.md actually needed?

• How often should you update your CLAUDE.md, and how do you know when it's become stale?

• Why does Claude still ignore CLAUDE.md instructions — even when they say MUST in all caps? (reddit)

Agents, Skills & Workflows (6)

• When should you use a command vs an agent vs a skill — and when is vanilla Claude Code just better?

• How often should you update your agents, commands, and workflows as models improve?

• Does giving your subagent a detailed persona improve quality? What does a "perfect persona/prompt" for research/QA subagent look like?

• Should you rely on Claude Code's built-in plan mode — or build your own planning command/agent that enforces your team's workflow?

• If you have a personal skill (e.g., /implement with your coding style), how do you incorporate community skills (e.g., /simplify) without conflicts — and who wins when they disagree?

• Are we there yet? Can we convert an existing codebase into specs, delete the code, and have AI regenerate the exact same code from those specs alone?

Specs & Documentation (3)

• Should every feature in your repo have a spec as a markdown file?

• How often do you need to update specs so they don't become obsolete when a new feature is implemented?

• When implementing a new feature, how do you handle the ripple effect on specs for other features?

REPORTS

1. Read the repo like a course, learn what commands, agents, skills, and hooks are before trying to use them. 2. Clone this repo and play with the examples, try /weather-orchestrator, listen to the hook sounds, run agent teams, so you can see how things actually work. 3. Go to your own project and ask Claude to suggest what best practices from this repo you should add, give it this repo as a reference so it knows what's possible.

1. Read the repo like a course, learn what commands, agents, skills, and hooks are before trying to use them. 2. Clone this repo and play with the examples, try /weather-orchestrator, listen to the hook sounds, run agent teams, so you can see how things actually work. 3. Go to your own project and ask Claude to suggest what best practices from this repo you should add, give it this repo as a reference so it knows what's possible.

✨Trending on Github in March 2026✨

Other Repos

claude-code-hooks · codex-cli-best-practice · codex-cli-hooks

Developed by

Workflow Description

/workflows:development-workflows Update the DEVELOPMENT WORKFLOWS table and cross-workflow analysis report by researching all 8 workflow repos in parallel

/workflows:best-practice:workflow-concepts Update the README CONCEPTS section with the latest Claude Code features and concepts

/workflows:best-practice:workflow-claude-settings Track Claude Code settings report changes and find what needs updating

/workflows:best-practice:workflow-claude-subagents Track Claude Code subagents report changes and find what needs updating

/workflows:best-practice:workflow-claude-commands Track Claude Code commands report changes and find what needs updating

/workflows:best-practice:workflow-claude-skills Track Claude Code skills report changes and find what needs updating

Star History