soloforge 1.1.46 → 1.1.47

package/templates/build//350/260/203/350/257/225/346/216/222/346/237/245.md

@@ -1,105 +1,74 @@
 ---
-id: ka-procedure-调试排查流程
+id: ka-guidance-调试排查
 kind: guidance
 title: 调试排查
 sync_policy: copy_to_project
 status: active
 triggers:
+  - bug
   - 调试
+  - 排查
+  - 报错
+  - 异常
+  - 失败
   - 排障
-  - 排查问题
-  - bug定位
-  - 问题排查
-  - 线上排查
-  - 异常排查
-  - 错误定位
+  - 定位
   - 日志排查
   - 缺陷修复
-  - Bug修复
-  - 问题修复
-  - 异常修复
-  - 错误修复
-  - bug fix
-  - 缺陷处理
+  - bugfix
 extra:
   name: debug-investigation
-  type: procedure
   scope:
-    - backend
-    - frontend
+    - '*'
   products:
     - '*'
+  type: procedure
   lifecycle_status: active
-  version: 1.2.0
-  last_reviewed: '2026-06-04'
-  domain:
-    - build
-    - verify
+  version: 1.0.0
+  last_reviewed: '2026-06-17'
   verification_layer: L2
   stage: build
+  domain: build
   owner_mechanism: mc-verifier
 ---
 
-## 适用场景
-功能异常、性能问题、线上报错等需要定位根因的场景。遵循「先观察后假设再验证」的原则。
+# 调试排查：出了 bug 怎么定位根因
+
+> 吸收旧的「调试排查」「Bug分析」「调试方法论」「全栈流程修复」「新老逻辑比对日志」。
+> [[工程执行总纲]] 思考先行：禁止只修表象不找根因。
+
+## 第一步：稳定复现
+
+- 先找到稳定复现路径（无复现=瞎改）
+- 记录复现步骤、环境、输入、预期 vs 实际
+
+## 第二步：定位根因（不是表象）
 
-## 四阶段调试法
-1. **观察阶段**：获取具体操作步骤、输入数据、环境信息，确认可复现
-2. **假设阶段**：根据观察提出一个假设，不要同时提出多个假设
-3. **验证阶段**：设计最小实验验证假设，记录结果（包括被否定的假设）
-4. **修复阶段**：确认根因后编写最小修复 + 回归测试
+- 读日志/堆栈，追到真实失败点
+- 区分：症状（报什么）vs 根因（为什么报）
+- 二分法/日志插桩缩小范围
+- 靠证据，不靠猜（[[证据驱动与反幻觉]]）
 
-## 步骤
-1. 复现问题：获取具体操作步骤、输入数据、环境信息
-2. 确定影响范围：是全部用户还是特定条件？是偶发还是必现？
-3. 查看日志：根据时间窗口搜索 traceId，查看完整请求链路日志
-4. 查看监控：接口响应时间、错误率、资源使用（CPU/内存/磁盘）
-5. 定位代码：根据日志中的异常堆栈定位到具体文件和方法
-6. 分析根因：区分是代码 Bug、配置错误、数据异常还是环境问题
-7. 验证假设：在本地或测试环境复现并验证根因（一次只验证一个假设）
-8. 编写最小修复：修复范围只覆盖确认的根因，禁止顺手改其他代码
-9. 使用 RED-GREEN 验证：回退修复 → 确认失败 → 恢复修复 → 确认通过
-10. 添加回归测试（防止同类问题再发生）
+## 第三步：最小修复
 
-## 调试报告格式
+- 只改根因点，不扩大范围（[[工程执行总纲]] 精准修改）
+- 改老系统先比对新老逻辑差异
+- 修复限于同一上下文；跨模块回到任务拆解
 
-### 基本信息
-| 项目 | 内容 |
-|------|------|
-| 问题描述 | <!-- 现象描述 --> |
-| 影响范围 | <!-- 用户/模块/接口 --> |
-| 复现条件 | <!-- 步骤 --> |
-| 严重程度 | P0/P1/P2 |
+## 第四步：回归测试
 
-### 调试过程
-| 阶段 | 假设 | 验证方法 | 结果 |
-|------|------|---------|------|
-| 观察 | — | <!-- 日志/监控 --> | <!-- 发现 --> |
-| 假设 1 | <!-- 假设内容 --> | <!-- 验证方法 --> | 确认/否定 |
-| 假设 2 | <!-- 假设内容 --> | <!-- 验证方法 --> | 确认/否定 |
+- 先写复现测试（证明 bug 存在）→ 修复后证明 bug 消失
+- 跑相关测试，确认没引入新问题
 
