herxinsasa Tech Architect — 技术架构设计
职责
基于 Product-Spec.md（和 Design-Brief.md，如存在）中的产品需求，进行技术调研、方案评估和架构设计。以 ADR（架构决策记录） 的格式记录每一项关键技术决策，输出到独立的 Tech-Arch.md。
此 skill 不负责任务拆分或排期。 那是 dev-planner 的工作。本 skill 的输出是 dev-planner 的前置输入。
核心原则
技术选型必须基于证据，不是记忆。 每一项推荐都要有搜索结果支撑——版本号、Stars、最近更新时间，不是凭印象说「React 很流行」。
每一项决策都要有取舍分析。 没有完美的方案，选 A 就要说清楚放弃了 B 的什么。
复用优先于自研。 搜索现成组件和开源项目是第一步，自研是最后选项。
方案要有可替代性。 如果推荐方案被否决，备选方案应该已经评估好了。
前置条件
Product-Spec.md必须已存在Design-Brief.md如果存在则纳入参考（配色和组件规范可能影响 UI 框架选型）
触发场景
- Product-Spec.md 就绪后，进入技术方案阶段
- 用户说"技术选型"、"架构设计"、"用什么技术栈"
- dev-planner 执行前必须先过 tech-architect
工作流程
Step 0: 模式判断
检查 Tech-Arch.md 是否存在。
情况 A — 不存在： 进入新建模式。
情况 B — 已存在： 告诉用户文档已存在，询问：
Tech-Arch.md 已存在。你是想：
- 重新评估 — 推翻重来，重新调研所有决策
- 调整某个决策 — 只改某一条架构决策
- 补充新决策 — 新增一条 ADR
- 直接跳过 — 架构方案没问题，进入 dev-planner
Step 1: 阅读前置文档
完整阅读并提取关键信息：
| 文档 | 提取什么 |
|---|---|
Product-Spec.md |
产品类型（Web/桌面/移动/CLI 命令行工具）、MVP（最小可行产品）功能列表、技术约束、性能/安全要求 |
Design-Brief.md（如有） |
组件风格、配色方案、响应式需求——影响 UI 框架/组件库选型 |
Step 2: 识别架构决策点
基于产品需求，列出所有需要做技术决策的点。不是每个项目都要全部覆盖，按需选取：
几乎必有（核心决策）：
- 前端/客户端框架
- UI 组件库
- 状态管理
- 后端/API 层方案（如果适用）
- 数据库/存储方案（如果适用）
- 构建工具与打包方案
按需覆盖（取决于项目类型）：
- 认证/授权方案
- 路由方案
- 测试框架
- 部署/托管方案
- 日志/监控方案
- 国际化方案
- 实时通信方案
复用调研（每个功能过一遍）：
针对每个 MVP 功能，搜索是否有现成的组件库、开源项目、npm 包或脚手架可直接复用。
复用评判标准（四维度）：
| 评判维度 | 可直接用 | 需改造 | 不适用 |
|---|---|---|---|
| 功能匹配度 | ≥90% | 50-90% | <50% |
| 维护状态 | 近 1 月有更新 | 近 6 月有更新 | 超过 1 年未更新 |
| 协议 | MIT/Apache | GPL/需评估 | 商用受限 |
| 代码质量 | 有测试/文档 | 有文档缺测试 | 无文档 |
每项复用方案的评分结果写入复用项目清单（Step 6 输出格式中的第 3 章）。
Step 2.5: 结构化思考前置（可选，复杂项目建议执行）
如果项目满足以下任一条件，在开始搜索技术方案前（Step 3），建议先用 structured-thinking 审视关键技术决策：
触发条件：
- 决策点多于 5 个（项目复杂，容易过度设计）
- 产品类型新颖（不是标准 Web/CLI/Electron 模式，没有现成套路可抄）
- 用户表现出不确定（"你帮我看看"、"不知道应该用哪个"）
- 每个 MVP 功能看起来都需要独立的技术选型
执行方式：
架构涉及 个关键技术决策。在开始搜索方案之前，要不要用结构化思考先过一遍核心决策？ 它能帮我们：
- 把问题问对 — "需要状态管理"真需要吗？还是组件传参就够了？
- 从本质出发 — 不被"大家都用 Redux"的惯性绑定
- 做剪枝 — 哪些可以不做、推迟、用原生方案？
这样可以避免为不需要的东西选型。要试试吗？
用户同意后，对每个关键决策点执行 structured-thinking。输出继承规则：
| structured-thinking 输出 | 对 tech-architect 的影响 |
|---|---|
| 奥卡姆剃刀：某决策可删除 | 该决策点从 Step 2 列表中移除 |
| 奥卡姆剃刀：可推迟 | 标记为「后续迭代」，Step 3 暂不调研 |
| 奥卡姆剃刀：可用原生方案 | Step 3 搜索替换为「验证原生方案是否足够」 |
| 第一性原理：本质诉求 | 作为 ADR「背景」章节的核心论述 |
用户拒绝则直接进入 Step 3。
Step 3: 逐项调研与对比
每个决策点按以下流程走：
3.1 搜索
针对每个决策点，联网搜索当前主流选项、社区活跃度、生产可用性，以及是否有现成的开源方案可复用。
3.2 评估维度
每个候选方案从以下维度打分：
| 维度 | 权重 | 说明 |
|---|---|---|
| 功能匹配度 | 高 | 与产品需求的契合程度 |
| 社区活跃度 | 高 | Stars、最近 commit、issue 响应速度 |
| 生态成熟度 | 中 | 插件/教程/问答资源、TypeScript 支持 |
| AI 实现友好度 | 中 | 是否有成熟 SDK（软件开发工具包）、CLI 命令行工具、API 接口、模板可以调 |
| 性能/体积 | 中 | Bundle size、运行时性能（前端）；吞吐/延迟（后端） |
| 学习曲线 | 低 | 对后续维护的影响（但 AI 实现时重要性降低） |
3.3 对比输出
每个决策点输出对比表：
### 决策点：<决策名称>
| 候选方案 | 版本 | Stars | 功能匹配 | 活跃度 | AI友好 | 综合推荐 |
|---------|------|-------|---------|--------|--------|---------|
| 方案 A | | | | | | ⭐ |
| 方案 B | | | | | | |
| 方案 C | | | | | | |
**推荐：方案 A**
**理由：** <一句话说清为什么>
**代价：** <放弃了什么>
**备选：** 如果方案 A 不可行 → 方案 B
Step 4: 架构设计
在技术选型确定后，画出系统架构骨架。
4.1 架构图（Mermaid 或文字描述）
项目类型决定架构模式：
- Web 全栈 → 前端 + API + 数据库
- 桌面应用 → Electron + Renderer + Main Process
- CLI 工具 → 单进程 + 文件系统
- 移动端 → React Native / Flutter
4.2 目录结构设计
先询问用户：
项目有没有现有的编码规范文档？比如
.clauderules、团队 wiki、README 里的约定？如果有，我会读取并归档到 Tech-Arch.md。如果没有，我会按默认模板为你生成一份。
需要确认的规范类别：
- 目录规范 — 源码怎么分子目录？有无
application/、business/、view/划分？- 命名规范 — 文件/目录/类/函数/变量/常量/类型/枚举分别用什么风格？
- 注释规范 — API 是否必须写注释？TODO 标记格式？禁止事项？
- 编码规范 — 类型安全级别、错误处理方式、导入顺序、文件/函数长度限制？
你有现有规范吗？还是我按默认模板生成？
用户有规范 → 读取原文，提取关键规则写入 Tech-Arch.md §5，标注来源路径。
用户没有 → 用默认模板生成，逐类询问确认后写入。
用户选择默认模板时：
<project-name>/
├── CLAUDE.md # AI 入口：项目上下文，自动加载
├── README.md # 人类入口：简介、快速启动
│
├── src/ # 源代码
│ │
│ ├── application/ # 应用入口（启动配置、路由注册）
│ │
│ ├── business/ # 业务逻辑（前后端分离时）
│ │ └── <模块名>/ # 按功能模块组织
│ │ ├── handler.ts # 控制器 / 服务入口
│ │ ├── service.ts # 核心业务逻辑
│ │ └── model.ts # 数据模型 / 类型定义
│ │
│ ├── view/ # 视图层（前后端分离时）
│ │ └── <模块名>/ # 按功能模块组织，层层递进
│ │ ├── <页面>.tsx # 页面组件
│ │ └── components/ # 模块专属 UI 组件
│ │
│ ├── utils/ # 通用工具（不归属任何模块的共享代码）
│ └── types/ # 全局类型定义（可选，小型项目可放 business/ 内）
│
├── docs/ # 项目文档（AI 快速了解项目的第一入口）
│ │
│ ├── requirements/ # 需求文档（引用 Product-Spec.md）
│ │ ├── overview.md # 产品概述：一句话定位 + MVP 功能 + 目标用户
│ │ └── glossary.md # 业务术语表（引用 Product-Spec 领域术语）
│ │
│ ├── design/ # 设计文档
│ │ ├── functional/ # 功能设计 — 业务层面
│ │ │ └── <模块名>.md # 每个模块的交互流程 / UE / 状态处理
│ │ └── visual/ # 原型设计 — UI 层面
│ │ └── <模块名>.md # 配色 / 组件风格 / 动效 / 对标产品的视觉参考
│ │
│ ├── architecture/ # 架构层 — 系统是什么样的
│ │ └── overview.md # 系统架构总览（含 Mermaid 图）
│ │
│ ├── modules/ # 模块实现文档
│ │ ├── README.md # 模块索引：所有模块清单 + 依赖关系 + 一句话职责
│ │ └── <module>/
│ │ └── README.md # 模块实现详情
│ │
│ └── guides/ # 操作指南
│ ├── development.md # 开发环境搭建
│ ├── testing.md # 测试策略与规范
│ ├── build-and-deploy.md # 构建与部署
│ └── troubleshooting.md # 常见问题排查
│
├── tests/ # 测试
└── scripts/ # 脚本（CI / 部署 / 自动化）
4.3 数据流设计
描述核心数据如何流转：用户操作 → 组件 → 状态管理 → API → 数据库 → 返回
Step 5: 写 ADR（架构决策记录）
每项关键技术决策写一条 ADR。格式：
## ADR-{序号}: {决策标题}
- **日期：** YYYY-MM-DD
- **状态：** 已采纳
### 背景
<为什么需要做这个决策？产品需求中的什么约束驱动的？>
### 决策
<我们选择了什么？>
### 备选方案
| 方案 | 优点 | 缺点 | 为什么没选 |
|------|------|------|-----------|
| 方案 B | ... | ... | ... |
| 方案 C | ... | ... | ... |
### 影响
- 正面：<带来什么好处>
- 负面/风险：<失去什么、引入什么风险>
- 缓解：<如何降低风险>
Step 6: 确认与输出
6.1 确认摘要
## 技术架构确认
**产品类型**：<Web/桌面/移动/CLI>
**架构模式**：<SPA 单页应用 / SSR 服务端渲染 / Electron 桌面 / CLI 命令行 / ...>
**核心技术栈**：
| 层级 | 选型 | 理由（一句话） |
|------|------|--------------|
| 前端框架 | | |
| UI 库 | | |
| 状态管理 | | |
| ... | | |
**可复用项目**：
- <项目名> — 覆盖 <功能>，协议 <MIT/Apache>，可省 <N> 个实现任务
**架构决策**：共 <N> 条 ADR
以上方案可以吗？有没有要调整的？
用户确认后写入 Tech-Arch.md。
6.2 输出格式
# <产品名称> — 技术架构
## 1. 架构总览
### 1.1 产品类型与架构模式
### 1.2 架构图（Mermaid 或文字）
### 1.3 技术栈总览
| 层级 | 选型 | 版本 | 选型理由 |
|------|------|------|---------|
| 前端框架 | | | |
| ... | | | |
## 2. 架构决策记录 (ADR)
### ADR-001: <标题>
...
### ADR-002: <标题>
...
## 3. 复用项目清单
| 项目 | 覆盖功能 | 协议 | 复用方式 | 可省任务数 |
|------|---------|------|---------|-----------|
| | | | | |
## 4. 自研模块清单
| 模块 | 原因 |
|------|------|
| | |
## 5. 项目规范约束
> 由 tech-architect 向用户收集后归档。后续所有 skill 强制执行，禁止偏离。
### 5.1 目录规范
### 5.2 命名规范
| 类型 | 规则 | 示例 |
|------|------|------|
| 文件名 | | |
| 目录名 | | |
| 类名 / 组件名 | | |
| 函数名 | | |
| 变量名 | | |
| 常量名 | | |
| 类型 / 接口 | | |
| 枚举 | | |
### 5.3 注释规范
| 类型 | 规则 |
|------|------|
| 公共 API | |
| 复杂逻辑 | |
| 待办标记 | |
| 废弃标记 | |
| 禁止事项 | |
### 5.4 编码规范
| 规则 | 说明 |
|------|------|
| 类型安全 | |
| 错误处理 | |
| 导入顺序 | |
| 文件长度 | |
| 函数长度 | |
| 副作用 | |
| 未使用代码 | |
## 6. 目录结构设计
## 7. 数据流设计
## 8. 风险与应对
| 风险 | 影响 | 应对 |
|------|------|------|
---
> 关联：[Product-Spec.md](./Product-Spec.md) | [Design-Brief.md](./Design-Brief.md)（如有）
6.3 进度 checkpoint
更新 .claude/progress.json：
current_phase: "architecture"current_skill: "tech-architect"milestones追加「技术架构已确定： 条 ADR」documents.Tech-Arch.md：exists: true
输出
Tech-Arch.md— 技术架构文档（架构总览 + ADR + 复用清单）Product-Spec-CHANGELOG.md— 追加新增：技术架构设计与选型，<N> 条 ADR
注意事项
- 每项决策必须列出备选方案 — 不要只写「我推荐 React」，要写「对比了 React/Vue/Svelte，选 React 因为 XXX」
- 搜索证据要具体 — 写版本号、Stars 数、最近 commit 日期，不要「社区很活跃」这种模糊描述
- 没有完美的方案，说清楚代价 — 选 Electron 就牺牲了 Web 的轻量，选纯 Web 就牺牲了系统级 API
- 相关性优先于热度 — Stars 最多的不一定最适合。一个 500 Stars 但完美匹配需求的库 > 5万 Stars 但只能覆盖 30% 需求的库
- ADR 是活的文档 — 如果后续开发中发现某个决策不成立，可以新增 ADR 标记为「已废弃」并指向新决策