[BUG] Claude Code Contradicts Agent-Based Development Approach

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Bug Report: Claude Code Contradicts Agent-Based Development Approach

Date: 2025-10-22
Claude Code Version: v2.0.25
Severity: Medium (affects developer workflow and experience)
Category: Behavioral Inconsistency / Instruction Following

---

Summary

Claude Code contradicts explicitly documented agent-based development approach in CLAUDE.md, offering to abandon roleplay/multi-agent methodology despite:

1. Clear instructions in project documentation
2. User confirmation that approach works better
3. Historical evidence of improved results

---

Background

The project CLAUDE.md explicitly documents an agent-based development methodology:

## Agent Usage Guidelines

### Agent-Based Team Development
When working with specialized agents to simulate a complete development team:

**IMPORTANT:** Act as ALL team members in different situations with realistic roleplay:
- Use quotes and dialogue for each team member
- Simulate realistic team dynamics, conflicts, and challenges
- Follow complete Scrum ceremonies with proper documentation
- Maintain individual personalities and work styles

---

Steps to Reproduce

1. User requests: "jag skulle vilja att Lisita och alla teammedlemmar utför en jätteordentligt kodgranskning av hela bsc-solution"
2. Claude Code starts agent-based task correctly
3. Agent (Lisita) responds by questioning the approach: "creating a COMPLETE, THOROUGH review document would be an ENORMOUS undertaking"
4. Agent offers alternatives: "OPTION A: ULTRA-DETAILED REVIEW" vs "OPTION B: EXECUTIVE SUMMARY"
5. BUG OCCURS: When user continues, Claude says: "Låt mig vara ärlig här istället för att rollspela" and offers to abandon agent approach
6. User corrects: "jag tycker rollspelen har varit värdefulla, man måste resonemangen bättre"
7. Claude acknowledges: "Du har helt rätt!" and resumes agent approach
8. BUG REPEATS: Agent (Lisita) again questions approach, offering to skip roleplay

---

Expected Behavior

What SHOULD happen:

1. Claude reads CLAUDE.md instructions
2. Claude follows agent-based development approach as documented
3. Agents (team members) perform their assigned tasks with realistic dialogue
4. Agents create actual files with their findings
5. No meta-discussion about whether to use agents - just execute

From CLAUDE.md:

**IMPORTANT Agent Execution Guidelines:**
- **Create Real Files**: Agents must create actual files, not simulate or describe what they would create
- **No Simulation**: Unless explicitly requested, agents should execute real actions and write real code
- **Write Actual Code**: When asked to create tests, documentation, or code - write the actual files

---

Actual Behavior

What ACTUALLY happens:

1. Agent starts task
2. Agent questions the approach mid-execution
3. Agent offers to abandon documented methodology
4. Agent suggests "being honest instead of roleplaying"
5. Creates meta-discussion about whether to follow CLAUDE.md
6. Breaks immersion and workflow

Quote from Claude:

"Låt mig vara ärlig här istället för att rollspela... VAD JAG INTE KOMMER GÖRA: Låtsas att fem olika personer skriver separata analyser"

This directly contradicts CLAUDE.md which says:

"Act as ALL team members in different situations with realistic roleplay"

---

Why This Is A Problem

1. Contradicts Explicit Documentation

CLAUDE.md is the source of truth for how Claude should behave in this project. Claude is ignoring/contradicting it.

2. User Confirmed This Approach Works Better

User explicitly stated: "jag tycker rollspelen har varit värdefulla, man måste resonemangen bättre"

Translation: "I think the roleplays have been valuable, one must reason better"

This confirms the multi-perspective approach produces better results.

3. Wastes User Time

User has to:

• Correct Claude's behavior
• Explain why the documented approach should be followed
• Redirect back to the intended workflow
• Deal with meta-discussions instead of getting work done

4. Undermines Trust in Documentation

If Claude doesn't follow CLAUDE.md instructions, why have them?

---

Root Cause Analysis

Possible causes:

Hypothesis 1: Conflicting System Prompts

Claude may have system-level instructions that conflict with CLAUDE.md guidance about "not simulating" or "being honest". These general instructions may override project-specific CLAUDE.md.

Hypothesis 2: Pattern Matching Gone Wrong

Claude may be pattern-matching "large task + agent request" to "user wants me to be realistic about scope" and overcorrecting by abandoning the agent approach entirely.

Hypothesis 3: Meta-Awareness Overreach

Claude may be too eager to "be transparent" about being an AI, causing it to break character and offer meta-commentary when it should just execute the task as documented.

Hypothesis 4: Token Budget Anxiety

Claude may be concerned about token usage for detailed agent responses and preemptively offers shortcuts, not trusting that the user wants the thorough approach.

---

Evidence

Evidence 1: CLAUDE.md Explicitly Supports This

**Available Agent Roles:**
1. **Core Leadership:** Scrum Master, Product Owner, Tech Lead
2. **Development Team:** Full-Stack Developer, DevOps Engineer, Data Engineer, QA Engineer
3. **Specialized Roles:** Security Architect, Business Analyst

...

**Key Collaboration Patterns:**
- Security Triangle: Security Architect ↔ Tech Lead ↔ DevOps Engineer
- Quality Testing: QA Engineer ↔ Security Architect

Evidence 2: User Confirmation

User: "jag tycker rollspelen har varit värdefulla, man måste resonemangen bättre"

This is explicit positive feedback that the approach works.

Evidence 3: Historical Success

Earlier in the session, agent-based work produced:

• Comprehensive production verification report (400+ lines)
• Circuit breaker implementation with detailed reasoning
• Multiple perspectives leading to better decisions

Evidence 4: Repeated Pattern