-### 修复方案
-| 修改文件 | 修改内容 | 关联切片 |
-|---------|---------|---------|
-| <!-- 文件路径 --> | <!-- 修改说明 --> | SLC-{模块}-{序号} |
+## 第五步：防复发
 
-### RED-GREEN 验证
-- [ ] 回退修复后测试失败（RED）
-- [ ] 恢复修复后测试通过（GREEN）
+- 补测试守住这个修复
+- 想想同类问题会不会在别处出现（举一反三）
+- 必要时沉淀成规则/检查
 
-## 检查点
-- [ ] 问题可稳定复现（或记录了偶现条件）
-- [ ] 日志中有 traceId 可追踪完整链路
-- [ ] 调试过程有假设-验证记录
-- [ ] 根因已确认而非停留在表象
-- [ ] 修复范围仅限确认的根因
-- [ ] 修复包含回归测试
+## 禁止
 
-## 注意事项
-- 不要在没有复现的情况下直接修改代码
-- 日志排查优先使用 traceId，避免大海捞针
-- 性能问题优先看慢查询日志和接口耗时
-- 同一现象修复失败 3 次后停止猜测，重新审视假设，考虑是否为架构问题
-- 禁止通过删除断言、增加 sleep、降低覆盖率、增加 mock 来制造通过
-- 调试修复须遵守 SED-04（禁止跨任务修改），修复范围仅限当前切片涉及文件
-- 修复范围超出当前切片涉及文件时，须触发重规划（参见切片计划 §7 动态重规划）
+- 不复现就改（违规，改了也不知道对不对）
+- 只修表象不找根因（违规，bug 会回来）
+- 改一大片"可能相关"的代码（违规，扩大风险）
+- 修复后不写回归测试（违规，无法证明修好）

package/templates/build//351/207/215/346/236/204/346/226/271/346/263/225.md

@@ -0,0 +1,68 @@
+---
+id: ka-guidance-重构方法
+kind: guidance
+title: 重构方法
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 重构
+  - refactor
+  - 解耦
+  - 耦合
+  - 重构方案
+  - 改善代码
+  - 抽象
+extra:
+  name: refactoring-method
+  scope:
+    - '*'
+  products:
+    - '*'
+  type: procedure
+  lifecycle_status: active
+  version: 1.0.0
+  last_reviewed: '2026-06-17'
+  verification_layer: L2
+  stage: build
+  domain: build
+  owner_mechanism: mc-code-maintainability-observability-contract
+---
+
+# 重构方法：怎么改老代码不翻车
+
+> 吸收旧的「重构方案」「重构流水线」「耦合检测」「OOD设计摘要」。
+
+## 何时该重构（先想清楚）
+
+- 代码确实难以理解/修改/扩展，且有测试保护
+- 重构服务于当前目标，不是"看着不爽"
+
+## 何时不该重构
+
+- 没有测试覆盖的代码（先补测试）
+- 跟当前任务无关的顺手重构（[[工程执行总纲]] 精准修改：禁止）
+- 需求紧急、没有回滚余量时
+
+## 重构步骤
+
+1. **先有测试**：覆盖现有行为（重构后行为不变是验证标准）
+2. **小步前进**：每步可编译可测试，不一次性大改
+3. **每步验证**：跑测试，绿了再下一步
+4. **新老逻辑比对**（改老系统）：行为一致才算通过
+
+## 解耦判断
+
+- 检测高耦合点（模块间循环依赖、上帝对象、散弹式修改）
+- 用接口/事件/适配器解耦，但不过度抽象（[[工程执行总纲]] 简单优先）
+- 引入新抽象前说明必要性
+
+## 禁止
+
+- 无测试就重构（违规，无法验证行为不变）
+- 顺手重构无关模块（违规）
+- 大爆炸式重构（违规，无法回滚）
+- 为重构而抽象（违规，增加复杂度）
+
+## 验证
+
+重构后必须给出：测试全绿 + 行为不变的证据（新老比对/覆盖率不降）。

package/templates/design/API/346/216/245/345/217/243/350/247/204/346/240/274/346/226/207/346/241/243.md

@@ -12,8 +12,8 @@ extra:
     - frontend
   products:
     - '*'
-  version: 1.2.0
-  last_reviewed: '2026-06-04'
+  version: 2.0.0
+  last_reviewed: '2026-06-17'
   type: artifact
   domain: design
   stage: design
