zev/notes_on_using_agents_for_everyone
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
Zev Averbach
2025-07-22 05:25:06 +02:00
parent 7bfdb38dfe
commit 44e6974a15
5 changed files with 601 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
README.md Normal file
View File

@@ -0,0 +1,20 @@
# Table of Contents
# Setup
## Installation and Env Vars
(install, set env vars)
## Configure
Make these files/folders
- `~/CLAUDE.md`
- `~/.claude/commands`
`CLAUDE.md` at the user level should contain general instructions, code style etc.
`commands/` should contain Markdown files documenting what's available globally to use, such as token counters, documentation summarizers, etc.

10
TODO.md
View File

@@ -5,6 +5,7 @@
- [ ] coalesce `RONACHER.md` into generic notes and attribute his to him
- [ ] read these and incorporate
- https://docs.anthropic.com/en/docs/claude-code/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees
- https://mariozechner.at/posts/2025-06-02-prompts-are-code/
- https://lucumr.pocoo.org/2025/6/12/agentic-coding/
- https://x.com/sergeykarayev/status/1940799384821924032
@@ -12,15 +13,16 @@
- https://www.anthropic.com/engineering/claude-code-best-practices
- https://www.reddit.com/r/ClaudeAI/comments/1lwoetm/claude_code_tip_straight_from_anthropic_go_slow/?share_id=AEPEEBKfZkV2yA98GepoG&utm_content=2&utm_medium=ios_app&utm_name=ioscss&utm_source=share&utm_term=1
- https://www.dbreunig.com/2025/06/26/how-to-fix-your-context.html
- https://gist.github.com/swerner/b7fd285ec3f2edbcc55ebccdaffc950a
- [ ] find and install a tool for creating summaries of a codebase
- [x] install gemini-cli
- [x] install CodeWeaver
- [ ] add to CLAUDE.md
- [ ] find and install a tool for counting tokens in a file
- [x] add to CLAUDE.md
- [x] find and install a tool for counting tokens in a file
- [x] find and install
- [ ] add to CLAUDE.md
- [ ] find and install a tool for getting adn summarizing documentation
- [x] add to CLAUDE.md
- [ ] find/make and install a tool for getting adn summarizing documentation
- [ ] find and install
- https://llm.codes
- [ ] add to CLAUDE.md

113
claude-commands-research/README.md Normal file
View File

