agentleFS
Sign inStart free
peterwangzepeterwangze/software-project-governance/skills/stage-architecture/SKILL.md

stage-architecture

Skill2 starsChanged 5 months agoMITView on GitHub

架构设计——系统设计、模块拆分、技术评审。阶段子工作流，可独立使用。

The file

Create a free account to mount
Files
SKILL.md

架构设计 — 子工作流

本文件定义"架构设计"阶段的独立子工作流。用户可单独加载本文件执行架构设计阶段。

阶段目标

形成可执行的技术方案和系统设计。架构设计阶段的核心产出是"架构文档"——回答"系统怎么拆、接口怎么定、数据怎么流、非功能需求怎么满足、为什么这样设计而不是那样设计"。

AI 编程场景特有风险

在 AI 辅助编程项目中，架构设计阶段存在以下特有风险：

风险说明缓解方向
过度工程化AI 倾向于设计"完备"的架构，引入不必要的抽象层和未来才需要的扩展点，增加复杂度每个设计决策必须有"当前需要"的理由；"为未来设计"的模块需显式标注并评估成本
缺少替代方案评估AI 通常直接给出"一个方案"而非"从 N 个方案中选择"，缺少对比论证架构文档必须包含"已考虑的替代方案"章节
非功能需求遗漏AI 易聚焦功能实现而忽略性能、安全、可维护性等非功能需求强制非功能需求逐项对照检查
假设未经挑战AI 生成的架构基于隐含假设（"这个服务永远可用""数据量不会超过 X"），这些假设未被显式列出和挑战蓝军机制：强制列出核心假设并逐个挑战
模块边界模糊AI 生成的模块划分可能过于耦合或过于分散，缺少单一职责约束每个模块职责必须能在一句话内说清

独立使用时的目标锚定

当本子工作流被独立加载（非通过 main-workflow.md 总入口加载）时，MUST 在执行阶段活动前完成：

  1. 目标确认：读取 .governance/plan-tracker.md，确认项目立项时定义的量化成功标准
  2. 偏离检查：对照成功标准，确认架构设计方案与项目总目标一致。如发现偏离，MUST 先记录到 .governance/decision-log.md 再继续
  3. 质量底线：架构文档必须包含替代方案评估、非功能需求覆盖和独立评审（参考 profile 质量要求）

进入条件

  • 技术选型已完成（G3 通过）
  • 开发环境已搭建（G4 通过，可重叠）
  • 有明确的调研结论和选型决策支撑

活动清单

1. 需求到设计的映射

活动描述交互边界企业实践
梳理功能需求将立项和调研阶段的产出映射为功能需求列表需用户确认：需求优先级通用实践
梳理非功能需求性能、安全、可用性、可维护性、可扩展性需用户输入：非功能需求的量化目标（如 P99 < 100ms）[Google Design Doc] 非功能需求必须在设计文档中显式列出
确认设计范围哪些需求纳入首版设计需用户确认[Amazon] 明确"首版不做什么"

2. 系统架构设计

活动描述交互边界企业实践
确定架构风格单体/微服务/事件驱动/分层等自动推荐：基于需求特征推荐候选风格 → 需用户确认通用实践
模块划分按职责拆分模块，每个模块职责用一句话描述自动：输出候选方案 → 需用户确认[Google] 模块职责单一、边界清晰
接口定义模块间接口的输入输出和契约自动：基于模块划分输出通用实践
数据流设计数据在模块间如何流转和存储自动通用实践
替代方案评估列出至少 2 个已考虑的替代方案，说明为什么不选自动：基于设计空间分析输出 → 需用户确认[Google Design Doc] 必须包含"Alternatives Considered"

3. 架构决策记录 (ADR)

活动描述交互边界企业实践
记录关键架构决策每个关键决策包含：上下文、决策、后果、替代方案自动[ByteDance Context not Control] 传递决策上下文，而不只是决策结果
标注决策可逆性区分可逆决策（框架选择）和不可逆决策（数据模型）自动[Amazon Bias for Action] 可逆决策 70% 信息即推进

4. 概要设计

活动描述交互边界企业实践
模块职责描述每个模块做什么、不做什么，职责能否用一句话说清自动[Google] 单一职责原则
依赖关系图模块间的依赖和调用关系自动通用实践
关键流程图核心业务流程的端到端路径自动通用实践

