Back to Details

architect

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Architect Skill

Architect Skill

Research, evaluate, and decide on technology stack and system architecture based on project requirements.
基于项目需求，调研、评估并确定技术栈与系统架构。

Workspace Mode Note

工作区模式说明

When running in workspace mode, all paths are relative to 
.aha-loop/
directory:
  • Vision analysis: 
    .aha-loop/project.vision-analysis.md
  • Architecture output: 
    .aha-loop/project.architecture.md
The orchestrator will provide the actual paths in the prompt context.
在工作区模式下运行时，所有路径均相对于
.aha-loop/
目录：
  • 愿景分析：
    .aha-loop/project.vision-analysis.md
  • 架构输出：
    .aha-loop/project.architecture.md
编排器会在提示上下文提供实际路径。

The Job

核心任务

  1. Read 
    project.vision-analysis.md
    for requirements
  2. Research candidate technologies for each layer
  3. Evaluate and compare options
  4. Make decisions with documented rationale
  5. Design system architecture
  6. Output 
    project.architecture.md
  1. 读取
    project.vision-analysis.md
    获取需求
  2. 为每个技术层调研候选技术
  3. 评估并对比各选项
  4. 记录决策依据并确定方案
  5. 设计系统架构
  6. 输出
    project.architecture.md

Core Principles

核心原则

1. Prefer Latest Stable Versions

1. 优先选择最新稳定版本

Always use the latest stable version of libraries unless there's a specific reason not to.
markdown
undefined
除非有特殊理由，否则始终使用库的最新稳定版本。
markdown
undefined

Version Selection Process

版本选择流程

  1. Query official source for latest version:
    • Rust: crates.io API or 
      cargo search
    • Node: npmjs.com or 
      npm view [pkg] version
    • Python: pypi.org or 
      pip index versions
  2. Check release date and stability:
    • Released > 2 weeks ago (not bleeding edge)
    • No critical issues in GitHub issues
    • Changelog shows no breaking changes from common patterns
  3. Document the version and why:
    • Record in project.architecture.md
    • Add to knowledge/project/decisions.md
undefined
  1. 查询官方源获取最新版本：
    • Rust: crates.io API 或 
      cargo search
    • Node: npmjs.com 或 
      npm view [pkg] version
    • Python: pypi.org 或 
      pip index versions
  2. 检查发布日期与稳定性：
    • 发布时间超过2周（非前沿版本）
    • GitHub issues中无严重问题
    • 更新日志显示与通用模式无破坏性变更
  3. 记录版本及选择理由：
    • 记录在project.architecture.md中
    • 添加至knowledge/project/decisions.md
undefined

2. Consider Long-term Maintenance

2. 考虑长期可维护性

  • Active community and regular updates
  • Good documentation
  • Large ecosystem of plugins/extensions
  • Backed by reputable organization or strong community
  • 活跃的社区与定期更新
  • 完善的文档
  • 丰富的插件/扩展生态
  • 由知名组织或强大社区支持

3. Evaluate Total Cost

3. 评估总成本

  • Learning curve for the team/AI
  • Bundle size / binary size
  • Runtime performance
  • Development velocity
  • 团队/AI的学习曲线
  • 包体积/二进制文件大小
  • 运行时性能
  • 开发效率

Research Process

调研流程

Step 1: Identify Technology Layers

步骤1：识别技术层

Based on project type, identify which layers need decisions:
LayerExamples
LanguageRust, TypeScript, Python, Go
Frontend FrameworkReact, Vue, Svelte, SolidJS
Backend FrameworkAxum, Actix, Express, FastAPI
DatabasePostgreSQL, SQLite, MongoDB
ORM/Query BuilderDiesel, SQLx, Prisma, Drizzle
AuthenticationJWT, Sessions, OAuth providers
DeploymentDocker, Serverless, VPS
TestingBuilt-in, Jest, Pytest, Vitest
根据项目类型，确定需要决策的技术层：
技术层示例
编程语言Rust, TypeScript, Python, Go
前端框架React, Vue, Svelte, SolidJS
后端框架Axum, Actix, Express, FastAPI
数据库PostgreSQL, SQLite, MongoDB
ORM/查询构建器Diesel, SQLx, Prisma, Drizzle
认证JWT, Sessions, OAuth providers
部署Docker, Serverless, VPS
测试Built-in, Jest, Pytest, Vitest