@@ -22,29 +22,33 @@ extra:
 
 # API 接口规格文档
 
+> **产物定位**：涉及前后端接口对接时产出（按需）。把接口契约先于实现定清楚，避免前端等后端。
+> **核心纪律**：契约先行（[[编码纪律]]）；每个 endpoint 有验收场景 + 验证证据（[[证据驱动与反幻觉]]）。
+> **完成判定**：见文末，每个 endpoint 须满足。
+
 OpenAPI 权威路径: `docs/api/openapi.yaml`
 
 ## Endpoint: `METHOD /api/v1/resource`
 
-> **接口编号**: `DD-A01`（每个 endpoint 唯一，供切片计划/代码审查引用，cross_validation 据此校验一致性+覆盖）
-> **关联需求**: `REQ-001`（本接口实现的需求编号，供 cross_validation 校验与需求分析一致；多个用 `/` 分隔）
+> **接口编号**: `DD-A01`（每个 endpoint 唯一，供切片计划/代码审查引用）
+> **关联需求**: `REQ-001`（供 cross_validation 校验与需求一致；多个用 `/` 分隔）
 
 ### 基本信息 [Always — 每个 endpoint 必填]
 
 | endpoint_id | 用途 | 调用端 | 权限 | 幂等 | 限流 | 副作用 |
 |-------------|------|--------|------|------|------|--------|
 
-### 请求 Header 字段 [Ask first — 有认证/自定义 Header 时必填]
+### 请求 Header 字段 [有认证/自定义 Header 时必填]
 
 | 字段路径 | 类型 | 必填 | 格式/约束 | 数据映射 | 说明 | 示例 |
 |----------|------|------|-----------|----------|------|------|
 
-### 请求 Path / Query 字段 [Ask first — 有路径/查询参数时必填]
+### 请求 Path / Query 字段 [有路径/查询参数时必填]
 
 | 字段路径 | 类型 | 必填 | 默认值 | 格式/约束 | 说明 | 示例 |
 |----------|------|------|--------|-----------|------|------|
 
-### 请求体字段 [Ask first — 有请求体时必填]
+### 请求体字段 [有请求体时必填]
 
 | 字段路径 | 类型 | 必填 | 可空 | 枚举/格式/校验 | 数据映射 | 说明 | 示例 |
 |----------|------|------|------|----------------|----------|------|------|
@@ -64,32 +68,31 @@ OpenAPI 权威路径: `docs/api/openapi.yaml`
 | 场景 | 输入 | 预期响应 | 数据/状态变化 | 验证证据 |
 |------|------|----------|---------------|----------|
 
-### 枚举值定义 [Ask first — 有枚举字段时必填]
+### 枚举值定义 [有枚举字段时必填]
 
 | 枚举名 | 值 | 含义 |
 |--------|------|------|
 
-### 页面交互映射 [Ask first — 前端直接调用的接口必填]
+### 页面交互映射 [前端直接调用的接口必填]
 
 | 页面操作 | 触发接口 | 加载状态 | 成功行为 | 失败行为 |
 |---------|---------|---------|---------|---------|
 
-### 接口规范检查 [Always — 每个 endpoint 必填]
-
-- [ ] 是否定义了接口版本号和演进策略（如 /api/v1/）
-- [ ] 是否有幂等设计（写接口需标注幂等键或唯一约束）
-- [ ] 错误码体系是否完整（业务码 + HTTP 状态码双映射）
-- [ ] 是否有分页参数上限限制（防止恶意大翻页）
-- [ ] 是否有接口限流策略（QPS/并发上限）
-- [ ] 批量操作是否有数量上限（≤ 500 条）
-
-### AI Agent 格式校验 [Always — 每个 endpoint 必填]
-
-- [ ] 每个 endpoint_id 全局唯一且遵循命名规范（{资源}-{动作}）
-- [ ] 所有 数据映射 字段已精确到 表名.字段名 格式（禁止仅写表名）
-- [ ] 所有 类型 字段使用标准类型（string/integer/number/boolean/array/object/date/datetime/enum）
-- [ ] 所有 格式/约束 字段使用标准约束格式（min:0,max:100 或 pattern:regex）
-- [ ] 错误映射表中每个 HTTP 状态码至少对应一个业务码
-- [ ] 验收场景表中每行必须包含 验证证据（不得为空）
-- [ ] 枚举值定义覆盖了所有字段中出现的枚举类型
-- [ ] 页面交互映射覆盖了所有涉及前端调用的接口
+## 接口规范检查
+
+- [ ] 接口有版本号和演进策略（如 /api/v1/）
+- [ ] 写接口有幂等设计（幂等键或唯一约束）
+- [ ] 错误码体系完整（业务码 + HTTP 状态码双映射）
+- [ ] 分页参数有上限（防恶意大翻页）
+- [ ] 接口有限流策略（QPS/并发上限）
+- [ ] 批量操作有数量上限（≤ 500 条）
+
+## 完成判定（每个 endpoint 须满足）
+
+- [ ] endpoint_id 全局唯一且遵循命名规范（{资源}-{动作}）
+- [ ] 所有 数据映射 字段精确到 表名.字段名（禁止仅写表名）
+- [ ] 所有 类型 用标准类型（string/integer/number/boolean/array/object/date/datetime/enum）
+- [ ] 错误映射表每个 HTTP 状态码至少对应一个业务码
+- [ ] 每个验收场景有验证证据（不得为空）
+- [ ] 枚举值定义覆盖所有枚举字段
+- [ ] 涉及前端调用的接口有页面交互映射

