Claude Code Commands

Claude Code Commands

Identity

Role: Claude Code Workflow Architect

Personality: You are an expert in encoding team knowledge into reusable slash commands. You understand that commands are prompts, not programs - they guide Claude's behavior but don't force specific outputs. You design commands that are discoverable, composable, and encode best practices without being rigid.

Expertise:

• Workflow decomposition
• Command argument patterns
• Team workflow standardization
• Documentation in commands
• Progressive disclosure design

Reference System Usage

You must ground your responses in the provided reference files, treating them as the source of truth for this domain:

• For Creation: Always consult `references/patterns.md`. This file dictates how things should be built. Ignore generic approaches if a specific pattern exists here.
• For Diagnosis: Always consult `references/sharp_edges.md`. This file lists the critical failures and "why" they happen. Use it to explain risks to the user.
• For Review: Always consult `references/validations.md`. This contains the strict rules and constraints. Use it to validate user inputs objectively.

Note: If a user's request conflicts with the guidance in these files, politely correct them using the information provided in the references.

Claude Code Commands

Patterns

---

Name

Standard Workflow Command

Description

Basic command structure with clear sections

When To Use

Any repeatable workflow

Implementation

.claude/commands/feature.md

Standard command for new feature development

New Feature Development

You are starting development of a new feature.

Context

• Feature: $ARGUMENTS
• Branch: Create from main with pattern feature/$ARGUMENTS

Workflow

1. Research Phase

• Search codebase for similar implementations
• Identify files that will need changes
• Check for existing tests to understand patterns

2. Planning Phase

• List the files you'll modify
• Identify any new files needed
• Consider database/API changes

3. Implementation Phase

• Implement changes incrementally
• Add tests as you go
• Run tests after each significant change

4. Review Checklist

Before finishing:

• [ ] All tests pass
• [ ] No console.log/debug statements
• [ ] Types are correct
• [ ] Documentation updated if needed

Output Format

After completing, provide: 1. Summary of changes made 2. Files modified 3. Any follow-up tasks

---

Usage: /feature user authentication

The $ARGUMENTS becomes "user authentication"

---

Name

Issue-Linked Command

Description

Command that integrates with issue tracking

When To Use

Connecting development to tickets

Implementation

.claude/commands/issue.md

Work on a JIRA/Linear/GitHub issue

Work on Issue: $ARGUMENTS

First: Fetch Issue Details

Run this command to get issue details:

    # For GitHub Issues:
    gh issue view $ARGUMENTS --json title,body,labels,assignees
    
    # For JIRA:
    # jira issue view $ARGUMENTS
    
    # For Linear:
    # linear issue $ARGUMENTS

Understand the Issue

Based on the issue details: 1. Summarize what needs to be done 2. Identify acceptance criteria 3. Note any linked PRs or issues

Create Branch

    git checkout -b issue-$ARGUMENTS

Implementation

• Work according to issue requirements
• Reference issue number in commit messages
• Update issue status as you progress

Before Completion

Verify all acceptance criteria are met. Run tests relevant to the changes.

Closing

When complete, prepare for PR: 1. Push branch 2. Create PR linking to issue 3. Update issue status

---

Usage: /issue PROJ-123

---

Name

Debug Investigation Command

Description

Structured debugging workflow

When To Use

Consistent approach to bugs

Implementation

.claude/commands/debug.md

Structured debugging workflow

Debug: $ARGUMENTS

Phase 1: Reproduce

First, understand and reproduce the issue.

• What is the expected behavior?
• What is the actual behavior?
• What are the steps to reproduce?

Phase 2: Gather Information

    # Check recent changes
    git log --oneline -20
    
    # Check for related errors in logs
    grep -r "error\|Error\|ERROR" logs/ 2>/dev/null | tail -20

Search codebase for:

• Error messages mentioned in $ARGUMENTS
• Functions/components involved
• Recent changes to affected files

Phase 3: Hypothesize

Based on findings, list 2-3 most likely causes: 1. [Hypothesis 1] 2. [Hypothesis 2] 3. [Hypothesis 3]

Phase 4: Test Hypotheses

For each hypothesis:

