Menu
技术架构设计。调研技术方案、评估开源项目、输出架构决策记录，写入 Tech-Arch.md。在 dev-planner 之前调用。
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
构建验证、版本管理与发布上线。多轮确认发布目标与推送路径后执行门禁与发布，写入状态与 release notes。用户提到发布、上线、deploy、打 tag、发版、merge 到 main、推远程、构建生产包、创建 PR 时，即使未说 release 也必须使用本 skill。
设计执行。基于 Design-Brief.md 产出原型、设计稿或设计系统。支持 Figma、Pencil、HTML/CSS 原型等多种输出方式。
需求收集与问题澄清。新建或迭代 PRD，通过交互式澄清生成结构化产品需求文档。
系统化调试修复 Bug。五阶段：收集证据→重现用例→分析(含根因归因)→假设→修复→进化记录。支持触发 code-review 和 feedback-writer。
代码审查和质量检查。调度 code-reviewer sub-agent 审查代码，检查是否符合计划和编码标准。
根据开发计划编写代码。按任务调度 implementer sub-agent，在 <project-name>/ 目录下创建项目。
| name | tech-architect |
| description | 技术架构设计。调研技术方案、评估开源项目、输出架构决策记录，写入 Tech-Arch.md。在 dev-planner 之前调用。 |
基于 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 框架选型）检查 Tech-Arch.md 是否存在。
情况 A — 不存在： 进入新建模式。
情况 B — 已存在： 告诉用户文档已存在，询问：
Tech-Arch.md 已存在。你是想：
- 重新评估 — 推翻重来，重新调研所有决策
- 调整某个决策 — 只改某一条架构决策
- 补充新决策 — 新增一条 ADR
- 直接跳过 — 架构方案没问题，进入 dev-planner
完整阅读并提取关键信息：
| 文档 | 提取什么 |
|---|---|
Product-Spec.md | 产品类型（Web/桌面/移动/CLI 命令行工具）、MVP（最小可行产品）功能列表、技术约束、性能/安全要求 |
Design-Brief.md（如有） | 组件风格、配色方案、响应式需求——影响 UI 框架/组件库选型 |
基于产品需求，列出所有需要做技术决策的点。不是每个项目都要全部覆盖，按需选取：
几乎必有（核心决策）：
按需覆盖（取决于项目类型）：
复用调研（每个功能过一遍）：
针对每个 MVP 功能，搜索是否有现成的组件库、开源项目、npm 包或脚手架可直接复用。
复用评判标准（四维度）：
| 评判维度 | 可直接用 | 需改造 | 不适用 |
|---|---|---|---|
| 功能匹配度 | ≥90% | 50-90% | <50% |
| 维护状态 | 近 1 月有更新 | 近 6 月有更新 | 超过 1 年未更新 |
| 协议 | MIT/Apache | GPL/需评估 | 商用受限 |
| 代码质量 | 有测试/文档 | 有文档缺测试 | 无文档 |
每项复用方案的评分结果写入复用项目清单（Step 6 输出格式中的第 3 章）。
如果项目满足以下任一条件，在开始搜索技术方案前（Step 3），建议先用 structured-thinking 审视关键技术决策：
触发条件：
执行方式：
架构涉及 个关键技术决策。在开始搜索方案之前，要不要用结构化思考先过一遍核心决策？ 它能帮我们：
- 把问题问对 — "需要状态管理"真需要吗？还是组件传参就够了？
- 从本质出发 — 不被"大家都用 Redux"的惯性绑定
- 做剪枝 — 哪些可以不做、推迟、用原生方案？
这样可以避免为不需要的东西选型。要试试吗？
用户同意后，对每个关键决策点执行 structured-thinking。输出继承规则：
| structured-thinking 输出 | 对 tech-architect 的影响 |
|---|---|
| 奥卡姆剃刀：某决策可删除 | 该决策点从 Step 2 列表中移除 |
| 奥卡姆剃刀：可推迟 | 标记为「后续迭代」，Step 3 暂不调研 |
| 奥卡姆剃刀：可用原生方案 | Step 3 搜索替换为「验证原生方案是否足够」 |
| 第一性原理：本质诉求 | 作为 ADR「背景」章节的核心论述 |
用户拒绝则直接进入 Step 3。
每个决策点按以下流程走：
针对每个决策点，联网搜索当前主流选项、社区活跃度、生产可用性，以及是否有现成的开源方案可复用。
每个候选方案从以下维度打分：
| 维度 | 权重 | 说明 |
|---|---|---|
| 功能匹配度 | 高 | 与产品需求的契合程度 |
| 社区活跃度 | 高 | Stars、最近 commit、issue 响应速度 |
| 生态成熟度 | 中 | 插件/教程/问答资源、TypeScript 支持 |
| AI 实现友好度 | 中 | 是否有成熟 SDK（软件开发工具包）、CLI 命令行工具、API 接口、模板可以调 |
| 性能/体积 | 中 | Bundle size、运行时性能（前端）；吞吐/延迟（后端） |
| 学习曲线 | 低 | 对后续维护的影响（但 AI 实现时重要性降低） |
每个决策点输出对比表：
### 决策点：<决策名称>
| 候选方案 | 版本 | Stars | 功能匹配 | 活跃度 | AI友好 | 综合推荐 |
|---------|------|-------|---------|--------|--------|---------|
| 方案 A | | | | | | ⭐ |
| 方案 B | | | | | | |
| 方案 C | | | | | | |
**推荐：方案 A**
**理由：** <一句话说清为什么>
**代价：** <放弃了什么>
**备选：** 如果方案 A 不可行 → 方案 B
在技术选型确定后，画出系统架构骨架。
项目类型决定架构模式：
- Web 全栈 → 前端 + API + 数据库
- 桌面应用 → Electron + Renderer + Main Process
- CLI 工具 → 单进程 + 文件系统
- 移动端 → React Native / Flutter
先询问用户：
项目有没有现有的编码规范文档？比如
.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 / 部署 / 自动化）
描述核心数据如何流转：用户操作 → 组件 → 状态管理 → API → 数据库 → 返回
每项关键技术决策写一条 ADR。格式：
## ADR-{序号}: {决策标题}
- **日期：** YYYY-MM-DD
- **状态：** 已采纳
### 背景
<为什么需要做这个决策？产品需求中的什么约束驱动的？>
### 决策
<我们选择了什么？>
### 备选方案
| 方案 | 优点 | 缺点 | 为什么没选 |
|------|------|------|-----------|
| 方案 B | ... | ... | ... |
| 方案 C | ... | ... | ... |
### 影响
- 正面：<带来什么好处>
- 负面/风险：<失去什么、引入什么风险>
- 缓解：<如何降低风险>
## 技术架构确认
**产品类型**：<Web/桌面/移动/CLI>
**架构模式**：<SPA 单页应用 / SSR 服务端渲染 / Electron 桌面 / CLI 命令行 / ...>
**核心技术栈**：
| 层级 | 选型 | 理由（一句话） |
|------|------|--------------|
| 前端框架 | | |
| UI 库 | | |
| 状态管理 | | |
| ... | | |
**可复用项目**：
- <项目名> — 覆盖 <功能>，协议 <MIT/Apache>，可省 <N> 个实现任务
**架构决策**：共 <N> 条 ADR
以上方案可以吗？有没有要调整的？
用户确认后写入 Tech-Arch.md。
# <产品名称> — 技术架构
## 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)（如有）
更新 .claude/progress.json：
current_phase: "architecture"current_skill: "tech-architect"milestones 追加「技术架构已确定： 条 ADR」documents.Tech-Arch.md：exists: trueTech-Arch.md — 技术架构文档（架构总览 + ADR + 复用清单）Product-Spec-CHANGELOG.md — 追加 新增：技术架构设计与选型，<N> 条 ADR