Spec-Driven Delegation

• Entity ID: ent-20260410-156856275f20
• Type: pattern
• Scope: shared
• Status: active

Description

Spec-driven delegation is the principle that agent prompts must be self-contained briefings containing exact files, expected signatures, and output formats rather than vague directives. In the Claude Code source, the coordinator system prompt (in coordinatorMode.ts) and the agent prompt module (tools/AgentTool/prompt.ts) enforce this at the prompt-engineering level: the coordinator is told to "synthesize findings into a specific prompt" and to "never write 'based on your findings, fix the bug'" because such phrases delegate understanding to the worker instead of doing it.

The pattern manifests across three layers. First, the coordinator prompt in coordinatorMode.ts provides explicit anti-patterns (lazy delegation examples like "fix the bug we discussed") alongside good examples that include file paths, line numbers, and the exact behavioral change required. Second, the fork-subagent prompt in forkSubagent.ts enforces a rigid output contract on forked children: output must begin with "Scope:", followed by "Result:", "Key files:", "Files changed:", and "Issues:" sections. Third, agent definitions in loadAgentsDir.ts structurally constrain each agent type with tools, disallowedTools, permissionMode, and omitClaudeMd fields, ensuring the delegation boundary is enforced at the tool-access level, not just by prompt wording.

The anti-pattern this addresses is the "handle the frontend" class of vague delegation. Without spec-driven prompts, an agent with full tool access might rewrite routing, refactor components, or add unwanted libraries. Claude Code's architecture prevents this through both prompt guidance ("Brief the agent like a smart colleague who just walked into the room") and structural constraints (read-only agents literally lack the Edit and Write tools).

Key claims

• clm-20260410-a1: The coordinator prompt explicitly bans lazy delegation phrases like "based on your findings, implement the fix" and "fix the bug we discussed", requiring the coordinator to synthesize research before prompting workers. Evidence: coordinatorMode.ts Section 5 "Writing Worker Prompts" -- "Never write 'based on your findings' or 'based on the research.' These phrases delegate understanding to the worker instead of doing it yourself."
• clm-20260410-a2: Fork children receive a strict output contract requiring structured sections (Scope, Result, Key files, Files changed, Issues) and a 500-word limit, preventing scope creep in delegated work. Evidence: forkSubagent.ts buildChildMessage() function specifies "Output format (plain text labels, not markdown headers): Scope / Result / Key files / Files changed / Issues."
• clm-20260410-a3: Agent definitions enforce delegation boundaries structurally through disallowedTools arrays -- read-only agents (Explore, Plan, verification) are denied FILE_EDIT_TOOL_NAME and FILE_WRITE_TOOL_NAME, making file modification impossible regardless of prompt instructions. Evidence: exploreAgent.ts, planAgent.ts, verificationAgent.ts all include disallowedTools: [AGENT_TOOL_NAME, FILE_EDIT_TOOL_NAME, FILE_WRITE_TOOL_NAME, NOTEBOOK_EDIT_TOOL_NAME].
• clm-20260410-a4: The prompt module distinguishes between fresh-agent prompts (which need full context because "it starts with zero context") and fork directives (which are short because the fork "inherits your full conversation context"), teaching callers to calibrate specification depth to the delegation target. Evidence: prompt.ts writingThePromptSection -- "Brief the agent like a smart colleague who just walked into the room" for fresh agents vs. "the prompt is a directive -- what to do, not what the situation is" for forks.

Relations

• rel-20260410-b1: ent-20260410-156856275f20 --[implemented_by]--> coordinatorMode.ts (getCoordinatorSystemPrompt)
• rel-20260410-b2: ent-20260410-156856275f20 --[implemented_by]--> tools/AgentTool/prompt.ts (writingThePromptSection)
• rel-20260410-b3: ent-20260410-156856275f20 --[implemented_by]--> tools/AgentTool/forkSubagent.ts (buildChildMessage)
• rel-20260410-b4: ent-20260410-156856275f20 --[enforced_by]--> tools/AgentTool/loadAgentsDir.ts (disallowedTools field)

Sources

src-20260410-spec-delegation-a: src/coordinator/coordinatorMode.ts, src/tools/AgentTool/prompt.ts, src/tools/AgentTool/forkSubagent.ts, src/tools/AgentTool/loadAgentsDir.ts