claude-code-best-practice

practice makes claude perfect

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

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

CONCEPTS

Feature	Location	Description
Commands	.claude/commands/<name>.md	Entry-point prompts for workflows — invoke with /command-name
Sub-Agents	.claude/agents/<name>.md	Custom agents with their own name, color, tools, permissions, and model
Skills	.claude/skills/<name>/SKILL.md	Reusable knowledge, workflows, and slash commands — load on-demand or invoke with /skill-name
Workflows	.claude/commands/weather-orchestrator.md
Hooks	.claude/hooks/	Deterministic scripts that run outside the agentic loop on specific events
MCP Servers	.claude/settings.json, .mcp.json	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	Hierarchical configuration system · Permissions · Model Config · Output Styles · Sandboxing · Keybindings · Fast Mode
Status Line	.claude/settings.json	Customizable status bar showing context usage, model, cost, and session info
Memory	CLAUDE.md, .claude/rules/, ~/.claude/rules/, ~/.claude/projects/<project>/memory/	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]	Command-line flags, subcommands, and environment variables for launching Claude Code
AI Terms		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	Isolated git branches for parallel development — each agent gets its own working copy
Ralph Wiggum Loop	plugin	Autonomous development loop for long-running tasks — iterates until completion

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

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

• Cross-Model Claude Code + Codex
• RPI
• Boris Feb26 workflow
• Ralph plugin with sandbox
• Human Layer RPI - Research Plan Implement
• AgentOs - 2026 its overkill (Brian Casel)
• Github Speckit
• GSD - Get Shit Done
• OpenSpec OPSX
• Superpower
• Andrej Karpathy Workflow
• Creator of Clawd Bot Workflow

TIPS AND TRICKS

■ Workflows

• CLAUDE.md should target under 200 lines per file. 60 lines in humanlayer (still not 100% guaranteed).
• use multiple CLAUDE.md for monorepos — ancestor + descendant loading
• use .claude/rules/ to split large instructions
• use commands for your workflows instead of sub-agents
• have feature specific sub-agents (extra context) with skills (progressive disclosure) instead of general qa, backend engineer.
• /memory, constitution.md does not guarantee anything
• avoid agent dumb zone, do manual /compact at max 50%
• always start with plan mode
• vanilla cc is better than any workflows with smaller tasks
• use skills in subfolders for monorepos
• agent teams with tmux and git worktrees for parallel development
• use Ralph Wiggum plugin for long-running autonomous tasks
• use ultrathink keyword in prompts for high effort reasoning
• use /model to select model and reasoning, /context to see context usage, /usage to set a weekly limit, /config to configure settings

■ Daily

• update Claude Code daily and start your day by reading the changelog
• follow r/ClaudeAI, r/ClaudeCode on Reddit
• follow Boris, Thariq, Cat, Lydia on X

■ Hourly

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

■ Utilities

• iTerm/Ghostty/tmux terminals instead of IDE (VS Code/Cursor)
• 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), Plans Directory, Spinner Verbs for a personalized experience
• /rename important sessions (e.g. [todo refactor task]) and /resume them later

■ 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

• Ask Claude to interview you using AskUserQuestion tool (Thariq) | 28/Dec/25 ● Tweet
• Boris setup - 5 tips | 03/Jan/26 ● Tweet
• 10 tips for using claude code by team itself | 01/Feb/26 ● Tweet
• 12 ways how people are customizing their claudes | 12/Feb/26 ● Tweet
• Git Worktrees - 5 ways how boris is using | 21 Feb 2026 ● Tweet
• Seeing like an Agent - lessons from building Claude Code (Thariq) | 28 Feb 2026 ● Article

☠️ 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)

Memory & Instructions (4)

1. What exactly should you put inside your CLAUDE.md — and what should you leave out?
2. If you already have a CLAUDE.md, is a separate constitution.md or rules.md actually needed?
3. How often should you update your CLAUDE.md, and how do you know when it's become stale?
4. Why does Claude still ignore CLAUDE.md instructions — even when they say MUST in all caps? (reddit)

Agents, Skills & Workflows (3)

1. When should you use a command vs an agent vs a skill — and when is vanilla Claude Code just better?
2. How often should you update your agents, commands, and workflows as models improve?
3. Does giving your subagent a detailed persona improve quality? What does a "perfect persona/prompt" for research/QA subagent look like?

Specs & Documentation (3)

1. Should every feature in your repo have a spec as a markdown file?
2. How often do you need to update specs so they don't become obsolete when a new feature is implemented?
3. When implementing a new feature, how do you handle the ripple effect on specs for other features?

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