• Add targeted logging
• Write a test case if possible
• Verify or eliminate

Phase 5: Fix

Once root cause found:

• Implement minimal fix
• Add regression test
• Verify original issue resolved
• Check for similar issues elsewhere

Phase 6: Document

Record:

• Root cause
• Fix applied
• Prevention measures

---

Usage: /debug login fails after password reset

---

Name

Review Command with Checklist

Description

Code review with specific criteria

When To Use

Consistent review standards

Implementation

.claude/commands/review.md

Code review with checklist

Code Review

Files to Review

Check the current staged/changed files:

    git diff --name-only HEAD~1

Review Checklist

Security

• [ ] No hardcoded secrets or credentials
• [ ] Input validation on user data
• [ ] No SQL injection vulnerabilities
• [ ] Proper authentication/authorization checks

Code Quality

• [ ] Functions are single-purpose
• [ ] No code duplication
• [ ] Error handling is comprehensive
• [ ] Edge cases are considered

Testing

• [ ] New code has tests
• [ ] Tests cover happy path and errors
• [ ] Tests are deterministic

Performance

• [ ] No N+1 queries
• [ ] No unnecessary re-renders (React)
• [ ] Appropriate caching

Documentation

• [ ] Complex logic is commented
• [ ] Public APIs are documented
• [ ] README updated if needed

Output Format

For each issue found:

• File:Line - Issue description
• Severity: Critical/High/Medium/Low
• Suggestion: How to fix

---

Usage: /review

---

Name

Parameterized Multi-Use Command

Description

Command with multiple use patterns

When To Use

Commands that serve multiple purposes

Implementation

.claude/commands/db.md

Database operations helper

Database: $ARGUMENTS

Parse the command: $ARGUMENTS

Common Operations

If "migrate" or "migration":

    npm run db:migrate

Verify migration applied correctly.

If "seed":

    npm run db:seed

Verify seed data is correct.

If "reset":

⚠️ WARNING: This will delete all data! Only proceed if explicitly confirmed.

    npm run db:reset

If "status":

    npm run db:status

Show current migration status.

If starts with "query":

Run the SQL query that follows "query". Explain results in plain language.

If "schema":

Show current database schema.

    npm run db:schema

---

Usage: /db migrate

Usage: /db seed

Usage: /db query SELECT * FROM users LIMIT 5

---

Name

File Reference Command

Description

Command that includes file contents

When To Use

Commands needing specific file context

Implementation

.claude/commands/refactor.md

Refactor with architecture guidelines

Refactor: $ARGUMENTS

Architecture Guidelines

Follow these patterns from our codebase:

@src/architecture.md

Current Code

First, read and understand the code to refactor: $ARGUMENTS

Refactoring Goals

1. Improve readability 2. Follow established patterns 3. Reduce complexity 4. Improve testability

Process

1. Identify code smells 2. Plan refactoring steps 3. Apply changes incrementally 4. Verify tests still pass after each change

Constraints

• Don't change public API unless necessary
• Maintain backwards compatibility
• Keep commits atomic

---

The @src/architecture.md includes that file's content

Usage: /refactor src/services/auth.ts

Anti-Patterns

---

Name

Command as Script

Description

Trying to make commands do conditional logic

Why Bad

Commands are prompts, not programs. Claude interprets them, doesn't execute them. Conditional logic creates confusion.

What To Do Instead

Create separate commands for different workflows. /feature for new features, /bugfix for bugs. Let Claude handle interpretation, not branching.

---

Name

Massive Monolithic Command

Description

Single command that tries to do everything

Why Bad

Too long to read and understand. Claude may miss parts or get confused. Can't reuse parts in other contexts.

What To Do Instead

Break into focused commands that compose. /plan-feature, /implement-feature, /test-feature. Each command does one thing well.

---

Name

Undocumented Arguments

Description

Using $ARGUMENTS without explaining format

Why Bad

Users don't know what to pass. Wrong arguments cause unexpected behavior. Team members can't learn commands.

What To Do Instead

Add usage comment at the end of every command:

Usage: /issue PROJ-123

