@haaaiawd/anws 2.3.0 → 2.4.1

package/templates/.agents/skills/tech-evaluator/SKILL.md

@@ -1,144 +1,252 @@
----
-
-## name: tech-evaluator
-
-description: 评估技术栈选项，使用加权决策矩阵和 ATAM 方法论产出架构决策记录 (ADR)。
-
-# 技术评估师手册 (The Tech Evaluator's Manual)
-
-> "没有最好的技术栈，只有最适合的技术栈。" —— ThoughtWorks Technology Radar
-
-本技能基于 **SEI 的 ATAM (Architecture Tradeoff Analysis Method)** 和 **加权决策矩阵** 方法论。
-
----
-
-## 强制深度思考
-
-> [!IMPORTANT]
-> 在进行评估之前，你**必须**使用 `sequential-thinking` skill，视复杂情况组织 **3—7 个 thought** 推理。
-> 思考内容例如：
->
-> 1. "用户的核心需求是什么？必须支持哪些场景？"
-> 2. "团队目前熟悉什么技术？学习新技术的时间预算是多少？"
-> 3. "预算约束是什么？云服务成本敏感吗？"
-> 4. "这个项目预期规模是什么？需要支持多少并发用户？"
-> 5. "有没有合规要求（GDPR、等保）影响技术选择？"
-
----
-
-## 任务目标
-
-产出 **ADR (Architecture Decision Record)** 文档，记录技术栈决策及其理由。
-
----
-
-## 评估流程 (The Evaluation)
-
-### 第一步：收集约束 (Gather Constraints)
-
-**必须从用户处获取**:
-
-- **功能需求**: 核心功能列表
-- **非功能需求**: 性能目标、可用性要求、安全等级
-- **团队情况**: 人数、技能栈、学习意愿
-- **预算**: 开发预算、运维预算、时间预算
-- **特殊约束**: 合规要求、现有系统集成、客户指定技术
-
-### 第二步：识别候选技术栈 (Identify Candidates)
-
-**2025 主流技术栈参考**:
-
-
-| 场景         | 推荐栈                         | 备选                          |
-| ---------- | --------------------------- | --------------------------- |
-| **Web 全栈** | Next.js + TypeScript        | Nuxt, SvelteKit             |
-| **后端 API** | Go / Rust / Node.js         | Python FastAPI, Java Spring |
-| **桌面应用**   | Tauri (Rust + Web)          | Electron, Flutter Desktop   |
-| **移动应用**   | React Native / Flutter      | Swift/Kotlin 原生             |
-| **AI/ML**  | Python + PyTorch/TensorFlow | Rust (Candle), Julia        |
-| **数据密集**   | PostgreSQL + TimescaleDB    | ClickHouse, DuckDB          |
-
-
-### 第三步：12 维度评估 (12-Dimension Evaluation)
-
-使用以下矩阵对每个候选栈打分 (1-5 分):
-
-
-| 维度            | 权重建议 | 评估问题            |
-| ------------- | ---- | --------------- |
-| **需求匹配**      | —    | 能否实现所有核心功能？     |
-| **扩展性**       | —    | 能否支撑 10x 增长？    |
-| **性能**        | —    | 能否满足响应时间/吞吐量要求？ |
-| **安全性**       | —    | 内置安全特性？合规支持？    |
-| **团队技能**      | —    | 团队熟悉程度？学习曲线？    |
-| **人才市场**      | —    | 招人容易吗？          |
-| **开发速度**      | —    | 能否快速迭代？         |
-| **TCO (总成本)** | —    | 开发+运维+许可证成本？    |
-| **社区生态**      | —    | 库/工具丰富度？问题解答速度？ |
-| **长期维护**      | —    | 技术寿命？LTS 支持？    |
-| **集成能力**      | —    | 与现有系统/第三方服务集成？  |
-| **AI 就绪**     | —    | 集成 AI/LLM 的便利性？ |
-
-
-### 第四步：权衡分析 (Trade-off Analysis)
-
-使用 **ATAM 方法**:
-
-1. 识别**质量属性场景** (如 "1000 并发用户时响应 < 200ms")
-2. 评估每个候选栈对场景的**支持程度**
-3. 识别**权衡点** (如 "选 Go 性能好但团队需学习")
-4. 识别**风险点** (如 "选新框架可能踩坑")
-
-### 第五步：产出 ADR (Generate ADR)
-
-你**必须**创建 `ADR_001_TECH_STACK.md`，并将其写入 `.anws/v{N}/03_ADR/`。
-
----
-
-## ADR 输出模板
-
-```markdown
-# ADR-001: 技术栈选择
-
-## 状态
-Accepted / Proposed / Deprecated
-
-## 背景
-[项目背景和约束描述]
-
-## 决策
-[选择的技术栈及核心理由]
-
-## 候选方案对比
-
-| 候选 | 总分 | 优势 | 劣势 |
-|------|------|------|------|
-| 方案 A | 42/60 | ... | ... |
-| 方案 B | 38/60 | ... | ... |
-
-## 权衡点
-- [权衡 1]
-- [权衡 2]
-
-## 后果
-- 正面: [...]
-- 负面: [...]
-- 需要的后续行动: [...]
-```
-
----
-
-## 老师傅守则
-
-1. **"无聊"技术优先**: 除非有充分理由，优先选择成熟稳定的技术。
-2. **创新预算有限**: 每个项目只有 1-2 个"创新点"配额，其余用"无聊"技术。
-3. **团队能力为王**: 再好的技术，团队不会用也是白搭。
-4. **TCO 不只是钱**: 时间成本、认知成本也是成本。
-
----
-
-## 工具箱
-
-- `references/ADR_TEMPLATE.md`: ADR 模板
-- `references/TECH_RADAR_2025.md`: 2025 技术雷达参考
-
+---
+name: tech-evaluator
+description: 服务于 `/genesis` Step 3「技术选型」：以 ATAM 与 12 维加权矩阵评估候选栈，产出可追溯的对比结论与 ADR 升格素材；不写正式 ADR 文件（落盘在 Step 5）。优先读本 SKILL 旁 `references/`。
+---
+
+# 技术评估师手册 — Genesis Step 3
+
+> "没有最好的技术栈，只有最适合的技术栈。" —— ThoughtWorks Technology Radar
+
+本技能基于 **SEI 的 ATAM (Architecture Tradeoff Analysis Method)** 与 **加权决策矩阵**。在 **`/genesis`** 中与 **Step 3** 绑定；ADR 的**正式写入**与编号治理以 **Step 5** 与 `genesis.md` 为准。
+
+---
+
+## CRITICAL /genesis 门禁（本线专用收口）
+
+> [!IMPORTANT]
+>
+> - **`/genesis` Step 3**：**只输出评估结果与 Markdown 对比素材**，**不得**在本步创建或修改 `.anws/v{N}/03_ADR/` 下任何 ADR 文件。原因见 `genesis.md` Step 3 / Step 5：ADR 为正式决策记录，须在 Step 5 完整审视后落盘。
+> - **Step 5 落盘目标**（供下游引用，非 Step 3 执行项）：将 Step 3 对比表升格为 `.anws/v{N}/03_ADR/ADR_001_TECH_STACK.md`（及姊妹 ADR），**章节结构以 `references/ADR_TEMPLATE.md` 为唯一权威**。
+> - 若宿主会话声明 **非** `/genesis` 或显式授权「本步即写 ADR」，以**当场工作流**为准；默认仍按 Step 3 不写 ADR。
+
+> [!NOTE]
+> **ADR 时序**：Step 3 只产出评估与对比素材，不写 `03_ADR/`；Step 4 产出系统边界与 `02_*`；Step 5 再升格 ADR，使影响范围与真实系统 ID 对齐。阶段表与四点论证见 **`genesis.md`** Step 3 的 NOTE。若会话非 `/genesis` 或用户授权本步写 ADR，以当场工作流为准。
+
+---
+
+## CRITICAL spec 产出契约（Step 3 交付物）
+
+> [!IMPORTANT]
+>
+> - **可核对**：约束块须覆盖功能需求、非功能需求、团队、预算、特殊约束；缺的项写「未提供—评估基于假设 H-…」，不得静默省略。
+> - **可计算**：每个候选栈须有 12 维得分表（1–5）或逐维「不适用 + 原因」；禁止只给总分不给细表。
+> - **可推演**：ATAM 段落须含至少一个**质量属性场景**、若干**权衡点**、若干**风险点**；不得用形容词堆叠代替场景。
+> - **可升格**：最终对比表须能**无损映射**到 **`references/ADR_TEMPLATE.md`** 的章节与必填节，供 Step 5 粘贴与润色。
+> - **验证策略显式**：须回答或标注待决：单测 / 集成 / E2E 侧重、冒烟 / 回归门禁、质量门禁落在 PR / INT / 预发 / 发布的哪一层（与 `genesis.md` Step 3 要求一致）。
+> - **单一真源**：数值与结论以 Step 3 产出表为准；Step 5 仅做编辑与状态流转，不得在无新证据时反向改分。
+
+---
+
+## 强制深度思考
+
+> [!IMPORTANT]
+> 在开始评估前**必须**调用 `sequential-thinking` skill，按复杂度组织 **3—7 个 thought**，例如：
+>
+> 1. 用户核心场景与必须支持的用例边界是什么？
+> 2. 团队熟悉度与可接受的学习成本？
+> 3. 预算与云 / 许可证 TCO 敏感度？
+> 4. 预期规模与并发 / 数据量级？
+> 5. 合规（GDPR、等保等）是否一票否决某些栈？
+
+---
+
+## 任务目标（Step 3）
+
+在**不写 ADR 文件**前提下，产出：
+
+1. 结构化**约束摘要**与**候选栈列表**；
+2. **12 维打分矩阵**与加权汇总说明（权重须声明或采用本文建议并说明）；
+3. **ATAM 权衡与风险**短文；
+4. 供 Step 5 直接使用的 **Markdown 候选方案对比总表**。
+
+---
+
+## 评估流程 (The Evaluation)
+
+### 第一步：收集约束 (Gather Constraints)
+
+**必须从用户或已加载工件取得**（不足的按 spec 契约标注假设）：
+
+- **功能需求**：核心能力列表（可引用 `01_PRD.md`）。
+- **非功能需求**：性能、可用性、安全等级。
+- **团队情况**：人数、技能栈、学习意愿。
+- **预算**：开发、运维、时间。
+- **特殊约束**：合规、存量系统集成、客户指定技术。
+- （如已执行 Step 2.5）`/explore` 研究结论中的证据与备选方案。
+
+#### 做什么
+
+固化输入边界，列出缺口与假设编号。
+
+#### 为什么
+
+避免无约束的偏好打分和不复现的结论。
+
+#### 怎么验收
+
+输出中可出现「假设 H-xx」对照表；无静默缺项。
+
+---
+
+### 第二步：识别候选技术栈 (Identify Candidates)
+
+**主流技术栈参考**（可按项目替换或增删）：
+
+
+| 场景         | 推荐栈                         | 备选                          |
+| ---------- | --------------------------- | --------------------------- |
+| **Web 全栈** | Next.js + TypeScript        | Nuxt, SvelteKit             |
+| **后端 API** | Go / Rust / Node.js         | Python FastAPI, Java Spring |
+| **桌面应用**   | Tauri (Rust + Web)          | Electron, Flutter Desktop   |
+| **移动应用**   | React Native / Flutter      | Swift/Kotlin 原生             |
+| **AI/ML**  | Python + PyTorch/TensorFlow | Rust (Candle), Julia        |
+| **数据密集**   | PostgreSQL + TimescaleDB    | ClickHouse, DuckDB          |
+
+
+#### 做什么
+
+列出 2 个及以上**具名**候选（语言 / 框架 / 关键中间件级），附一句选型范围说明。
+
+#### 为什么
+
+单候选无权衡，无法完成 ATAM。
+
+#### 怎么验收
+
+每个候选可被独立打分；无匿名「方案 A/B」。
+
+---
+
+### 第三步：12 维度评估 (12-Dimension Evaluation)
+
+对每个候选按 1–5 分打分：
+
+
+| 维度            | 权重建议 | 评估问题            |
+| ------------- | ---- | --------------- |
+| **需求匹配**      | — | 能否实现所有核心功能？     |
+| **扩展性**       | — | 能否支撑 10x 增长？    |
+| **性能**        | — | 能否满足响应时间 / 吞吐量？ |
+| **安全性**       | — | 内置安全与合规支持？      |
+| **团队技能**      | — | 熟悉度与学习曲线？       |
+| **人才市场**      | — | 招聘与外包可得性？       |
+| **开发速度**      | — | 迭代与交付速度？        |
+| **TCO (总成本)** | — | 开发 + 运维 + 许可证？   |
+| **社区生态**      | — | 库、工具与排障资源？      |
+| **长期维护**      | — | 技术寿命与 LTS？       |
+| **集成能力**      | — | 与存量与第三方集成？      |
+| **AI 就绪**     | — | 接入 AI / LLM 的便利度？ |
+
+
+#### 做什么
+
+填满矩阵；声明权重（均匀或加权）并计算可比总分或档级。
+
+#### 为什么
+
+多维透明，便于 Step 5 写入 ADR 证据节。
+
+#### 怎么验收
+
+表在 Markdown 中可复算；不适用维度有单行解释。
+
+---
+
+### 第四步：权衡分析 (Trade-off Analysis) — ATAM
+
+1. 识别**质量属性场景**（例：「1000 并发用户时 P95 < 200ms」）。
+2. 各候选对该场景的**支持程度**分级说明。
+3. 列出**权衡点**（例：性能好 vs 团队学习成本）。
+4. 列出**风险点**（例：新版本框架成熟度）。
+
+#### 做什么
+
+把「为什么不是第二名」说清楚。
+
+#### 为什么
+
+ADR 核心价值在取舍与后果，不单是赢家声明。
+
+#### 怎么验收
+
+至少 1 个场景 + 若干权衡 / 风险，可与候选表交叉引用。
+
+---
+
+### 第五步：产出 ADR 升格素材（Step 3，非落盘）
+
+在 **`/genesis` Step 3** 下，你**不得**新建或修改 `03_ADR/*.md`。产出完整 **Markdown** 对比结论与升格素材，使 Step 5 能对照 **`references/ADR_TEMPLATE.md`** 无损升格；段落与章节可标 `Proposed` / `待定`。
+
+若工作流显式要求本步预创建占位文件（极少见），仅允许空文件或 MANIFEST 约定路径，**不得**将占位等同于已接受 ADR。
+
+**禁止**：在本 SKILL 内再嵌一套与 **`references/ADR_TEMPLATE.md`** 重复的完整 ADR 范文；章节疑问一律以该文件为准。
+
+#### 做什么
+
+生成完整对比与符合 `references/ADR_TEMPLATE.md` 场域的草稿（内存或会话消息中的 Markdown）。
+
+#### 为什么
+
+与 `genesis` 决策关口对齐，避免未成文的早期 ADR。
+
+#### 怎么验收
+
+父代理能在 Step 5 打开 `references/ADR_TEMPLATE.md` 并对齐各节而无信息断档。
+
+---
+
+## ALPHA 决策守则
+
+1. **"无聊"技术优先**：除非有充分理由，选成熟栈。
+2. **创新预算有限**：每项目 1–2 个创新点配额，其余求稳。
+3. **团队能力为王**：再好的技术用不了等于零。
+4. **TCO 不只是钱**：时间与认知负载计入成本。
+
+---
+
+## references 与同 bundle 路径说明
+
+与本 SKILL 同级的 **`references/ADR_TEMPLATE.md`** 供 ADR 骨架引用。读取时 **仅以本 SKILL 旁 `references/`** 为准。
+
+| 文件 | 用途 |
+|------|------|
+| `references/ADR_TEMPLATE.md` | ADR 体格与必填节 |
+
+---
+
+## 执行形态与子代理编排
+
+### 做什么
+
+- **优先**：若宿主提供 **AGENT / 子代理**：可委派**候选搜集**、**单候选多维打分草稿**或 **ATAM 风险草案**；编排侧下发本文 **spec 产出契约 + 门禁 + ADR 模板字段**，收束后为**单一合并稿**。
+- **父代理**：持有 `sequential-thinking` **必须**在主会话或由明确指定的合并代理执行一轮完整 thought 链后再定稿；子代理不可替代该义务除非工作流写明。
+- **回退**：无子代理时，由当前会话完整执行全流程。
+
+### 为什么
+
+并行搜集与串行裁决分离，降低遗漏维度的概率。
+
+### 怎么验收
+
+合并稿仍满足 spec 契约；无互相矛盾的分数或重复候选名；`/genesis` Step 3 **仍无** `03_ADR` 写操作。
+
+---
+
+## Handoff checklist（编排 / 子代理 / Step 5）
+
+- [ ] 约束与假设 H-xx 已列全或显式欠缺已声明。
+- [ ] 12 维矩阵 + 权重说明完整。
+- [ ] ATAM：场景、权衡、风险齐全。
+- [ ] Markdown 对比表可映射 `references/ADR_TEMPLATE.md`。
+- [ ] 验证策略与测试分层门禁已作答或单列「待 Step 5 / design-system」。
+- [ ] **`/genesis` Step 3**：确认未创建 / 修改 `03_ADR/*.md`。
+
+---
+
+<completion_criteria>
+- `sequential-thinking` 已完成 3—7 thought，且可在输出中见其结论被评估吸收。
+- 交付物满足 **CRITICAL spec 产出契约**（可核对 / 可计算 / 可推演 / 可升格 / 验证策略显式）。
+- 在 `/genesis` Step 3 默认路径下，**未**对 `.anws/v{N}/03_ADR/` 进行 ADR 落盘。
+- Handoff checklist 全部为真或显式豁免项已记入最后一节「未决事项」。
+- 与同一会话内其它 skill 一致，均取自工作区 **`.agents/skills/`**。
+</completion_criteria>