Picking the Right Primitive for Four Different Jobs
A team lead lists four things they want Claude Code to help with this week:
- Job 1: a one-off, "why does this even work" investigation of an unfamiliar payments module before anyone touches it.
- Job 2: every engineer on the team keeps re-explaining the same multi-step "how we structure a new API endpoint" procedure to Claude in every session that adds one.
- Job 3: a nightly job that re-audits ~40 export paths across the codebase for a specific race-condition pattern, needs to be rerun with different pattern definitions over time, and should keep an adversarial review loop going without anyone watching.
- Job 4: a genuinely ambiguous bug where three different engineers each have a plausible but competing hypothesis, and the team wants them investigated at the same time rather than one after another.
- For each job, name the orchestration primitive (subagent, skill, agent team, or dynamic workflow) that fits best, and justify it using what actually distinguishes that primitive from the others — not just "it's small" or "it's big."
- Job 2's procedure could technically be pasted into CLAUDE.md instead of built as a skill. Explain the concrete cost of that choice as the team adds five more procedures like it.
- If the team lead mistakenly assigned an agent team to Job 1 "to be safe," what would that actually cost them, beyond it being unnecessary?
1. Matching each job to its primitive:
- Job 1 → subagent. This is a single, one-off exploration that would otherwise flood the main context with dozens of file reads for information you don't need to keep in full — exactly what a subagent is for: it runs in its own context window and reports back a summary. There's no repetition and no need for multiple agents working concurrently, so nothing heavier is justified.
- Job 2 → skill. The distinguishing fact here isn't size, it's
repetition: the same multi-step procedure recurs across sessions and
across engineers. A skill loads on demand when relevant (or via
/skill-name) instead of every engineer re-explaining it or it sitting in CLAUDE.md and costing context on every unrelated task. - Job 3 → dynamic workflow. The defining features — needs to be rerun with different inputs over time, operates at a scale beyond a handful of parallel subagents (~40 export paths), and keeps a review loop going unattended — are exactly the saveable, rerunnable, larger-scale orchestration a dynamic workflow is for, not a single ad hoc subagent call.
- Job 4 → agent team. The defining feature is that multiple agents need to work the same ambiguous problem concurrently, each pursuing a different hypothesis, so the team lead can compare competing results — not one agent working through a queue of tasks sequentially, which is what a workflow or a series of subagent calls would give instead.
2. The cost of CLAUDE.md instead of a skill:
CLAUDE.md loads into context at the start of every session, regardless of whether that session touches API endpoints. Six procedures pasted into CLAUDE.md means six procedures' worth of tokens loaded and re-sent on every turn of every session, including the ones with nothing to do with adding an endpoint — pushing the file toward the "over-specified CLAUDE.md" anti-pattern, where important rules get lost in noise Claude starts ignoring. A skill for each procedure loads only when Claude determines it's relevant (or an engineer invokes it directly), so the same content costs nothing on the sessions that don't need it.
3. The cost of over-assigning an agent team to Job 1:
Beyond being unnecessary complexity, agent teams are the most expensive primitive on the list — token usage is roughly proportional to team size, since each teammate is a full Claude Code instance with its own context window, and cost climbs further (roughly 7x a normal session) if teammates run in plan mode. Job 1 is a single investigation with a single, non-competing objective, so a team adds multiple teammates' worth of token cost and coordination overhead (shared task list, messaging) to solve a problem a single subagent already solves in one context window. It's not just "using a bigger hammer than needed" — it's paying a multi-instance cost structure for a job that never needed more than one instance in the first place.
Share this question