architect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

核心任务

Read
```
project.vision-analysis.md
```
for requirements
Research candidate technologies for each layer
Evaluate and compare options
Make decisions with documented rationale
Design system architecture
Output
```
project.architecture.md
```

读取
```
project.vision-analysis.md
```
获取需求
为每个技术层调研候选技术
评估并对比各选项
记录决策依据并确定方案
设计系统架构
输出
```
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

版本选择流程

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
```
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
Document the version and why:
- Record in project.architecture.md
- Add to knowledge/project/decisions.md

undefined

查询官方源获取最新版本：
- Rust: crates.io API 或
```
cargo search
```
- Node: npmjs.com 或
```
npm view [pkg] version
```
- Python: pypi.org 或
```
pip index versions
```
检查发布日期与稳定性：
- 发布时间超过2周（非前沿版本）
- GitHub issues中无严重问题
- 更新日志显示与通用模式无破坏性变更
记录版本及选择理由：
- 记录在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:

Layer	Examples
Language	Rust, TypeScript, Python, Go
Frontend Framework	React, Vue, Svelte, SolidJS
Backend Framework	Axum, Actix, Express, FastAPI
Database	PostgreSQL, SQLite, MongoDB
ORM/Query Builder	Diesel, SQLx, Prisma, Drizzle
Authentication	JWT, Sessions, OAuth providers
Deployment	Docker, Serverless, VPS
Testing	Built-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:

Identify 2-4 candidates - Don't over-research
Fetch source code if needed for deep understanding
Check latest versions - Use web search or package registry
Read documentation - Understand core concepts
Compare tradeoffs - Performance, DX, ecosystem

针对每个需要决策的技术层：

筛选2-4个候选技术 - 避免过度调研
如需深入理解则获取源码
检查最新版本 - 使用网页搜索或包注册表
阅读文档 - 理解核心概念
对比权衡 - 性能、开发体验、生态

Step 3: Use Structured Comparison

步骤3：结构化对比

markdown

undefined

markdown

undefined

[Layer Name] Decision

[技术层名称]决策

Candidates

候选技术

Criterion	Option A	Option B	Option C
Latest Version	v1.2.3	v2.0.0	v0.9.0
Release Date	2026-01-15	2026-01-20	2025-12-01
GitHub Stars	45k	30k	15k
Bundle Size	50kb	80kb	30kb
Learning Curve	Medium	Low	High
Documentation	Excellent	Good	Fair
TypeScript Support	Native	Via types	Partial
Community Activity	Very Active	Active	Moderate

评估维度	选项A	选项B	选项C
最新版本	v1.2.3	v2.0.0	v0.9.0
发布日期	2026-01-15	2026-01-20	2025-12-01
GitHub星标数	45k	30k	15k
包体积	50kb	80kb	30kb
学习曲线	中等	低	高
文档质量	优秀	良好	一般
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)

bash

undefined

bash

undefined

Get latest 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)

bash

undefined

bash

undefined

Get latest 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

核心技术

Layer	Technology	Version	Rationale
Language	Rust	1.75	Performance, safety
Web Framework	Axum	0.7.4	Ergonomic, async
Database	SQLite	3.45	Simple, embedded
ORM	SQLx	0.7.3	Compile-time checks

技术层	技术	版本	决策依据
编程语言	Rust	1.75	性能、安全性
Web框架	Axum	0.7.4	易用、异步支持
数据库	SQLite	3.45	简单、嵌入式
ORM	SQLx	0.7.3	编译时检查

Development Tools

开发工具

Tool	Version	Purpose
cargo-watch	8.5.2	Auto-rebuild
sqlx-cli	0.7.3	Migrations

工具	版本	用途
cargo-watch	8.5.2	自动重建
sqlx-cli	0.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: ...

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

下一步计划

Initialize project structure
Set up CI/CD
Begin roadmap planning

---

初始化项目结构
搭建CI/CD
开始路线图规划

---

Integration with Orchestrator

与编排器的集成

After architecture design:

Save
```
project.architecture.md
```
to project root
Update
```
knowledge/project/decisions.md
```
with ADRs
Signal completion to orchestrator
Roadmap Skill uses architecture as input

完成架构设计后：

将
```
project.architecture.md
```
保存至项目根目录
更新
```
knowledge/project/decisions.md
```
中的ADR记录
向编排器发送完成信号
路线图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

核心技术

Layer	Technology	Version	Rationale
Language	TypeScript	5.3.3	Type safety, ecosystem
Framework	SvelteKit	2.5.0	Fast, simple, SSR+SPA
Styling	Tailwind CSS	3.4.1	Utility-first, fast
Database	IndexedDB (Dexie)	4.0.1	Offline-first PWA
Build	Vite	5.0.12	Fast, modern

技术层	技术	版本	决策依据
编程语言	TypeScript	5.3.3	类型安全、生态丰富
框架	SvelteKit	2.5.0	快速、简洁、SSR+SPA支持
样式	Tailwind CSS	3.4.1	实用优先、快速开发
数据库	IndexedDB (Dexie)	4.0.1	离线优先PWA
构建工具	Vite	5.0.12	快速、现代化

PWA Stack

PWA技术栈

Component	Technology	Version
Service Worker	Workbox	7.0.0
Manifest	Vite PWA Plugin	0.17.4

组件	技术	版本
服务工作者	Workbox	7.0.0
清单	Vite PWA Plugin	0.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