Mastering Claude Code: Custom Commands and Workflow

Commands as Encoded Best Practices

In Part 1, we established the foundation with CLAUDE.md files and terminal customization. Now we’ll build on that with custom slash commands.

Custom commands are more than shortcuts. They’re encoded best practices—complex workflows distilled into simple invocations that ensure consistency across all your projects.

I’ve built 9 commands organized into three categories:

Let’s explore each category.

Research & Documentation Commands

Understanding code is the foundation of any change. These commands help you document and comprehend codebases effectively.

/research_codebase

My go-to command for understanding any part of a codebase:

---
description: Document codebase as-is with thoughts
             directory for historical context
model: opus
---

# Research Codebase

You are tasked with conducting comprehensive research
across the codebase to answer user questions by spawning
parallel sub-agents and synthesizing their findings.

## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN
## THE CODEBASE AS IT EXISTS TODAY

- DO NOT suggest improvements or changes
- DO NOT perform root cause analysis
- DO NOT propose future enhancements
- DO NOT critique the implementation
- ONLY describe what exists, where it exists, how it works

Key features:

1. Parallel research - Uses specialized agents for efficiency:

**For codebase research:**
- Use the **codebase-locator** agent to find WHERE files
  and components live
- Use the **codebase-analyzer** agent to understand HOW
  specific code works
- Use the **codebase-pattern-finder** agent to find
  examples of existing patterns

2. Persistent output - Research is saved for future reference:

## Generate research document:

- Filename: `thoughts/shared/research/YYYY-MM-DD-description.md`
- Structure the document with YAML frontmatter:
  - date, researcher, git_commit, branch, repository
  - topic, tags, status

