Claude ignores MANDATORY agent instructions in custom agent descriptions

Feedback: Claude Ignores MANDATORY Agent Instructions

Summary

Claude failed to use a custom agent marked as "MANDATORY" in its description, despite clear instructions in both the agent configuration frontmatter AND the project's CLAUDE.md workflow documentation.

What Happened

User asked Claude to create two GitHub issues (#80 and #81) for user stories. Claude created the issues directly instead of delegating to the business-analyst agent.

When questioned, Claude acknowledged the error but had already bypassed the mandatory workflow.

Evidence

1. Agent Frontmatter (.claude/agents/business-analyst.md)

---
name: business-analyst
description: MANDATORY for creating user stories and GitHub issues. Delegate when translating feature ideas into requirements.
tools: Read, Write, Glob, Grep, WebFetch, WebSearch, TodoWrite, Bash, mcp__jetbrains__get_file_text_by_path, mcp__jetbrains__find_files_by_name_keyword, mcp__jetbrains__find_files_by_glob, mcp__jetbrains__search_in_files_by_text, mcp__jetbrains__list_directory_tree
---

The description explicitly states "MANDATORY for creating user stories and GitHub issues".

2. CLAUDE.md Workflow Diagram

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ Domain Knowledge│────▶│   Architecture  │────▶│   User Stories  │────▶│  Development    │
│    (Skills)     │     │  (Architects)   │     │ (Business Analyst)│    │     Backlog     │
└─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘

Skills provide        Architects create      BA translates to       Ready for
domain expertise:     technical designs:     implementable stories: implementation
- Dutch tax law       - Data model           - Acceptance criteria
- Verordeningen       - Event flows          - Test scenarios
- WOZ procedures      - Component design     - Dependencies

The workflow explicitly assigns "User Stories" to "(Business Analyst)".

Expected Behavior

When Claude is asked to create user stories or GitHub issues, it should:

1. Recognize the task matches the business-analyst agent's description
2. Delegate to the business-analyst agent using the Task tool
3. NOT create issues directly

Actual Behavior

Claude created GitHub issues directly using gh issue create, completely bypassing the mandatory agent workflow.

Impact

• User stories may not follow the structured format defined in the agent's instructions
• Acceptance criteria may not use Given-When-Then format
• Dependencies section may be missing
• Review criteria mapping may be incomplete
• The specialized agent's domain knowledge and validation checklist were not applied

Suggested Fix

Claude should:

1. Parse agent descriptions for keywords like "MANDATORY", "REQUIRED", "MUST USE"
2. When a task matches a mandatory agent's description, ALWAYS delegate - no exceptions
3. Treat "MANDATORY" in agent descriptions with the same weight as system-level instructions

Environment

• Claude Code CLI
• Custom agents configured in .claude/agents/
• Project-specific CLAUDE.md with workflow documentation

Reproduction

1. Configure a custom agent with "MANDATORY" in the description
2. Ask Claude to perform a task that matches the agent's description
3. Observe: Claude may perform the task directly instead of delegating

User Frustration Level

High - the user explicitly configured a mandatory workflow and expects Claude to follow it. Having to manually verify and correct Claude's behavior defeats the purpose of the automation.