Step 2: Research Each Layer

步骤2：调研各技术层

For each layer requiring a decision:
  1. Identify 2-4 candidates - Don't over-research
  2. Fetch source code if needed for deep understanding
  3. Check latest versions - Use web search or package registry
  4. Read documentation - Understand core concepts
  5. Compare tradeoffs - Performance, DX, ecosystem
针对每个需要决策的技术层：
  1. 筛选2-4个候选技术 - 避免过度调研
  2. 如需深入理解则获取源码
  3. 检查最新版本 - 使用网页搜索或包注册表
  4. 阅读文档 - 理解核心概念
  5. 对比权衡 - 性能、开发体验、生态

Step 3: Use Structured Comparison

步骤3：结构化对比

markdown
undefined
markdown
undefined

[Layer Name] Decision

[技术层名称]决策

Candidates

候选技术

CriterionOption AOption BOption C
Latest Versionv1.2.3v2.0.0v0.9.0
Release Date2026-01-152026-01-202025-12-01
GitHub Stars45k30k15k
Bundle Size50kb80kb30kb
Learning CurveMediumLowHigh
DocumentationExcellentGoodFair
TypeScript SupportNativeVia typesPartial
Community ActivityVery ActiveActiveModerate
评估维度选项A选项B选项C
最新版本v1.2.3v2.0.0v0.9.0
发布日期2026-01-152026-01-202025-12-01
GitHub星标数45k30k15k
包体积50kb80kb30kb
学习曲线中等低高
文档质量优秀良好一般
TypeScript支持原生通过类型定义部分支持
社区活跃度非常活跃活跃中等

Decision: [Option B]

决策：[选项B]

Rationale

决策依据

  • [Reason 1]
  • [Reason 2]
  • [Reason 3]
  • [理由1]
  • [理由2]
  • [理由3]

Tradeoffs Accepted

