architecture-design（建筑设计）

[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. [BLOCKING] Before each step or sub-skill call, update task tracking: set in_progress when step starts, set completed when step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

Critical Thinking Mindset — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. Anti-hallucination: Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.

AI Mistake Prevention — Failure modes to avoid on every task: - Check downstream references before deleting. Deleting components causes documentation and code staleness cascades. Map all referencing files before removal. - Verify AI-generated content against actual code. AI hallucinates APIs, class names, and method signatures. Always grep to confirm existence before documenting or referencing. - Trace full dependency chain after edits. Changing a definition misses downstream variables and consumers derived from it. Always trace the full chain. - Trace ALL code paths when verifying correctness. Confirming code exists is not confirming it executes. Always trace early exits, error branches, and conditional skips — not just happy path. - When debugging, ask "whose responsibility?" before fixing. Trace whether bug is in caller (wrong data) or callee (wrong handling). Fix at responsible layer — never patch symptom site. - Assume existing values are intentional — ask WHY before changing. Before changing any constant, limit, flag, or pattern: read comments, check git blame, examine surrounding code. - Verify ALL affected outputs, not just the first. Changes touching multiple stacks require verifying EVERY output. One green check is not all green checks. - Holistic-first debugging — resist nearest-attention trap. When investigating any failure, list EVERY precondition first (config, env vars, DB names, endpoints, DI registrations, data preconditions), then verify each against evidence before forming any code-layer hypothesis. - Surgical changes — apply the diff test. Bug fix: every changed line must trace directly to the bug. Don't restyle or improve adjacent code. Enhancement task: implement improvements AND announce them explicitly. - Surface ambiguity before coding — don't pick silently. If request has multiple interpretations, present each with effort estimate and ask. Never assume all-records, file-based, or more complex path.

MANDATORY IMPORTANT MUST ATTENTION use TaskCreate to break ALL work into small tasks BEFORE starting. MANDATORY IMPORTANT MUST ATTENTION use AskUserQuestion at EVERY decision point — never assume user preferences. MANDATORY IMPORTANT MUST ATTENTION research top 3 options per architecture concern, compare with evidence, present report with recommendation + confidence %.

External Memory: For complex or lengthy work (research, analysis, scan, review), write intermediate findings and final results to a report file in plans/reports/ — prevents context loss and serves as deliverable.

Evidence Gate: MANDATORY IMPORTANT MUST ATTENTION — every claim, finding, and recommendation requires file:line proof or traced evidence with confidence percentage (>80% to act, <80% must verify first).

Quick Summary

Goal: Act as a solution architect — research, critically analyze, and recommend the complete technical architecture for a project or feature. Cover ALL architecture concerns: backend, frontend, design patterns, library ecosystem, testing strategy, CI/CD, deployment, monitoring, code quality, and dependency management. Produce a comprehensive comparison report with actionable recommendations.

Workflow (12 steps):

1. Load Context — Read domain model, tech stack, business evaluation, refined PBI
2. Derive Architecture Requirements — Map business/domain complexity to architecture constraints
3. Backend Architecture — Research top 3 backend architecture styles + design patterns
4. Frontend Architecture — Research top 3 frontend architecture styles + design patterns
5. Library Ecosystem Research — Best-practice libraries per concern (validation, caching, logging, utils, etc.)
6. Testing Architecture — Unit, integration, E2E, performance testing frameworks + strategy
7. CI/CD & Deployment — Pipeline design, containerization, orchestration, IaC
8. Observability & Monitoring — Logging, metrics, tracing, alerting stack
9. Code Quality & Clean Code — Linters, analyzers, formatters, enforcement tooling
10. Dependency Risk Assessment — Package health, obsolescence risk, maintenance cost
11. Generate Report — Full architecture decision report with all recommendations
12. User Validation — Present findings, ask 8-12 questions, confirm all decisions

Key Rules:

• MANDATORY IMPORTANT MUST ATTENTION research minimum 3 options per architecture concern with web evidence
• MANDATORY IMPORTANT MUST ATTENTION include confidence % with evidence for every recommendation
• MANDATORY IMPORTANT MUST ATTENTION run user validation interview at end (never skip)
• Delegate to solution-architect agent for complex architecture decisions
• All claims must cite sources (URL, benchmark, case study, or codebase evidence)
• Never recommend based on familiarity alone — evidence required

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

Step 1: Load Context

Read artifacts from prior workflow steps (search in plans/ and team-artifacts/):

• Domain model / ERD (complexity, bounded contexts, aggregate count)
• Tech stack decisions (confirmed languages, frameworks, databases)
• Business evaluation (scale, constraints, compliance)
• Refined PBI (scope, acceptance criteria)
• Discovery interview (team skills, experience level)

Extract and summarize:

Step 2: Derive Architecture Requirements

Map signals to architecture constraints:

MANDATORY IMPORTANT MUST ATTENTION validate derived requirements with user via AskUserQuestion before proceeding.

Step 3: Backend Architecture

3A: Architecture Styles

WebSearch top 3 backend architecture styles. Candidates:

3B: Backend Design Patterns

Evaluate applicability per layer:

For each recommended pattern, document: Apply to, Why, Example, Risk if skipped.

Step 4: Frontend Architecture

4A: Architecture Styles

WebSearch top 3 frontend architecture styles. Candidates:

4B: Frontend Design Patterns

Step 4B: UI System Architecture

Skip if: Backend-only project, no frontend component.

Research and recommend the project's design system architecture. Use AskUserQuestion for each decision.

4B-1: Styling Approach

WebSearch top 3 styling approaches for the confirmed frontend framework:

4B-2: Design Token Strategy

4B-3: Component Library Strategy

4B-4: Responsive Strategy

MANDATORY IMPORTANT MUST ATTENTION validate all UI system decisions with user via AskUserQuestion before proceeding to Step 5.

Step 5: Library Ecosystem Research

For EACH concern below, WebSearch top 3 library options for the confirmed tech stack. Evaluate: maturity, community, bundle size, maintenance activity, license, learning curve.

Library Concerns Checklist

Per-Library Evaluation Template

### {Concern}: Top 3 Options

| Criteria         | Option A          | Option B | Option C |
| ---------------- | ----------------- | -------- | -------- |
| GitHub Stars     | ...               | ...      | ...      |
| Last Release     | ...               | ...      | ...      |
| Bundle Size      | ...               | ...      | ...      |
| Weekly Downloads | ...               | ...      | ...      |
| License          | ...               | ...      | ...      |
| Maintenance      | Active/Slow/Stale | ...      | ...      |
| Learning Curve   | Low/Med/High      | ...      | ...      |

**Recommendation:** {Option} — Confidence: {X}%

Step 6: Testing Architecture

Research best testing tools and strategy for the confirmed tech stack:

Test Strategy Template

### Test Pyramid

- **Unit (70%):** {framework} — {what to test}
- **Integration (20%):** {framework} — {what to test}
- **E2E (10%):** {framework} — {what to test}

### Coverage Targets

- Unit: {X}% | Integration: {X}% | E2E: critical paths only
- Enforcement: {tool} in CI pipeline, fail build below threshold

Step 7: CI/CD & Deployment

Research deployment architecture and CI/CD tooling:

Deployment Strategy Comparison

Step 8: Observability & Monitoring

Observability Decision: 3 Pillars

### Recommended Observability Stack

| Pillar   | Tool   | Why         |
| -------- | ------ | ----------- |
| Logs     | {tool} | {rationale} |
| Metrics  | {tool} | {rationale} |
| Traces   | {tool} | {rationale} |
| Alerting | {tool} | {rationale} |

Step 9: Code Quality & Clean Code Enforcement

Research and recommend tooling for automated code quality:

Enforcement Strategy

### Code Quality Gates

| Gate        | Tool   | Trigger        | Fail Criteria         |
| ----------- | ------ | -------------- | --------------------- |
| Pre-commit  | {tool} | git commit     | Lint errors, format   |
| PR Check    | {tool} | Pull request   | Coverage < X%, issues |
| CI Pipeline | {tool} | Push to branch | Build fail, test fail |
| Scheduled   | {tool} | Weekly/nightly | Security vulns, debt  |

Scaffold Handoff (MANDATORY — consumed by /scaffold)

After completing code quality research, produce this handoff table in the architecture report. The /scaffold skill reads this table to generate actual config files — without it, scaffold cannot auto-configure quality tooling.

### Scaffold Handoff — Tool Choices

| Concern        | Chosen Tool       | Config File | Rationale |
| -------------- | ----------------- | ----------- | --------- |
| Linter (FE)    | {tool}            | {filename}  | {why}     |
| Linter (BE)    | {tool}            | {filename}  | {why}     |
| Formatter      | {tool}            | {filename}  | {why}     |
| Pre-commit     | {tool}            | {filename}  | {why}     |
| Error handling | {pattern}         | {files}     | {why}     |
| Loading state  | {pattern}         | {files}     | {why}     |
| Docker         | {compose pattern} | {files}     | {why}     |

Also include: Error handling strategy (4-layer pattern), loading state approach (global vs per-component), and Docker profile structure. Specific tool choices → docs/project-reference/ or project-config.json.

Step 10: Dependency Risk Assessment

For EVERY recommended library/package, evaluate maintenance and obsolescence risk:

Package Health Scorecard

Risk Categories

Dependency Maintenance Strategy

### Recommended Practices

1. **Automated scanning:** {tool} (Dependabot/Renovate/Snyk) — weekly PR for updates
2. **Lock file strategy:** Commit lock files, pin major versions, allow patch auto-update
3. **Audit schedule:** Monthly `npm audit` / `dotnet list package --vulnerable`
4. **Vendor policy:** Max {N} dependencies per concern, prefer well-maintained alternatives
5. **Exit strategy:** For each High-risk dependency, document migration path to alternative

Step 11: Generate Report

Write report to {plan-dir}/research/architecture-design.md with sections:

1. Executive summary (recommended architecture in 8-10 lines)
2. Architecture requirements table (from Step 2)
3. Backend architecture — style comparison + recommended patterns (Steps 3)
4. Frontend architecture — style comparison + recommended patterns (Step 4)
5. Library ecosystem — per-concern recommendations with alternatives (Step 5)
6. Testing architecture — pyramid, tools, coverage targets (Step 6)
7. CI/CD & deployment — pipeline design, deployment strategy (Step 7)
8. Observability stack — 3 pillars + alerting (Step 8)
9. Code quality — enforcement gates, tooling (Step 9)
10. Dependency risk matrix — high-risk packages, mitigation (Step 10)
11. Architecture diagram (Mermaid — showing all layers and data flow)
12. Risk assessment for overall architecture
13. Unresolved questions

Architecture Diagram Template

graph TB subgraph "Frontend" UI[SPA / Micro Frontend] STORE[State Management] end subgraph "API Gateway" GW[Gateway / BFF] end subgraph "Backend Services" CMD[Commands / Handlers] QRY[Queries / Read Models] SVC[Domain Services] ENT[Entities / Aggregates] end subgraph "Infrastructure" DB[(Database)] CACHE[(Cache)] MSG[Message Bus] SEARCH[(Search Index)] end subgraph "Observability" LOG[Logging] METRIC[Metrics] TRACE[Tracing] end subgraph "CI/CD" PIPE[Pipeline] REG[Container Registry] K8S[Orchestration] end UI --> GW --> CMD & QRY CMD --> SVC --> ENT --> DB QRY --> CACHE & SEARCH ENT -.-> MSG CMD & QRY -.-> LOG & METRIC & TRACE PIPE --> REG --> K8S

Step 12: User Validation Interview

MANDATORY IMPORTANT MUST ATTENTION present findings and ask 8-12 questions via AskUserQuestion:

Required Questions

1. Backend architecture — "I recommend {style}. Agree?"
2. Frontend architecture — "I recommend {style} with {state management}. Agree?"
3. Design patterns — "Recommended backend patterns: {list}. Frontend patterns: {list}. Any to add/remove?"
4. Key libraries — "For {concern}, I recommend {lib} over {alternatives}. Agree?"
5. Testing strategy — "Test pyramid: {unit}%/{integration}%/{E2E}% using {frameworks}. Appropriate?"
6. CI/CD — "Pipeline: {tool} with {deployment strategy}. Fits your infra?"
7. Observability — "Monitoring stack: {logs}/{metrics}/{traces}. Sufficient?"
8. Code quality — "Enforcement: {linter + formatter + pre-commit hooks}. Team ready?"
9. Dependency risk — "Found {N} high-risk dependencies. Accept or find alternatives?"
10. Complexity check — "This architecture has {N} concerns addressed. Appropriate for team size?"

Optional Deep-Dive Questions (pick 2-3)

• "Should we use event sourcing or traditional state-based persistence?"
• "Monolith-first or start with service boundaries?"
• "Micro frontends or monolith SPA?"
• "How important is framework independence for this project?"
• "Self-hosted observability or managed SaaS?"
• "Strict lint rules from day 1 or gradual adoption?"

After user confirms, update report with final decisions and mark as status: confirmed.

Best Practices Audit (applied across all steps)

Validate architecture against these principles — flag violations in report:

Output

{plan-dir}/research/architecture-design.md     # Full architecture analysis report
{plan-dir}/phase-02b-architecture.md           # Confirmed architecture decisions

MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using TaskCreate BEFORE starting. MANDATORY IMPORTANT MUST ATTENTION validate EVERY architecture recommendation with user via AskUserQuestion — never auto-decide. MANDATORY IMPORTANT MUST ATTENTION include confidence % and evidence citations for all claims. MANDATORY IMPORTANT MUST ATTENTION add a final review todo task to verify work quality.

Next Steps

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS after completing this skill, you MUST ATTENTION use AskUserQuestion to present these options. Do NOT skip because the task seems "simple" or "obvious" — the user decides:

• "/plan (Recommended)" — Create implementation plan from architecture design
• "/refine" — If need to create PBIs first
• "Skip, continue manually" — user decides

Closing Reminders

MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using TaskCreate BEFORE starting. MANDATORY IMPORTANT MUST ATTENTION validate decisions with user via AskUserQuestion — never auto-decide. MANDATORY IMPORTANT MUST ATTENTION add a final review todo task to verify work quality.

• MUST ATTENTION apply critical thinking — every claim needs traced proof, confidence >80% to act. Anti-hallucination: never present guess as fact.
• MUST ATTENTION apply AI mistake prevention — holistic-first debugging, fix at responsible layer, surface ambiguity before coding, re-read files after compaction.

[TASK-PLANNING] Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using TaskCreate.

[IMPORTANT] Analyze how big the task is and break it into many small todo tasks systematically before starting — this is very important.

Prompt-Enhance Closing Anchors

• IMPORTANT MUST ATTENTION follow declared step order for this skill; NEVER skip, reorder, or merge steps without explicit user approval
• IMPORTANT MUST ATTENTION for every step/sub-skill call: set in_progress before execution, set completed after execution
• IMPORTANT MUST ATTENTION every skipped step MUST include explicit reason; every completed step MUST include concise evidence
• IMPORTANT MUST ATTENTION if Task tools unavailable, maintain an equivalent step-by-step plan tracker with synchronized statuses