Claude Code Best Practice: The Complete Guide to Mastering Agentic Coding with Claude
In the rapidly evolving landscape of AI-assisted development, Claude Code has emerged as the leading terminal-native agentic coding tool. But raw power means nothing without the right practices to channel it. Enter claude-code-best-practice — a meticulously curated, community-driven repository that has become the definitive reference for anyone serious about getting the most out of Claude Code. With 15,100+ stars and 1,400+ forks on GitHub, it's not just popular — it's the gold standard.
Created and maintained by shanraisshan, this repository distills wisdom from Claude Code's own creators — Boris Cherny, Thariq Shihipar, and the Anthropic team — alongside battle-tested patterns from the developer community. Whether you're a beginner exploring agentic coding for the first time or a power user orchestrating multi-agent workflows, this guide covers everything you need to know.
Repository: shanraisshan/claude-code-best-practice on GitHub
What Makes This Repository Special?
Unlike scattered blog posts or outdated documentation, claude-code-best-practice is a living document that evolves alongside Claude Code itself. It's organized into clear sections that mirror the real developer journey:
- Concepts — Understanding Commands, Sub-Agents, Skills, Hooks, MCP Servers, Plugins, Memory, and more
- Development Workflows — Battle-tested patterns like Cross-Model, RPI, and the Ralph Wiggum Loop
- Tips and Tricks — 30+ actionable tips covering prompting, planning, workflows, debugging, and utilities
- Startups & Businesses — Strategic questions and answers for engineering teams
- Reports — Deep-dive technical analyses comparing different approaches
The repository doesn't just tell you what to do — it explains why, with direct references to tweets and blog posts from the Claude Code engineering team.
Key Concepts: The Building Blocks
At the heart of effective Claude Code usage is understanding its core primitives. The repository organizes these into a clear hierarchy:
Commands (/.claude/commands/)
Custom slash commands are your primary workflow orchestrators. They define specific, repeatable tasks that Claude can execute on demand:
.claude/commands/<name>.md
The repo includes a fully working example: /weather-orchestrator, which demonstrates the Command → Agent → Skill orchestration pattern — the most powerful design pattern in Claude Code.
Sub-Agents (/.claude/agents/)
Sub-agents are specialized Claude instances with focused expertise. The key insight from the repo: don't create generic agents like "QA agent" or "backend engineer." Instead, create feature-specific sub-agents with targeted context:
.claude/agents/<name>.md
Boris Cherny himself advises: "Have feature-specific sub-agents (extra context) with skills (progressive disclosure) instead of general QA, backend engineer."
Skills (/.claude/skills/)
Skills provide progressive disclosure — Claude only loads them when relevant, keeping the context window clean:
.claude/skills/<name>/SKILL.md
The repo links to Anthropic's official skills library and demonstrates how to use skills in subfolders for monorepos.
Hooks, MCP Servers, and Plugins
The repository covers the complete Claude Code extension ecosystem:
- Hooks (
.claude/hooks/) — Automated actions triggered by Claude events - MCP Servers (
.claude/settings.jsonor.mcp.json) — External tool integrations - Plugins — Marketplace extensions like the Ralph Wiggum plugin for autonomous long-running tasks
Development Workflows: Proven Patterns
🔥 Cross-Model Workflow (Claude Code + Codex)
One of the hottest patterns in the repo is the cross-model workflow — using Claude Code for implementation but leveraging OpenAI Codex (or another model) for review and quality assurance. This creates a natural check-and-balance system where different AI models catch each other's blind spots.
The repo provides a complete implementation guide with practical templates.
🔥 RPI (Research → Plan → Implement)
The RPI workflow from HumanLayer's Advanced Context Engineering has become the standard approach:
- Research — Let Claude explore the codebase and gather context
- Plan — Create a detailed implementation plan with tests
- Implement — Execute the plan in a fresh, focused context
🔥 Ralph Wiggum Loop
For long-running autonomous tasks, the Ralph Wiggum plugin creates a loop where Claude continues working until the task is complete. The repo provides implementation details and use cases.
Other Notable Workflows
The repository catalogues many other community workflows:
| Workflow | Creator | Stars |
|---|---|---|
| GitHub Speckit | GitHub | 74K ★ |
| Superpowers | obra | 72K ★ |
| OpenSpec OPSX | Fission-AI | 28K ★ |
| Get Shit Done (GSD) | gsd-build | 25K ★ |
| Agent OS | Brian Casel | 4K ★ |
30+ Tips and Tricks: The Real Value
This is where the repository truly shines. Every tip is sourced from actual practitioners — many directly from Boris Cherny, Thariq Shihipar, and other Anthropic team members.
Prompting Tips
- Challenge Claude: Use prompts like "Grill me on these changes and don't make a PR until I pass your test" or "Prove to me this works."
- After a mediocre fix: Tell Claude: "Knowing everything you know now, scrap this and implement the elegant solution."
- Ultra-thinking: Use the
ultrathinkkeyword in prompts for high-effort reasoning mode.
Planning Tips
- Always start with Plan Mode — Claude performs significantly better when it plans before coding
- Start with a minimal spec — Ask Claude to interview you using the
AskUserQuestiontool, then use a new session to execute - Phase-wise gated plans — Each phase should have unit, automation, and integration tests
- Use a second Claude for review — Spin up a second instance to review your plan as a staff engineer
- Reduce ambiguity — Detailed specs = better output, every time
Workflow Tips (12 Essential Rules)
| # | Tip | Source |
|---|---|---|
| 1 | Keep CLAUDE.md under 200 lines per file | Boris Cherny |
| 2 | Use multiple CLAUDE.md files for monorepos | Best practice |
| 3 | Use .claude/rules/ to split large instructions | Official docs |
| 4 | Prefer Commands over Sub-Agents for workflows | Boris Cherny |
| 5 | Feature-specific agents + skills over generic roles | Boris Cherny |
| 6 | memory.md and constitution.md don't guarantee compliance | Community finding |
| 7 | Manual /compact at max 50% context usage | Best practice |
| 8 | Vanilla Claude Code beats complex workflows for smaller tasks | Community consensus |
| 9 | Use skills in subfolders for monorepos | Report |
| 10 | Use /model, /context, /usage, /extra-usage, /config regularly | Official docs |
| 11 | Enable thinking mode and explanatory output style | Boris Cherny |
| 12 | Use ultrathink keyword for high-effort reasoning | Anthropic docs |
Advanced Workflow Tips
- ASCII diagrams: Use them frequently to help Claude understand architecture
- Agent teams with tmux and Git worktrees for parallel development
/loopfor recurring monitoring — polls deployments, babysits PRs, checks builds (runs up to 3 days!)- Wildcard permissions (
Bash(npm run *),Edit(/docs/**)) instead ofdangerously-skip-permissions /sandboxfor file and network isolation to reduce permission prompts
Debugging Tips
- Share screenshots — Make it a habit to take screenshots and share with Claude whenever stuck
- Use MCP for browser debugging — Claude in Chrome, Playwright MCP, Chrome DevTools MCP
- Run terminals as background tasks for better log debugging
/doctorto diagnose installation, authentication, and configuration issues- Cross-model QA — Use Codex for plan and implementation review
Utility Tips
- Use iTerm/Ghostty/tmux terminals instead of VS Code or Cursor IDE
- Wispr Flow for voice prompting (reported 10x productivity boost)
- claude-code-voice-hooks for audio feedback from Claude
- Status line customization for context awareness and fast compacting
- Explore
settings.jsonfeatures like Plans Directory and Spinner Verbs
Hot Features (2026)
The repo tracks the latest Claude Code features as they launch:
/btw— Side-chain conversations while Claude works on the main task- Code Review — Built-in code review capabilities (Claude blog)
- Scheduled Tasks with
/loop— Recurring automation for up to 3 days - Voice Mode with
/voice— Voice-driven coding sessions /simplifyand/batch— Streamline and batch operations- Agent Teams — Multiple Claude instances working in parallel
- Remote Control with
/rc— Control Claude remotely - Headless Mode — Non-interactive Claude for CI/CD pipelines
- Git Worktrees — Parallel branch development
Startups and Businesses: Strategic Questions
The repository includes a thoughtful section addressing critical questions for engineering teams adopting Claude Code:
Memory & Instructions
- What exactly belongs in
CLAUDE.mdvs.constitution.mdvs.rules.md? - How often should you update your
CLAUDE.md? - Why does Claude sometimes ignore
CLAUDE.mdinstructions even withMUSTin caps?
Agents, Skills & Workflows
- When to use Commands vs. Agents vs. Skills vs. vanilla Claude Code?
- How to handle conflicts between personal skills and community skills?
- Can we delete code and regenerate it entirely from specs? (Not yet, but getting closer.)
Specs & Documentation
- Should every feature have a markdown spec?
- How to handle the ripple effect when one feature changes specs for others?
Reports: Deep-Dive Technical Analyses
The repo includes original technical reports that provide unique insights:
| Report | Topic |
|---|---|
| Agent SDK vs CLI System Prompts | Comparing API and CLI approaches |
| Browser Automation MCP Comparison | Claude in Chrome vs Chrome DevTools MCP |
| Global vs Project Settings | ~/.claude/ hierarchy explained |
| Skills Discovery in Monorepos | How Claude discovers and loads skills |
| Agent Memory Frontmatter | User, project, and local memory scopes |
| Advanced Tool Use Patterns | Power-user tool configurations |
| Usage, Rate Limits & Extra Usage | Understanding plan limits |
| LLM Day-to-Day Degradation | Tracking model performance over time |
| Agents vs Commands vs Skills | When to use which primitive |
Claude Code Best Practice vs Alternatives
This repo is a best practices collection, so let's compare it to other Claude Code learning resources:
| Feature | claude-code-best-practice | claude-code-ultimate-guide | Anthropic Official Docs |
|---|---|---|---|
| ⭐ Stars | 15,100+ | 1,400+ | N/A (official docs) |
| 📋 Format | Curated tips & links table | Long-form tutorial/guide | Official documentation |
| 🔥 Updated | Daily (community-driven) | Weekly | With releases |
| 🎯 Focus | Practical tips from creators | Beginner-to-power-user journey | Feature reference |
| 📚 Depth | Tips with source links | Deep explanations with quizzes | API-level detail |
| 🧪 Examples | Weather orchestrator demo | Production-ready templates | Basic examples |
| 👥 Community | Large, active | Growing, with discussions | Official support |
| 🎓 Learning | Reference/cheatsheet style | Structured course with quizzes | Documentation style |
| 📊 Reports | Yes (9 original reports) | No | No |
| 🔗 Sources | Direct links to creator tweets | Original content | Official content |
When to use each:
- claude-code-best-practice → You want a quick reference and latest tips from the people who built Claude Code
- claude-code-ultimate-guide → You want a structured learning path from beginner to advanced with exercises
- Anthropic Official Docs → You need feature-level documentation and API references
Getting Started: The Repo's Own Recommendation
The repository suggests a three-step onboarding:
- Read the repo like a course — Learn what commands, agents, skills, and hooks are before trying to use them
- Clone and play with examples — Try
/weather-orchestrator, listen to the hook sounds, run agent teams - Apply to your own project — Ask Claude to suggest which best practices to add, using this repo as a reference
Daily Habits for Claude Code Users
The repo recommends three daily habits:
- Update Claude Code daily and read the changelog
- Follow Reddit communities: r/ClaudeAI and r/ClaudeCode
- Follow the creators on X: Boris Cherny, Thariq Shihipar, Cat Wu, Lydia Hallie, Claude AI, Alex Albert
FAQ
Q: Is this repo only for advanced users? A: No. It's organized from basic concepts to advanced workflows. Beginners can start with the Concepts section and gradually move through the tips.
Q: How often is the repository updated? A: Very frequently — the repo tracks new Claude Code features as they're released, often within hours of announcements.
Q: Do I need a Claude Max plan to use these practices?
A: Most practices work with any Claude Code plan. Some advanced features like agent teams and extended /loop sessions may require higher-tier plans.
Q: Can I contribute my own tips? A: Yes! The repository is open-source under the MIT License and actively accepts contributions.
Q: Does this replace the official Anthropic documentation? A: No — it complements it. The official docs cover feature specifications, while this repo focuses on practical patterns and tips from real-world usage.
Q: What's the Command → Agent → Skill orchestration pattern? A: It's the recommended architecture where a Command orchestrates the workflow, delegates to Agents for specialized work, and Agents use Skills for specific capabilities. The weather-orchestrator example demonstrates this pattern end-to-end.
Q: Why does the repo recommend Commands over Sub-Agents for workflows? A: Commands are lighter-weight, don't consume extra context, and are better suited for defining repeatable workflows. Sub-Agents should be reserved for tasks that need specialized context and personas.
Conclusion
claude-code-best-practice isn't just a collection of tips — it's the operational handbook for anyone using Claude Code seriously. With direct insights from the tool's creators, community-battle-tested patterns, and a commitment to staying current with every new feature, it's earned its 15,000+ stars for good reason.
Whether you're trying to figure out the right CLAUDE.md structure, debating Commands vs. Agents, or looking for the latest cross-model workflow patterns, this repository has you covered. Clone it, bookmark it, and make it part of your daily Claude Code workflow.
Start here: github.com/shanraisshan/claude-code-best-practice
Last updated: March 2026. Stars, forks, and features reflect the latest available data.