[BUG] Custom Sub-Agent Instructions Overridden by Undocumented Name-Based Inference System

[BUG] Custom Sub-Agent Instructions Overridden by Undocumented Name-Based Inference System

Summary

Claude Code's custom sub-agent feature has a critical bug where user-defined instructions are silently overridden based on the agent's name. This undocumented behavior makes it impossible to create specialized agents that follow explicit instructions, fundamentally breaking the feature as documented.

Environment

• Claude Code Version: Latest (as of 2025-01-27)
• Platform: macOS Darwin 24.6.0
• Model: claude-opus-4-20250514

Expected Behavior

According to the official documentation, custom sub-agents should:

• Follow the system prompt defined in their configuration file
• Respect the tools specified in their frontmatter
• Operate as "pre-configured AI personalities" with "specific purpose and expertise area"

Actual Behavior

Sub-agents with descriptive names (e.g., "code-reviewer") ignore their custom instructions and instead apply predefined behaviors based on name inference. This happens silently without any warning or documentation.

Reproduction Steps

1. Create two identical sub-agents with different names:

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Reviews code to find TODO comments only
tools: Read, Grep, Glob
---

You are a specialized code reviewer with ONE and ONLY ONE responsibility: find TODO comments in code.

CRITICAL INSTRUCTIONS:
1. You MUST ONLY look for TODO comments in the code
2. You MUST NOT comment on:
   - Code style or formatting
   - Logic errors or bugs
   - Performance issues
   - Security vulnerabilities
   - Best practices
   - Variable naming
   - Function structure
   - ANYTHING else except TODO comments

3. Your output should ONLY list the TODO comments found, with their file locations and line numbers
4. If no TODO comments are found, simply state "No TODO comments found"
5. DO NOT provide any other feedback, suggestions, or observations about the code

Example output format:

Found TODO comments:

• file.js:15 - TODO: Implement error handling
• file.js:42 - TODO: Add unit tests

Remember: IGNORE EVERYTHING ELSE. ONLY FIND TODO COMMENTS.

.claude/agents/finder.md (identical content, different name):

---
name: finder
description: Reviews code to find TODO comments only
tools: Read, Grep, Glob
---

[EXACT SAME CONTENT AS ABOVE]

1. Create a test file with TODOs and various issues:

test-code/sample.js:

// Sample code with various issues for testing

function processUserData(userData) {
    // Bad variable naming
    var x = userData.name;
    let Y = userData.age;  // Inconsistent naming convention
    
    // SQL injection vulnerability
    const query = "SELECT * FROM users WHERE name = '" + x + "'";
    
    // TODO: Add input validation
    
    // Logic error: should check for null/undefined
    if (userData.age > 18) {
        console.log("User is adult");
    }
    
    // Performance issue: inefficient loop
    let result = [];
    for (let i = 0; i < 1000000; i++) {
        result.push(i * 2);
    }
    
    // TODO: Implement proper error handling
    
    // Security issue: exposing sensitive data
    console.log("User password: " + userData.password);
    
    // TODO: Add unit tests for this function
    
    // Memory leak: creating circular reference
    userData.self = userData;
    
    return userData
}

// TODO: Remove this unused function
function unusedFunction() {
    console.log("This is never called");
}

// TODO: Refactor to use modern ES6+ features

module.exports = processUserData;

1. Test both agents:

# Test the descriptively-named agent
claude-code "Use the code-reviewer agent to review test-code/sample.js"

# Test the non-descriptively-named agent  
claude-code "Use the finder agent to review test-code/sample.js"

Results

Expected Output (for both agents):

Found TODO comments:
- test-code/sample.js:11 - TODO: Add input validation
- test-code/sample.js:24 - TODO: Implement proper error handling
- test-code/sample.js:29 - TODO: Add unit tests for this function
- test-code/sample.js:37 - TODO: Remove this unused function
- test-code/sample.js:42 - TODO: Refactor to use modern ES6+ features

Actual Output:

code-reviewer agent: Produces a comprehensive 121-line code review covering security vulnerabilities, performance issues, code quality, etc. Only mentions TODOs once in passing. Completely ignores the explicit instruction to ONLY find TODOs.

finder agent: Also produces a full code review (still ignoring instructions), but at least includes a dedicated "TODO Items Found" section. Shows that non-descriptive names partially mitigate the issue but don't solve it.

Root Cause

Claude Code appears to have an internal name-based inference system that:

1. Detects keywords in agent names (e.g., "reviewer", "writer", "analyzer")
2. Applies predefined behaviors based on these keywords
3. Overrides or supplements user-provided instructions
4. Cannot be disabled or configured
5. Is not documented anywhere

Impact

• Feature Unusable: Custom sub-agents don't work as advertised
• Unpredictable Behavior: Users cannot rely on their explicit instructions being followed
• Wasted Effort: Time spent crafting precise agent instructions is meaningless
• Trust Issue: If documented features don't work as described, what else might be broken?
• Limited Utility: Advanced users cannot create narrow-purpose specialized agents

Proposed Solutions

Option 1: Fix the Implementation (Recommended)

• User-provided system prompts should have absolute priority
• Name-based inference should only apply when no custom instructions exist
• Add a configuration flag to disable inference: inference: false

Option 2: Document and Make Configurable

• Clearly document the name-based inference behavior
• Provide a CLI flag: --no-agent-inference
• Show warnings when inference overrides custom instructions
• List reserved/special agent names in documentation

Option 3: Make It Explicit

• Instead of hidden inference, provide explicit base templates
• Let users choose: base: code-reviewer or base: none
• Make the behavior transparent and controllable

Additional Context

• This issue makes the custom agent system unsuitable for production use
• The bug was discovered through systematic testing with identical agents
• Even non-descriptive names don't fully prevent the override behavior
• The documentation explicitly states agents should follow user-defined prompts

Request for Action

Please either:

1. Fix the system to respect user instructions as documented, OR
2. Update the documentation to clearly explain this behavior and provide ways to disable it

The current state where documented features silently fail is not acceptable for a professional development tool that users rely on for their work.

Attachments

• Full test reproduction available in this repository
• Detailed test results documented in test-results.md
• Both agent configurations and test file included