claude-code-best-practice

from vibe coding to agentic engineering - practice makes claude perfect

= Agents · = Commands · = Skills

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

[!TIP] Visit the How to Use section to take full advantage of this repo.

🧠 CONCEPTS

Feature	Location	Description
Subagents	.claude/agents/<name>.md
Commands	.claude/commands/<name>.md
Skills	.claude/skills/<name>/SKILL.md	Official Skills · Skills for Mono-repos
Workflows	.claude/commands/weather-orchestrator.md
Hooks	.claude/hooks/	Guide
MCP Servers	.claude/settings.json, .mcp.json
Plugins	distributable packages	Marketplaces · Create Marketplaces
Settings	.claude/settings.json	Permissions · Model Config · Output Styles · Sandboxing · Keybindings · Auto Mode Config
Status Line	.claude/settings.json
Memory	CLAUDE.md, .claude/rules/, ~/.claude/rules/, ~/.claude/projects/<project>/memory/	Auto Memory · Auto Memory Deep-dive · Rules
Checkpointing	automatic (file-edit tracking)
CLI Startup Flags	claude [flags]	Interactive Mode · Env Vars
AI Terms
Best Practices		Prompt Engineering · Extend Claude Code

🔥 Hot

Feature	Location	Description
Ultrareview	/code-review ultra, claude ultrareview [target]	Tasks tracking
Devcontainers	.devcontainer/
Channels	--channels, plugin-based	Reference
Ultraplan	/ultraplan
No Flicker Mode	/tui fullscreen, CLAUDE_CODE_NO_FLICKER=1
Auto Mode	--permission-mode auto, Shift+Tab	Blog
Power-ups	/powerup
Fast Mode	/fast, "fastMode": true
Advisor	/advisor, advisorModel, --advisor	Blog
Computer Use	computer-use MCP server	Desktop
Agent SDK	npm / pip package	Quickstart · Examples
Ralph Wiggum Loop	plugin
Chrome	--chrome, extension
Claude Code Web	claude.ai/code	Routines
Slack	@Claude in Slack
Code Review	GitHub App (managed)	Blog Local /code-review
GitHub Actions	.github/workflows/	GitLab CI/CD
Remote Control	/remote-control, /rc	Headless Mode
Deep Links	claude-cli://open?repo=…&q=…
Dynamic Workflows	/workflows, ultracode keyword, /effort ultracode, .claude/workflows/	Deep Research
Agent Teams	built-in (env var)
Agent View	claude agents, --bg, /bg
Scheduled Tasks	/loop, /schedule, cron tools	Desktop scheduled tasks · Announcement
Routines	claude.ai/code/routines, /schedule	Desktop Tasks
Tasks	/tasks, ~/.claude/tasks/	Ultrareview tracking
Goal	/goal <condition>, /goal clear
Voice Dictation	/voice
Bundled Skills	/code-review, /batch
Git Worktrees	--worktree/-w, .worktreeinclude, EnterWorktree/ExitWorktree, isolation: "worktree", WorktreeCreate/WorktreeRemove hooks

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

claude
/weather-orchestrator

⚙️ DEVELOPMENT WORKFLOWS

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

Name	★	Workflow
Superpowers	236k	→ → → → → → → → → → →	0	0	14
Everything Claude Code	220k	→ → → → →	67	84	271
Matt Pocock Skills	142k	→ → → → → → → → →	0	0	34
Spec Kit	115k	→ → → → → → → → →	0	10	0
gstack	113k	→ → → → → → → → → → → →	0	0	53
Get Shit Done	65k	→ → → → → → →	33	67	0
agent-skills	61k	→ → → → →	3	7	21
OpenSpec	56k	→ → → →	0	11	0
BMAD-METHOD	50k	→ → → → → → → → → →	6	0	42
oh-my-claudecode	37k	→ → → → →	19	0	40
Compound Engineering	22k	→ → → →	0	1	27
HumanLayer	11k	→ → → → → → → → →	6	27	0

Note: yellow tags are sub-loops — steps that repeat inside a parent step (e.g. per task, per story, or until a verify condition passes).

Others

• RPI
• Ralph Wiggum Loop
• Andrej Karpathy (Founding Member, OpenAI) Workflow
• Peter Steinberger (Creator of OpenClaw) Workflow
• Boris Cherny (Creator of Claude Code) Workflow — 13 Tips · 10 Tips · 12 Tips · 2 Tips · 15 Tips · 6 Tips
• Thariq (Anthropic) Workflow — Skills · Session Management

