claude-code-best-practice

from vibe coding to agentic engineering - practice makes claude perfect

<a href="https://github.com/shanraisshan/claude-code-best-practice/stargazers"><img src="https://img.shields.io/github/stars/shanraisshan/claude-code-best-practice?style=flat&label=%E2%98%85&labelColor=555&color=white" alt="GitHub Stars"></a><br>

<br> <img src="!/tags/a.svg" height="14"> = Agents · <img src="!/tags/c.svg" height="14"> = Commands · <img src="!/tags/s.svg" height="14"> = Skills

<p align="center">
  <img src="!/claude-jumping.svg" alt="Claude Code mascot jumping" width="120" height="100"><br>
  <a href="https://github.com/trending"><img src="!/root/github-trending-day.svg" alt="GitHub Trending #1 Repository Of The Day"></a>
</p>

<p align="center">
  <img src="!/root/supported-label.svg" alt="Supported by:" height="34">&nbsp;&nbsp;<a href="https://disrupt.com/?utm_source=github&utm_campaign=shayan_claude_code_best_practice"><img src="!/root/supported-disrupt.svg" alt="Disrupt.com — Ventures Reimagined" height="34"></a>&nbsp;&nbsp;<a href="https://claudekit.cc/?utm_source=github&utm_medium=sponsorship&utm_campaign=shayan_claude_code_best_practice"><img src="!/root/supported-claudekit.svg" alt="ClaudeKit — Production-ready skills and workflows" height="34"></a>
</p>

<p align="center">
  <img src="!/root/boris-slider.gif" alt="Boris Cherny on Claude Code" width="600"><br>
  Boris Cherny on X (<a href="https://x.com/bcherny/status/2007179832300581177">tweet 1</a> · <a href="https://x.com/bcherny/status/2017742741636321619">tweet 2</a> · <a href="https://x.com/bcherny/status/2021699851499798911">tweet 3</a>)
</p>

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

🧠 CONCEPTS

Feature	Location	Description
<img src="!/tags/a.svg" height="14"> Subagents	.claude/agents/<name>.md
<img src="!/tags/c.svg" height="14"> Commands	.claude/commands/<name>.md
<img src="!/tags/s.svg" height="14"> 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
Artifacts	/share, Artifact tool
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

<p align="center">
  <img src="!/claude-jumping.svg" alt="section divider" width="60" height="50">
</p>

<a id="orchestration-workflow"></a>

<a href="orchestration-workflow/orchestration-workflow.md"><img src="!/tags/orchestration-workflow-hd.svg" alt="Orchestration Workflow"></a>

See orchestration-workflow for implementation details of <img src="!/tags/c.svg" height="14"> Command → <img src="!/tags/a.svg" height="14"> Agent → <img src="!/tags/s.svg" height="14"> Skill pattern.

<p align="center">
  <img src="orchestration-workflow/orchestration-workflow.svg" alt="Command Skill Agent Architecture Flow" width="100%">
</p>

<p align="center">
  <img src="orchestration-workflow/orchestration-workflow.gif" alt="Orchestration Workflow Demo" width="600">
</p>

claude
/weather-orchestrator

<p align="center">
  <img src="!/claude-jumping.svg" alt="section divider" width="60" height="50">
</p>

⚙️ DEVELOPMENT WORKFLOWS

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

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

<p align="center">
  <img src="!/claude-jumping.svg" alt="section divider" width="60" height="50">
</p>

🔀 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.

<p align="center">
  <img src="!/claude-jumping.svg" alt="section divider" width="60" height="50">
</p>

🧰 SKILL COLLECTIONS

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

<p align="center">
  <img src="!/claude-jumping.svg" alt="section divider" width="60" height="50">
</p>

🤖 AGENT COLLECTIONS

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

<p align="center">
  <img src="!/claude-jumping.svg" alt="section divider" width="60" height="50">
</p>

💡 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

<a id="tips-prompting"></a>■ 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 🚫👶

<a id="tips-planning"></a>■ 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

<a id="tips-context"></a>■ 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 🚫👶

<a id="tips-session"></a>■ 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

<a id="tips-claudemd"></a>■ 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

<a id="tips-agents"></a><img src="!/tags/a.svg" height="14"> 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

<a id="tips-commands"></a><img src="!/tags/c.svg" height="14"> 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

<a id="tips-skills"></a><img src="!/tags/s.svg" height="14"> 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

<a id="tips-hooks"></a>■ 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

<a id="tips-workflows"></a>■ Workflows (5)

Tip	Source
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
/focus mode hides all intermediate work and shows only the final result — trust the model to run the right commands and just look at the outcome (toggle with /focus)
tune effort level with Opus 4.7's adaptive thinking — low for speed and fewer tokens, max for most intelligence (slider: low · medium · high · xhigh · max)

<a id="tips-workflows-advanced"></a>■ Workflows Advanced (9)

Tip	Source
use ASCII diagrams a lot to understand your architecture
use /loop for local recurring monitoring (up to 7 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