If you’ve been using Claude Code for more than a few days, you’ve probably hit the same wall I did: you get it working, you’re impressed, and then you realize you’re barely scratching the surface of what it can actually do.
A developer named Shan Raisshan has been maintaining a Claude Code best practices repository on GitHub that documents the full feature set in one place — and it’s genuinely one of the more useful resources I’ve found for getting serious with agentic AI development.
Here’s what the repo covers and what I think is actually worth your time.
The Eight Building Blocks of Claude Code
Claude Code isn’t just a coding assistant you type at. It has an architecture — and once you understand its components, your whole mental model of what’s possible shifts.
1. Commands (.claude/commands/)
Commands are entry-point prompts you invoke with a slash. You define them as markdown files in .claude/commands/, and they can accept arguments, inject dynamic context via shell commands, and target specific models.
The best practice guide documents every frontmatter field: description, argument-hint, allowed-tools, and model. Commands also support string substitutions like $ARGUMENTS, $ARGUMENTS[N], and dynamic shell injection using backtick syntax.
Practically speaking: if you find yourself typing the same instructions repeatedly, that’s a command waiting to be written.
2. Sub-Agents (.claude/agents/)
Sub-agents are custom agents with their own name, model, tool permissions, memory scope, and even lifecycle hooks. They’re defined in .claude/agents/ and can be invoked explicitly or configured to fire proactively based on their description.
What makes this interesting is the level of isolation and control. You can set a sub-agent to run in a git worktree (isolation: "worktree"), limit its tool access, cap its turn count, preload specific skills at startup, and configure it to run as a background task. The permissionMode field lets you decide how much autonomy it gets — from requiring approval on every tool call to bypassing permissions entirely.
3. Skills (.claude/skills/)
Skills are reusable knowledge bundles — domain context, workflows, and procedures that agents can load on demand. Unlike commands (which are user-invoked entry points), skills are knowledge that agents pull in when they need it.
You can preload skills into a sub-agent at startup so it always has that context available, or let agents discover and invoke skills dynamically as tasks require them.
4. Hooks (.claude/hooks/)
Hooks are deterministic scripts that run outside the agentic loop on specific events: PreToolUse, PostToolUse, Stop. They’re defined separately from the AI and execute reliably on the triggers you specify.
The repo links to a separate voice hooks project as a real-world example. The value here is that hooks give you a way to inject side effects and validation that don’t depend on the LLM making the right call — they just run.
5. MCP Servers
Model Context Protocol connections let Claude Code talk to external tools, databases, and APIs. Configuration lives in .claude/settings.json or .mcp.json. This is how you connect Claude Code to real systems — your database, your internal APIs, external services.
6. Memory (CLAUDE.md)
Persistent context that Claude loads at startup. The main file is CLAUDE.md, but the memory system also supports .claude/rules/, global rules at ~/.claude/rules/, and project-specific memory at ~/.claude/projects/<project>/memory/.
The auto-memory feature and @path imports let you build structured context that scales beyond a single file.
7. Checkpointing
Automatic git-based tracking of file edits. You can rewind with Esc Esc or /rewind, and targeted summarization means you get meaningful checkpoints rather than just raw diffs. This alone changes how you think about letting Claude make wide-ranging edits — you have a real undo system.
8. Settings (.claude/settings.json)
A hierarchical configuration system covering permissions, model config, output styles, sandboxing, keybindings, fast mode, and the status line (which you can customize to show context usage, cost, and session info).
The Orchestration Pattern: Command → Agent → Skill
The repo’s most useful conceptual contribution is documenting the orchestration pattern explicitly. The flow is:
- Command — The entry point that handles user interaction and orchestrates the workflow
- Agent — Receives a task, uses its preloaded skill as domain knowledge to execute it
- Skill — Either preloaded into an agent at startup, or invoked directly by the command for independent tasks
The weather system demo in the repo illustrates this well: a /weather-orchestrator command asks the user for temperature preference, spawns a weather-agent that has the weather-fetcher skill preloaded, and independently invokes a weather-svg-creator skill for the visual output.
This pattern — separating user interaction, data logic, and output generation into distinct components — is what takes Claude Code from “smart assistant” to “actual software architecture.”
The Newer Features Worth Knowing About
Agent Teams
Multiple agents working in parallel on the same codebase with shared task coordination. This is the feature that fundamentally changes what Claude Code can accomplish on large projects — instead of one agent sequentially working through a task list, you get a team with specialization and parallelism.
Git Worktrees
Each agent gets its own isolated git branch and working copy. Boris Cherny (who leads Claude Code at Anthropic) has been posting about this on X — it’s the foundation for true parallel development. One agent refactors the API while another writes tests while another updates documentation, all without stepping on each other.
Ralph Wiggum Loop
Named after the Simpsons character known for enthusiastic persistence, this is an autonomous development loop plugin for long-running tasks. It iterates until completion — essentially giving Claude Code the ability to run unattended on complex tasks that require multiple cycles of work and verification.
There’s a how-to guide and the plugin lives at anthropics/claude-code.
Voice Mode
Speak to prompt. Activate with /voice. This is newer and I haven’t used it extensively, but the practical implication for anyone working in environments where typing is impractical is obvious.
Remote Control
Continue local Claude Code sessions from any device — phone, tablet, browser. Combined with headless mode, this means your AI development environment isn’t tied to a single machine.
What’s Actually Useful From This Repo
The best-practice files are worth bookmarking as reference material. When I’m setting up a new Claude Code project, the commands and sub-agents frontmatter tables alone save me from having to dig through official docs to remember which fields are available and what each one does.
The orchestration workflow document is the part I keep coming back to. It’s easy to use Claude Code as a fancy autocomplete or a one-off task runner. The Command → Agent → Skill pattern is a reminder that you can — and probably should — architect your AI workflows the same way you’d architect software.
If you’re building anything serious with Claude Code, the repo is at github.com/shanraisshan/claude-code-best-practice. It’s actively maintained (last updated March 2026) and tracks the latest feature additions faster than the official docs do.
