name	tech-architect
description	技术架构设计。调研技术方案、评估开源项目、输出架构决策记录，写入 Tech-Arch.md。在 dev-planner 之前调用。

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 标记为「已废弃」并指向新决策