---
name: soloforge-design-doc
description: 把已确认需求转化为可实施、可演进、可验证的架构设计。
when: 架构设计 / design_doc / requirement_analysis 之后
---

# 架构设计

## 适用性

需求目标、scope 和关键端划分已确认后使用。若需求仍在变化、brownfield 事实未盘点或高影响技术取舍未确认，先补事实和决策，不要直接写结论。

## 事实输入

- 需求分析中的目标、需求、非功能指标、端清单和外部依赖。
- 当前代码库、部署拓扑、数据存储、构建方式和历史兼容约束。
- `.soloforge/intent.yaml` 中已确认的 projects 与技术栈。
- `template.md` 和 `examples.md`；示例只展示论证深度。

## 关键决策

- 模块边界、依赖方向、数据所有权、发布单元和故障边界。
- 技术选型必须比较适配性、迁移成本、运维成本和退出方案。
- 安全、并发、一致性、容量、RTO/RPO 等高影响约束必须有证据或用户确认。
- 端模块是产品与发布决策，AI 不得自行增删或改名。

## 产出方法

1. 从需求和现有系统事实推导约束，不从模板反推项目。
2. 使用已安装的 `soloforge project-modules` 获取端模块约束，并与需求端清单核对后写入设计。
3. 描述模块职责、公开接口、数据流、依赖方向、状态机和失败恢复。
4. 对关键取舍记录候选方案、选择理由、反例条件和未来重审触发器。
5. 默认路径是 `docs/architecture/01-架构设计文档.md`；有 project map override 时使用解析后的权威路径。

## 禁止项

- 不得用“业界主流、最佳实践、方便扩展”替代项目证据。
- 不得让共享模块拥有业务数据或形成双向/循环依赖。
- 不得只画组件图而不写运行时链路、失败模式和恢复方式。
- 不得只改设计文档中的端目录；端声明变化须先经用户确认并更新项目声明。

## 交付自检

- 每个需求都能落到负责模块和验证路径。
- 目录、端模块、部署单元与磁盘和项目声明一致。
- 状态机覆盖非法转移、幂等、重试和并发冲突。
- 风险、回滚、RTO/RPO 与真实基础设施能力匹配。

## 权威验证

编辑后先处理 quick 反馈，再调用 `sf_verify action="full" task_id="当前任务ID" artifact="design_doc"`。结构正确不等于设计正确；语义风险还需独立审查闭环。


## 交付前对抗审查

`sf_verify` 通过只证明结构/编译/测试层；语义质量（承接正确性、异常/并发/权限/边界是否可靠、是否含空话或无法证伪的承诺）须经独立对抗审查。advance/deliver 前用 `sf_review action="start" task_id="当前任务ID" artifact="<本产物 kind>"` 发起 per_artifact 审查，用**独立 session/subagent**（非产出本产物的同一会话）执行返回的 prompt、submit findings，按 next_step 完成 K 次独立采样与闭环。deliver 会阻断未完成/未闭环的审查；活跃豁免与被驳回 error 会被注入审查 focus 供独立复核。