Impact01Approach02Case Studies03Work Together04Insights05About Me06Let's talk →
Insights · Part 4 of 10

Architectural System Design

Translating refined product requirements into technical architecture, explicit API contracts, and database schemas before writing code.

12 August 2026

01

The Gap Without Upfront System Design

Once requirements are defined, the temptation is to immediately prompt an execution agent to "build the backend API" or "create the UI components." But jumping directly from product requirements to implementation code introduces architectural entropy.

Without an explicit, upfront system design phase, four structural failures reliably occur:

  1. Component Coupling & Boundaries Drift. Developers (and AI agents) write monoliths or misplaced abstractions because module boundaries were never formally drawn.
  2. Ambiguous API Contracts. Frontend and backend development get blocked or desynchronized because request payloads, error codes, and endpoints are decided on the fly.
  3. Database & Schema Drift. Data models are created incrementally per feature, leading to redundant fields, missing indexes, and unnormalized relational tables.
  4. Ignored Non-Functional Requirements. Latency targets, security guards, caching strategies, and rate limits are treated as afterthoughts rather than core architectural constraints.

Code is cheap to regenerate, but a broken architectural foundation propagates technical debt across every downstream file. System Design creates the immutable blueprint that keeps concurrent execution agents aligned.

Rule of Thumb

Never let AI write implementation code without a written architecture plan. If backend and frontend contracts are not formally specified in plan.md, expect integration bugs during merge.

02

The Skill: /sprint-plan

In the sprint-workflow operating system, after product requirements are finalized in brainstorm.md, we invoke the system design phase:

/sprint-plan <N>

Where <N> is the sprint iteration or slug (e.g., /sprint-plan 04 or /sprint-plan user-auth-v2).

Executing /sprint-plan initiates a structured system architecture session:

  • Input Consumption: Ingests .sprint/<slug>/docs/brainstorm.md and workspace patterns (existing schemas, API style guides, dependency manifests).
  • System Architecture Drafting: Defines high-level component diagrams, data flows, and subsystem boundaries.
  • Contract Specification: Formulates explicit REST/gRPC API endpoints, TypeScript interfaces, and database migrations.
  • Artefact Generation: Writes the completed blueprint to .sprint/<slug>/docs/plan.md and updates sprint-manifest.json.

Unlock the Full Article

This article covers the full walkthrough, model choice, and pitfalls. Please connect to find out more.

Next ArticleStories & Tasks Breakdown