claude-code-best-practice
from vibe coding to agentic engineering - practice makes claude perfect
= Agents · = Commands · = Skills
[!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) | |
| Sessions | --resume, --continue, /resume, /branch | |
| Context Window | /compact, /clear, /context | |
| CLI Startup Flags | claude [flags] | Interactive Mode · Env Vars |
| AI Terms | | |
| Best Practices | Prompt Engineering · Extend Claude Code | |
| Prompt Library |
🔥 Hot
| Feature | Location | Description |
|---|---|---|
Ultrareview  | /code-review ultra, claude ultrareview [target] | Tasks tracking |
| Devcontainers | .devcontainer/ | |
| Channels | --channels, plugin-based | Reference |
| 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 | |
| Cross-Session Messaging | SendMessage, ListAgents, /list-agents | |
| 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
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.
🤖 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 | |
| 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 🚫👶 | |
| 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 (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 | |
| use auto mode instead of dangerously-skip-permissions — a model-based classifier decides if each command is safe and auto-approves, pauses and asks if risky. Shift+Tab to cycle Ask → Plan → Auto modes 🚫👶 | |
| use /less-permission-prompts skill to scan session history for safe bash/MCP commands that repeatedly prompt, then get a recommended allowlist to paste into settings | |
| build a /go skill that (1) tests end-to-end via bash/browser/computer use (2) runs /simplify (3) puts up a PR — so when you come back, you know the code works 🚫👶 | |
■ 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)
| Tip | Source |
|---|---|
| iTerm/Ghostty/tmux terminals instead of IDE (VS Code/Cursor) | |
| /voice or 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 (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 | | YouTube |
| The Secrets of Claude Code From the Engineers Who Built It (Cat) | 29 Oct 2025 | Every | | YouTube |
🔔 SUBSCRIBE
☠️ STARTUPS / BUSINESSES
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?
- 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?
🤔 Does code matter?
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-orchestratorto 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
Star History
stars and counting
Other Repos
Developed by
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 [email protected].