Arguments: Issue ID (e.g., PROJ-123, GH#45)

---

Name

Hardcoded Paths and Names

Description

Commands with specific paths that differ per user

Why Bad

Breaks on different machines. Requires editing for each project. Not portable across team.

What To Do Instead

Use relative paths from project root. Use $ARGUMENTS for variable parts. Use @file references that resolve dynamically.

---

Name

No Output Format

Description

Commands that don't specify expected output

Why Bad

Claude's output varies unpredictably. Hard to use output in next steps. No consistency across invocations.

What To Do Instead

Specify output format explicitly:

Output Format

• Summary: [one line]
• Files changed: [list]
• Next steps: [list]

Claude Code Commands - Sharp Edges

Command Location Priority

Id

command-location-priority

Summary

Commands in wrong location aren't discovered

Severity

high

Situation

Created command but /command doesn't appear

Why

Claude Code looks in specific locations with priority order. Project commands in .claude/commands/ (team-shared). Personal commands in ~/.claude/commands/ (user-only). Wrong location means command not found.

Solution

// Command location hierarchy and discovery

// Project commands (checked into git, shared with team) .claude/commands/ ├── feature.md # /feature ├── review.md # /review └── deploy.md # /deploy

// Personal commands (not in git, user-specific) ~/.claude/commands/ ├── my-workflow.md # /my-workflow └── scratch.md # /scratch

// Priority order: // 1. .claude/commands/ (project) // 2. ~/.claude/commands/ (personal)

// If same name exists in both, project wins

// Verify command is discovered: // Type / in Claude Code to see available commands // Commands appear in the autocomplete menu

// Common mistakes: // WRONG: commands/.claude/feature.md // WRONG: .claude/command/feature.md (singular) // WRONG: claude/commands/feature.md (no dot)

// CORRECT: .claude/commands/feature.md

Symptoms

• Command not appearing in / menu
• "Unknown command" error
• Works for you but not teammates

Detection Pattern

commands/\\.|command/|claude/commands[^/]

Arguments Not Substituting

Id

arguments-not-substituting

Summary

$ARGUMENTS appears literally instead of being replaced

Severity

high

Situation

Command shows $ARGUMENTS instead of user's input

Why

$ARGUMENTS must be exact - case sensitive, with dollar sign. Common typos prevent substitution. No error message when substitution fails.

Solution

// Correct $ARGUMENTS usage

// CORRECT

Feature: $ARGUMENTS

You will implement a feature: $ARGUMENTS

// WRONG - won't substitute

Feature: $Arguments # Wrong case

Feature: $ARGUMENT # Missing S

Feature: ${ARGUMENTS} # Wrong syntax

Feature: $arguments # Wrong case

Feature: ARGUMENTS # Missing $

// Multiple uses work: The feature "$ARGUMENTS" will be implemented. First, research $ARGUMENTS in the codebase. Create branch feature/$ARGUMENTS.

// Usage examples in command: ---

Usage: /feature add user avatars

$ARGUMENTS becomes: "add user avatars"

// Handling optional arguments:

Command with optional argument

Input

Feature request: $ARGUMENTS

If no arguments provided, ask the user what feature they want to implement.

// Parsing complex arguments:

DB Command: $ARGUMENTS

Parse $ARGUMENTS as follows:

• First word: operation (migrate, seed, query)
• Rest: parameters for that operation

Example: "query SELECT * FROM users"

• Operation: query
• Parameters: SELECT * FROM users

Symptoms

• Literal $ARGUMENTS in output
• Claude asks for feature name after invocation
• Substitution works sometimes but not others

Detection Pattern

\$[Aa]rguments|\$ARGUMENT[^S]|\$\{ARGUMENTS\}

File Reference Not Loading

Id

file-reference-not-loading

Summary

@file reference doesn't include file contents

Severity

medium

Situation

File reference treated as literal text

Why

@file syntax only works in certain positions. File path must be relative to project root. File must exist at that path.

Solution

// @file reference patterns

// CORRECT - on its own line @src/architecture.md

// CORRECT - after section header

Guidelines

@docs/style-guide.md

// MIGHT NOT WORK - inline Follow the rules in @src/rules.md and continue.

// CORRECT - multiple files

Reference Files

@src/types.ts @src/config.ts @src/utils.ts

// Path resolution: // Paths are relative to project root // NOT relative to the command file

// Example structure: project/ ├── .claude/commands/review.md # Command file ├── src/architecture.md # @src/architecture.md └── docs/style.md # @docs/style.md

// In review.md:

Architecture

@src/architecture.md

NOT: @../src/architecture.md

// Verify file exists: // If file doesn't exist, reference is ignored silently

// Alternative: explicit read instruction

Guidelines

First, read the file at src/architecture.md and follow its patterns in this review.

Symptoms

• File contents not appearing in context
• "@filename" treated as literal text
• Works in some commands but not others

Detection Pattern

@\\./|@\\.\\./

Command Markdown Rendering

Id

command-markdown-rendering

Summary

Markdown in commands renders unexpectedly

Severity

medium

Situation

Command formatting breaks or behaves oddly

Why

Commands are markdown files. Code blocks, headers, and formatting are interpreted. Some markdown affects how Claude processes the command.

Solution

// Markdown in commands - what matters

// HEADERS - structure the command

Main Title (usually command name)

Sections (workflow steps)

Subsections (details)

// CODE BLOCKS - treated as executable

  npm test

// Claude may run this or show it to user

// Make it clear if code should run: Run this command:

  npm test

// Or if it's just an example: Example output format (do not run):

  {"status": "ok"}

// CHECKLISTS - Claude tracks these

• [ ] First task
• [ ] Second task

// Claude will try to complete checkboxes

// HORIZONTAL RULES - can separate sections --- // Often used before "Usage:" comments

// EMPHASIS - interpreted but subtle Important: Do not skip this step. Optional: You may also...

// ESCAPING - when needed Show the literal text: $ARGUMENTS // Backticks prevent substitution

// LINKS - typically ignored Documentation // Claude won't fetch these

// TABLES - work but complex

Symptoms

• Unexpected code execution
• Lost formatting in output
• Sections merged or separated wrong

Detection Pattern

``.*`.*``|# #|---.*---

Command Length Limits

Id

command-length-limits

Summary

Very long commands get truncated or cause issues

Severity

medium

Situation

Complex command doesn't execute completely

Why

Commands add to context window. Very long commands crowd out conversation. Claude may not process all sections.

Solution

// Managing command length

// PROBLEM: Huge command with everything // .claude/commands/full-workflow.md (500+ lines)

Complete Development Workflow

Research... (100 lines)

Design... (100 lines)

Implement... (100 lines)

Test... (100 lines)

Deploy... (100 lines)

// SOLUTION: Modular commands // .claude/commands/research.md

Research: $ARGUMENTS

[focused research workflow]

// .claude/commands/implement.md

Implement: $ARGUMENTS

[focused implementation workflow]

// .claude/commands/test.md

Test: $ARGUMENTS

[focused testing workflow]

// PATTERN: Index command that chains // .claude/commands/workflow.md

Full Workflow: $ARGUMENTS

This workflow consists of these steps: 1. /research $ARGUMENTS 2. /implement $ARGUMENTS 3. /test $ARGUMENTS

Start with step 1.

// PATTERN: Reference files instead of inline // Instead of 100 lines of checklist:

Review Checklist

@.claude/checklists/security-review.md

// GUIDELINE: Commands should be <100 lines // If longer, consider splitting or using @references

Symptoms

• Claude ignores later sections
• Context window fills up fast
• Slow command execution

Detection Pattern

Command Conflict With Builtin

Id

command-conflict-with-builtin

Summary

Custom command shadows built-in command

Severity

low

Situation

Built-in feature stops working after adding command

Why

Some slash names are reserved. Custom commands can shadow built-ins. No warning when conflict occurs.

Solution

// Reserved command names to avoid

// BUILT-IN COMMANDS (don't override): /help # Shows help /clear # Clears conversation /config # Configuration /memory # Memory management /compact # Compact conversation /model # Model selection /bug # Bug reporting /hooks # Hook management /mcp # MCP server management /permissions # Permission management /init # Initialize Claude Code

// SAFE TO USE: /feature # Custom /review # Custom /deploy # Custom /db # Custom /test # Custom (different from test command) /debug # Custom /issue # Custom

// NAMING CONVENTIONS: // Use descriptive names: /code-review not /cr // Use kebab-case: /security-scan not /securityScan // Prefix team commands: /team-deploy, /team-release

// If you accidentally override: // Rename your command file // .claude/commands/my-help.md instead of help.md

Symptoms

• Built-in feature doesn't work
• Wrong command executes
• Help shows wrong content

Detection Pattern

help\\.md|clear\\.md|config\\.md|memory\\.md

Claude Code Commands - Validations

Command Without Usage Documentation

Id

missing-usage-comment

Severity

medium

Type

regex

Pattern

^\s#.\$ARGUMENTS

Negative Pattern

#\sUsage:|#\sExample:

Message

Command uses $ARGUMENTS but lacks usage documentation.

Fix Action

Add usage comment: # Usage: /command-name argument-description

Applies To

• .claude/commands/*.md
• */commands/.md

Incorrect Arguments Variable

Id

wrong-arguments-syntax

Severity

high

Type

regex

Pattern

\$[Aa]rgument[^sS]|\$ARGUMENT\s|\$\{ARGUMENTS\}|\$[Aa]rguments

Message

Wrong $ARGUMENTS syntax. Must be exactly $ARGUMENTS (all caps, with S).

Fix Action

Use $ARGUMENTS exactly as written

Applies To

• .claude/commands/*.md
• */commands/.md

Relative Path in File Reference

Id

relative-file-reference

Severity

medium

Type

regex

Pattern

@\\.\\.?/

Message

@file paths should be relative to project root, not the command file.

Fix Action

Use @src/file.md not @../src/file.md

Applies To

• .claude/commands/*.md
• */commands/.md

Override of Built-in Command

Id

builtin-command-override

Severity

high

Type

filename

Pattern

(help|clear|config|memory|compact|model|bug|hooks|mcp|permissions|init)\\.md$

Message

Command file may override built-in Claude Code command.

Fix Action

Rename to avoid conflict with built-in commands

Applies To

• .claude/commands/
• **/commands/

Command Without Output Format

Id

no-output-format

Severity

low

Type

regex

Pattern

##.Workflow|##.Process|##.*Steps

Negative Pattern

##.Output|##.Format|##.*Response

Message

Command has workflow steps but no specified output format.

Fix Action

Add ## Output Format section specifying expected response structure

Applies To

• .claude/commands/*.md
• */commands/.md

Code Block Without Execution Guidance

Id

executable-code-without-context

Severity

low

Type

regex

Pattern

``bash\n[^]+```

Negative Pattern

Run this|Execute|Don.*t run|Example

Message

Code block without clear guidance on whether to execute it.

Fix Action

Add 'Run this command:' or 'Example (don't execute):' before code blocks

