Prompting for Architecture: Building Full-Stack Systems with Claude

Generating a function with AI is a solved problem. Generating a system is not. The difference is memory: a model will write you a flawless controller and, three prompts later, invent a second data shape that contradicts the first — because it never held the whole architecture, only the last few thousand tokens of it. Building enterprise software with Claude is not a prompting skill. It is a context engineering discipline, and it has two pillars: Shadow Documentation and strict contextual boundaries.

The real failure mode: context collapse

Every serious AI build dies the same way. Early prompts are crisp and the output is excellent. As the system grows, the model's working picture of it drifts — naming conventions wander, the schema mutates, the same concern gets implemented twice in two incompatible ways. This is not a model weakness; it is an architecture-of-context weakness. You are asking a stateless system to maintain a stateful invariant. The fix is to make the architecture itself the context.

Shadow Documentation

Shadow Documentation is a living, machine-readable specification of your system that you maintain alongside the code and feed into every significant prompt. Not prose for humans — a dense, current statement of the contracts, the boundaries, and the decisions already made. It is the memory the model does not have.

# Contracts (authoritative)
CaseRecord: { id, statuteRefs[], timeline[], verdict? }
Verdict: { decision: "guilty" | "not_guilty", citations[] }

# Boundaries
- retrieval lives in /agent; never in /api controllers
- all LLM output validated by zod before persistence

# Decisions
- Mongo over Postgres: document-shaped case data
- one Zustand store owns render state; DB stores records only

What goes in the shadow docs

Three things, ruthlessly current: the contracts (the canonical data shapes every layer must honor), the boundaries (what lives where, and what is forbidden from crossing), and the decisions (the choices already made, so the model stops relitigating them). When the spec and the code disagree, the spec is the bug report.

Contextual boundaries: one layer per prompt

The second pillar is scope discipline. A prompt that asks for "the feature" invites the model to improvise across three layers at once, which is exactly where contradictions are born. Scope every prompt to a single layer and a single contract: generate the Mongoose model for this schema; now the controller that satisfies this contract; now the React hook that consumes that endpoint. Each prompt inherits the shadow docs and touches one seam. The architect holds the system; the model fills one cell of it at a time.

Prompts as specifications

Treat prompts the way you treat infrastructure: versioned, precise, and reviewed. An ambiguous prompt is an ambiguous requirement that merely fails faster. The prompts that built streamerOS read like architecture tickets — a contract, a constraint, an acceptance check — not like a conversation. That is the whole trick: you are not chatting with a coder, you are issuing specifications to a build system that happens to understand English.

AI does not replace the architect. It removes every excuse the architect ever had for an unclear specification.

The complete workflow — shadow docs, prompt structure, and the review loop behind a production system — is detailed in the streamerOS breakdown.