Boost Your Development Workflow with Claude Code: 10 Must‑Know Custom Commands

Custom Commands in Claude Code

Claude Code lets you store a prompt in a markdown file under .claude/commands/. The file name becomes a slash command (e.g., /preflight). Because the files are version‑controlled with Git, every team member runs the exact same prompt and can update it via a pull.

File layout and scopes

Project‑scoped : your-repo/.claude/commands/preflight.md → /preflight User‑scoped : ~/.claude/commands/orient.md → /orient Sub‑directory : .claude/commands/db/migrate.md →

/db:migrate

Command template structure

Optional YAML front‑matter to declare tool permissions, model overrides, or a description.

Prompt body where the placeholder $ARGUMENTS receives any extra input supplied after the command name.

Shell commands prefixed with ! that run before the LLM processes the prompt, allowing dynamic context such as the current branch or recent commits.

Example Commands for a FastAPI ML Service

1. /env-check – Validate local development environment

---
description: Validate local development environment setup
allowed-tools: Bash(node *), Bash(npm *), Bash(python *), Bash(which *), Bash(cat *), Bash(docker *), Read, Glob
---
Check that this project's development environment is properly configured.
## Step 1: Read project requirements
!`cat .node-version .nvmrc .python-version .tool-versions .env.example 2>/dev/null`
!`cat package.json | head -30 2>/dev/null`
!`cat docker-compose.yml 2>/dev/null | head -10`
## Step 2: Validate each requirement
- **Runtime versions**: compare installed Node/Python/Ruby with required versions.
- **Dependencies**: ensure node_modules/venv are up‑to‑date.
- **Env vars**: compare .env.example with actual .env.
- **Services**: verify required containers are running.
- **Git hooks**: check for husky/lefthook.
## Output format
✅ Node v20.11.0 (matches .nvmrc)
❌ Missing env var: DATABASE_URL (required by .env.example)
⚠️ node_modules out of date (run npm install)

2. /orient – Rebuild working context after a clear

---
description: Rebuild working context after /clear
allowed-tools: Bash(git *), Read, Glob
---
Load current working state:
1. Uncommitted changes: !`git diff HEAD`
2. Last 5 commits with diffs: !`git log --oneline -5`
3. TODO/FIXME markers: !`git diff --name-only HEAD | head -20`
4. Current branch: !`git branch --show-current`
5. Commits ahead of main: !`git log main..HEAD --oneline`
Provide a brief summary of what is being worked on, key files, pending TODOs, and branch distance.

3. /preflight – Pre‑commit scan for debug artifacts

---
description: Pre‑commit scan for debug artifacts and code smells
allowed-tools: Bash(git *), Bash(grep *), Read, Glob
---
Scan staged changes for:
- console.log/debug/warn statements
- TODO, FIXME, HACK, XXX comments
- Commented‑out code blocks (3+ consecutive lines)
- Hard‑coded secrets (API keys, tokens)
- Test files marked .only or .skip
- Debugger statements
- Large binary files
- Dev‑only imports in production code
## Output format
If all checks pass: "✅ Preflight clear. Staged changes look clean."
If issues found: list each file, line context, and a suggested fix command.

4. /dissect – Deep structural review of a file or module

---
description: Deep structural review of a file or module
allowed-tools: Read, Glob, Grep
argument-hint: <file-path-or-directory>
---
Review dimensions:
- **Error handling**: are all error paths explicit?
- **Edge cases**: null/undefined, boundary values, implicit coercions.
- **Concurrency**: possible race conditions, shared‑resource safety.
- **Dependencies**: unused imports, circular risks, tight coupling.
- **Naming & structure**: accurate function names, single‑purpose functions.
## Output format
For each finding: severity (🔴 Critical, 🟡 Warning, 🔵 Note), location, description, and a suggested code fix.

5. /testmatch – Generate tests matching existing project patterns