🔀 CROSS-MODEL WORKFLOWS

Use Claude Code together with other models — Codex, Gemini, GPT, Kimi, DeepSeek, local — via three mechanisms:

• Plugin — another model's CLI runs inside Claude Code (slash commands like /codex:review)
• MCP — Claude Code calls another model as a tool through Model Context Protocol
• Router — Claude Code's API endpoint is swapped to a different provider

Methodology: Cross-Model (Claude Code + Codex) Workflow — manual two-terminal flow with Plan in Claude, QA-Review in Codex.

🧰 SKILL COLLECTIONS

Repos primarily known as curated libraries of SKILL.md files (distinct from full workflow methodologies above). Sorted by stars descending.

Name	★
anthropics/skills	153k	17
mattpocock/skills	136k	30
Egonex-AI/Understand-Anything	67k	8
wshobson/agents	37k	156
scientific-agent-skills	29k	147
impeccable	27k	1 (with 7 design domain references)
agent-skills	27k	21
awesome-agent-skills	26k	1,424+ (curated list)
claude-skills	15k	246 (across 9 domains)
shanraisshan/draw-json-architecture-skill	3	1

🤖 AGENT COLLECTIONS

Repos primarily known as curated libraries of subagent definitions (.claude/agents/*.md). Sorted by stars descending.

Name	★
msitarzewski/agency-agents	115k	271
VoltAgent/awesome-claude-code-subagents	22k	156

💡 TIPS AND TRICKS (83)

🚫👶 = do not babysit

Prompting · Planning · Context · Session · CLAUDE.md + .claude/rules · 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 (7)

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)
break PRDs into vertical slices (tracer bullets) that cross all layers (DB + service + UI) — AI defaults to horizontal phasing (DB phase, then API phase, then frontend phase) which delays end-to-end feedback until the last phase. From the Pragmatic Programmer 🚫👶
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

■ Context (5)

Tip	Source
context rot kicks in around ~300-400k tokens on the 1M context model — don't let sessions drift past that for intelligence-sensitive work
dumb zone kicks in around ~40% context — "you hit this point where you have degrading results". Newcomers: "shoot to keep it under 40%, and if you get up to 60%, think about wrapping it up". Experienced: "aggressively keep it below 30%" — push to 60% only on simple tasks. Manual /compact or /clear to reset when switching tasks
rewind > correct — double-Esc or /rewind back to before the failed attempt and re-prompt with what you learned, instead of leaving failed attempts + corrections polluting context 🚫👶
/compact with a hint (/compact focus on the auth refactor, drop the test debugging) beats letting autocompact fire — the model is at its least intelligent point when auto-compacting due to context rot
use subagents for context management — ask yourself "will I need this tool output again, or just the conclusion?" — 20 file reads + 12 greps + 3 dead ends stay in the child's context, only the final report returns 🚫👶

■ Session Management (6)

Tip	Source
every turn is a branching point — after Claude ends a turn, pick between Continue, /rewind, /clear, /compact, or Subagent based on how much existing context you need to carry forward
new task = new session — related tasks (e.g. writing docs for what you just built) can reuse context for efficiency, but genuinely new tasks deserve a fresh session
use "summarize from here" before rewinding to have Claude write a handoff message — like a note to the previous iteration of Claude from its future self
/compact vs /clear — compact is lossy but momentum-friendly (mid-task, fuzzy details ok); /clear + brief is more work but you control exactly what carries forward (high-stakes next step)
use recaps for long-running sessions — short summaries of what Claude did and what's next, useful when returning after minutes or hours. Disable with recaps in /config
/rename important sessions (e.g. [TODO - refactor task]) and /resume them later — label each instance when running multiple Claudes simultaneously

■ CLAUDE.md + .claude/rules (8)

Tip	Source
CLAUDE.md should target under 200 lines per file. 60 lines in humanlayer (still not 100% guaranteed)
.claude/rules/*.md auto-load into every session like CLAUDE.md — add paths: YAML frontmatter to lazy-load them only when Claude touches files matching the glob
wrap domain-specific CLAUDE.md rules in <important if="..."> 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
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 🚫👶

…view the full README on GitHub.