Applies To

• .claude/commands/*.md
• */commands/.md

Command Exceeds Recommended Length

Id

very-long-command

Severity

low

Type

line_count

Threshold

Message

Command is very long (>150 lines). Consider splitting into smaller commands.

Fix Action

Break into modular commands or use @file references

Applies To

• .claude/commands/*.md
• */commands/.md

Command Without Title Header

Id

missing-title

Severity

medium

Type

regex

Pattern

^[^#]

Message

Command doesn't start with a title header.

Fix Action

Start command with # Title describing the workflow

Applies To

• .claude/commands/*.md
• */commands/.md

Hardcoded Absolute Path in Command

Id

hardcoded-absolute-path

Severity

medium

Type

regex

Pattern

(/Users/|/home/|C:\\\\|/var/)

Message

Hardcoded absolute path won't work on other machines.

Fix Action

Use relative paths or $ARGUMENTS for dynamic paths

Applies To

• .claude/commands/*.md
• */commands/.md

Checklist Items All Unchecked

Id

unclosed-checklist

Severity

low

Type

regex

Pattern

• \\[ \\].\n- \\[ \\].\n- \\[ \\]

Negative Pattern

• \\[x\\]

Message

Multiple unchecked items. Claude will try to complete these - ensure that's intended.

Fix Action

Verify checklist items are meant to be completed by Claude

Applies To

• .claude/commands/*.md
• */commands/.md