跪拜 Guibai
← All articles
AI Programming · Claude

Turn Specs into Sub-Agent Tasks Without Guessing: The AI-SDLC Design Phase

By ZzT ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

As AI coding agents move from single-prompt assistance to parallel multi-agent execution, teams need a rigorous handoff so sub-agents don't re-derive context or guess. This design-phase process shows a concrete, tool-agnostic pattern (with Claude Code and Codex specifics) for making parallel agent development deterministic and reviewable by humans.

Summary

In the fourth post of the AI-SDLC series, the author details how the design phase takes the spec, decision record, and fixed code baseline from requirements, and produces a technical plan plus a task breakdown that drives parallel development by multiple sub-agents. The core principle: sub-agents see only their assigned task, with no design-phase conversation or sibling tasks, so the design must be complete enough that development needs no guessing.

The post explains the seven required deliverables, a fixed template for per-module technical design documents with five content parts and four Mermaid diagrams, and an acceptance mapping table ensuring each spec criterion maps to a design part and a test. It also addresses how to stop agents from pulling in out-of-scope features, breaking tasks by observable business behavior rather than by platform or layer, and writing machine-readable YAML task blocks with read refs, write scope, done-when conditions, and verify commands. A notable change: the author removed a slow in-phase review loop, now generating the plan once and having a human judge it, while the CLI only checks structural order (duplicate IDs, missing dependencies, cycles).

The article also covers handling incomplete materials by pausing affected tasks, distinguishing what must exist before coding from what only arrives after, and the single confirmation step where the developer authorizes the task-graph scope, isolated working copy, and local checks.

Takeaways
— The design phase accepts spec, decision record, and a fixed code baseline, and delivers seven files: implementation plan, decision record, technical design document, test intent, tasks.md, task graph, and handoff file.
— Architectural questions go to a human only for six types: business-result changes, architectural boundaries, repository scope, compatibility strategy, risk acceptance, and external system writes.
— Out-of-scope agent suggestions are paused and recorded as 'out-of-scope candidates' until the developer decides, never entering the plan or tasks without explicit confirmation.
— The technical design document uses a fixed five-part template and four Mermaid diagrams; diagrams must be grounded in existing code or confirmed design, and an acceptance mapping table must list every spec criterion with a design part and test.
— The plan is generated once (oneshot); no independent review or multi-round self-review occurs inside the phase, avoiding slow loops. A checklist only fixes mechanical issues, not plan quality.
— Tasks are broken down by observable business behavior, not by platform or layer, so each task can be independently verified; task descriptions must be specific enough to judge 'done'.
— Each task includes a YAML block with id, title, repository, depends_on, owner, read_refs, write_scope, create_scope, done_when, verify, and case_ids, because sub-agents have no design-phase context.
— Claude Code sub-agents start in independent contexts (unless forked); Codex v1 multi-agent has fork_context off by default, while v2 requires explicit fork_turns: none to avoid inheriting parent history.
— The task graph is compiled from tasks.md by the CLI, which only errors on duplicate IDs, nonexistent dependencies, or cycles; overlapping write scopes only warn and serialize.
— Missing materials are tracked in a gap list; affected tasks pause, unaffected ones proceed, and the plan and diagrams are written anyway with test intents and a materials request
— One confirmation covers the plan and development scope; the developer must explicitly list the allowed write scope, and external writes like interface sync or remote Mock creation require separate authorization.
Conclusions

Removing the in-phase review loop and trusting a single human review reflects a pragmatic trade-off: agent self-review loops are far more expensive in time than a one-shot generation that may be imperfect, and human feedback becomes the training signal for the next generation.

The emphasis on 'no guessing' makes explicit that context isolation for sub-agents is the fundamental constraint; every drafting choice, from YAML blocks to read_refs, exists to compensate for the sub-agent's lack of parent conversation.

Breaking tasks by business behavior instead of by platform or layer is a generalizable principle: verification capability, not code structure, should drive task boundaries, even when that means accepting larger tasks for joint validation.

The distinction between missing materials that block coding and those only obtainable after code exists (real-device effects, live redirects) prevents needless pauses and keeps the design phase moving without waiting on external teams.

Concepts & terms
One-shot generation
A process where the AI agent generates the technical plan exactly once, without independent review agents or multiple self-revision rounds; a human reviews the single output, and feedback is saved to improve future one-shot generations rather than revising the current one.
Task graph
A compiled representation of the tasks.md file, where nodes are tasks and edges are dependencies. The CLI checks only structural validity (duplicate IDs, missing dependencies, cycles) and does not judge semantics; the development phase schedules tasks by dependency, write-scope overlap, and a concurrency limit.
Out-of-scope candidate
An item the agent proposes during design that is not in the current requirement (e.g., future capability, generic base class, refactor). It is recorded as a candidate without entering the plan or tasks, and waits for the developer's separate confirmation.
From the discussion
Featured comments
智测星球

The plan is generated only once, and I haven't seen this pitfall covered in your repository. If the testing intent isn't written into the task description, will the sub-agent still be able to see that acceptance criterion when it starts work?

See top comments, translated →
Source: juejin.cn ↗ Google Translate ↗ Backup ↗