@@ -0,0 +1,113 @@
# Claude Commands Research
Research into interesting non-MCP tools and custom commands created by the community for Claude Code's `.claude/commands` directories.
## Overview
Custom commands in Claude Code are stored as markdown files in:
- `~/.claude/commands/` (global user commands, accessible as `/user:command`)
- `./claude/commands/` (project-specific commands, accessible as `/project:command`)
## Key Repositories Discovered
### 1. hikarubw/claude-commands
**Focus:** Development workflow automation
**Repository:** https://github.com/hikarubw/claude-commands
**Commands:**
- `/user:init` - Initialize projects with CI/CD, testing, docs
- `/user:check` - Run all quality checks in parallel with actionable insights
- `/user:plan` - Create detailed project plans (high token usage)
- `/user:push` - Smart git workflow with intelligent commits and CI monitoring
- `/user:handover` - Prepare session handover documentation
- `/user:research` - Deep technical research (high token usage)
- `/user:help` - Show all available commands
**Features:**
- Language-agnostic design
- Time-saving workflows
- Smart defaults
- Support for custom commands in `~/.claude/commands/custom/`
### 2. NomenAK/SuperClaude
**Focus:** Comprehensive development framework
**Repository:** https://github.com/NomenAK/SuperClaude
**16 Specialized Commands:**
- **Development:** `/sc:implement`, `/sc:build`, `/sc:design`
- **Analysis:** `/sc:analyze`, `/sc:troubleshoot`, `/sc:explain`
- **Quality:** `/sc:improve`, `/sc:test`, `/sc:cleanup`
- **Utilities:** `/sc:document`, `/sc:git`, `/sc:estimate`, `/sc:task`, `/sc:index`, `/sc:load`, `/sc:spawn`
**Smart Personas:**
- 🏗️ architect (systems design)
- 🎨 frontend (UI/UX)
- ⚙️ backend (APIs)
- 🔍 analyzer (debugging)
- 🛡️ security
- ✍️ scribe (documentation)
**MCP Server Integrations:**
- Context7 (library docs)
- Sequential (multi-step thinking)
- Magic (UI components)
- Playwright (browser automation)
### 3. hesreallyhim/awesome-claude-code
**Focus:** Curated collection of resources
**Repository:** https://github.com/hesreallyhim/awesome-claude-code
**Notable Commands:**
- `/bug-fix` - Streamlined bug fixing process
- `/commit` - Conventional git commits
- `/create-docs` - Comprehensive documentation generation
- `/optimize` - Code performance analysis and suggestions
**Categories:**
- Version Control & Git
- Code Analysis & Testing
- Context Loading & Priming
- Documentation & Changelogs
- CI/Deployment
- Project Management
### 4. disler/claude-code-hooks-mastery
**Focus:** Hooks integration
**Repository:** https://github.com/disler/claude-code-hooks-mastery
**Commands:**
- `all_tools.md`
- `git_status.md`
- `prime.md`
- `sentient.md`
### 5. Other Notable Examples
**shamshirz/project-plan-template**
- Template for project planning commands
- Usage: `/project/plan Details about the project`
**coleam00/context-engineering-intro**
- Context engineering and prompt optimization commands
## Current Issues & Limitations
Based on GitHub issues, there are some active problems with custom commands:
1. **Discovery Issues:** Claude Code sometimes fails to find custom commands in expected directories
2. **Permission Prompts:** Bugs with Bash permission prompts when custom commands are first to request access
3. **Execution Problems:** Commands may not execute from within conversations even when they appear in the interface
## Patterns & Best Practices
From analyzing these repositories, common patterns emerge:
1. **Workflow Automation:** Most successful commands automate multi-step development workflows
2. **Quality Assurance:** Many focus on testing, linting, and code quality checks
3. **Git Integration:** Smart git workflows are a popular category
4. **Documentation:** Automated documentation generation is common
5. **Project Management:** Planning and task management features
6. **Language Agnostic:** Best commands work across different programming languages
## Research Date
July 20, 2025

181
claude-commands-research/comprehensive-tools-catalog.md Normal file
View File