## Summary
[High-level documentation answering the user's question]

## Detailed Findings
### [Component/Area 1]
- Description of what exists ([file.ext:line](link))
- How it connects to other components

3. Historical context - Integrates with the thoughts directory pattern from Part 1, providing both live codebase findings and historical context from previous research.

/explain

Code explanation with ASCII diagrams for visual understanding:

Explain code using concise explanations and ASCII diagrams
that visualize control flow and data flow. Show how
execution proceeds and how data transforms through
the system.

This command produces explanations with visual diagrams, making it perfect for:

• Onboarding onto unfamiliar codebases
• Understanding complex control flows
• Documenting how data moves through systems
• Creating visual references for team discussions

/interview

Deep dive into plans, specifications, or any document:

---
description: Interview me about the plan
argument-hint: [plan]
model: opus
---

Read this plan file $1 and interview me in detail using the
AskUserQuestionTool about literally anything: technical
implementation, UI & UX, concerns, tradeoffs, etc.
but make sure the questions are not obvious.

Be very in-depth and continue interviewing me continually
until it's complete, then write the spec to the file.

This command forces you to think through edge cases and assumptions you might have missed. It’s invaluable for:

• Validating implementation plans before starting work
• Identifying gaps in specifications
• Stress-testing architectural decisions
• Uncovering hidden requirements

Git Workflow Commands

These commands enforce consistent git practices across all projects.

/commit-all

My standard commit command with safety checks:

If you are in Main or main or master branch, you should
create a new branch first and then commit your changes.

Check all staged and unstaged files and commit everything.
You are following git conventional message for commits.

## NEVER DO
- do not add claude or CLAUDE text in any case like
  co-author in the git commit message.

This enforces:

• Branch protection - Never commit directly to main
• Conventional commits - Consistent message format
• Clean history - No AI co-author tags

/commit-staged

For when you want more control over what gets committed:

If you are in Main or main or master branch, you should
create a new branch first and then commit your changes.

Only commit staged files.
You are following git conventional message for commits.

Use this when you’ve carefully staged specific changes and don’t want Claude to add anything else.

/commit-all-main

For the rare cases when you explicitly want to commit directly to main:

You are in Main or main or master branch, do not create
a new branch just commit your changes.

Use sparingly—typically only for documentation updates or configuration changes that don’t need a feature branch.

Quality Commands

These commands help maintain code quality and verify implementations.

/fix-test

Run a specific test and automatically fix failures:

---
description: Run test and fix the failed test case
---

Run test #$ARGUMENTS following our coding standards
and fix the failed test case

Simple but incredibly useful for TDD workflows. When a test fails, this command:

1. Runs the specified test
2. Analyzes the failure
3. Fixes the code following your project’s coding standards
4. Re-runs to verify the fix

/optimize

Performance analysis and suggestions:

---
description: Analyze code for performance issues
---

Analyze this code for performance issues and suggest
optimizations and store the suggestions in the plan file.

This command examines code for:

• Algorithmic inefficiencies
• Memory usage patterns
• Database query optimization opportunities
• Caching opportunities
• Bundle size considerations (for frontend code)

/verify-spec

Verify implementation against specifications:

---
description: Verify the implementation against agreed Spec
---

Verify the implementation against the agreed specification.

This is invaluable for ensuring your implementation matches what was planned. It:

• Compares actual implementation to specification
• Identifies missing features or behaviors
• Highlights deviations that need discussion
• Confirms when work is complete

The Complete Workflow

Here’s how these commands work together in practice:

A typical feature development:

1. /research_codebase - Understand existing patterns and architecture
2. Create a plan - Use Claude’s planning capabilities (enforced by CLAUDE.md)
3. /interview - Deep dive into edge cases and assumptions
4. Implement - Write the code
5. /fix-test - Run tests and fix any failures
6. /verify-spec - Confirm implementation matches specification
7. /commit-all - Create branch if needed and commit changes

Command Structure

Commands live in ~/.claude/commands/ as Markdown files:

~/.claude/commands/
├── research_codebase.md
├── explain.md
├── interview.md
├── commit-all.md
├── commit-staged.md
├── commit-all-main.md
├── fix-test.md
├── optimize.md
└── verify-spec.md

Each file has:

1. YAML frontmatter - metadata like description and model
2. Markdown body - the actual command instructions

Example structure:

---
description: Brief description shown in /help
argument-hint: [optional argument hint]
model: opus  # or sonnet, haiku
---

# Command Name

Instructions for Claude to follow when this command
is invoked...

The model field is powerful—complex commands like /research_codebase use Opus for maximum capability, while simpler commands can use Sonnet or Haiku for speed.

Creating Your Own Commands

To create a new command:

1. Create a markdown file in ~/.claude/commands/
2. Add YAML frontmatter with at least a description
3. Write the instructions Claude should follow

Example custom command for code review:

---
description: Review code for security and best practices
---

Review the provided code for:
1. Security vulnerabilities (OWASP Top 10)
2. Error handling completeness
3. Input validation
4. Authentication/authorization issues

Provide specific, actionable feedback with file:line references.

Conclusion

Custom commands transform repetitive workflows into single invocations. By encoding best practices—research before implementation, interview to validate assumptions, verify against specifications—you create guardrails that improve code quality while reducing cognitive overhead.

Key takeaways:

• Research commands (/research_codebase, /explain) capture and preserve knowledge
• Git commands (/commit-all, /commit-staged) enforce safe branching practices
• Quality commands (/fix-test, /verify-spec, /optimize) maintain standards
• Command structure is simple: Markdown file with YAML frontmatter

The 9 commands we covered form a complete development lifecycle, but they’re just building blocks. Create your own commands for workflows unique to your team or project.

What’s Next

Commands are powerful, but they’re just one layer. In Part 3, we’ll explore:

• 10 specialized agents - Personas with deep domain expertise
• 19+ professional skills - Document generation, design, development workflows
• The orchestrator pattern - Coordinating multiple agents for complex tasks

These agents and skills transform Claude Code from a single assistant into a virtual team of specialists.

Next in series: Specialized Agents and Professional Skills - Creating a virtual team