notes_on_using_agents_for_everyone/claude-commands-research/implementation-guide.md

Claude Commands Implementation Guide

Getting Started with Custom Commands

Basic Setup

1. Create Commands Directory

   # For global commands (accessible as /user:command)
   mkdir -p ~/.claude/commands
   
   # For project-specific commands (accessible as /project:command)
   mkdir -p ./.claude/commands
   

2. Basic Command Structure

   # .claude/commands/example.md
   You are a helpful assistant that will: $ARGUMENTS
   
   Please follow these guidelines:
   - Be thorough and systematic
   - Provide clear explanations
   - Include error handling
   

Advanced Command Patterns

Workflow Automation

# .claude/commands/feature.md
Create a new feature: $ARGUMENTS

Steps to follow:
1. Analyze the existing codebase structure
2. Create the necessary files and directories
3. Implement the core functionality
4. Add comprehensive tests
5. Update documentation
6. Create a pull request with proper description

Ensure you follow the project's:
- Coding standards and style guide
- Testing patterns
- Documentation standards
- Git workflow conventions

Testing Automation

# .claude/commands/test-suite.md
Generate comprehensive test suite for: $ARGUMENTS

Requirements:
- Use the project's existing testing framework
- Create unit tests for all public methods
- Add integration tests for complex workflows
- Include edge cases and error scenarios
- Ensure 90%+ code coverage
- Mock external dependencies appropriately
- Follow AAA pattern (Arrange, Act, Assert)

Code Review Automation

# .claude/commands/review.md
Perform a comprehensive code review of: $ARGUMENTS

Review checklist:
- Code quality and style consistency
- Security vulnerabilities
- Performance implications
- Test coverage adequacy
- Documentation completeness
- Accessibility compliance
- Error handling robustness
- Maintainability concerns

Provide:
1. Summary of findings
2. Detailed feedback with line-specific comments
3. Suggested improvements
4. Priority rating (High/Medium/Low)

Team Implementation Strategies

Repository Setup

# Standard team structure
.claude/
├── commands/
│   ├── dev/
│   │   ├── setup.md
│   │   ├── test.md
│   │   └── deploy.md
│   ├── review/
│   │   ├── security.md
│   │   └── performance.md
│   └── docs/
│       ├── api.md
│       └── readme.md
└── CLAUDE.md

CLAUDE.md Best Practices

# CLAUDE.md
## Project Overview
[Brief description of the project and its purpose]

## Development Environment
- Node.js version: 18+
- Package manager: npm
- Database: PostgreSQL
- Testing: Jest + React Testing Library

## Key Commands
- `npm run dev` - Start development server
- `npm run test` - Run test suite
- `npm run lint` - Run ESLint
- `npm run build` - Build for production

## Architecture Notes
[Key architectural decisions and patterns]

## Testing Strategy
[Testing approach and requirements]

## Common Issues
[Known issues and their solutions]

Advanced Patterns

Conditional Logic

# .claude/commands/smart-deploy.md
Deploy the application: $ARGUMENTS

Before deploying:
1. Check if all tests pass
2. Verify no security vulnerabilities
3. Ensure documentation is up to date
4. Confirm environment variables are set

If staging deployment:
- Deploy to staging environment
- Run smoke tests
- Notify team in #staging channel

If production deployment:
- Require explicit confirmation
- Create deployment checklist
- Deploy with zero-downtime strategy
- Monitor for 15 minutes post-deployment
- Create rollback plan

Multi-Step Workflows

# .claude/commands/release-prep.md
Prepare release for: $ARGUMENTS

Complete release preparation workflow:

Phase 1 - Code Preparation:
- Ensure all features are complete
- Run full test suite
- Update version numbers
- Generate changelog

Phase 2 - Documentation:
- Update API documentation
- Review and update README
- Create migration guides if needed

Phase 3 - Quality Assurance:
- Security audit
- Performance benchmarks
- Accessibility testing
- Cross-browser testing

Phase 4 - Release Artifacts:
- Build production assets
- Create release notes
- Tag release in Git
- Prepare deployment scripts

Provide checklist for manual verification.

Integration Examples

GitHub Actions Integration

# .github/workflows/claude-commands.yml
name: Claude Commands CI
on: [push, pull_request]

jobs:
  validate-commands:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Validate Commands
        run: |
          # Validate command syntax
          find .claude/commands -name "*.md" -exec markdown-lint {} \;

Git Hooks Integration

#!/bin/sh
# .git/hooks/pre-commit
# Automatically run code review command
claude -p "Review the staged changes for any issues" --staged

Troubleshooting Common Issues

Command Discovery Problems

1. Ensure correct directory structure: .claude/commands/
2. Use .md file extension
3. Restart Claude Code after adding new commands
4. Check file permissions

Permission Issues

1. Commands requiring Bash access need user permission
2. Use explicit permission requests in commands
3. Test commands individually before combining

Execution Problems

1. Verify command syntax and structure
2. Test with simple commands first
3. Check for conflicting command names
4. Review Claude Code logs for errors

Performance Optimization

Token Usage

• Keep commands concise but comprehensive
• Use clear, specific instructions
• Avoid redundant information
• Structure for readability

Response Time

• Break complex workflows into steps
• Use specific rather than general commands
• Minimize context switching
• Cache common patterns

Security Considerations

Command Security

• Never include secrets in commands
• Validate all input parameters
• Use secure coding practices
• Review commands for vulnerabilities

Access Control

• Use project-specific commands for sensitive operations
• Implement approval workflows for critical commands
• Log command execution for audit trails

Maintenance

Regular Updates

• Review and refactor commands quarterly
• Update based on team feedback
• Keep documentation current
• Remove deprecated commands

Version Control

• Track command changes in Git
• Use semantic versioning for major updates
• Document breaking changes
• Maintain backward compatibility when possible

Research Date

July 20, 2025