# Tech Architect > 技术架构设计。调研技术方案、评估开源项目、输出架构决策记录，写入 Tech-Arch.md。在 dev-planner 之前调用。 - Skill: `herxinsasa/tech-architect` (Agent Skill) - Install (CLI): `npx skillmds@latest add herxinsasa/tech-architect` - Raw SKILL.md: https://api.skillmd.com/api/skills/herxinsasa/tech-architect/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: herxinsasa (https://skillmd.com/u/herxinsasa) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/herxinsasa/tech-architect --- # 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，标注来源路径。 **用户没有 →** 用默认模板生成，逐类询问确认后写入。 **用户选择默认模板时：** ``` / ├── 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 # 模块索引：所有模块清单 + 依赖关系 + 一句话职责 │ │ └── / │ │ └── README.md # 模块实现详情 │ │ │ └── guides/ # 操作指南 │ ├── development.md # 开发环境搭建 │ ├── testing.md # 测试策略与规范 │ ├── build-and-deploy.md # 构建与部署 │ └── troubleshooting.md # 常见问题排查 │ ├── tests/ # 测试 └── scripts/ # 脚本（CI / 部署 / 自动化） ``` #### 4.3 数据流设计 描述核心数据如何流转：用户操作 → 组件 → 状态管理 → API → 数据库 → 返回 --- ### Step 5: 写 ADR（架构决策记录） 每项关键技术决策写一条 ADR。格式： ```markdown ## ADR-{序号}: {决策标题} - **日期：** YYYY-MM-DD - **状态：** 已采纳 ### 背景 <为什么需要做这个决策？产品需求中的什么约束驱动的？> ### 决策 <我们选择了什么？> ### 备选方案 | 方案 | 优点 | 缺点 | 为什么没选 | |------|------|------|-----------| | 方案 B | ... | ... | ... | | 方案 C | ... | ... | ... | ### 影响 - 正面：<带来什么好处> - 负面/风险：<失去什么、引入什么风险> - 缓解：<如何降低风险> ``` --- ### Step 6: 确认与输出 #### 6.1 确认摘要 ``` ## 技术架构确认 **产品类型**： **架构模式**： **核心技术栈**： | 层级 | 选型 | 理由（一句话） | |------|------|--------------| | 前端框架 | | | | UI 库 | | | | 状态管理 | | | | ... | | | **可复用项目**： - <项目名> — 覆盖 <功能>，协议 ，可省 个实现任务 **架构决策**：共 条 ADR 以上方案可以吗？有没有要调整的？ ``` 用户确认后写入 `Tech-Arch.md`。 #### 6.2 输出格式 ```markdown # <产品名称> — 技术架构 ## 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` — 追加 `新增：技术架构设计与选型， 条 ADR` ## 注意事项 - **每项决策必须列出备选方案** — 不要只写「我推荐 React」，要写「对比了 React/Vue/Svelte，选 React 因为 XXX」 - **搜索证据要具体** — 写版本号、Stars 数、最近 commit 日期，不要「社区很活跃」这种模糊描述 - **没有完美的方案，说清楚代价** — 选 Electron 就牺牲了 Web 的轻量，选纯 Web 就牺牲了系统级 API - **相关性优先于热度** — Stars 最多的不一定最适合。一个 500 Stars 但完美匹配需求的库 > 5万 Stars 但只能覆盖 30% 需求的库 - **ADR 是活的文档** — 如果后续开发中发现某个决策不成立，可以新增 ADR 标记为「已废弃」并指向新决策