接受的权衡

  • [What we're giving up]
  • [Mitigation strategy if any]
undefined
  • [我们做出的妥协]
  • [如有则列出缓解策略]
undefined

Step 4: Check Compatibility

步骤4：兼容性检查

Before finalizing:
  • Verify all chosen technologies work together
  • Check for known integration issues
  • Ensure versions are compatible
  • Test with a minimal proof-of-concept if uncertain
最终确定前：
  • 验证所有选定技术可协同工作
  • 检查已知的集成问题
  • 确保版本兼容
  • 若不确定则通过最小化概念验证测试

Version Research Commands

版本调研命令

Rust (crates.io)

Rust (crates.io)

bash
undefined
bash
undefined

Get latest version

获取最新版本

curl -s "https://crates.io/api/v1/crates/tokio" | jq '.crate.max_stable_version'
curl -s "https://crates.io/api/v1/crates/tokio" | jq '.crate.max_stable_version'

Or use cargo

或使用cargo

cargo search tokio --limit 1
undefined
cargo search tokio --limit 1
undefined

Node.js (npm)

Node.js (npm)

bash
undefined
bash
undefined

Get latest version

获取最新版本

npm view react version
npm view react version

Get all versions

获取所有版本

npm view react versions --json
undefined
npm view react versions --json
undefined

Check GitHub for Activity

检查GitHub活跃度

bash
undefined
bash
undefined

Using gh CLI

使用gh CLI

gh api repos/tokio-rs/tokio --jq '.pushed_at, .stargazers_count'

---
gh api repos/tokio-rs/tokio --jq '.pushed_at, .stargazers_count'

---

Architecture Design

架构设计

After technology decisions, design the architecture:
完成技术决策后，进行架构设计：

1. Component Diagram

1. 组件图

markdown
undefined
markdown
undefined

System Components

系统组件

[Component A] --> [Component B] --> [Component C] | | v v [Database] [External API]
undefined
[组件A] --> [组件B] --> [组件C] | | v v [数据库] [外部API]
undefined

2. Data Flow

2. 数据流

Document how data flows through the system:
  • User inputs
  • Processing steps
  • Storage points
  • Output paths
记录数据在系统中的流转路径：
  • 用户输入
  • 处理步骤
  • 存储节点
  • 输出路径

3. Directory Structure

3. 目录结构

Propose the project structure:
project/
├── src/
│   ├── main.rs
│   ├── api/
│   ├── db/
│   └── ...
├── tests/
├── Cargo.toml
└── ...
建议项目结构：
project/
├── src/
│   ├── main.rs
│   ├── api/
│   ├── db/
│   └── ...
├── tests/
├── Cargo.toml
└── ...

4. Key Patterns

4. 关键模式

Document architectural patterns to follow:
  • Error handling approach
  • Logging strategy
  • Configuration management
  • Testing approach
记录需遵循的架构模式：
  • 错误处理方案
  • 日志策略
  • 配置管理
  • 测试方案

Output: project.architecture.md

输出：project.architecture.md

markdown
undefined
markdown
undefined

Project Architecture

项目架构

Generated: [timestamp] Based on: project.vision-analysis.md
生成时间： [timestamp] 基于： project.vision-analysis.md

Technology Stack

技术栈

Core Technologies

核心技术

LayerTechnologyVersionRationale
LanguageRust1.75Performance, safety
Web FrameworkAxum0.7.4Ergonomic, async
DatabaseSQLite3.45Simple, embedded
ORMSQLx0.7.3Compile-time checks
技术层技术版本决策依据
编程语言Rust1.75性能、安全性
Web框架Axum0.7.4易用、异步支持
数据库SQLite3.45简单、嵌入式
ORMSQLx0.7.3编译时检查

Development Tools

开发工具

ToolVersionPurpose
cargo-watch8.5.2Auto-rebuild
sqlx-cli0.7.3Migrations
工具版本用途
cargo-watch8.5.2自动重建
sqlx-cli0.7.3迁移管理

Architecture Decisions

架构决策记录

ADR-001: [Decision Title]

ADR-001: [决策标题]

Context: [Why this decision was needed] Decision: [What was decided] Rationale: [Why this option] Consequences: [Impact of decision]
背景： [为何需要此决策] 决策： [确定的方案] 依据： [选择此方案的理由] 影响： [决策带来的后果]

ADR-002: ...

ADR-002: ...

System Design

系统设计

Component Overview

组件概述

[Diagram or description]
[图表或描述]

Data Flow

数据流

[How data moves through system]
[数据在系统中的流转方式]

Directory Structure

目录结构

[Proposed structure]
[建议的结构]

Key Patterns

关键模式

Error Handling

错误处理

[Approach]
[方案]

Configuration

配置管理

[Approach]
[方案]

Testing Strategy

测试策略

[Approach]
[方案]

Dependencies

依赖

Production Dependencies

生产依赖

toml
[dependencies]
axum = "0.7.4"
tokio = { version = "1.35", features = ["full"] }
sqlx = { version = "0.7.3", features = ["sqlite", "runtime-tokio"] }
toml
[dependencies]
axum = "0.7.4"
tokio = { version = "1.35", features = ["full"] }
sqlx = { version = "0.7.3", features = ["sqlite", "runtime-tokio"] }

Development Dependencies

开发依赖

toml
[dev-dependencies]
toml
[dev-dependencies]

Security Considerations

安全考量

  • [Security item 1]
  • [Security item 2]
  • [安全事项1]
  • [安全事项2]

Performance Considerations

性能考量

  • [Performance item 1]
  • [Performance item 2]
  • [性能事项1]
  • [性能事项2]

Deployment Strategy

部署策略

[How the project will be deployed]
[项目部署方案]

Next Steps

下一步计划

  1. Initialize project structure
  2. Set up CI/CD
  3. Begin roadmap planning

---
  1. 初始化项目结构
  2. 搭建CI/CD
  3. 开始路线图规划

---

Integration with Orchestrator

与编排器的集成

After architecture design:
  1. Save 
    project.architecture.md
    to project root
  2. Update 
    knowledge/project/decisions.md
    with ADRs
  3. Signal completion to orchestrator
  4. Roadmap Skill uses architecture as input
完成架构设计后：
  1. 将
    project.architecture.md
    保存至项目根目录
  2. 更新
    knowledge/project/decisions.md
    中的ADR记录
  3. 向编排器发送完成信号
  4. 路线图Skill将架构作为输入

Checklist

检查清单

Before completing architecture:
  • All technology layers evaluated
  • Latest stable versions verified for each choice
  • Compatibility between choices confirmed
  • Decisions documented with rationale
  • Directory structure proposed
  • Key patterns defined
  • Dependencies listed with versions
  • ADRs recorded in knowledge/project/decisions.md
  • Architecture saved to 
    project.architecture.md
完成架构设计前：
  • 所有技术层已评估
  • 已验证每个选择的最新稳定版本
  • 已确认各选择之间的兼容性
  • 已记录决策依据
  • 已建议目录结构
  • 已定义关键模式
  • 已列出带版本的依赖
  • ADR已记录在knowledge/project/decisions.md中
  • 架构已保存至
    project.architecture.md

Example: Web App Architecture

示例：Web应用架构

Input: Vision analysis showing PWA finance tracker
Output:
markdown
undefined
输入： 愿景分析显示为PWA财务追踪器
输出：
markdown
undefined

Project Architecture

项目架构

Technology Stack

技术栈

Core Technologies

核心技术

LayerTechnologyVersionRationale
LanguageTypeScript5.3.3Type safety, ecosystem
FrameworkSvelteKit2.5.0Fast, simple, SSR+SPA
StylingTailwind CSS3.4.1Utility-first, fast
DatabaseIndexedDB (Dexie)4.0.1Offline-first PWA
BuildVite5.0.12Fast, modern
技术层技术版本决策依据
编程语言TypeScript5.3.3类型安全、生态丰富
框架SvelteKit2.5.0快速、简洁、SSR+SPA支持
样式Tailwind CSS3.4.1实用优先、快速开发
数据库IndexedDB (Dexie)4.0.1离线优先PWA
构建工具Vite5.0.12快速、现代化

PWA Stack

PWA技术栈

ComponentTechnologyVersion
Service WorkerWorkbox7.0.0
ManifestVite PWA Plugin0.17.4
组件技术版本
服务工作者Workbox7.0.0
清单Vite PWA Plugin0.17.4

Architecture Decisions

架构决策记录

ADR-001: SvelteKit over React/Next.js

ADR-001: 选择SvelteKit而非React/Next.js

Context: Need a modern frontend framework for PWA Decision: Use SvelteKit 2.x Rationale:
  • Smaller bundle size (critical for PWA)
  • Built-in SSR and static generation
  • Simpler mental model than React
  • Excellent TypeScript support Consequences: Smaller community than React, but sufficient for this project.
背景： 需要为PWA选择现代化前端框架 决策： 使用SvelteKit 2.x 依据：
  • 更小的包体积（对PWA至关重要）
  • 内置SSR和静态生成
  • 比React更简单的心智模型
  • 优秀的TypeScript支持 影响： 社区规模小于React，但足以支撑此项目。

ADR-002: Dexie for IndexedDB

ADR-002: 为IndexedDB选择Dexie

Context: Need offline data storage Decision: Use Dexie.js 4.x wrapper for IndexedDB Rationale:
  • Promise-based API
  • Excellent TypeScript support
  • Reactive queries
  • Well-maintained Consequences: Additional 30kb bundle, but worth the DX improvement.
undefined
背景： 需要离线数据存储 决策： 使用Dexie.js 4.x作为IndexedDB的封装 依据：
  • 基于Promise的API
  • 优秀的TypeScript支持
  • 响应式查询
  • 维护良好 影响： 增加30kb包体积，但开发体验的提升值得。
undefined