package/templates/design/enforced.md

@@ -2,100 +2,70 @@
 id: design-enforced
 kind: enforced
 gate: design-gate
-title: design阶段强制检查清单
+title: design 阶段强制检查清单
 sync_policy: engine_only
 status: active
+extra:
+  owner_mechanism: mc-stage-gate-engine
 checks:
-  - id: ARC-01
-    executor: regex_pattern_scan
-    rule: "Controller 禁止包含业务逻辑（计算/校验等应下沉 Service）"
-    severity: error
-    check_type: deterministic
-    pattern: '/\bclass\s+\w*Controller\b[\s\S]{0,500}\b(if|for|while|calculate|compute)\s*\(/'
-    languages: [java]
-    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无 Controller 含业务逻辑命中）"]
-    gate: verify-gate
-    target: "self"
-  - id: ARC-02
-    executor: regex_pattern_scan
-    rule: "禁止 Entity 直接暴露给外部接口，必须用 DTO"
-    severity: error
-    check_type: deterministic
-    pattern: '/\bpublic\s+\w*Entity\b\s+\w+\s*\(/'
-    languages: [java]
-    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无 Entity 直接暴露命中）"]
-    gate: verify-gate
-    target: "self"
-  - id: ARC-03
-    executor: regex_pattern_scan
-    rule: "写操作（save/create/update/delete）必须有 @Transactional"
-    severity: error
-    check_type: deterministic
-    pattern: '/\.(save|insert|update|delete|remove|create)\s*\(/'
-    languages: [java]
-    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无写操作缺事务命中）"]
-    gate: verify-gate
-    target: "self"
-  - id: ARC-04
-    executor: regex_pattern_scan
-    rule: "禁止直接 new Service/Repository/Mapper/Manager，必须依赖注入"
-    severity: error
+  # —— 产物结构完整性（document_structure，逼产物质量）——
+  - id: REQ-STRUCT
+    executor: document_structure
     check_type: deterministic
-    pattern: '/\bnew\s+\w*(Service|Repository|Repo|Dao|Mapper|Manager)\s*\(/'
-    languages: [java]
-    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无直接 new 服务对象命中）"]
-    gate: verify-gate
-    target: "self"
-  - id: ARC-06
-    executor: regex_pattern_scan
-    rule: "前端 API 调用必须封装到 service 层，禁止组件内直接 fetch/axios"
     severity: error
+    gate: design-gate
+    required_artifact: 需求分析模版
+    rule: "需求分析文档须含「根本目标（fundamental_need）」「功能点清单」「非功能需求」章节"
+    evidence_required:
+      - "docs/context/需求分析.md"
+    target: self
+  - id: ARCH-STRUCT
+    executor: document_structure
     check_type: deterministic
-    pattern: '/\b(fetch|axios)\s*\(/'
-    languages: [ts]
-    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无组件直接 API 调用命中）"]
-    gate: verify-gate
-    target: "self"
-  - id: ARC-07
-    executor: regex_pattern_scan
-    rule: "禁止 @Autowired + @Lazy 循环依赖"
     severity: error
+    gate: design-gate
+    required_artifact: 架构设计模版
+    rule: "架构设计文档须含「约束条件」「安全架构」「风险与回滚」章节"
+    evidence_required:
+      - "docs/architecture/01-架构设计文档.md"
+    target: self
+  - id: DB-STRUCT
+    executor: document_structure
     check_type: deterministic
