mirror of
https://github.com/anthropics/claude-code.git
synced 2025-10-19 03:17:50 +03:00
docs: Add comprehensive plugin documentation (#9797)
- Add plugins section to main README with link to detailed docs - Create plugins/README.md with overview of all available plugins - Add detailed READMEs for agent-sdk-dev, commit-commands, and feature-dev plugins - Document all commands, agents, usage patterns, and workflows 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Ashwin Bhat
@@ -20,6 +20,10 @@ npm install -g @anthropic-ai/claude-code
|
||||
|
||||
2. Navigate to your project directory and run `claude`.
|
||||
|
||||
## Plugins
|
||||
|
||||
This repository includes several Claude Code plugins that extend functionality with custom commands and agents. See the [plugins directory](./plugins/README.md) for detailed documentation on available plugins.
|
||||
|
||||
## Reporting Bugs
|
||||
|
||||
We welcome your feedback. Use the `/bug` command to report issues directly within Claude Code, or file a [GitHub issue](https://github.com/anthropics/claude-code/issues).
|
||||
|
||||
93
plugins/README.md
Normal file
93
plugins/README.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# Claude Code Plugins
|
||||
|
||||
This directory contains some official Claude Code plugins that extend functionality through custom commands, agents, and workflows. These are examples of what's possible with the Claude Code plugin system—many more plugins are available through community marketplaces.
|
||||
|
||||
## What are Claude Code Plugins?
|
||||
|
||||
Claude Code plugins are extensions that enhance Claude Code with custom slash commands, specialized agents, hooks, and MCP servers. Plugins can be shared across projects and teams, providing consistent tooling and workflows.
|
||||
|
||||
Learn more in the [official plugins documentation](https://docs.claude.com/en/docs/claude-code/plugins).
|
||||
|
||||
## Plugins in This Directory
|
||||
|
||||
### [agent-sdk-dev](./agent-sdk-dev/)
|
||||
|
||||
**Claude Agent SDK Development Plugin**
|
||||
|
||||
Streamlines the development of Claude Agent SDK applications with scaffolding commands and verification agents.
|
||||
|
||||
- **Command**: `/new-sdk-app` - Interactive setup for new Agent SDK projects
|
||||
- **Agents**: `agent-sdk-verifier-py` and `agent-sdk-verifier-ts` - Validate SDK applications against best practices
|
||||
- **Use case**: Creating and verifying Claude Agent SDK applications in Python or TypeScript
|
||||
|
||||
### [commit-commands](./commit-commands/)
|
||||
|
||||
**Git Workflow Automation Plugin**
|
||||
|
||||
Simplifies common git operations with streamlined commands for committing, pushing, and creating pull requests.
|
||||
|
||||
- **Commands**:
|
||||
- `/commit` - Create a git commit with appropriate message
|
||||
- `/commit-push-pr` - Commit, push, and create a PR in one command
|
||||
- `/clean_gone` - Clean up stale local branches marked as [gone]
|
||||
- **Use case**: Faster git workflows with less context switching
|
||||
|
||||
### [feature-dev](./feature-dev/)
|
||||
|
||||
**Comprehensive Feature Development Workflow Plugin**
|
||||
|
||||
Provides a structured 7-phase approach to feature development with specialized agents for exploration, architecture, and review.
|
||||
|
||||
- **Command**: `/feature-dev` - Guided feature development workflow
|
||||
- **Agents**:
|
||||
- `code-explorer` - Deeply analyzes existing codebase features
|
||||
- `code-architect` - Designs feature architectures and implementation blueprints
|
||||
- `code-reviewer` - Reviews code for bugs, quality issues, and project conventions
|
||||
- **Use case**: Building new features with systematic codebase understanding and quality assurance
|
||||
|
||||
## Installation
|
||||
|
||||
These plugins are included in the Claude Code repository. To use them in your own projects:
|
||||
|
||||
1. Install Claude Code globally:
|
||||
```bash
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
```
|
||||
|
||||
2. Navigate to your project and run Claude Code:
|
||||
```bash
|
||||
claude
|
||||
```
|
||||
|
||||
3. Use the `/plugin` command to install plugins from marketplaces, or configure them in your project's `.claude/settings.json`.
|
||||
|
||||
For detailed plugin installation and configuration, see the [official documentation](https://docs.claude.com/en/docs/claude-code/plugins).
|
||||
|
||||
## Plugin Structure
|
||||
|
||||
Each plugin follows the standard Claude Code plugin structure:
|
||||
|
||||
```
|
||||
plugin-name/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json # Plugin metadata
|
||||
├── commands/ # Slash commands (optional)
|
||||
├── agents/ # Specialized agents (optional)
|
||||
└── README.md # Plugin documentation
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
When adding new plugins to this directory:
|
||||
|
||||
1. Follow the standard plugin structure
|
||||
2. Include a comprehensive README.md
|
||||
3. Add plugin metadata in `.claude-plugin/plugin.json`
|
||||
4. Document all commands and agents
|
||||
5. Provide usage examples
|
||||
|
||||
## Learn More
|
||||
|
||||
- [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code/overview)
|
||||
- [Plugin System Documentation](https://docs.claude.com/en/docs/claude-code/plugins)
|
||||
- [Agent SDK Documentation](https://docs.claude.com/en/api/agent-sdk/overview)
|
||||
208
plugins/agent-sdk-dev/README.md
Normal file
208
plugins/agent-sdk-dev/README.md
Normal file
@@ -0,0 +1,208 @@
|
||||
# Agent SDK Development Plugin
|
||||
|
||||
A comprehensive plugin for creating and verifying Claude Agent SDK applications in Python and TypeScript.
|
||||
|
||||
## Overview
|
||||
|
||||
The Agent SDK Development Plugin streamlines the entire lifecycle of building Agent SDK applications, from initial scaffolding to verification against best practices. It helps you quickly start new projects with the latest SDK versions and ensures your applications follow official documentation patterns.
|
||||
|
||||
## Features
|
||||
|
||||
### Command: `/new-sdk-app`
|
||||
|
||||
Interactive command that guides you through creating a new Claude Agent SDK application.
|
||||
|
||||
**What it does:**
|
||||
- Asks clarifying questions about your project (language, name, agent type, starting point)
|
||||
- Checks for and installs the latest SDK version
|
||||
- Creates all necessary project files and configuration
|
||||
- Sets up proper environment files (.env.example, .gitignore)
|
||||
- Provides a working example tailored to your use case
|
||||
- Runs type checking (TypeScript) or syntax validation (Python)
|
||||
- Automatically verifies the setup using the appropriate verifier agent
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
/new-sdk-app my-project-name
|
||||
```
|
||||
|
||||
Or simply:
|
||||
```bash
|
||||
/new-sdk-app
|
||||
```
|
||||
|
||||
The command will interactively ask you:
|
||||
1. Language choice (TypeScript or Python)
|
||||
2. Project name (if not provided)
|
||||
3. Agent type (coding, business, custom)
|
||||
4. Starting point (minimal, basic, or specific example)
|
||||
5. Tooling preferences (npm/yarn/pnpm or pip/poetry)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
/new-sdk-app customer-support-agent
|
||||
# → Creates a new Agent SDK project for a customer support agent
|
||||
# → Sets up TypeScript or Python environment
|
||||
# → Installs latest SDK version
|
||||
# → Verifies the setup automatically
|
||||
```
|
||||
|
||||
### Agent: `agent-sdk-verifier-py`
|
||||
|
||||
Thoroughly verifies Python Agent SDK applications for correct setup and best practices.
|
||||
|
||||
**Verification checks:**
|
||||
- SDK installation and version
|
||||
- Python environment setup (requirements.txt, pyproject.toml)
|
||||
- Correct SDK usage and patterns
|
||||
- Agent initialization and configuration
|
||||
- Environment and security (.env, API keys)
|
||||
- Error handling and functionality
|
||||
- Documentation completeness
|
||||
|
||||
**When to use:**
|
||||
- After creating a new Python SDK project
|
||||
- After modifying an existing Python SDK application
|
||||
- Before deploying a Python SDK application
|
||||
|
||||
**Usage:**
|
||||
The agent runs automatically after `/new-sdk-app` creates a Python project, or you can trigger it by asking:
|
||||
```
|
||||
"Verify my Python Agent SDK application"
|
||||
"Check if my SDK app follows best practices"
|
||||
```
|
||||
|
||||
**Output:**
|
||||
Provides a comprehensive report with:
|
||||
- Overall status (PASS / PASS WITH WARNINGS / FAIL)
|
||||
- Critical issues that prevent functionality
|
||||
- Warnings about suboptimal patterns
|
||||
- List of passed checks
|
||||
- Specific recommendations with SDK documentation references
|
||||
|
||||
### Agent: `agent-sdk-verifier-ts`
|
||||
|
||||
Thoroughly verifies TypeScript Agent SDK applications for correct setup and best practices.
|
||||
|
||||
**Verification checks:**
|
||||
- SDK installation and version
|
||||
- TypeScript configuration (tsconfig.json)
|
||||
- Correct SDK usage and patterns
|
||||
- Type safety and imports
|
||||
- Agent initialization and configuration
|
||||
- Environment and security (.env, API keys)
|
||||
- Error handling and functionality
|
||||
- Documentation completeness
|
||||
|
||||
**When to use:**
|
||||
- After creating a new TypeScript SDK project
|
||||
- After modifying an existing TypeScript SDK application
|
||||
- Before deploying a TypeScript SDK application
|
||||
|
||||
**Usage:**
|
||||
The agent runs automatically after `/new-sdk-app` creates a TypeScript project, or you can trigger it by asking:
|
||||
```
|
||||
"Verify my TypeScript Agent SDK application"
|
||||
"Check if my SDK app follows best practices"
|
||||
```
|
||||
|
||||
**Output:**
|
||||
Provides a comprehensive report with:
|
||||
- Overall status (PASS / PASS WITH WARNINGS / FAIL)
|
||||
- Critical issues that prevent functionality
|
||||
- Warnings about suboptimal patterns
|
||||
- List of passed checks
|
||||
- Specific recommendations with SDK documentation references
|
||||
|
||||
## Workflow Example
|
||||
|
||||
Here's a typical workflow using this plugin:
|
||||
|
||||
1. **Create a new project:**
|
||||
```bash
|
||||
/new-sdk-app code-reviewer-agent
|
||||
```
|
||||
|
||||
2. **Answer the interactive questions:**
|
||||
```
|
||||
Language: TypeScript
|
||||
Agent type: Coding agent (code review)
|
||||
Starting point: Basic agent with common features
|
||||
```
|
||||
|
||||
3. **Automatic verification:**
|
||||
The command automatically runs `agent-sdk-verifier-ts` to ensure everything is correctly set up.
|
||||
|
||||
4. **Start developing:**
|
||||
```bash
|
||||
# Set your API key
|
||||
echo "ANTHROPIC_API_KEY=your_key_here" > .env
|
||||
|
||||
# Run your agent
|
||||
npm start
|
||||
```
|
||||
|
||||
5. **Verify after changes:**
|
||||
```
|
||||
"Verify my SDK application"
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
This plugin is included in the Claude Code repository. To use it:
|
||||
|
||||
1. Ensure Claude Code is installed
|
||||
2. The plugin commands and agents are automatically available
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Always use the latest SDK version**: `/new-sdk-app` checks for and installs the latest version
|
||||
- **Verify before deploying**: Run the verifier agent before deploying to production
|
||||
- **Keep API keys secure**: Never commit `.env` files or hardcode API keys
|
||||
- **Follow SDK documentation**: The verifier agents check against official patterns
|
||||
- **Type check TypeScript projects**: Run `npx tsc --noEmit` regularly
|
||||
- **Test your agents**: Create test cases for your agent's functionality
|
||||
|
||||
## Resources
|
||||
|
||||
- [Agent SDK Overview](https://docs.claude.com/en/api/agent-sdk/overview)
|
||||
- [TypeScript SDK Reference](https://docs.claude.com/en/api/agent-sdk/typescript)
|
||||
- [Python SDK Reference](https://docs.claude.com/en/api/agent-sdk/python)
|
||||
- [Agent SDK Examples](https://docs.claude.com/en/api/agent-sdk/examples)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Type errors in TypeScript project
|
||||
|
||||
**Issue**: TypeScript project has type errors after creation
|
||||
|
||||
**Solution**:
|
||||
- The `/new-sdk-app` command runs type checking automatically
|
||||
- If errors persist, check that you're using the latest SDK version
|
||||
- Verify your `tsconfig.json` matches SDK requirements
|
||||
|
||||
### Python import errors
|
||||
|
||||
**Issue**: Cannot import from `claude_agent_sdk`
|
||||
|
||||
**Solution**:
|
||||
- Ensure you've installed dependencies: `pip install -r requirements.txt`
|
||||
- Activate your virtual environment if using one
|
||||
- Check that the SDK is installed: `pip show claude-agent-sdk`
|
||||
|
||||
### Verification fails with warnings
|
||||
|
||||
**Issue**: Verifier agent reports warnings
|
||||
|
||||
**Solution**:
|
||||
- Review the specific warnings in the report
|
||||
- Check the SDK documentation references provided
|
||||
- Warnings don't prevent functionality but indicate areas for improvement
|
||||
|
||||
## Author
|
||||
|
||||
Ashwin Bhat (ashwin@anthropic.com)
|
||||
|
||||
## Version
|
||||
|
||||
1.0.0
|
||||
225
plugins/commit-commands/README.md
Normal file
225
plugins/commit-commands/README.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# Commit Commands Plugin
|
||||
|
||||
Streamline your git workflow with simple commands for committing, pushing, and creating pull requests.
|
||||
|
||||
## Overview
|
||||
|
||||
The Commit Commands Plugin automates common git operations, reducing context switching and manual command execution. Instead of running multiple git commands, use a single slash command to handle your entire workflow.
|
||||
|
||||
## Commands
|
||||
|
||||
### `/commit`
|
||||
|
||||
Creates a git commit with an automatically generated commit message based on staged and unstaged changes.
|
||||
|
||||
**What it does:**
|
||||
1. Analyzes current git status
|
||||
2. Reviews both staged and unstaged changes
|
||||
3. Examines recent commit messages to match your repository's style
|
||||
4. Drafts an appropriate commit message
|
||||
5. Stages relevant files
|
||||
6. Creates the commit
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
/commit
|
||||
```
|
||||
|
||||
**Example workflow:**
|
||||
```bash
|
||||
# Make some changes to your code
|
||||
# Then simply run:
|
||||
/commit
|
||||
|
||||
# Claude will:
|
||||
# - Review your changes
|
||||
# - Stage the files
|
||||
# - Create a commit with an appropriate message
|
||||
# - Show you the commit status
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Automatically drafts commit messages that match your repo's style
|
||||
- Follows conventional commit practices
|
||||
- Avoids committing files with secrets (.env, credentials.json)
|
||||
- Includes Claude Code attribution in commit message
|
||||
|
||||
### `/commit-push-pr`
|
||||
|
||||
Complete workflow command that commits, pushes, and creates a pull request in one step.
|
||||
|
||||
**What it does:**
|
||||
1. Creates a new branch (if currently on main)
|
||||
2. Stages and commits changes with an appropriate message
|
||||
3. Pushes the branch to origin
|
||||
4. Creates a pull request using `gh pr create`
|
||||
5. Provides the PR URL
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
/commit-push-pr
|
||||
```
|
||||
|
||||
**Example workflow:**
|
||||
```bash
|
||||
# Make your changes
|
||||
# Then run:
|
||||
/commit-push-pr
|
||||
|
||||
# Claude will:
|
||||
# - Create a feature branch (if needed)
|
||||
# - Commit your changes
|
||||
# - Push to remote
|
||||
# - Open a PR with summary and test plan
|
||||
# - Give you the PR URL to review
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Analyzes all commits in the branch (not just the latest)
|
||||
- Creates comprehensive PR descriptions with:
|
||||
- Summary of changes (1-3 bullet points)
|
||||
- Test plan checklist
|
||||
- Claude Code attribution
|
||||
- Handles branch creation automatically
|
||||
- Uses GitHub CLI (`gh`) for PR creation
|
||||
|
||||
**Requirements:**
|
||||
- GitHub CLI (`gh`) must be installed and authenticated
|
||||
- Repository must have a remote named `origin`
|
||||
|
||||
### `/clean_gone`
|
||||
|
||||
Cleans up local branches that have been deleted from the remote repository.
|
||||
|
||||
**What it does:**
|
||||
1. Lists all local branches to identify [gone] status
|
||||
2. Identifies and removes worktrees associated with [gone] branches
|
||||
3. Deletes all branches marked as [gone]
|
||||
4. Provides feedback on removed branches
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
/clean_gone
|
||||
```
|
||||
|
||||
**Example workflow:**
|
||||
```bash
|
||||
# After PRs are merged and remote branches are deleted
|
||||
/clean_gone
|
||||
|
||||
# Claude will:
|
||||
# - Find all branches marked as [gone]
|
||||
# - Remove any associated worktrees
|
||||
# - Delete the stale local branches
|
||||
# - Report what was cleaned up
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Handles both regular branches and worktree branches
|
||||
- Safely removes worktrees before deleting branches
|
||||
- Shows clear feedback about what was removed
|
||||
- Reports if no cleanup was needed
|
||||
|
||||
**When to use:**
|
||||
- After merging and deleting remote branches
|
||||
- When your local branch list is cluttered with stale branches
|
||||
- During regular repository maintenance
|
||||
|
||||
## Installation
|
||||
|
||||
This plugin is included in the Claude Code repository. The commands are automatically available when using Claude Code.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Using `/commit`
|
||||
- Review the staged changes before committing
|
||||
- Let Claude analyze your changes and match your repo's commit style
|
||||
- Trust the automated message, but verify it's accurate
|
||||
- Use for routine commits during development
|
||||
|
||||
### Using `/commit-push-pr`
|
||||
- Use when you're ready to create a PR
|
||||
- Ensure all your changes are complete and tested
|
||||
- Claude will analyze the full branch history for the PR description
|
||||
- Review the PR description and edit if needed
|
||||
- Use when you want to minimize context switching
|
||||
|
||||
### Using `/clean_gone`
|
||||
- Run periodically to keep your branch list clean
|
||||
- Especially useful after merging multiple PRs
|
||||
- Safe to run - only removes branches already deleted remotely
|
||||
- Helps maintain a tidy local repository
|
||||
|
||||
## Workflow Integration
|
||||
|
||||
### Quick commit workflow:
|
||||
```bash
|
||||
# Write code
|
||||
/commit
|
||||
# Continue development
|
||||
```
|
||||
|
||||
### Feature branch workflow:
|
||||
```bash
|
||||
# Develop feature across multiple commits
|
||||
/commit # First commit
|
||||
# More changes
|
||||
/commit # Second commit
|
||||
# Ready to create PR
|
||||
/commit-push-pr
|
||||
```
|
||||
|
||||
### Maintenance workflow:
|
||||
```bash
|
||||
# After several PRs are merged
|
||||
/clean_gone
|
||||
# Clean workspace ready for next feature
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- Git must be installed and configured
|
||||
- For `/commit-push-pr`: GitHub CLI (`gh`) must be installed and authenticated
|
||||
- Repository must be a git repository with a remote
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `/commit` creates empty commit
|
||||
|
||||
**Issue**: No changes to commit
|
||||
|
||||
**Solution**:
|
||||
- Ensure you have unstaged or staged changes
|
||||
- Run `git status` to verify changes exist
|
||||
|
||||
### `/commit-push-pr` fails to create PR
|
||||
|
||||
**Issue**: `gh pr create` command fails
|
||||
|
||||
**Solution**:
|
||||
- Install GitHub CLI: `brew install gh` (macOS) or see [GitHub CLI installation](https://cli.github.com/)
|
||||
- Authenticate: `gh auth login`
|
||||
- Ensure repository has a GitHub remote
|
||||
|
||||
### `/clean_gone` doesn't find branches
|
||||
|
||||
**Issue**: No branches marked as [gone]
|
||||
|
||||
**Solution**:
|
||||
- Run `git fetch --prune` to update remote tracking
|
||||
- Branches must be deleted from the remote to show as [gone]
|
||||
|
||||
## Tips
|
||||
|
||||
- **Combine with other tools**: Use `/commit` during development, then `/commit-push-pr` when ready
|
||||
- **Let Claude draft messages**: The commit message analysis learns from your repo's style
|
||||
- **Regular cleanup**: Run `/clean_gone` weekly to maintain a clean branch list
|
||||
- **Review before pushing**: Always review the commit message and changes before pushing
|
||||
|
||||
## Author
|
||||
|
||||
Anthropic (support@anthropic.com)
|
||||
|
||||
## Version
|
||||
|
||||
1.0.0
|
||||
412
plugins/feature-dev/README.md
Normal file
412
plugins/feature-dev/README.md
Normal file
@@ -0,0 +1,412 @@
|
||||
# Feature Development Plugin
|
||||
|
||||
A comprehensive, structured workflow for feature development with specialized agents for codebase exploration, architecture design, and quality review.
|
||||
|
||||
## Overview
|
||||
|
||||
The Feature Development Plugin provides a systematic 7-phase approach to building new features. Instead of jumping straight into code, it guides you through understanding the codebase, asking clarifying questions, designing architecture, and ensuring quality—resulting in better-designed features that integrate seamlessly with your existing code.
|
||||
|
||||
## Philosophy
|
||||
|
||||
Building features requires more than just writing code. You need to:
|
||||
- **Understand the codebase** before making changes
|
||||
- **Ask questions** to clarify ambiguous requirements
|
||||
- **Design thoughtfully** before implementing
|
||||
- **Review for quality** after building
|
||||
|
||||
This plugin embeds these practices into a structured workflow that runs automatically when you use the `/feature-dev` command.
|
||||
|
||||
## Command: `/feature-dev`
|
||||
|
||||
Launches a guided feature development workflow with 7 distinct phases.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
/feature-dev Add user authentication with OAuth
|
||||
```
|
||||
|
||||
Or simply:
|
||||
```bash
|
||||
/feature-dev
|
||||
```
|
||||
|
||||
The command will guide you through the entire process interactively.
|
||||
|
||||
## The 7-Phase Workflow
|
||||
|
||||
### Phase 1: Discovery
|
||||
|
||||
**Goal**: Understand what needs to be built
|
||||
|
||||
**What happens:**
|
||||
- Clarifies the feature request if it's unclear
|
||||
- Asks what problem you're solving
|
||||
- Identifies constraints and requirements
|
||||
- Summarizes understanding and confirms with you
|
||||
|
||||
**Example:**
|
||||
```
|
||||
You: /feature-dev Add caching
|
||||
Claude: Let me understand what you need...
|
||||
- What should be cached? (API responses, computed values, etc.)
|
||||
- What are your performance requirements?
|
||||
- Do you have a preferred caching solution?
|
||||
```
|
||||
|
||||
### Phase 2: Codebase Exploration
|
||||
|
||||
**Goal**: Understand relevant existing code and patterns
|
||||
|
||||
**What happens:**
|
||||
- Launches 2-3 `code-explorer` agents in parallel
|
||||
- Each agent explores different aspects (similar features, architecture, UI patterns)
|
||||
- Agents return comprehensive analyses with key files to read
|
||||
- Claude reads all identified files to build deep understanding
|
||||
- Presents comprehensive summary of findings
|
||||
|
||||
**Agents launched:**
|
||||
- "Find features similar to [feature] and trace implementation"
|
||||
- "Map the architecture and abstractions for [area]"
|
||||
- "Analyze current implementation of [related feature]"
|
||||
|
||||
**Example output:**
|
||||
```
|
||||
Found similar features:
|
||||
- User authentication (src/auth/): Uses JWT tokens, middleware pattern
|
||||
- Session management (src/session/): Redis-backed, 24hr expiry
|
||||
- API security (src/api/middleware/): Rate limiting, CORS
|
||||
|
||||
Key files to understand:
|
||||
- src/auth/AuthService.ts:45 - Core authentication logic
|
||||
- src/middleware/authMiddleware.ts:12 - Request authentication
|
||||
- src/config/security.ts:8 - Security configuration
|
||||
```
|
||||
|
||||
### Phase 3: Clarifying Questions
|
||||
|
||||
**Goal**: Fill in gaps and resolve all ambiguities
|
||||
|
||||
**What happens:**
|
||||
- Reviews codebase findings and feature request
|
||||
- Identifies underspecified aspects:
|
||||
- Edge cases
|
||||
- Error handling
|
||||
- Integration points
|
||||
- Backward compatibility
|
||||
- Performance needs
|
||||
- Presents all questions in an organized list
|
||||
- **Waits for your answers before proceeding**
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Before designing the architecture, I need to clarify:
|
||||
|
||||
1. OAuth provider: Which OAuth providers? (Google, GitHub, custom?)
|
||||
2. User data: Store OAuth tokens or just user profile?
|
||||
3. Existing auth: Replace current auth or add alongside?
|
||||
4. Sessions: Integrate with existing session management?
|
||||
5. Error handling: How to handle OAuth failures?
|
||||
```
|
||||
|
||||
**Critical**: This phase ensures nothing is ambiguous before design begins.
|
||||
|
||||
### Phase 4: Architecture Design
|
||||
|
||||
**Goal**: Design multiple implementation approaches
|
||||
|
||||
**What happens:**
|
||||
- Launches 2-3 `code-architect` agents with different focuses:
|
||||
- **Minimal changes**: Smallest change, maximum reuse
|
||||
- **Clean architecture**: Maintainability, elegant abstractions
|
||||
- **Pragmatic balance**: Speed + quality
|
||||
- Reviews all approaches
|
||||
- Forms opinion on which fits best for this task
|
||||
- Presents comparison with trade-offs and recommendation
|
||||
- **Asks which approach you prefer**
|
||||
|
||||
**Example output:**
|
||||
```
|
||||
I've designed 3 approaches:
|
||||
|
||||
Approach 1: Minimal Changes
|
||||
- Extend existing AuthService with OAuth methods
|
||||
- Add new OAuth routes to existing auth router
|
||||
- Minimal refactoring required
|
||||
Pros: Fast, low risk
|
||||
Cons: Couples OAuth to existing auth, harder to test
|
||||
|
||||
Approach 2: Clean Architecture
|
||||
- New OAuthService with dedicated interface
|
||||
- Separate OAuth router and middleware
|
||||
- Refactor AuthService to use common interface
|
||||
Pros: Clean separation, testable, maintainable
|
||||
Cons: More files, more refactoring
|
||||
|
||||
Approach 3: Pragmatic Balance
|
||||
- New OAuthProvider abstraction
|
||||
- Integrate into existing AuthService
|
||||
- Minimal refactoring, good boundaries
|
||||
Pros: Balanced complexity and cleanliness
|
||||
Cons: Some coupling remains
|
||||
|
||||
Recommendation: Approach 3 - gives you clean boundaries without
|
||||
excessive refactoring, and fits your existing architecture well.
|
||||
|
||||
Which approach would you like to use?
|
||||
```
|
||||
|
||||
### Phase 5: Implementation
|
||||
|
||||
**Goal**: Build the feature
|
||||
|
||||
**What happens:**
|
||||
- **Waits for explicit approval** before starting
|
||||
- Reads all relevant files identified in previous phases
|
||||
- Implements following chosen architecture
|
||||
- Follows codebase conventions strictly
|
||||
- Writes clean, well-documented code
|
||||
- Updates todos as progress is made
|
||||
|
||||
**Notes:**
|
||||
- Implementation only starts after you approve
|
||||
- Follows patterns discovered in Phase 2
|
||||
- Uses architecture designed in Phase 4
|
||||
- Continuously tracks progress
|
||||
|
||||
### Phase 6: Quality Review
|
||||
|
||||
**Goal**: Ensure code is simple, DRY, elegant, and functionally correct
|
||||
|
||||
**What happens:**
|
||||
- Launches 3 `code-reviewer` agents in parallel with different focuses:
|
||||
- **Simplicity/DRY/Elegance**: Code quality and maintainability
|
||||
- **Bugs/Correctness**: Functional correctness and logic errors
|
||||
- **Conventions/Abstractions**: Project standards and patterns
|
||||
- Consolidates findings
|
||||
- Identifies highest severity issues
|
||||
- **Presents findings and asks what you want to do**:
|
||||
- Fix now
|
||||
- Fix later
|
||||
- Proceed as-is
|
||||
- Addresses issues based on your decision
|
||||
|
||||
**Example output:**
|
||||
```
|
||||
Code Review Results:
|
||||
|
||||
High Priority Issues:
|
||||
1. Missing error handling in OAuth callback (src/auth/oauth.ts:67)
|
||||
2. Memory leak: OAuth state not cleaned up (src/auth/oauth.ts:89)
|
||||
|
||||
Medium Priority:
|
||||
1. Could simplify token refresh logic (src/auth/oauth.ts:120)
|
||||
2. Consider extracting OAuth config validation
|
||||
|
||||
All tests pass. Code follows project conventions.
|
||||
|
||||
What would you like to do?
|
||||
```
|
||||
|
||||
### Phase 7: Summary
|
||||
|
||||
**Goal**: Document what was accomplished
|
||||
|
||||
**What happens:**
|
||||
- Marks all todos complete
|
||||
- Summarizes:
|
||||
- What was built
|
||||
- Key decisions made
|
||||
- Files modified
|
||||
- Suggested next steps
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Feature Complete: OAuth Authentication
|
||||
|
||||
What was built:
|
||||
- OAuth provider abstraction supporting Google and GitHub
|
||||
- OAuth routes and middleware integrated with existing auth
|
||||
- Token refresh and session integration
|
||||
- Error handling for all OAuth flows
|
||||
|
||||
Key decisions:
|
||||
- Used pragmatic approach with OAuthProvider abstraction
|
||||
- Integrated with existing session management
|
||||
- Added OAuth state to prevent CSRF
|
||||
|
||||
Files modified:
|
||||
- src/auth/OAuthProvider.ts (new)
|
||||
- src/auth/AuthService.ts
|
||||
- src/routes/auth.ts
|
||||
- src/middleware/authMiddleware.ts
|
||||
|
||||
Suggested next steps:
|
||||
- Add tests for OAuth flows
|
||||
- Add more OAuth providers (Microsoft, Apple)
|
||||
- Update documentation
|
||||
```
|
||||
|
||||
## Agents
|
||||
|
||||
### `code-explorer`
|
||||
|
||||
**Purpose**: Deeply analyzes existing codebase features by tracing execution paths
|
||||
|
||||
**Focus areas:**
|
||||
- Entry points and call chains
|
||||
- Data flow and transformations
|
||||
- Architecture layers and patterns
|
||||
- Dependencies and integrations
|
||||
- Implementation details
|
||||
|
||||
**When triggered:**
|
||||
- Automatically in Phase 2
|
||||
- Can be invoked manually when exploring code
|
||||
|
||||
**Output:**
|
||||
- Entry points with file:line references
|
||||
- Step-by-step execution flow
|
||||
- Key components and responsibilities
|
||||
- Architecture insights
|
||||
- List of essential files to read
|
||||
|
||||
### `code-architect`
|
||||
|
||||
**Purpose**: Designs feature architectures and implementation blueprints
|
||||
|
||||
**Focus areas:**
|
||||
- Codebase pattern analysis
|
||||
- Architecture decisions
|
||||
- Component design
|
||||
- Implementation roadmap
|
||||
- Data flow and build sequence
|
||||
|
||||
**When triggered:**
|
||||
- Automatically in Phase 4
|
||||
- Can be invoked manually for architecture design
|
||||
|
||||
**Output:**
|
||||
- Patterns and conventions found
|
||||
- Architecture decision with rationale
|
||||
- Complete component design
|
||||
- Implementation map with specific files
|
||||
- Build sequence with phases
|
||||
|
||||
### `code-reviewer`
|
||||
|
||||
**Purpose**: Reviews code for bugs, quality issues, and project conventions
|
||||
|
||||
**Focus areas:**
|
||||
- Project guideline compliance (CLAUDE.md)
|
||||
- Bug detection
|
||||
- Code quality issues
|
||||
- Confidence-based filtering (only reports high-confidence issues ≥80)
|
||||
|
||||
**When triggered:**
|
||||
- Automatically in Phase 6
|
||||
- Can be invoked manually after writing code
|
||||
|
||||
**Output:**
|
||||
- Critical issues (confidence 75-100)
|
||||
- Important issues (confidence 50-74)
|
||||
- Specific fixes with file:line references
|
||||
- Project guideline references
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### Full workflow (recommended for new features):
|
||||
```bash
|
||||
/feature-dev Add rate limiting to API endpoints
|
||||
```
|
||||
|
||||
Let the workflow guide you through all 7 phases.
|
||||
|
||||
### Manual agent invocation:
|
||||
|
||||
**Explore a feature:**
|
||||
```
|
||||
"Launch code-explorer to trace how authentication works"
|
||||
```
|
||||
|
||||
**Design architecture:**
|
||||
```
|
||||
"Launch code-architect to design the caching layer"
|
||||
```
|
||||
|
||||
**Review code:**
|
||||
```
|
||||
"Launch code-reviewer to check my recent changes"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use the full workflow for complex features**: The 7 phases ensure thorough planning
|
||||
2. **Answer clarifying questions thoughtfully**: Phase 3 prevents future confusion
|
||||
3. **Choose architecture deliberately**: Phase 4 gives you options for a reason
|
||||
4. **Don't skip code review**: Phase 6 catches issues before they reach production
|
||||
5. **Read the suggested files**: Phase 2 identifies key files—read them to understand context
|
||||
|
||||
## When to Use This Plugin
|
||||
|
||||
**Use for:**
|
||||
- New features that touch multiple files
|
||||
- Features requiring architectural decisions
|
||||
- Complex integrations with existing code
|
||||
- Features where requirements are somewhat unclear
|
||||
|
||||
**Don't use for:**
|
||||
- Single-line bug fixes
|
||||
- Trivial changes
|
||||
- Well-defined, simple tasks
|
||||
- Urgent hotfixes
|
||||
|
||||
## Requirements
|
||||
|
||||
- Claude Code installed
|
||||
- Git repository (for code review)
|
||||
- Project with existing codebase (workflow assumes existing code to learn from)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Agents take too long
|
||||
|
||||
**Issue**: Code exploration or architecture agents are slow
|
||||
|
||||
**Solution**:
|
||||
- This is normal for large codebases
|
||||
- Agents run in parallel when possible
|
||||
- The thoroughness pays off in better understanding
|
||||
|
||||
### Too many clarifying questions
|
||||
|
||||
**Issue**: Phase 3 asks too many questions
|
||||
|
||||
**Solution**:
|
||||
- Be more specific in your initial feature request
|
||||
- Provide context about constraints upfront
|
||||
- Say "whatever you think is best" if truly no preference
|
||||
|
||||
### Architecture options overwhelming
|
||||
|
||||
**Issue**: Too many architecture options in Phase 4
|
||||
|
||||
**Solution**:
|
||||
- Trust the recommendation—it's based on codebase analysis
|
||||
- If still unsure, ask for more explanation
|
||||
- Pick the pragmatic option when in doubt
|
||||
|
||||
## Tips
|
||||
|
||||
- **Be specific in your feature request**: More detail = fewer clarifying questions
|
||||
- **Trust the process**: Each phase builds on the previous one
|
||||
- **Review agent outputs**: Agents provide valuable insights about your codebase
|
||||
- **Don't skip phases**: Each phase serves a purpose
|
||||
- **Use for learning**: The exploration phase teaches you about your own codebase
|
||||
|
||||
## Author
|
||||
|
||||
Sid Bidasaria (sbidasaria@anthropic.com)
|
||||
|
||||
## Version
|
||||
|
||||
1.0.0
|
||||
Reference in New Issue
Block a user