| name | tech-stack |
| description | 撰写和维护技术选型文档（输出到 specs/tech-stack/ 目录，按分类拆分文件），覆盖前端、后端、数据库、运维、工程规范等全栈技术决策。参考技术表仅供选型参考，用户可自由选择任何技术方案——包括表中未列出的技术。所有架构图和 ER 图使用 Mermaid。 务必在以下场景使用本 skill：用户提到技术选型、tech stack、技术架构、技术方案、架构设计、数据库设计、database design、stack decisions、框架选择、技术栈、技术路线、依赖选择、工具链选型、前后端选型、基础设施选型，或者用户要求编写/修订/评审技术架构文档、讨论该用什么框架/库/工具，即使没有明确说“技术选型”。不适用于具体功能需求文档。 |
技术架构选型
本 Skill 负责技术选型文档（specs/tech-stack/ 目录，按分类拆分文件）——帮助团队将分散的技术决策统一成一组可追溯、可评审的文档。技术选型文档的核心价值是：让每个技术决策都有据可查、有理可循，避免"我以为你用的是 X"这类沟通问题。
不展开需求六段式 Specs 的写法。
原则
- 在独立文档中写清实际采用的路线与依赖，每个技术选择都应说明选择理由和对比过的备选方案——这让后来者理解决策背景，也方便未来重新评估。
- 推荐不等于强制：参考技术表（
references/tech-reference-tables.md）为每个分类提供了默认推荐方案（如后端推荐 NestJS、数据库推荐 PostgreSQL 等），供快速决策参考。但用户可以根据团队熟悉度、项目规模、业务场景选择其他技术（包括表中未列出的），只需在文档中说明选择理由即可。
- 前端框架、后端框架、数据库等核心选型均由用户根据团队熟悉度、项目规模、业务场景决定；必须明确所选路线及理由，而非罗列全部可能技术。
- Monorepo 目录约定（如采用）：
apps/ 存放业务应用/可运行项目；packages/ 存放可复用包（组件库、工具库、配置包等）。技术选型文档中应写明仓库是否采用该结构及例外说明。
- 运行时与工具链版本：技术选型文档中应明确写出项目采用的运行时版本（如 Node.js、Java 等）和包管理器版本（如 pnpm、npm、yarn 等）。版本信息应在
package.json（或等效配置）、CI 与容器配置中保持一致。
图表绘制策略
技术选型文档中凡需可视化，不使用 PlantUML、Draw.io 源文件、纯图片替代可编辑结构图等其它绘图方式（导出图若来自 Mermaid 渲染则可）。
| 场景 | 工具 | Mermaid 形式 |
|---|
| 架构图（部署、数据流） | Mermaid | flowchart / flowchart LR |
| 模块图（依赖、调用关系） | Mermaid | graph TD / graph LR |
| 流程图（请求处理、鉴权等） | Mermaid | flowchart |
| 时序图（多角色交互） | Mermaid | sequenceDiagram |
| ER 图（数据库实体关系） | Mermaid | erDiagram |
| 目录树 / 文件结构 | 纯文本树（├── └──） | — |
规则：逻辑、模块、流程、时序、架构、ER 等结构图严格使用 Mermaid 代码；目录树/文件结构使用纯文本树格式。Mermaid 是纯文本，可 Git 管理、可 diff、可 PR review。
画图时机：架构图是技术选型文档的标配，至少要有一张全局架构视图；数据库设计必须有 ER 图；前后端交互复杂的场景配时序图。
产出目录结构
技术选型文档按分类拆分为独立文件，输出到 specs/tech-stack/ 目录：
specs/tech-stack/
├── overview.md # 概述：项目形态、仓库结构、运行时版本、全局架构图
├── frontend.md # 前端：框架选型、UI 组件库、构建工具、状态管理等
├── backend.md # 后端：框架、API 风格、认证、权限、日志等
├── database.md # 数据库：数据库选型、ORM、缓存、ER 图
├── ops.md # 运维与基础设施：部署、容器化、反向代理、CI/CD
└── engineering-standards.md # 工程规范：Lint、Git 钩子、提交规范、版本管理
根据项目实际规模按需增减文件。小型项目可合并为更少的文件；大型项目可进一步拆分（如前端按应用拆分子文件）。
各文件内容指引
- overview.md：项目形态、仓库结构（Monorepo 时说明目录职责）、前后端边界；运行时与工具链版本及锁定方式；可配架构图。
- frontend.md：框架选型及理由、跨框架通用选项、UI 组件库选型；可配模块图说明应用与包关系。
- backend.md：框架选型及理由、API 风格、接口文档、参数校验、认证鉴权、权限模型、日志方案。
- database.md：数据库选型及理由、ORM 选型、缓存方案；数据库设计须用 Mermaid
erDiagram 给出核心实体、字段与关系。
- ops.md（可选）：部署方案、反向代理、容器化、CI/CD 流水线。根据项目实际部署需求决定是否需要。
- engineering-standards.md：Lint/格式化、Git 钩子、提交规范、版本管理、CLI 工具等（按需取舍并写明版本或范围）。
每一节的技术选择都应包含简短的选型理由（一两句话即可），说明为什么选它、有没有考虑过其他方案。这让文档不仅是一份清单，更是一份决策记录。
参考技术表
覆盖运行时与包管理、前端、UI 与组件库、后端、数据库、运维基础设施、工程规范等类别。写入文档时对每项标注「采用 / 不采用 / 待定」并说明理由。
推荐 ≠ 强制：参考技术表中标注的「推荐」项为默认建议方案，用户可根据实际情况选择其他技术（包括表中未涵盖的），只需说明选择理由。
全部参考技术表见 → references/tech-reference-tables.md
执行方式
- 根据用户已给约束（团队规定、遗留栈、云厂商等）收敛选项；参考技术表中标注「推荐」的为默认建议方案，推荐不等于强制，用户可选择表中未列出的技术。未采用的技术不必写入最终文档，或标注「未采用」。
- 输出物为
specs/tech-stack/ 目录下按分类拆分的 Markdown 文件，便于纳入版本库并与实现保持一致；与结构、流程、协作、数据库实体关系相关的说明应配 Mermaid 图（含 erDiagram），避免仅用长段落描述。
- 若用户未给出运行时版本：应结合当前稳定版本与依赖最低要求，在选型文档中给出建议版本并提醒同步写入相应配置文件。
常见问题与处理
- 用户只说"帮我做个技术选型"：先确认项目类型（Web 应用？移动端？管理后台？）、团队规模、是否有已有技术栈约束，再给出选型建议。
- 用户要求对比两个技术方案：从功能覆盖度、生态成熟度、学习曲线、团队熟悉度、社区活跃度等维度做对比表，给出推荐及理由。
- 版本锁定不一致：检查
package.json 的 engines/packageManager、.nvmrc、CI 配置、Docker 镜像中的版本，如有不一致应在文档中指出并给出统一方案。
