Skip to content

PhysShell/claude-code-best-practice

 
 

Repository files navigation

claude-code-best-practice

practice makes claude perfect

Last Updated GitHub Stars

Best Practice Click on this badge to show the latest best practice
Implemented Click on this badge to show implementation in this repo
Orchestration Workflow Click on this badge to see the Command → Agent → Skill orchestration workflow

Claude Code mascot jumping

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

CONCEPTS

Feature Location Description
Commands .claude/commands/<name>.md Best Practice Implemented Entry-point prompts for workflows — invoke with /command-name
Sub-Agents .claude/agents/<name>.md Best Practice Implemented Custom agents with their own name, color, tools, permissions, and model
Skills .claude/skills/<name>/SKILL.md Best Practice Implemented Reusable knowledge, workflows, and slash commands — load on-demand or invoke with /skill-name
Workflows .claude/commands/weather-orchestrator.md Orchestration Workflow
Hooks .claude/hooks/ Best Practice Implemented Deterministic scripts that run outside the agentic loop on specific events
MCP Servers .claude/settings.json, .mcp.json Best Practice Implemented Model Context Protocol connections to external tools, databases, and APIs
Plugins distributable packages Bundles of skills, subagents, hooks, and MCP servers · Marketplaces
Settings .claude/settings.json Best Practice Implemented Hierarchical configuration system · Permissions · Model Config · Output Styles · Sandboxing · Keybindings · Fast Mode
Status Line .claude/settings.json Best Practice Implemented Customizable status bar showing context usage, model, cost, and session info
Memory CLAUDE.md, ~/.claude/projects/<project>/memory/ Best Practice Implemented Persistent context via CLAUDE.md files and @path imports · Auto Memory · Rules
Checkpointing automatic (git-based) Automatic tracking of file edits with rewind (Esc Esc or /rewind) and targeted summarization
CLI Startup Flags claude [flags] Best Practice Command-line flags, subcommands, and environment variables for launching Claude Code
AI Terms Best Practice Agentic Engineering · Context Engineering · Vibe Coding
Best Practices Official best practices · Prompt Engineering · Extend Claude Code

🔥 Hot

Feature Location Description
Agent Teams .claude/agents/<name>.md Multiple agents working in parallel on the same codebase with shared task coordination
Voice Mode built-in command speak to prompt - /voice to activate
Remote Control built-in command Continue local sessions from any device — phone, tablet, or browser · Headless Mode
Git Worktrees built-in Best Practice Isolated git branches for parallel development — each agent gets its own working copy
Ralph Wiggum Loop plugin Best Practice Implemented Autonomous development loop for long-running tasks — iterates until completion

Orchestration Workflow

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

Command Skill Agent Architecture Flow

How to Use

claude /weather-orchestrator
Component Role Example
Command Entry point, user interaction /weather-orchestrator
Agent Fetches data with preloaded skill (agent skill) weather-agent with weather-fetcher
Skill Creates output independently (skill) weather-svg-creator

DEVELOPMENT WORKFLOWS

TIPS AND TRICKS

Shayan

Workflows

Daily

Hourly

  • commit often, as soon as task is completed, commit.

Utilities

  • iTerm terminal instead of IDE (crash issue)
  • Wispr Flow for voice prompting (10x productivity)
  • claude-code-voice-hooks for claude feedback
  • status line for context awareness and fast compacting
  • /permissions with wildcard syntax (Bash(npm run *), Edit(/docs/**)) instead of dangerously-skip-permissions
  • /sandbox to reduce permission prompts with file and network isolation
  • explore settings.json features like Output Styles (e.g. Explanatory when learning a new codebase), Plan Directory, Spinner Verbs for a personalized experience

Debugging

  • /doctor
  • always ask claude to run the terminal (you want to see logs of) as a background task for better debugging
  • use mcp (Claude in Chrome, Playwright, Chrome DevTools) to let claude see chrome console logs on its own
  • provide screenshots of the issue
  • use a different model for QA — e.g. Codex for plan and implementation review

Boris Cherny + Team

☠️ STARTUPS / BUSINESSES

Claude Replaced
Voice Mode Wispr Flow, SuperWhisper
Remote Control OpenClaw
Cowork OpenAI Operator, AgentShadow
Tasks Beads
Plan Mode Agent OS
Skills / Plugins YC AI wrapper startups (reddit)

REPORTS

Report Description
Agent SDK vs CLI System Prompts Why Claude CLI and Agent SDK outputs may differ—system prompt architecture and determinism
Browser Automation MCP Comparison Comparison of Playwright, Chrome DevTools, and Claude in Chrome for automated testing
Global vs Project Settings Which features are global-only (~/.claude/) vs dual-scope, including Tasks and Agent Teams
Skills Discovery in Monorepos How skills are discovered and loaded in large monorepo projects
Agent Memory Frontmatter Persistent memory scopes (user, project, local) for subagents — enabling agents to learn across sessions
Advanced Tool Use Patterns Programmatic Tool Calling (PTC), Tool Search, and Tool Use Examples
Usage, Rate Limits & Extra Usage Usage commands (/usage, /extra-usage, /cost), rate limits, and pay-as-you-go overflow billing

About

practice made claude perfect

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • HTML 85.4%
  • Python 14.6%