Chapter 6: Scaling the Workflow: Phases, Parallelism, Hygiene
Series: LLM Development Guide
Chapter 6 of 15
Previous: Chapter 5: The Execution Loop: Review Discipline + Commit Discipline
Next: Chapter 7: Choosing the Right Model: Capability Tiers, Not Hype
What you’ll be able to do
You’ll be able to take the same workflow and scale it up without chaos:
- Split work into phases that do not overlap on files.
- Run parallel sessions or agents safely.
- Decide when artifacts stay local vs. get committed.
TL;DR
- Scale by splitting phases, not by writing bigger prompts.
- Keep phase files small (rule of thumb: under ~200 lines).
- Parallel work requires clean boundaries and explicit interfaces.
- Decide up front whether
plan/,prompts/,work-notes/live in git.
Table of contents
When to sub-phase
Sub-phase when:
- A phase touches too many files.
- The phase cannot be verified independently.
- The phase depends on decisions that are not written down.
Example layout:
plan/
phase-1a-analysis.md
phase-1b-design.md
phase-2a-scaffold.md
phase-2b-core-impl.md
phase-3-validation.md
Keep each phase “one session friendly”: small enough to complete (or at least checkpoint) in 1 to 2 sessions.
Parallel execution requirements
Parallel work is possible, but only if you make boundaries explicit.
Requirements:
- No overlapping files between parallel phases.
- Explicit interfaces (types, APIs, data shapes) written down.
- A merge plan (who rebases, who resolves conflicts, how often you sync).
A simple pattern:
- Phase A defines interfaces and contracts.
- Phase B implements with those interfaces.
- Phase C adds tests and validation.
Repository hygiene
Decide whether artifacts are local scaffolding or part of the repo.
Common default:
- Keep
plan/,prompts/,work-notes/local (gitignored).
Commit them deliberately when they become:
- Long-lived docs.
- Reusable templates.
- Onboarding material.
If you commit them, consider moving to docs/ and editing for humans.
Verification
These checks help you catch “phases are too big” early:
# Find phase files that are getting too large.
# (This uses line count as a blunt proxy.)
find plan -type f -name '*.md' -maxdepth 2 -print0 | xargs -0 wc -l | sort -n
# Find prompts that do not reference work notes.
rg -n "work-notes/" prompts || true
# Find phases that might overlap on files (manual review).
# Start by listing deliverables per phase in each prompt doc.
rg -n "^## Deliverables" -n prompts
Gotchas
- Parallelization without clean boundaries just creates merge conflicts faster.
- If you don’t define interfaces early, later phases stall.
- If artifacts are committed, treat them like code: review, version, maintain.
Continue -> Chapter 7: Choosing the Right Model: Capability Tiers, Not Hype