115 lines
3.8 KiB
Markdown
115 lines
3.8 KiB
Markdown
# Claude Code Agents
|
|
|
|
This project uses specialized Claude Code agents for different types of Haskell refactoring. Each agent has focused expertise to provide targeted improvements.
|
|
|
|
## Available Agents
|
|
|
|
### haskell-refactoring-expert
|
|
**Purpose**: Basic code quality and structural improvements
|
|
|
|
**Expertise**:
|
|
- Type consistency (String vs Text vs ByteString)
|
|
- Module organization and file splitting (>150 lines)
|
|
- Naming conventions and clarity
|
|
- Dependency management
|
|
- Basic code structure improvements
|
|
|
|
**When to use**:
|
|
- Inconsistent type usage across the codebase
|
|
- Large files that need module organization
|
|
- Poor naming or unclear function responsibilities
|
|
- Mixed concerns in single modules
|
|
|
|
**Example**: Converting a 300-line Main.hs into proper module hierarchy
|
|
|
|
### haskell-higher-order
|
|
**Purpose**: Advanced functional programming patterns and architectural refactoring
|
|
|
|
**Expertise**:
|
|
- Monad transformer patterns (ExceptT, ReaderT, StateT)
|
|
- Pipeline composition with monadic operators
|
|
- Higher-order abstractions and strategy patterns
|
|
- Effect management and pure/IO separation
|
|
- Functional design patterns
|
|
|
|
**When to use**:
|
|
- Nested case statements handling Either values in IO
|
|
- Duplicated functions that differ only in specific steps
|
|
- Manual threading of configuration or state
|
|
- Imperative-style code that could be more functional
|
|
- Complex error handling that needs cleanup
|
|
|
|
**Example**: Converting nested Either/IO handling to ExceptT pipelines
|
|
|
|
## Agent Boundaries and Trade-offs
|
|
|
|
### Complementary Design
|
|
These agents are designed to work **sequentially**:
|
|
1. **First pass**: `haskell-refactoring-expert` for structural cleanup
|
|
2. **Second pass**: `haskell-higher-order` for functional patterns
|
|
|
|
### Why Separate Agents?
|
|
|
|
**Benefits**:
|
|
- **Focused expertise**: Each agent has deep knowledge in its domain
|
|
- **Clear boundaries**: Easy to know which agent to use
|
|
- **Manageable complexity**: Avoids instruction bloat in single agent
|
|
- **Progressive enhancement**: Apply increasingly sophisticated refactoring
|
|
- **Composability**: Can run both agents or just one as needed
|
|
|
|
**Trade-offs**:
|
|
- **Coordination overhead**: Need to run multiple agents
|
|
- **Context switching**: Each agent analyzes code independently
|
|
- **Potential overlap**: Some patterns might fit both agents
|
|
|
|
### Decision Framework
|
|
|
|
**Use haskell-refactoring-expert when you have**:
|
|
- ❌ Mixed String/Text types
|
|
- ❌ Large monolithic files (>150 lines)
|
|
- ❌ Unclear naming or responsibilities
|
|
- ❌ Basic structural issues
|
|
|
|
**Use haskell-higher-order when you have**:
|
|
- ❌ Nested error handling (Either in IO)
|
|
- ❌ Duplicated function structures
|
|
- ❌ Manual state/config threading
|
|
- ❌ Imperative-style patterns
|
|
|
|
**Use both agents when**:
|
|
- ❌ You want comprehensive refactoring
|
|
- ❌ Code has both structural and architectural issues
|
|
- ❌ You're doing major codebase improvements
|
|
|
|
## Usage Patterns
|
|
|
|
### Sequential Refactoring
|
|
```bash
|
|
# Run basic refactoring first
|
|
/agent haskell-refactoring-expert "Please refactor the Main.hs file"
|
|
|
|
# Then apply advanced patterns
|
|
/agent haskell-higher-order "Please improve the error handling patterns"
|
|
```
|
|
|
|
### Targeted Improvements
|
|
```bash
|
|
# Just structural cleanup
|
|
/agent haskell-refactoring-expert "Split this large module"
|
|
|
|
# Just functional patterns
|
|
/agent haskell-higher-order "Convert these nested cases to monadic style"
|
|
```
|
|
|
|
## Evolution Strategy
|
|
|
|
These agents can evolve independently:
|
|
- **haskell-refactoring-expert**: Add more structural patterns, linting rules
|
|
- **haskell-higher-order**: Add more advanced patterns (free monads, effect systems)
|
|
|
|
New specialized agents could be added:
|
|
- **haskell-performance**: Optimization-focused refactoring
|
|
- **haskell-testing**: Test-driven refactoring and property-based testing
|
|
- **haskell-domain**: Domain modeling and type design
|
|
|
|
The key is maintaining clear boundaries and complementary functionality. |