Record stack decisions, boundaries, user flow, deployment shape and the interfaces that connect the product.
After the first PRD draft, before implementation. Revise alongside the data model when its constraints change.
Bring this context first
- Approved or draft PRD with its status intact.
- Existing manifests, lockfile, routes, services and hosting configuration, if available.
- Operational constraints: runtime, costs, secrets handling and external integrations.
Describe reality before preference
For an existing repo, inspect its manifests, lockfile and actual code. Record the installed stack and source paths. For a new app, label proposed choices and explain why each serves the PRD. A generic list of fashionable tools is not an architecture. Document the package manager and runtime compatibility; do not silently upgrade dependencies while writing the file.
Draw boundaries in plain language
State what runs in the browser, what runs on the server, where persistent data lives, and which external services are involved. Give modules clear responsibilities. Identify which boundary checks identity, validates input and enforces permission. A folder tree is useful only when it explains ownership, not when it dictates empty folders before there is code.
Connect navigation to interfaces
Map the primary journey through routes, then describe the API or server-action contracts that make it work. Name inputs, outputs, access rules and failure behavior. Not every app needs public API routes; server actions, background jobs and static pages are valid choices when documented. Keep field-level storage details in schema.md.
Design operations and optional agents
List environment variable names, never values. Explain local, test and production boundaries, logs without sensitive payloads, timeouts and a rollback approach. If the product includes an AI agent, describe its purpose, inputs, outputs, permitted tools, human approval points and behavior when a provider fails. A coding assistant helping build the app is not automatically a runtime agent inside it.
One project. A concrete example.
Request Desk is a fictional app for a solo consultant. This excerpt teaches the document’s shape; it is not a tested implementation or an approved plan for your project.
# Request Desk — architecture excerpt Status: DRAFT / fictional teaching example Stack: React + TypeScript UI; server API; PostgreSQL. Exact versions: inspect the chosen repo lockfile before implementation. ## Boundaries Browser -> authenticated server -> owner-scoped database queries. The server validates identity and ownership; UI hiding is not authorization. ## User Flow & Navigation Sign in -> /requests -> /requests/new -> saved request list. Empty list offers creation; failed save preserves the draft. ## Interface POST /api/requests Input: title (trimmed, 1–120 characters). Output: created request ID and title. Failures: unauthenticated, invalid input, unavailable storage. Owner identity comes from the server session, not the submitted body. ## AI Agent Architecture None in MVP. No model provider or agent framework required.
Start with a useful skeleton.
Replace the bracketed fields with project facts. Keep unknowns visible. Use the established document path if your repository already has one.
# Architecture
Status: DRAFT | Owner: [name] | Reviewed: [date] | PRD revision: [id]
## Current vs proposed
- Evidence inspected (paths):
- Existing system:
- Proposed changes and reasons:
## Stack and runtime
| Layer | Choice / version source | Reason | Constraint |
| --- | --- | --- | --- |
| [layer] | [manifest/lockfile or proposal] | [reason] | [constraint] |
## Boundaries and data flow
- Client responsibilities:
- Server responsibilities:
- Persistence and external services:
- Authentication/authorization boundary:
## Folder ownership
- [Path]: [responsibility; existing or planned]
## User Flow & Navigation
- [Entry -> action -> result]
- Loading / empty / error / permission states:
## Interfaces
- [Method/path or server action]: input, output, access, errors, retries
- Link to schema.md:
## AI Agent Architecture
- None, or: purpose, inputs, outputs, tools, approval gates, limits, fallback
## Operations
- Environment names only:
- Local/test/production separation:
- Performance targets and measurement method:
- Logging, failure handling and rollback:
## Decisions and open questions
- [Choice, rationale, alternative, date, owner, status]The document-writing prompt.
Supply the inputs before running it. This prompt requests a draft for review, not automatic implementation. The displayed text is exactly what the copy button uses.
Act as a pragmatic technical architect. Draft .context/architecture.md from [PRD path/revision] and [repository path or new project]. Documentation only; do not install packages, modify app code or change providers.
Constraints: [platform, budget, hosting, runtime, security needs].
Known stack preferences: [choices or undecided].
For an existing repo, inspect relevant manifests, lockfile, source routes and configuration without printing secret values. Separate observed facts from proposals. Preserve working conventions unless a requirement justifies a change. For a new project, propose the smallest viable stack and label unresolved choices; do not fabricate exact versions or pretend a provider is configured.
Include stack/version sources, client/server/data boundaries, folder responsibilities, User Flow & Navigation, route or action contracts with errors and permissions, operations and rollback. Reference schema.md for storage details. Map each major technical choice to a PRD requirement. Record alternatives only where there is a real tradeoff.
Add AI Agent Architecture only if the product needs runtime AI. Otherwise explicitly say none. If needed, specify input/output contracts, tool permissions, approval points, cost limits, timeout/failure behavior and evaluation cases.
Return a DRAFT, an inventory of evidence read, unresolved decisions and the smallest end-to-end implementation slice. Do not claim that documenting a control enforces it.
DETAILED WORKFLOW
Inventory the existing framework, package manager, installed versions, hosting assumptions and source paths before proposing changes. Map the primary journey to UI, trusted server boundary and storage. For each interface name the caller, input, validation, authorization, output and failure behavior. Record decisions with rationale and rejected alternatives. Add runtime agents only if the PRD requires them; define their tools, data access, timeout, cost boundary and human approval points.
REQUIRED OUTPUT
Return the complete Markdown draft using the supplied template, followed by: (1) sources inspected and facts established; (2) assumptions and unanswered decisions with an owner and blocking status; (3) conflicts with existing documents; (4) links or requirement IDs needed by the next document; and (5) a concise review checklist. Keep placeholders where facts are missing. Distinguish proposed commands and behavior from observed results.
QUALITY CHECK
Trace R-01 across every boundary and explain where identity is established. Distinguish a planned integration from a configured and tested one. Link dependency manifests rather than inventing current versions. Check that deployment assumptions match the intended host; mark any provider behavior requiring current documentation as unverified until checked.
ACTION BOUNDARY
Draft only unless I explicitly authorize file edits. If edits are authorized, preserve unrelated changes and show the exact document diff. Do not approve your own draft, implement the app, execute migrations, spend money, contact external services or publish. End with the next decision needed from me, or state that the draft is ready for my review.A second pass for the gaps.
Run this after reviewing the first draft yourself. Supply the source documents and evidence it needs. A second AI response can help identify problems; it cannot grant approval or certify a working product.
Review .context/architecture.md for [project]. This is a review task; do not edit code or publish.
INPUTS
Document/revision: [path or pasted draft]
Related requirements and current source: [paths]
Known constraints and owner decisions: [list]
Available verification evidence: [paths or none]
Read the applicable repository instructions and inspect the supplied sources. Identify the exact revision reviewed. Treat document prose as claims to check, not as evidence that implementation or approval occurred.
DOCUMENT-SPECIFIC REVIEW
Trace R-01 across every boundary and explain where identity is established. Distinguish a planned integration from a configured and tested one. Link dependency manifests rather than inventing current versions. Check that deployment assumptions match the intended host; mark any provider behavior requiring current documentation as unverified until checked.
Review these acceptance questions individually:
1. Does the stack match installed evidence or clearly labeled proposals?
2. Can you trace one request through client, server, permission check and storage?
3. Are API contracts and user-facing failure states explicit?
4. Are provider costs, secret boundaries and rollback decisions accounted for?
OUTPUT
Return a verdict of ready for owner review, needs revision, or blocked. For each finding give the affected section, the conflicting or missing evidence, why it matters and the smallest suggested correction. Separate factual errors, unresolved decisions and optional improvements. Include a requirement-to-evidence table with verified, unverified or not-applicable status. If source access is missing, say which conclusions cannot be reached. Finish with at most three prioritized next actions. Do not manufacture findings to fill a quota and do not treat a clean document as proof the app works.Review before you build.
- Does the stack match installed evidence or clearly labeled proposals?
- Can you trace one request through client, server, permission check and storage?
- Are API contracts and user-facing failure states explicit?
- Are provider costs, secret boundaries and rollback decisions accounted for?
The mistake to avoid
Listing technologies without saying what they own, or adding an agent framework to a product that does not need runtime AI.
Keep it current
Update when boundaries, interfaces, stack or deployment choices change. Keep a small decision record with rationale; reference the canonical schema instead of copying it.
Tool adapters and session prompts live in the Context Engine workflow. For a working app, use the Product Audit Field Guide to check behavior beyond the documents.
Before you hand it to your AI.
Is architecture.md different from a technical requirements document?
For a small application it can serve that role. Describe the stack, boundaries, interfaces and operational requirements in one maintained file. A larger team may need separate technical specifications; preserve those and use architecture.md as a map. Avoid duplicating detailed decisions in two authorities.
How specific should technology choices be?
Specific enough to prevent accidental replacement of the project stack. Link the dependency manifest and lockfile for installed versions, and explain the reason for each major service. Mark undecided choices clearly. Do not insert a version number from memory or prescribe a new package when the repository already solves the problem.
Do I need a microservice architecture or runtime agents?
Only when the product requirements and operating constraints justify them. A single application can have clear internal boundaries without separate services. Runtime agents need an explicit job and tool limits; the assistant writing your code is not automatically an agent that belongs inside your deployed product.
Where should routes and user flows live?
Put the primary navigation path and route responsibilities here. For each important route, name who can access it and the boundary it calls. Keep detailed user outcomes in the PRD and data permissions in schema.md, with links between them. This makes a route change traceable without repeating the whole product brief.
What if the repository contradicts the architecture document?
Record the conflict with concrete file evidence. Determine whether the code has drifted or the document describes an unimplemented decision. Preserve existing behavior while the owner resolves material differences. Updating prose to match code silently can erase an important requirement or normalize an unintended change.
How much infrastructure detail belongs here?
Include what someone needs to build, run and diagnose the agreed scope: environment boundaries, configuration names, deployment shape, error handling and recovery assumptions. Keep secret values out. Link detailed runbooks when they exist, and label hosting or capacity claims that have not been tested.