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 | · |
🔥 Hot
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
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
🔀 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.
| Name | ★ | Type | Bridges to | What it does |
|---|
| musistudio/claude-code-router | 34k | Router | OpenRouter, DeepSeek, Ollama, Gemini, Kimi, Qwen, Groq, +more | Routes Claude Code's API to any compatible provider, with per-task model selection |
| router-for-me/CLIProxyAPI | 32k | Router | Gemini CLI, Codex, Claude Code, Antigravity | Wraps each CLI as an OpenAI/Gemini/Claude/Codex-compatible API service |
| openai/codex-plugin-cc | 18k | Plugin | Codex / GPT-5 | Official OpenAI plugin: /codex:review, /codex:adversarial-review, /codex:rescue inside Claude Code |
| BeehiveInnovations/pal-mcp-server | 12k | MCP | Gemini, OpenAI, Azure, Grok, Ollama, OpenRouter (50+ models) | Multi-model MCP server (formerly zen-mcp-server) — call other models as Claude tools |
🧰 SKILL COLLECTIONS
Repos primarily known as curated libraries of SKILL.md files (distinct from full workflow methodologies above). Sorted by stars descending.
🤖 AGENT COLLECTIONS
Repos primarily known as curated libraries of subagent definitions (.claude/agents/*.md). Sorted by stars descending.
💡 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 | |
■ 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)
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 🚫👶 | |
■ 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 (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) |
■ 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 | |
| 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 (6)
| 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 | |
| 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)
■ Daily (2)
Tips from Claude code CLI binary
Spinner Verbs & Tips (extracted from CLI binary v2.1.121)
🎬 VIDEOS / PODCASTS
| Video / Podcast | Source | YouTube |
|---|
| From Vibe Coding to Agentic Engineering (Andrej) | 02 May 2026 | AI Engineer |  | YouTube |
| Full Walkthrough: Workflow for AI Coding (Matt) | 24 Apr 2026 | Matt Pocock | | YouTube |
| Everything We Got Wrong About Research-Plan-Implement (Dex) | 24 Mar 2026 | MLOps Community | | 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 |
🔔 SUBSCRIBE
| Source | Name | Badge |
|---|
 | r/ClaudeAI, r/ClaudeCode, r/Anthropic | |
 | Claude, Claude Devs, Anthropic, Boris, Thariq, Cat, Lydia, Noah, Anthony, Alex, Kenneth | |
| Jesse Kriss (Superpowers), Affaan Mustafa (ECC), Garry Tan (gstack), Dex Horthy (HumanLayer), (), (), (), (), (), (), (), (), (), (), () |
☠️ STARTUPS / BUSINESSES
If you have answers, do let me know at shanraisshan@gmail.com
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?
- Should you have a generalist subagent or a feature-specific/role-specific agent? Does giving your subagent a detailed persona improve quality, and what does a "perfect persona prompt" for research/vision 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
Get the maximum out of this repo by following these steps:
- Read this repo as a course, not as a workflow or skill. It's reference material first; you'll run things later.
- Don't use Claude as a chatbot. Learn the primitives — agents, commands, skills, hooks — and assemble them into your own workflow.
- Run
/weather-orchestrator to see a complete command → agent → skill flow. Use it as a template for any dev workflow, from planning to shipping.
- Listen for the custom hook sounds while you work. Their implementation lives in the dedicated Claude Code Hooks repo; other patterns like Agent Teams ship inside this repo's
implementation/ directory.
- Learn the advanced topics and their implementations from the 🔥 Hot sub-table — for example, the Ralph Wiggum self-evolving loop is a full working repo you can clone to see one of these patterns end-to-end.
- Point Claude at the tips and tricks section in your own project and ask it to suggest edits — especially how to restructure your
CLAUDE.md. Every tip is sourced from the Claude team or the community.
- Subscribe to the Reddit and YouTube channels in the Subscribe section to keep up with the community.
🎬 Videos
📊 Presentations
✨Trending on Github in March 2026✨
Star History
stars and counting
Other Repos
Developed by
| # | Workflow | Description |
|---|
| 1 | /workflows:development-workflows | Update the DEVELOPMENT WORKFLOWS table and cross-workflow analysis report by researching all 10 workflow repos in parallel |
| 2 | /workflows:skill-collections | Update the SKILL COLLECTIONS table by researching all 5 skill-collection repos in parallel |
| 3 | /workflows:agent-collections | Update the AGENT COLLECTIONS table by researching all agent-collection repos in parallel |
| 4 | /workflows:best-practice:workflow-concepts | Update the README CONCEPTS section with the latest Claude Code features and concepts |
| 5 | /workflows:best-practice:workflow-claude-settings | Track Claude Code settings report changes and find what needs updating |
| 6 | /workflows:best-practice:workflow-claude-subagents | Track Claude Code subagents report changes and find what needs updating |
| 7 | /workflows:best-practice:workflow-claude-commands | Track Claude Code commands report changes and find what needs updating |
| 8 | /workflows:best-practice:workflow-claude-skills | Track Claude Code skills report changes and find what needs updating |
Extras
Sponsor My Work
If you like my work, buy me a doodh patti 🍵 on
Polar
Want your brand in the header? Header placements are available — email shanraisshan@gmail.com.
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
→ 