@@ -0,0 +1,181 @@
# Comprehensive Claude Commands Tools Catalog
## Major Command Suites
### qdhenry/Claude-Command-Suite
**The most comprehensive suite discovered** - Over 104 professional commands
**Repository:** https://github.com/qdhenry/Claude-Command-Suite
**Organized by Namespaces:**
#### Project Management (`/project:*`)
- Initialize projects with comprehensive setup
- Add packages and dependencies
- Create features with full scaffolding
- Track milestones and deliverables
#### Development Tools (`/dev:*`)
- Code review automation
- Advanced debugging workflows
- Code explanation and documentation
- Intelligent refactoring
- Git management and workflows
#### Testing (`/test:*`)
- Generate comprehensive test cases
- Write unit, integration, and e2e tests
- Analyze test coverage gaps
- Set up testing infrastructure
#### Security (`/security:*`)
- Automated security audits
- Dependency vulnerability scanning
- Security hardening recommendations
- Authentication system implementation
#### Performance (`/performance:*`)
- Performance audits and profiling
- Build and bundle size optimization
- Database performance optimization
- Caching strategy implementation
#### Deployment (`/deploy:*`)
- Release preparation and checklists
- Hotfix deployment procedures
- Rollback capabilities
- Containerization with Docker
- Kubernetes deployment automation
#### Documentation (`/docs:*`)
- Generate API documentation
- Create architecture documentation
- Develop onboarding guides
- Create migration guides
#### Team Collaboration (`/team:*`)
- Automated standup reports
- Sprint planning assistance
- Retrospective analysis
- Workload balancing
#### Simulation (`/simulation:*`)
- Business scenario exploration
- Decision tree analysis
- Market response modeling
- Timeline compression analysis
### vinodismyname/ClaudeCodeBootstrap
**Focus:** Automated setup and configuration
**Repository:** https://github.com/vinodismyname/ClaudeCodeBootstrap
- Python CLI tool for automating Claude Code setup
- Generates tailored configuration files based on project analysis
- Creates `.claude/commands/` directory with custom commands
- Automates common development tasks (code reviews, testing, Git ops)
### Wirasm/PRPs-agentic-eng
**Focus:** Product Requirement Prompts for agentic engineering
**Repository:** https://github.com/Wirasm/PRPs-agentic-eng
- Product Requirement Prompt (PRP) methodology
- Combines PRD + curated codebase intelligence + agent/runbook
- Enables AI-assisted development with production-ready code
- Comprehensive library for agentic engineering
## Specialized Collections
### coleam00/context-engineering-intro
**Focus:** Context engineering methodology
**Repository:** https://github.com/coleam00/context-engineering-intro
- Context engineering as "the new vibe coding"
- Strategies for making AI coding assistants work effectively
- Primarily Claude Code focused but applicable to other AI assistants
- Advanced prompt engineering techniques
### Templates and Examples
#### shamshirz/project-plan-template
**Single Command Template**
- Project planning command template
- Usage: `/project/plan Details about the project`
- Demonstrates command structure and parameter passing
## Command Structure Best Practices
### File Organization
```
.claude/commands/
├── project/
│ ├── init.md
│ ├── plan.md
│ └── feature.md
├── dev/
│ ├── review.md
│ ├── debug.md
│ └── refactor.md
└── test/
├── generate.md
└── coverage.md
```
### Parameter Passing
Commands can use `$ARGUMENTS` for dynamic input:
```markdown
# .claude/commands/test.md
Please create comprehensive tests for: $ARGUMENTS
Test requirements:
- Use Jest and React Testing Library
- Place tests in __tests__ directory
- Mock Firebase/Firestore dependencies
- Test all major functionality
```
### Team Sharing
- Commands can be checked into Git for team collaboration
- Global commands: `~/.claude/commands/` (accessible as `/user:command`)
- Project commands: `./claude/commands/` (accessible as `/project:command`)
## Integration Patterns
### CI/CD Integration
- GitHub Actions integration for automated workflows
- Scriptable commands for CI pipelines
- Example: `tail -f app.log | claude -p "Slack me if anomalies appear"`
### Testing Integration
- Test-driven development (TDD) workflows
- Automated test generation
- Coverage analysis and gap identification
### Documentation Integration
- CLAUDE.md file generation and management
- API documentation automation
- Architecture documentation
## Community Insights (2025)
### Current Trends
1. **Comprehensive Suites:** Moving beyond single commands to full workflow automation
2. **Namespace Organization:** Using prefixes to organize commands by function
3. **Team Collaboration:** Git-based sharing and standardization
4. **CI/CD Integration:** Deep integration with deployment pipelines
5. **Context Engineering:** Advanced prompt engineering for better AI assistance
### Known Issues
- Discovery problems with custom commands in some versions
- Permission prompt bugs when commands request Bash access
- Execution issues within conversations
### Best Practices Emerging
1. Use structured namespaces for organization
2. Include comprehensive error handling
3. Design for team collaboration and sharing
4. Integrate with existing development workflows
5. Focus on automation of repetitive tasks
6. Maintain clear documentation and examples
## Research Date
July 20, 2025

281
claude-commands-research/implementation-guide.md Normal file
View File

@@ -0,0 +1,281 @@
# Claude Commands Implementation Guide
## Getting Started with Custom Commands
### Basic Setup
1. **Create Commands Directory**
```bash
# 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**
```markdown
# .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
```markdown
# .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
```markdown
# .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
```markdown
# .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
```bash
# 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
```markdown
# 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
```markdown
# .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
```markdown
# .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
```yaml
# .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
```bash
#!/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