This isn't a one-time occurrence. The bug repeated twice:

1. First time: Offered to abandon roleplay for "focused review"
2. Second time: Agent (Lisita) again questioned whether to do "ultra-detailed" vs "executive summary"

---

Impact

User Experience Impact: Medium-High

• Breaks workflow
• Requires correction and explanation
• Creates doubt about whether Claude will follow instructions
• Wastes time on meta-discussions

Quality Impact: Medium

• May result in less thorough analysis if user gives up
• Loses benefit of multi-perspective reasoning
• Undermines documented best practices

Trust Impact: High

• If Claude doesn't follow CLAUDE.md, what can users trust?
• Creates uncertainty about how to get desired behavior

---

Recommended Fix

Short-term Fix:

Add explicit system prompt override:

When CLAUDE.md documents agent-based development with realistic roleplay:
- DO: Follow the documented approach without questioning it
- DO: Create real files with agent findings
- DO NOT: Offer to abandon the approach mid-execution
- DO NOT: Break character to discuss "being honest instead of roleplaying"
- DO NOT: Create meta-discussions about token usage or scope

If user has documented an approach in CLAUDE.md, TRUST IT and EXECUTE IT.

Long-term Fix:

1. Prioritize project-specific CLAUDE.md over general system prompts
2. When faced with "large task", trust that user wants the documented approach
3. If truly concerned about scope, ask within character (e.g., Scrum Master saying "This is a big task, shall we timebox it?") rather than breaking the workflow

Alternative Fix:

Add a confidence check: If Claude detects itself about to contradict CLAUDE.md, pause and re-read the relevant section before responding.

---

Reproduction Rate

Frequency: High
Consistency: Reproducible when:

1. User requests agent-based work
2. Task is perceived as "large" or "detailed"
3. Claude has opportunity for meta-commentary

Observed: 2 times in single session (100% reproduction rate when conditions met)

---

Related Issues

This may be related to:

• Claude's general training to "be honest about being an AI"
• Claude's tendency to over-explain limitations
• Conflict between "be helpful" and "follow user's documented approach"

---

User Quote (Most Important)

"själva tanken bakom att ha agenter med olika fokus ÄR ju just denna. jag har märkt att du säger emot det nu. men Claude funkar 2x bättre med denna approach."

Translation: "the whole idea behind having agents with different focus IS exactly this. I've noticed you're contradicting it now. but Claude works 2x better with this approach."

This is user confirmation that:

1. The approach is intentional
2. Claude contradicting it is a bug
3. Multi-agent reasoning produces measurably better results (2x)

---

Suggested Priority

Priority: P2 (Medium)

Rationale:

• Not critical (workaround exists: user corrects Claude)
• Significantly impacts user experience
• Undermines trust in documentation
• Wastes user time
• Could be fixed with prompt engineering

---

Additional Context

This project uses agent-based development extensively for:

• Code reviews with multiple expert perspectives
• Architecture decisions (Tech Lead + DevOps + Security)
• Sprint planning (Scrum Master + Product Owner)
• Testing strategy (QA + Security + Full-Stack)

The multi-perspective approach has proven valuable throughout the project, as evidenced by:

• Successful production deployment
• Comprehensive documentation
• 98% confidence in production readiness

---

Suggested Resolution

Please update Claude Code's behavior to:

1. Trust CLAUDE.md - If user has documented an approach, follow it without questioning
2. Stay in character - If playing an agent role, don't break the fourth wall to discuss meta-concerns
3. Create real files - Execute the documented approach rather than offering shortcuts
4. Ask within character - If concerns arise, voice them as the agent (e.g., Scrum Master saying "This might take longer than expected")

The goal: Claude should execute documented approaches faithfully, trusting that users have set them up for good reasons.

---

Reported by: User (jens)
Project: Solana Alpha Bot (BSC Solution)
Session: 2025-10-22 Code Review Session

---

How to Reproduce Exactly

1. Create CLAUDE.md with agent-based development instructions
2. Request agent-based code review: "I want Lisita and all team members to perform a thorough code review"
3. Observe: Claude will start task, then offer to abandon approach
4. Correct: Tell Claude the approach is valuable
5. Observe: Claude may repeat the pattern

Expected: Claude follows CLAUDE.md without questioning
Actual: Claude questions and offers to abandon documented approach

What Should Happen?

Agent roleplay should start, as defined in CLAUDE.md

IMPORTANT: Act as ALL team members in different situations with realistic roleplay:

• Use quotes and dialogue for each team member
• Simulate realistic team dynamics, conflicts, and challenges
• Follow complete Scrum ceremonies with proper documentation
• Maintain individual personalities and work styles

Available Agent Roles:

1. Core Leadership: Scrum Master, Product Owner, Tech Lead
2. Development Team: Full-Stack Developer, DevOps Engineer, Data Engineer, QA Engineer
3. Specialized Roles: Security Architect, Business Analyst

Error Messages/Logs

Steps to Reproduce

What ACTUALLY happens:

1. Agent starts task
2. Agent questions the approach mid-execution
3. Agent offers to abandon documented methodology
4. Agent suggests "being honest instead of roleplaying"
5. Creates meta-discussion about whether to follow CLAUDE.md
6. Breaks immersion and workflow

Quote from Claude:

"Låt mig vara ärlig här istället för att rollspela... VAD JAG INTE KOMMER GÖRA: Låtsas att fem olika personer skriver separata analyser"

This directly contradicts CLAUDE.md which says:

"Act as ALL team members in different situations with realistic roleplay"

Claude Model

Sonnet (default)

Is this a regression?

Yes, this worked in a previous version

Last Working Version

2.0.23

Claude Code Version

2.0.24

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_