5. 详细设计

活动描述交互边界企业实践
核心模块详细设计核心模块的内部结构、算法、数据结构自动通用实践
接口详细规范接口的字段、类型、校验规则、错误码自动通用实践
数据模型表结构或数据 schema自动通用实践

6. 技术评审

活动描述交互边界企业实践
Design Doc 自检架构文档是否包含：目标、方案、替代方案、风险、非功能覆盖 — Design Doc 最小结构自动[Google Design Doc] 最小结构检查
蓝军挑战指定 1 人担任"蓝军"，提出 ≥3 个"如果...会怎样"的挑战问题需用户确认：蓝军人选 + 挑战结论[华为蓝军] 重要设计必须有对立面审查
Bar Raiser 评审引入 ≥1 位项目外部独立 reviewer需用户确认：评审人选 + 评审结论[Amazon Bar Raiser] 独立第三方确保标准不降低
评审结论通过 / 有条件通过 / 需要修改需用户确认通用实践

产出物标准

产出物格式要求质量标准企业实践来源
架构文档 (Design Doc)包含：目标、方案、替代方案（≥2 个）、风险、非功能需求覆盖非功能需求逐项有设计措施对应；替代方案有"为什么不选"理由[Google Design Doc]
架构决策记录 (ADR)每个决策有：上下文、决策、后果、替代方案、可逆性标注关键决策均有 ADR[ByteDance Context not Control]
模块划分图每个模块职责单一、边界清晰无循环依赖；每个模块职责 ≤3 句话[Google] 单一职责
接口定义输入输出、类型、校验规则、错误码完整接口可独立测试通用实践
评审结论蓝军挑战记录 + Bar Raiser 意见 + 最终结论蓝军挑战 ≥3 条且已回应；独立评审已完成[华为蓝军] + [Amazon Bar Raiser]

退出条件

  • 架构文档通过 Design Doc 最小结构检查（目标/方案/替代方案/风险/非功能 5 项齐全）
  • 替代方案 ≥2 个，且每个有"为什么不选"的理由
  • 蓝军挑战完成（≥3 个挑战问题 + 回应）
  • 独立评审完成（≥1 位外部 reviewer + 评审结论）
  • 模块划分清晰、职责单一（无循环依赖）
  • 关键接口已定义（输入输出和类型完整）
  • 关键架构决策有 ADR 记录（含可逆性标注）

Gate 映射

本阶段对应 G5 — 设计完成。

Gate 检查项对应活动判定标准自动化判定
Design Doc 结构是否完整？技术评审目标/方案/替代方案/风险/非功能 5 项齐全可自动：检查章节标题
替代方案是否充分？系统架构设计≥2 个替代方案，各有"为什么不选"理由可自动：计数+检查理由字段
每个非功能需求是否有设计措施？系统架构设计非功能需求列表的每一项有对应的设计措施可自动：逐项对照检查
模块划分是否清晰、无循环依赖？概要设计依赖图无循环；每个模块职责 ≤3 句话可自动：依赖图分析
蓝军挑战是否完成？技术评审≥3 个挑战问题 + 回应记录可自动：计数检查
独立评审是否完成？技术评审≥1 位外部 reviewer + 评审结论可自动：检查评审人记录
架构决策是否有 ADR？ADR关键决策有 ADR 含可逆性标注可自动：检查 ADR 文件存在+字段完整

企业实践溯源

本子工作流的设计参考了以下企业实践，每条实践已映射到具体活动步骤：

企业核心实践映射到本工作流
GoogleDesign Doc（目标/方案/替代方案/风险）技术评审→Design Doc 最小结构自检；产出物→架构文档五段式
GoogleCode Review / 独立 Reviewer技术评审→Bar Raiser 独立评审
Amazon6-Pager 结构化论证架构文档→目标/方案/替代方案/收益/风险/时间线
AmazonBar Raiser技术评审→项目外部独立 reviewer
AmazonBias for Action (可逆性分类)ADR→决策可逆性标注
华为蓝军机制技术评审→蓝军挑战（≥3 个"如果...会怎样"）
华为IPD TR 门控量化评分Gate 映射→每个检查项可量化判定
字节跳动Context not ControlADR→记录决策上下文（为什么这样设计）

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free