architecture（架构）

Architecture

Design the technical architecture for a set of requirements: components, data flow, dependency graph, tech stack decisions, integration points, and risks.

When to Use

• A PRD exists and the technical approach needs to be designed
• Before task breakdown — architecture defines WHAT components exist; breakdown defines the ORDER to build them
• When architectural decisions need to be documented (data model, API design, component structure)
• When integration with existing systems requires explicit mapping

When NOT to use: The technical approach is already documented in an architecture.md, or the change is trivial (single file, no architectural decisions).

Input

• prd.md from the artifact folder (required)
• context-map.md from the artifact folder (required — for tech stack and existing patterns)
• brainstorming.md from the artifact folder (recommended — for chosen direction rationale)

Output

• architecture.md saved to the artifact folder (see references/formats.md for template)

The Process

Step 1: Load Upstream Artifacts

Read prd.md, context-map.md, and optionally brainstorming.md from the artifact folder. If prd.md or context-map.md is missing, tell the user which skill to run first.

Also check for project documentation listed in references/context-sources.md (docs/TechStack.md, docs/ProjectStructure.md). If available, use them for tech stack details and project structure when designing components and mapping integration points.

Extract:

• User stories and functional requirements (from PRD)
• Tech stack, patterns, and conventions (from context map)
• Chosen direction and trade-offs accepted (from brainstorming)

Step 2: Identify Components

From the PRD requirements, identify the distinct components needed:

• Data layer: schemas, models, migrations
• Backend logic: services, business rules, validation
• API layer: endpoints, routes, middleware
• Frontend components: views, forms, widgets
• Shared utilities: helpers, types, constants

For each component, define:

• Responsibility — what it does (single responsibility)
• Location — where it lives in the project (follow existing conventions from context map)
• Interface — key functions, endpoints, or props it exposes
• Dependencies — what other components it needs

Follow existing codebase patterns. If the project uses a service layer pattern, use it. If components are colocated with tests, follow that. Do not invent new patterns when existing ones work.

Step 3: Map Data Flow

Describe how data moves through the system for the key user stories:

[User Action]
  → [Frontend Component] (handles UI state)
    → [API Call] (request to backend)
      → [Route Handler] (validation, auth)
        → [Service] (business logic)
          → [Database] (persistence)
        ← [Response]
      ← [API Response]
    ← [UI Update] (re-render with new data)

Cover the primary happy path and the most important error path.

Step 4: Build Dependency Graph

Map what must be built before what. This directly feeds the task breakdown:

[Database Schema / Migrations]
    ├── [Types / Interfaces]
    │       ├── [Service Layer]
    │       │       ├── [API Endpoints]
    │       │       │       └── [Frontend API Client]
    │       │       │               └── [UI Components]
    │       │       └── [Validation Logic]
    │       └── [Test Utilities]
    └── [Seed Data]

Implementation order follows the graph bottom-up: foundations first.

Step 5: Document Tech Decisions

For every non-trivial technical choice, record:

Do not introduce new dependencies without justification. Check the existing stack first (context map).

Step 6: Map Integration Points

How does this feature connect to what already exists?

• Which existing files will be modified?
• Which existing APIs will be consumed?
• Which existing components will be extended or composed?
• Are there database schema changes that affect other features?

Step 7: Define Boundaries

State what is and isn't allowed during implementation:

• Always: [e.g. follow existing naming conventions, write tests for new logic, use existing error handling patterns]
• Ask first: [e.g. adding new dependencies, changing shared types, modifying database schema]
• Never: [e.g. bypass validation, commit secrets, modify unrelated code]

Step 8: Identify Risks

Flag high-risk items — these should be tackled early in the task breakdown (fail fast).

Step 9: Write and Save Architecture Document

Write architecture.md to the artifact folder using the template from references/formats.md.

Present the architecture to the user for review. Walk through:

1. Component overview
2. Data flow for the primary user story
3. Key tech decisions and their rationale
4. Any risks or open questions

Apply requested changes, then save.

Announce the saved path:

"Architecture saved to [path]/architecture.md."

Common Rationalizations

Red Flags

• No dependency graph — implementation order will be wrong
• Components that don't follow existing codebase patterns
• New dependencies added without checking what's already in the stack
• No integration points mapped — feature will break existing functionality
• Empty risks section — every architecture has risks
• Writing code during the architecture phase

Verification

Before handing off, confirm:

• All upstream artifacts loaded (PRD, context map)
• Components identified with responsibilities, locations, and interfaces
• Data flow documented for primary user story
• Dependency graph shows implementation order
• Tech decisions documented with rationale
• Integration points with existing system mapped
• Boundaries defined (Always / Ask first / Never)
• Risks identified with mitigations
• User has reviewed and approved the architecture
• architecture.md saved to artifact folder

Next

"Architecture complete. Next recommended skill: breakdown — slice this into ordered, interlinked development tasks."