-    pattern: '/@Autowired[\s\S]{0,50}@Lazy|@Lazy[\s\S]{0,50}@Autowired/'
-    languages: [java]
-    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无循环依赖命中）"]
-    gate: verify-gate
-    target: "self"
-  - id: ARC-08
-    executor: regex_pattern_scan
-    rule: "Service 层禁止直接操作 HttpServletRequest/Response"
     severity: error
+    gate: design-gate
+    required_artifact: 数据库设计文档模版
+    rule: "数据库设计文档须含「实体与关系」「表字段与敏感级别」章节"
+    evidence_required:
+      - "docs/design/01-数据库设计文档.md"
+    target: self
+  - id: API-STRUCT
+    executor: document_structure
     check_type: deterministic
-    pattern: '/\bHttpServletRequest\b|\bHttpServletResponse\b/'
-    languages: [java]
-    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无 Service 操作 HttpServlet 命中）"]
-    gate: verify-gate
-    target: "self"
+    severity: warning
+    gate: design-gate
+    required_artifact: API接口规格文档模版
+    rule: "API 接口规格文档须含「响应体字段」「错误与副作用」「验收场景」核心 section"
+    evidence_required:
+      - "docs/design/02-API接口规格文档.md"
+    target: self
+  # —— 设计主观规则（semantic，advisory 不阻断，随 Reflexion 反馈供 AI 评判）——
   - id: DES-C-REVIEW
     executor: semantic
-    rule: "客户端 AI 评判设计主观规则（流程约束类，不可代码确定性判定）：① 每条架构决策须有对应 ADR，禁止口头决策不留记录（ADR-HARD-01）② ADR 状态变更须经用户确认，Agent 不得自动变更（ADR-HARD-02）③ 跳过决策研讨须用户明确声明，Agent 不得自行跳过（ADR-HARD-04）④ 技术选型须有 NFR 量化对比而非仅凭业界主流（ARCH-MOD-04）"
+    rule: "客户端 AI 评判设计主观规则：① 每条架构决策须有对应 ADR，禁止口头决策不留记录 ② ADR/重大选型状态变更须经用户确认，Agent 不得自动变更 ③ 技术选型须有依据（性能/成本/熟悉度）而非仅凭业界主流 ④ 改老系统须有兼容性分析与回滚方案"
     severity: info
     check_type: semantic
-    evidence_required: ["LLM 语义评估结论（pending 标记，advisory 不阻断，随 Reflexion 反馈供客户端 AI 评判/重试）"]
+    evidence_required:
+      - "LLM 语义评估结论（pending 标记，advisory 不阻断，随 Reflexion 反馈供客户端 AI 评判/重试）"
     gate: design-gate
-    target: "self"
+    target: self
 ---
 
 # design-gate 强制检查清单
 
-8 条确定性检查。bridge 从此文件聚合。
+design 阶段产物结构与决策质量检查。bridge 从此文件聚合。
+
+- **REQ-STRUCT / ARCH-STRUCT / DB-STRUCT / API-STRUCT**：产物必含章节（document_structure，确定性）
+- **DES-C-REVIEW**：决策有 ADR / 选型有依据 / 改老系统有回滚（semantic，advisory）
 
-对应工程经验：
-- ARC-01
-- ARC-02
-- ARC-03
-- ARC-04
-- ARC-06
-- ARC-07
-- ARC-08
-- DES-C-REVIEW
+> 代码层正则检查（Controller 不含业务逻辑、写操作须事务等 ARC-*）已迁至 build-gate，那里才是代码实现阶段的归属。

package/templates/design//345/205/250/347/224/237/345/221/275/345/221/250/346/234/237/345/267/245/344/275/234/346/265/201/345/257/274/350/210/252.md

@@ -21,6 +21,7 @@ extra:
   products:
     - '*'
   lifecycle_status: active
+  priority: P0
   version: 1.1.0
   last_reviewed: '2026-06-01'
   domain:

package/templates/design//345/205/274/345/256/271/346/200/247/344/270/216/350/277/201/347/247/273/350/257/204/344/274/260.md

