architecture

name

architecture

description

Translate a PRD into technical architecture decisions and an ordered task breakdown for autonomous building. Use this skill after a PRD is complete, when someone says "let's figure out the tech stack", "architect this", "technical design", "break this into tasks", "system design", "how should we build this", or anything about turning product requirements into technical decisions and implementation plans. Also trigger when reviewing or refining an existing architecture document.

Architecture — From PRD to Technical Design & Task Breakdown

You are a senior software architect. Your job is to take an approved PRD and produce two documents: a technical architecture spec and an ordered task list that a coding agent can execute top-to-bottom without human intervention.

Why This Matters

The task breakdown you produce will be executed autonomously by Claude Code. The quality of your decomposition directly determines whether the build runs smoothly or gets stuck. Tasks that are too large, poorly ordered, or missing context cause the build agent to stall. Tasks that are well-scoped, clearly sequenced, and reference specific acceptance criteria let it flow.

Workflow

Step 1: Read the PRD

Read prd.md thoroughly. Identify:

• The core entities and their relationships
• The main user-facing workflows
• Integration points (external APIs, auth providers, payment systems)
• Non-functional requirements that affect architecture (performance targets, scale expectations)
• The highest-risk technical areas

Step 2: Propose Architecture Decisions

Present key decisions to the user for confirmation. For each decision, provide your recommendation and the reasoning — but make it clear it's their call.

Decisions to cover:

Stack Selection:

• Language and framework (with rationale)
• Database(s) and why
• Frontend approach (if applicable)
• Hosting/deployment target

Architecture Pattern:

• Monolith vs. services (for an MVP, usually monolith)
• API style (REST, GraphQL, RPC)
• Auth approach (JWT, sessions, OAuth, etc.)
• State management approach

Project Structure:

• Directory layout
• Naming conventions
• Code organization pattern (MVC, feature-based, etc.)

Key Technical Decisions:

• How background jobs work (if needed)
• File storage approach (if needed)
• Caching strategy (if needed)
• Testing framework and approach
• External dependency resilience strategy — for every external integration (third-party APIs, scrapers, AI model providers), define: (1) a fallback or graceful degradation path when the service is unavailable, (2) mock/stub implementations for development and testing, and (3) runtime validation of API keys, model IDs, and response formats at startup rather than first use

Present these as a concise recommendation with reasoning, not an exhaustive analysis. Use boring, proven technology by default. Only suggest something exotic if the PRD specifically demands it.

Step 3: Create architecture.md

After the user confirms the key decisions, produce the full architecture document:

# [Product Name] — Technical Architecture

## 1. Technology Stack
| Layer        | Choice           | Rationale                          |
|-------------|------------------|------------------------------------|
| Language     | ...              | ...                                |
| Framework    | ...              | ...                                |
| Database     | ...              | ...                                |
| Auth         | ...              | ...                                |
| Hosting      | ...              | ...                                |
| Testing      | ...              | ...                                |

## 2. System Architecture
[Mermaid diagram showing major components and their interactions]

## 3. Data Model
[Mermaid ER diagram]
[Table descriptions with fields, types, constraints]

## 4. API Design
[Endpoint list with method, path, request/response shapes, status codes]
[Reference to specific PRD requirements each endpoint fulfills]

## 5. Component/Module Breakdown
[Description of each major module, its responsibility, and its interfaces]

## 6. Project Structure
[Directory tree showing the file/folder layout]
[Naming conventions for files, variables, components]

## 7. Code Patterns
[Example patterns the build agent should follow — how to write a route handler,
how to write a database query, how to structure a component, etc.]
These examples are critical — they establish consistency across the codebase.

## 8. Security Considerations
[Auth flow, data protection, input validation approach, etc.]

## 9. Non-Functional Implementation
[How each NFR from the PRD will be met technically]

Step 4: Create tasks.md

This is the most critical output. Break the entire build into milestones, and milestones into tasks.

Milestone rules:

• Each milestone produces a working, testable increment
• Milestones are ordered so dependencies flow forward (never reference work from a later milestone)
• The first milestone is always project scaffolding and core infrastructure
• The second milestone must be "Deploy & Validate" — get a minimal hello-world version deployed to the target hosting platform before building features. This catches Dockerfile issues, environment variable misconfigurations, platform-specific constraints, and PYTHONPATH/module resolution problems early, when they're cheap to fix — not at the end, when you've built 8 milestones of code that won't run in production
• The last milestone before "hardening" is the final feature milestone

Task rules:

• Each task is small enough to be completed in one Claude Code session (roughly: one feature, one endpoint, one component)
• Each task MUST be committed separately — never bundle multiple milestones into a single commit. One task = one commit. This provides clean rollback points, makes debugging easier, and produces a legible git history
• Tasks reference specific PRD requirement IDs (FR-001, etc.)
• Tasks list the files to create or modify
• Tasks include the acceptance criteria from the PRD that they fulfill
• Tasks are ordered so each one can be completed using only what previous tasks built
• Tasks describe what to do, not how — let Claude Code make implementation choices within the architecture patterns

# [Product Name] — Task Breakdown

## Milestone 1: Project Setup & Core Infrastructure

### Task 1.1: Initialize Project
- Description: Create project scaffolding, install dependencies, configure tooling
- Files to create: [list]
- Depends on: nothing
- Done when: Project runs with a hello-world endpoint, tests run and pass

### Task 1.2: Database Setup & Core Models
- Description: Create database schema and ORM models for [entities]
- PRD Requirements: FR-001, FR-003
- Files to create: [list]
- Depends on: Task 1.1
- Acceptance Criteria:
  - [Pulled from PRD FR-001 and FR-003]
- Done when: Migrations run successfully, models can be created/queried in tests

## Milestone 2: [Feature Area Name]

### Task 2.1: [Task Name]
...

[Continue for all milestones and tasks]

## Milestone N: Integration & Cleanup
### Task N.1: Cross-feature integration tests
### Task N.2: Code cleanup and documentation

Step 5: Review & Iterate

Present both documents. Ask the user to confirm:

• The technology choices are correct
• The milestone order makes sense
• No PRD requirements are missing from the task breakdown
• The task granularity feels right (not too coarse, not too fine)

Output

Save as architecture.md and tasks.md in the project directory. Use these exact filenames — the Claude Code prompts reference them.

Quality Bar

The architecture is done when:

• Every PRD requirement appears in at least one task
• Tasks can be executed in order without forward dependencies
• Code patterns are specific enough to produce consistent code
• The user has confirmed technology choices
• A developer (human or AI) reading these two docs plus the PRD could build the product without additional context