---
description: Generate tests that match existing project test patterns
allowed-tools: Read, Glob, Grep, Bash(npx *), Bash(npm test *)
argument-hint: <file-to-test>
---
## Step 1: Learn existing test patterns
!`find . -name "*.test.*" -o -name "*.spec.*" | head -5`
Identify framework, assertion style, naming convention, setup/teardown, mocking approach.
## Step 2: Read target file
!`cat $ARGUMENTS`
## Step 3: Generate tests
- Follow identified patterns exactly.
- Cover every exported function.
- Include happy path, error cases, edge cases.
- Use same mocking and file naming conventions.
Do NOT introduce new patterns.

6. /explain-func – Generate why‑focused documentation

---
description: Generate why‑focused documentation for complex functions
allowed-tools: Read, Grep
argument-hint: <function-name-or-file:line>
---
Rules:
- Explain *why* a decision was made, not *what* the code does.
- Document non‑obvious decisions, invariants, constraints, and gotchas.
- Keep comments under 100 characters.
Output: function with JSDoc/docstring header and inline comments where needed.

7. /refactor-safe – Refactor internals without changing public API

---
description: Refactor internals without changing public API
allowed-tools: Read, Grep, Glob
argument-hint: <file-or-function>
---
Hard constraints:
- Do NOT change exported signatures, return types, or symbol names.
- Do NOT add new dependencies.
- Preserve existing behavior, edge cases, and error messages.
Improvements:
- Extract repeated logic to private helpers.
- Simplify nested conditionals.
- Remove dead code.
- Replace magic numbers with constants.
- Improve variable names.
Verification: exported API unchanged; existing tests would still pass.

8. /ship – Validate and generate PR description

---
description: Validate and generate PR description from current branch
allowed-tools: Bash(git *), Bash(gh *), Bash(pytest *), Bash(npm test *), Read, Glob
---
## Step 1: Pre‑flight validation
Run test suite; abort if failures.
!`git diff --stat main..HEAD`
## Step 2: Assess diff
!`git log main..HEAD --oneline`
!`git diff --stat main..HEAD`
Flag large PRs (>500 lines) or many commits (>15).
## Step 3: Generate PR description
Sections: Summary, Changes (grouped), How to test, Risk assessment, Related issues.
## Step 4: Output
Print markdown ready for GitHub. Do NOT create the PR automatically.

9. /migrate-draft – Draft a database migration with rollback plan

---
description: Draft a database migration with rollback plan
allowed-tools: Read, Glob, Grep
argument-hint: <description-of-schema-change>
---
## Step 1: Identify migration system
!`ls migrations/ db/migrate/ prisma/migrations/ drizzle/ alembic/versions/ 2>/dev/null | head -20`
Read 2‑3 existing migrations to infer ORM, naming convention, and up/down structure.
## Step 2: Generate migration file
Create file following project conventions.
Requirements:
- Include both UP and DOWN logic; DOWN must perfectly reverse UP.
- Provide sensible defaults for NOT NULL columns.
- Document data‑loss warnings for column removals.
- Verify index naming conventions.
## Step 3: Safety checklist
- Estimated row count.
- Potential table locks.
- Backward compatibility.
- Independent deployability.
- Failure handling.
Do NOT run the migration; output file content only.

10. /debt-scan – Scan for technical debt and prioritize fixes

---
description: Scan for technical debt patterns and prioritize remediation
allowed-tools: Bash(git *), Bash(npm *), Bash(npx *), Bash(wc *), Bash(find *), Read, Glob, Grep
---
Scan dimensions:
- **Code complexity**: largest files, long functions, many imports.
- **Dependency health**: outdated packages, deprecation notices.
- **Test coverage gaps**: source files without tests.
- **Code smells**: any‑type assertions, eslint‑disable, @ts‑ignore, duplicated blocks.
- **Architectural smells**: circular deps, business logic in handlers, raw DB queries.
## Output format
Group findings by priority (🔴 High, 🟡 Medium, 🔵 Low) with file, description, effort estimate, and ticket‑ready title.

Notes

Claude Code also supports a newer .claude/skills/ directory for richer capabilities, but the simpler .claude/commands/ approach remains a solid starting point for sharing reproducible prompts across a team.