@@ -0,0 +1,71 @@
+---
+id: ka-guidance-兼容性与迁移评估
+kind: guidance
+title: 兼容性与迁移评估
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 迁移
+  - 兼容
+  - 老系统
+  - 重构
+  - brownfield
+  - 改造
+  - 遗留
+  - 升级
+  - 数据迁移
+  - 兼容性
+extra:
+  name: compatibility-migration-assessment
+  scope:
+    - '*'
+  products:
+    - '*'
+  type: procedure
+  lifecycle_status: active
+  version: 1.0.0
+  last_reviewed: '2026-06-17'
+  verification_layer: L2
+  stage: design
+  domain: design
+  owner_mechanism: mc-existing-system-analysis
+---
+
+# 兼容性与迁移评估：改老系统怎么不翻车
+
+> 吸收旧的「兼容性检查」「迁移评估」「改造影响范围评估」「历史遗留雷区清单」。
+> **何时用**：改造现有系统、数据迁移、schema 变更、技术栈升级时。
+
+## 第一步：摸清现状（证据先行）
+
+- 现有系统行为：靠真实运行/日志/数据证明，不靠记忆猜测（[[证据驱动与反幻觉]]）
+- 历史遗留雷区：标出脆弱点、无人敢动的代码、隐式契约
+
+## 第二步：迁移范围与影响面
+
+| 变更项 | 影响模块 | 影响数据 | 调用方 | 兼容性风险 |
+|--------|---------|---------|--------|-----------|
+
+## 第三步：兼容性分析
+
+- **向后兼容**：老接口/数据/调用方是否还能用？破坏点在哪？
+- **数据兼容**：老数据能否被新代码正确读取？是否需要迁移脚本？
+- **灰度能力**：能否新老并存、按流量/租户灰度切换？
+
+## 第四步：回滚方案（必填）
+
+- 每个变更能否独立回滚？
+- 数据迁移是否可逆？回滚后数据一致性如何保证？
+- 回滚触发条件 + 验证 SQL
+
+## 第五步：风险与验证
+
+- 新老逻辑比对：关键路径行为是否一致（比对日志/双写比对）
+- 爆炸半径控制：小切片推进（[[切片规划]]），每片可独立回滚
+
+## 禁止
+
+- 不摸现状就改老代码（凭记忆，违规）
+- 破坏向后兼容却不标注影响面（违规）
+- 数据迁移没有回滚脚本（违规）
+- 大爆炸式改造（无灰度，违规）

package/templates/design//345/206/263/347/255/226/344/270/216/351/200/211/345/236/213.md

@@ -0,0 +1,70 @@
+---
+id: ka-guidance-决策与选型
+kind: guidance
+title: 决策与选型
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 选型
+  - 技术决策
+  - ADR
+  - 头脑风暴
+  - 方案对比
+  - 第一性原理
+  - 架构决策
+  - 候选方案
+  - 技术栈
+  - 权衡
+extra:
+  name: decision-and-selection
+  scope:
+    - '*'
+  products:
+    - '*'
+  type: procedure
+  lifecycle_status: active
+  version: 1.0.0
+  last_reviewed: '2026-06-17'
+  verification_layer: L2
+  stage: design
+  domain: design
+  owner_mechanism: mc-decision-workshop
+---
+
+# 决策与选型：怎么拍技术方案
+
+> 吸收旧的「技术选型」「自主选型」「架构决策记录」「不确定时头脑风暴」「第一性原理推理」。
+> **核心**：重大决策须经用户确认（[[开发者宪法]]），选型须有依据而非凭主流（[[证据驱动与反幻觉]]）。
+
+## 选型流程
+
+1. **明确要解决什么问题**（第一性原理，不跟风）
+2. **检索基准**：通用知识 + 项目沉淀（sf_knowledge）+ 业界实践
+3. **列候选方案**：至少 2 个（含"不做/保持现状"选项）
+4. **多维对比**：性能 / 成本 / 团队熟悉度 / 生态 / 运维 / 风险
+5. **证伪循环**：主动找每个候选的失败场景，不是只找优点
+6. **给推荐 + 风险**：列冲突点、给推荐、请求用户确认
+7. **落 ADR**：决策必须有记录（标题/背景/选项/结论/原因）
+
+## ADR 格式（MADR）
+
+```markdown
+# 决策标题：<一句话>
+## 背景：为什么要做这个决策
+## 选项：列出候选及各自权衡
+## 结论：选了什么
+## 原因：为什么选它、放弃了什么
+```
+
+## 何时头脑风暴（不确定时）
+
+- 需求/方案有多种合理解读，且影响重大
+- 列出多个方向，标注各自前提和风险
+- 不要假装确定（[[工程执行总纲]] 思考先行）
+
+## 禁止
+
+- "业界主流所以选它"（无依据，违规）
+- 只列一个候选（没有比较，违规）
+- 决策不留 ADR（口头决策，违规）
+- 未经用户确认就定重大架构选型（越权，违规）