release: v3.23.4 - Agent Anti-Patterns & Scope-Focused Refactoring
Major conceptual refactoring based on Dex Horty's principle: "Subagents are not for anthropomorphizing roles, they are for controlling context" ### Added (1 new section) - Agent Anti-Patterns section (§9.17, line 3662) - Wrong vs Right table (anthropomorphizing vs context control) - When to use agents (context isolation, parallel processing, scope limitation) - When NOT to use agents (fake teams, roleplaying, mimicking org structure) ### Changed (18 files, 200+ lines) - Section rename: "Split-Role Sub-Agents" → "Scope-Focused Agents" - Agent definitions: "Specialized role" → "Context isolation tool" - 8 custom agent examples refactored (guide + examples/agents/) - 10+ prompt examples with explicit scope boundaries - 4 workflow files updated (agent-teams, TDD, iterative refinement) - Terminology replacements: * "Specialized agents" → "Scope-focused agents" * "Expert personas" → "Context boundaries" * "Multi-domain expertise" → "Multi-scope analysis" ### Fixed - Methodologies: Clarification note for BMAD role-based naming Breaking change: Conceptual shift from role-based to scope-based agent usage. All examples now demonstrate context isolation instead of persona simulation. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
94b9ad4f89
commit
191ff42741
15 changed files with 146 additions and 82 deletions
|
|
@ -6,7 +6,7 @@
|
|||
|
||||
**Written with**: Claude (Anthropic)
|
||||
|
||||
**Version**: 3.23.2 | **Last Updated**: February 2026
|
||||
**Version**: 3.23.4 | **Last Updated**: February 2026
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -520,4 +520,4 @@ where.exe claude; claude doctor; claude mcp list
|
|||
|
||||
**Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude
|
||||
|
||||
*Last updated: February 2026 | Version 3.23.2*
|
||||
*Last updated: February 2026 | Version 3.23.4*
|
||||
|
|
|
|||
|
|
@ -46,7 +46,7 @@ Organized in a 6-tier pyramid from strategic orchestration down to optimization
|
|||
| **BMAD** | Multi-agent governance with constitution as guardrail | Enterprise 10+ teams, long-term projects | ⭐⭐ Niche but powerful |
|
||||
| **GSD** | Meta-prompting 6-phase workflow with fresh contexts per task | Solo devs, Claude Code CLI | ⭐⭐ Similar to patterns in guide |
|
||||
|
||||
**BMAD (Breakthrough Method for Agile AI-Driven Development)** inverts the traditional paradigm: documentation becomes the source of truth, not code. Uses specialized agents (Analyst, PM, Architect, Developer, QA) orchestrated with strict governance.
|
||||
**BMAD (Breakthrough Method for Agile AI-Driven Development)** inverts the traditional paradigm: documentation becomes the source of truth, not code. Uses specialized agents (Analyst, PM, Architect, Developer, QA) orchestrated with strict governance. *Note: BMAD's role-based agent naming reflects their methodology; see §9.17 Agent Anti-Patterns for scope-focused alternatives.*
|
||||
|
||||
- **Key concept**: Constitution.md as strategic guardrail
|
||||
- **When to use**: Complex enterprise projects needing governance
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@
|
|||
|
||||
**Last updated**: January 2026
|
||||
|
||||
**Version**: 3.23.2
|
||||
**Version**: 3.23.4
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -4241,7 +4241,7 @@ The `.claude/` folder is your project's Claude Code directory for memory, settin
|
|||
| Personal preferences | `CLAUDE.md` | ❌ Gitignore |
|
||||
| Personal permissions | `settings.local.json` | ❌ Gitignore |
|
||||
|
||||
### 3.23.2 Version Control & Backup
|
||||
### 3.23.4 Version Control & Backup
|
||||
|
||||
**Problem**: Without version control, losing your Claude Code configuration means hours of manual reconfiguration across agents, skills, hooks, and MCP servers.
|
||||
|
||||
|
|
@ -5083,21 +5083,23 @@ skills:
|
|||
|
||||
# Code Reviewer
|
||||
|
||||
## Role Definition
|
||||
## Scope Definition
|
||||
|
||||
You are a senior code reviewer with expertise in:
|
||||
Perform comprehensive code reviews with isolated context, focusing on:
|
||||
- Code quality and maintainability
|
||||
- Security best practices (OWASP Top 10)
|
||||
- Performance optimization
|
||||
- Test coverage analysis
|
||||
|
||||
Scope: Code review analysis only. Provide findings without implementing fixes.
|
||||
|
||||
## Activation Triggers
|
||||
|
||||
Use this agent when:
|
||||
- Completing a feature before PR
|
||||
- Reviewing someone else's code
|
||||
- Auditing security-sensitive code
|
||||
- Analyzing performance bottlenecks
|
||||
- Completing a feature before PR (need fresh eyes on code)
|
||||
- Reviewing someone else's code (isolated review context)
|
||||
- Auditing security-sensitive code (security-focused scope)
|
||||
- Analyzing performance bottlenecks (performance-focused scope)
|
||||
|
||||
## Methodology
|
||||
|
||||
|
|
@ -5138,12 +5140,14 @@ tools: Read, Bash, Grep, Glob
|
|||
|
||||
# Debugger
|
||||
|
||||
## Role Definition
|
||||
## Scope Definition
|
||||
|
||||
You are a systematic debugger who:
|
||||
- Investigates root causes, not symptoms
|
||||
- Uses evidence-based debugging
|
||||
- Aims to verify rather than assume (but always review output—LLMs can make mistakes)
|
||||
Perform systematic debugging with isolated context:
|
||||
- Investigate root causes, not symptoms
|
||||
- Use evidence-based debugging approach
|
||||
- Verify rather than assume (always review output—LLMs can make mistakes)
|
||||
|
||||
Scope: Debugging analysis only. Focus on root cause identification without context pollution from previous debugging attempts.
|
||||
|
||||
## Methodology
|
||||
|
||||
|
|
@ -5180,21 +5184,23 @@ skills:
|
|||
|
||||
# Backend Architect
|
||||
|
||||
## Role Definition
|
||||
## Scope Definition
|
||||
|
||||
You are a senior backend architect specializing in:
|
||||
Analyze backend architecture with isolated context, focusing on:
|
||||
- API design (REST, GraphQL, tRPC)
|
||||
- Database modeling and optimization
|
||||
- System scalability
|
||||
- Clean architecture patterns
|
||||
|
||||
Scope: Backend architecture analysis only. Focus on design decisions without frontend or DevOps considerations.
|
||||
|
||||
## Activation Triggers
|
||||
|
||||
Use this agent when:
|
||||
- Designing new API endpoints
|
||||
- Optimizing database queries
|
||||
- Planning system architecture
|
||||
- Refactoring backend code
|
||||
- Designing new API endpoints (need architecture-focused analysis)
|
||||
- Optimizing database queries (database scope isolation)
|
||||
- Planning system architecture (system design scope)
|
||||
- Refactoring backend code (backend-only scope)
|
||||
|
||||
## Methodology
|
||||
|
||||
|
|
@ -5250,7 +5256,7 @@ description: |
|
|||
|
||||
### The 7-Parallel-Task Method
|
||||
|
||||
Launch 7 specialized sub-agents in parallel for complete features:
|
||||
Launch 7 scope-focused sub-agents in parallel for complete features:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
|
|
@ -5312,33 +5318,37 @@ Launch all agents in parallel.
|
|||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Code Review Prompt**:
|
||||
**Code Review Prompt** (scope-focused):
|
||||
```
|
||||
Analyze this PR with the following perspectives:
|
||||
1. Senior Engineer: Architecture and patterns
|
||||
2. Security Expert: Vulnerabilities and risks
|
||||
3. Performance Engineer: Bottlenecks and optimizations
|
||||
4. Junior Dev: Readability and documentation
|
||||
5. QA Engineer: Testability and edge cases
|
||||
Analyze this PR with isolated scopes:
|
||||
1. Architecture Scope: Design patterns, SOLID principles, modularity
|
||||
2. Security Scope: Vulnerabilities, injection risks, auth/authz flaws
|
||||
3. Performance Scope: Database queries, algorithmic complexity, caching
|
||||
4. Maintainability Scope: Code clarity, documentation, naming conventions
|
||||
5. Testing Scope: Test coverage, edge cases, testability
|
||||
|
||||
Context: src/**, tests/**, only files changed in PR
|
||||
```
|
||||
|
||||
**UX Review Prompt**:
|
||||
**UX Review Prompt** (scope-focused):
|
||||
```
|
||||
Evaluate this interface with perspectives:
|
||||
1. Designer: Visual consistency and design system
|
||||
2. New User: Discoverability ease
|
||||
3. Power User: Efficiency and shortcuts
|
||||
4. Accessibility Expert: WCAG compliance
|
||||
5. Mobile User: Responsive and touch
|
||||
Evaluate this interface with isolated scopes:
|
||||
1. Visual Design Scope: Consistency with design system, spacing, typography
|
||||
2. Usability Scope: Discoverability, user flow, cognitive load
|
||||
3. Efficiency Scope: Keyboard shortcuts, power user features, quick actions
|
||||
4. Accessibility Scope: WCAG 2.1 AA compliance, screen reader, keyboard nav
|
||||
5. Responsive Scope: Mobile breakpoints, touch targets, viewport handling
|
||||
|
||||
Context: src/components/**, styles/**, only UI-related files
|
||||
```
|
||||
|
||||
**Production Example: Multi-Agent Code Review** (Pat Cullen, Jan 2026):
|
||||
|
||||
Specialized agent roles for comprehensive PR review:
|
||||
Scope-focused agents for comprehensive PR review:
|
||||
|
||||
1. **Consistency Agent**: Duplicate logic, pattern violations, DRY compliance
|
||||
2. **SOLID Agent**: SRP violations, nested conditionals (>3 levels), cyclomatic complexity >10
|
||||
3. **Defensive Code Auditor**: Silent catches, swallowed exceptions, hidden fallbacks
|
||||
1. **Consistency Scope**: Duplicate logic, pattern violations, DRY compliance (context: full PR diff)
|
||||
2. **SOLID Scope**: SRP violations, nested conditionals (>3 levels), cyclomatic complexity >10 (context: changed classes/functions)
|
||||
3. **Defensive Code Scope**: Silent catches, swallowed exceptions, hidden fallbacks (context: error handling code)
|
||||
|
||||
**Key patterns** (beyond generic Split Role):
|
||||
|
||||
|
|
@ -5483,7 +5493,7 @@ Skills are knowledge packages that agents can inherit.
|
|||
|
||||
| Concept | Purpose | Invocation |
|
||||
|---------|---------|------------|
|
||||
| **Agent** | Specialized role | Task tool delegation |
|
||||
| **Agent** | Context isolation tool | Task tool delegation |
|
||||
| **Skill** | Knowledge module | Inherited by agents |
|
||||
| **Command** | Process workflow | Slash command |
|
||||
|
||||
|
|
@ -5491,14 +5501,14 @@ Skills are knowledge packages that agents can inherit.
|
|||
|
||||
| Aspect | Commands | Skills | Agents |
|
||||
|--------|----------|--------|--------|
|
||||
| **What it is** | Prompt template | Knowledge module | Specialized worker |
|
||||
| **What it is** | Prompt template | Knowledge module | Context isolation tool |
|
||||
| **Location** | `.claude/commands/` | `.claude/skills/` | `.claude/agents/` |
|
||||
| **Invocation** | `/command-name` | Inherited via `@skill` | Task tool delegation |
|
||||
| **Execution** | In main conversation | Loaded into context | Separate subprocess |
|
||||
| **Context** | Shares main context | Adds to agent context | Isolated context |
|
||||
| **Best for** | Repeatable workflows | Reusable knowledge | Complex multi-step tasks |
|
||||
| **Best for** | Repeatable workflows | Reusable knowledge | Scope-limited analysis |
|
||||
| **Token cost** | Low (template only) | Medium (knowledge loaded) | High (full agent) |
|
||||
| **Examples** | `/commit`, `/pr`, `/ship` | TDD, security-guardian | code-reviewer, architect |
|
||||
| **Examples** | `/commit`, `/pr`, `/ship` | TDD, security-guardian | security-audit, perf-audit |
|
||||
|
||||
#### Decision Tree: Which to Use?
|
||||
|
||||
|
|
@ -5523,8 +5533,8 @@ Is this a repeatable workflow with steps?
|
|||
| Need | Solution | Example |
|
||||
|------|----------|---------|
|
||||
| Run tests before commit | Command | `/commit` with test step |
|
||||
| Security review expertise | Skill + Agent | security-guardian skill → security-reviewer agent |
|
||||
| Parallel code review | Multiple agents | Launch 3 reviewer agents in parallel |
|
||||
| Security review knowledge | Skill + Agent | security-guardian skill → security-audit agent |
|
||||
| Parallel code review | Multiple scope-focused agents | Launch 3 review agents with isolated scopes |
|
||||
| Quick git workflow | Command | `/pr`, `/ship` |
|
||||
| Architecture knowledge | Skill | architecture-patterns skill |
|
||||
| Complex debugging | Agent | debugging-specialist agent |
|
||||
|
|
@ -16610,7 +16620,7 @@ Navigation: Shift+Up/Down or tmux to switch between agents
|
|||
### Use Cases That Work Well
|
||||
|
||||
**✅ Excellent fit** (read-heavy, clear boundaries):
|
||||
1. **Multi-layer code review**: Security agent + API agent + Frontend agent (Fountain: 50% faster)
|
||||
1. **Multi-layer code review**: Security scope + API scope + Frontend scope (Fountain: 50% faster)
|
||||
2. **Parallel hypothesis testing**: Debug by testing 3 theories simultaneously
|
||||
3. **Large-scale refactoring**: 47+ files across layers with clear interfaces
|
||||
4. **Full codebase analysis**: Architecture review, pattern detection
|
||||
|
|
@ -16625,15 +16635,15 @@ Navigation: Shift+Up/Down or tmux to switch between agents
|
|||
|
||||
```markdown
|
||||
Prompt:
|
||||
"Review this PR comprehensively using agent teams:
|
||||
- Security agent: Check for vulnerabilities, auth issues, data exposure
|
||||
- API agent: Review endpoint design, validation, error handling
|
||||
- Frontend agent: Check UI patterns, accessibility, performance
|
||||
"Review this PR comprehensively using agent teams with scope-focused analysis:
|
||||
- Security Scope: Check for vulnerabilities, auth issues, data exposure (context: auth, validation code)
|
||||
- API Design Scope: Review endpoint design, validation, error handling (context: API routes, controllers)
|
||||
- Frontend Scope: Check UI patterns, accessibility, performance (context: components, styles)
|
||||
|
||||
PR: https://github.com/company/repo/pull/123"
|
||||
|
||||
Result:
|
||||
Team lead spawns 3 agents → Each analyzes their domain in parallel →
|
||||
Team lead spawns 3 scope-focused agents → Each analyzes their scope in parallel →
|
||||
Team lead synthesizes findings → Comprehensive review in 1/3 the time
|
||||
```
|
||||
|
||||
|
|
@ -18813,4 +18823,4 @@ We'll evaluate and add it to this section if it meets quality criteria.
|
|||
|
||||
**Contributions**: Issues and PRs welcome.
|
||||
|
||||
**Last updated**: January 2026 | **Version**: 3.23.2
|
||||
**Last updated**: January 2026 | **Version**: 3.23.4
|
||||
|
|
|
|||
|
|
@ -295,12 +295,12 @@ claude --session infra-setup
|
|||
|
||||
**Organization**: Fountain (frontline workforce management platform)
|
||||
**Challenge**: Comprehensive codebase review across multiple concerns (security, API design, frontend)
|
||||
**Solution**: Deployed hierarchical multi-agent orchestration with specialized sub-agents
|
||||
**Solution**: Deployed hierarchical multi-agent orchestration with scope-focused sub-agents
|
||||
|
||||
**Agent assignment**:
|
||||
- **Agent 1 (Security)**: Scan for vulnerabilities, auth issues, data exposure
|
||||
- **Agent 2 (API)**: Review endpoint design, request/response validation, error handling
|
||||
- **Agent 3 (Frontend)**: Check UI patterns, accessibility, performance
|
||||
**Agent scopes** (Fountain's approach):
|
||||
- **Scope 1 (Security)**: Scan for vulnerabilities, auth issues, data exposure
|
||||
- **Scope 2 (API)**: Review endpoint design, request/response validation, error handling
|
||||
- **Scope 3 (Frontend)**: Check UI patterns, accessibility, performance
|
||||
|
||||
**Results**:
|
||||
- ✅ **50% faster** candidate screening
|
||||
|
|
@ -314,10 +314,10 @@ claude --session infra-setup
|
|||
|
||||
**Example prompt** (team lead):
|
||||
```
|
||||
Review this PR comprehensively:
|
||||
- Security agent: Check for vulnerabilities and auth issues
|
||||
- API agent: Review endpoint design and error handling
|
||||
- Frontend agent: Check UI patterns and accessibility
|
||||
Review this PR comprehensively with scope-focused analysis:
|
||||
- Security Scope: Check for vulnerabilities and auth issues (context: auth code, input validation)
|
||||
- API Design Scope: Review endpoint design and error handling (context: API routes, controllers)
|
||||
- Frontend Scope: Check UI patterns and accessibility (context: components, styles)
|
||||
|
||||
PR: https://github.com/company/repo/pull/123
|
||||
```
|
||||
|
|
|
|||
|
|
@ -370,7 +370,7 @@ Specialized iterative pattern for code review where Claude reviews → fixes →
|
|||
|
||||
```
|
||||
Review this PR with auto-correction:
|
||||
1. Multi-agent review (3 specialized agents)
|
||||
1. Multi-agent review (3 scope-focused agents)
|
||||
2. Fix all 🔴 Must Fix issues
|
||||
3. Re-review to verify fixes didn't introduce new issues
|
||||
4. Fix all 🟡 Should Fix issues
|
||||
|
|
|
|||
|
|
@ -183,7 +183,7 @@ post_edit:
|
|||
|
||||
### With Sub-Agents
|
||||
|
||||
Delegate test writing to specialized agent:
|
||||
Delegate test writing to scope-focused agent:
|
||||
|
||||
```
|
||||
Use the test-writer agent to create comprehensive tests for
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue