# Software Design Evidence > 根据软件、AI、模型、算法、算子或平台需求，以及一个或多个穿刺代码 commit、commit range、PR、测试、Profiling 或运行材料，生成可评审的软件子系统设计文档或关键模块设计方案、任职能力举证报告、双向追踪矩阵和缺口清单。用于补齐或审计 4+1 视图、安全威胁分析、可靠/可用性、可测试性、功能安全、体验、性能、架构治理、设计原则/模式和技术决策；当证据不足时必须指出缺少的设计、代码、测试、度量或治理工作，不得根据现有代码虚构原始决策。 - Skill: `kirrito-k423/software-design-evidence` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add kirrito-k423/software-design-evidence` - Raw SKILL.md: https://api.skillmd.com/api/skills/kirrito-k423/software-design-evidence/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Kirrito-k423 (https://skillmd.com/u/kirrito-k423) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/kirrito-k423/software-design-evidence --- # 软件设计与任职举证 ## 目标 把“需求 + 代码提交”转化为两类彼此分离、相互链接的交付物： 1. **软件设计文档**回答为什么这样设计、系统如何工作、怎样处理风险与质量属性； 2. **任职举证报告**回答候选人承担了什么责任、做了什么关键判断、哪些结果有可核验证据、还有什么不能声称。 同时输出缺口清单。材料不足时继续完成可证部分，禁止用完整文档外观掩盖证据缺失。 ## 基本纪律 - **事实、推断、假设、建议分开。**每个核心结论都附来源与证据等级。 - **commit 只证明实现事实。**它不能单独证明原始需求、候选方案比较、决策动机、个人主导程度或业务结果。 - **结果不高于证据。**没有同条件 baseline/candidate 测量，不声称性能提升；没有故障或安全验证，不声称风险已消减。 - **不机械补图。**4+1 是关注点模型，不是固定五张 UML 图；只选择能回答评审问题的表示法。 - **不机械套模式。**只有当问题、协作结构、权衡和代码位置均能对应时，才声称使用某个设计模式。 - **功能安全按适用域裁剪。**普通软件不得因为“不能出错”就声称符合 ISO 26262、IEC 61508 或某个 SIL/ASIL。 - **保护用户代码。**分析任务默认只读，不修改实现代码；只有用户明确要求补实现或测试时才编辑。 - **遵循仓库规则。**读取目标仓库的 `AGENTS.md`；存在 `.codegraph/` 时先用 CodeGraph 定位代码。 ## 输入合同 ### 最小输入 - 需求、问题陈述或目标； - 目标系统/子系统/模块边界； - 仓库路径； - 至少一个 commit、commit range、PR 或明确的代码路径。 ### 强支持输入 - Top 问题、事故、客户场景、性能瓶颈或业务影响； - 需求/验收条件、设计文档、ADR、评审纪要和候选方案； - 架构图、接口、部署、配置、数据契约和所有权信息； - 测试、Profiling、Benchmark、SLO、故障演练、安全扫描、用户研究； - 候选人的角色、负责范围、合作者、决策权和评审人； - 任职标准原文、时间边界和脱敏要求。 缺少材料时先生成“已知事实、待确认项、可继续部分、结论上限”，只有缺失选择会改变系统边界或交付目标时才请求用户决定。 ## 选择交付模式 | 条件 | 模式 | 主交付物 | |---|---|---| | 跨多个模块、进程、部署单元或团队，且需同时论证多个质量属性 | 子系统设计 | 完整 4+1 与横切质量设计 | | 边界集中于一个关键模块或机制，主要解决一个 Top 问题 | 关键模块设计 | 模块内部设计、交互、风险、性能与验证 | | 设计已存在，用户只要求任职材料 | 举证审计 | 能力映射、STAR/CAR 叙事、证据索引与缺口 | | 不确定 | 双轨草案 | 先输出范围判定和两种目录的裁剪建议 | 使用 `references/design-document-template.md` 生成设计文档，使用 `references/evidence-report-template.md` 生成举证报告，使用 `references/assessment-rubric.md` 做最终审计。 ## 工作流 ### 阶段零：冻结分析边界 1. 记录仓库、基线 commit、目标 commits/range、分支、工作树状态和分析截止时间。 2. 定义目标系统、外部参与者、上游/下游、部署环境、明确非目标和候选人负责范围。 3. 建立材料清单：需求、设计、代码、测试、性能、安全、可靠性、治理和结果。 4. 为每项材料记录来源、时间、作者/责任人、可验证路径和证据等级。 **评审门：**能明确说明“正在证明哪个系统、哪段时间、谁的哪项责任”，不能把团队成果全部归于个人。 ### 阶段一：收集 Git 与代码证据 优先运行只读收集器： ```bash python3 /scripts/collect_git_evidence.py \ --repo \ --commit \ --range .. ``` 收集器输出 commit 元数据、父提交、主题/正文、文件状态、增删行和路径，不替分析者推断设计动机。 随后定位： 1. 入口、核心调用路径、数据/控制流和配置开关； 2. 新增/修改接口、状态、错误语义、并发和资源生命周期； 3. 测试与生产代码的对应关系； 4. 兼容、迁移、回退、观测和部署变化； 5. commit 之间的演进、返工、修复和取舍信号。 关键代码结论必须固定仓库、revision、文件、symbol 和行号。不要用目录名猜模块职责。 ### 阶段二：建立事实与决策账本 为每条发现分类： | 类型 | 含义 | 允许写法 | |---|---|---| | 事实 | 原始材料直接支持 | “commit X 在文件 Y 增加接口 Z” | | 推断 | 多项事实支持但无原始记录 | “从调用链和测试推断，该改动可能用于隔离重试策略” | | 假设 | 需要责任人确认 | “假设 Top 问题是尾延迟而非平均吞吐” | | 建议 | 为补齐设计或证据提出 | “补 ADR 比较单点重试与分层重试” | 建立决策账本：问题/约束、候选方案、选择、正负后果、反事实方案、重审触发器、证据。若没有 ADR，只能生成**回溯 ADR 草案**并标明待责任人确认，不能伪装成当时记录。 ### 阶段三：构建 4+1 视图 对每个视图回答固定问题，并链接到场景、代码和验证： | 视图 | 核心问题 | 常用模型 | 必须追踪到 | |---|---|---|---| | 逻辑 | 系统提供哪些能力，关键抽象和职责是什么 | Context、领域模型、组件图、接口/数据契约 | 需求、模块/API、单元/契约测试 | | 进程 | 运行时如何并发、同步、通信、限流和失败 | 时序、活动、状态、运行拓扑 | 线程/任务/队列、超时重试、集成/故障测试 | | 开发 | 代码如何组织、构建、依赖并由谁维护 | 模块/包/层次、构建图、所有权表 | 文件/target、依赖规则、CI 架构检查 | | 物理 | 软件怎样映射到节点、网络、设备和区域 | 部署图、网络拓扑、资源表 | 配置/IaC、容量、HA/DR、部署验证 | | 场景 | 哪些正常/异常/质量场景驱动并校验前四个视图 | 用例、时序、Given-When-Then | 需求 ID、设计元素、测试和结果 | 视图之间必须交叉检查：逻辑组件能映射到开发模块和运行单元；关键场景能穿过所有相关视图；图中的组件、接口、队列和节点在代码/配置中有对应或被明确标为设计提议。 ### 阶段四：横切质量分析 #### 安全威胁 1. 定义关键资产、安全目标、攻击者能力和适用边界； 2. 画信任边界、数据流、入口/出口、身份和权限； 3. 用 STRIDE 等提示枚举威胁，再用攻击树/攻击路径连接入口、前置条件、漏洞、横移和资产影响； 4. 对每条威胁记录可能性、影响、现有控制、拟增控制、残余风险和责任人； 5. 把控制追踪到需求、代码、配置、扫描、渗透或负向测试。 拒绝只有“加密、鉴权、最小权限”等口号而没有资产、路径和验证的安全章节。 #### 可靠与可用性 1. 定义用户可观察的服务、任务时长、SLO、RTO、RPO、数据耐久和一致性边界； 2. 建立依赖/故障域、单点、容量和故障传播图； 3. 用 FMEA 自底向上分析组件故障模式、影响、探测和处置； 4. 用 FTA 自顶向下分析 Top failure 的组合路径； 5. 设计隔离、冗余、幂等、超时、有限重试、退避、降级、熔断/限流、回滚、备份与恢复； 6. 追踪到故障注入、演练、恢复测试、监控和 SLO 结果。 区分**可靠性**（任务期间持续无故障）与**可用性**（需要时可提供服务）。不要只写副本数。 #### 可测试性 从可控、可观、可隔离、可重复和可自动化五个方向检查：依赖注入/端口、确定性种子/时钟、状态查询、结构化日志/指标/Trace、测试夹具、故障注入点、契约、边界与回归分层。每个设计机制都要有具体测试入口和 oracle。 #### 功能安全 先判定是否适用。适用时记录 hazard、运行场景、严重度/暴露度/可控度或行业方法、安全目标、安全需求、独立性、监控/降级/安全状态、验证和确认。无法确认行业标准、目标完整性等级或安全责任人时，结论只能是“待专业安全流程确认”。 #### 体验 记录目标用户、任务、环境、关键旅程、认知负担、错误预防与恢复、反馈、可访问性、运维/开发者体验和用户验证。UI 截图只能证明界面存在，不能证明任务体验改善。 #### 性能 1. 固定负载模型、数据规模、硬件软件版本、精度、并发、预热、重复和统计口径； 2. 分解端到端关键路径与资源预算，覆盖平均值和尾部百分位； 3. 分析算法复杂度、对象生命周期、拷贝、序列化、锁、队列、I/O、通信、缓存和扩展瓶颈； 4. 设计容量、背压、限流、批处理、并行/异步、缓存和降级； 5. 使用同条件 baseline/candidate Profiling 或 Benchmark 验证，并记录代价与回归。 “模块无明显性能问题”必须由需求阈值、Profiling 范围和已知上限共同支持，不能从“测试通过”推导。 ### 阶段五：原则、模式与架构风格 为每个声称采用的原则或模式填写：问题信号、适用对象、代码位置、带来的收益、代价、替代方案和验证。 - **原则候选**：信息隐藏、关注点分离、SOLID、KISS、DRY、YAGNI、组合优于继承；默认拒绝、最小权限、完全仲裁、权限分离、开放设计等安全原则。 - **设计模式**：GoF 23 及领域中确有证据的其他模式。 - **架构风格**：分层、组件化、端口适配器、事件驱动、微服务等。 不要求模式越多越好。若一个简单函数或数据结构已经解决问题，应把避免过度设计视为正向判断。 ### 阶段六：架构治理与技术决策 1. 识别循环依赖、跨层调用、共享数据库、重复模型、接口泄漏、隐式全局状态、版本漂移、文档/代码不一致、不可观测路径等腐化点； 2. 为每项记录趋势、影响、触发证据、责任人、整改计划和完成条件； 3. 把关键约束转成架构适应度函数：依赖/循环检查、API/Schema 兼容检查、容量/性能阈值、安全门禁、部署策略和文档模型校验； 4. 对重大决定写 ADR，并用轻量 ATAM/QAW 场景识别风险、敏感点和权衡点； 5. 说明候选人的具体主导动作：提出、比较、拍板、组织评审、推动落地或持续治理，避免把“参与会议”夸大为“主导决策”。 ### 阶段七：建立双向追踪与结论 建立主链： ```text 需求/Top 问题 -> 质量场景 -> 设计决定/ADR -> 4+1 元素 -> 风险/消减 -> commit/PR/代码 -> 测试/运行证据 -> 能力项 -> 任职结论 ``` 检查反向链：每个代码改动和举证结论都能回到已确认需求、风险或架构决定；无法回溯的改动标为范围外、偶然实现或待确认。 ## 证据等级与结论措辞 | 等级 | 支撑材料 | 允许结论 | |---|---|---| | E0 陈述 | 个人描述，无可核验路径 | “候选人陈述……” | | E1 设计 | 设计文档、ADR、评审记录 | “提出/设计了……” | | E2 实现 | commit、PR、代码、配置 | “实现/组织落地了……” | | E3 验证 | 测试、Profiling、演练、SLO、用户验证、治理对比 | “在给定边界下验证了……” | 证据互相矛盾时，不做多数表决；列出冲突、时间顺序、可能解释和最小确认问题。 ## 缺口分类 对每项任职要求给出 `充分 / 部分 / 缺失 / 不适用 / 证据冲突`，并将缺口拆成可执行工作： - **设计缺口**：边界、视图、场景、ADR、威胁、FMEA/FTA、容量或治理规则缺失； - **代码缺口**：控制、隔离、回退、观测、接口或架构约束未实现； - **测试缺口**：无负向、故障、恢复、契约、性能、安全或用户验证； - **度量缺口**：无 baseline、环境、统计口径、阈值或线上时间窗； - **归属缺口**：无法证明候选人角色、决策权或组织动作； - **时间缺口**：材料生成于结果之后，不能证明事前决策。 每个缺口必须包含影响、优先级、最小补齐动作、责任人、产物、验收方式和预计能提升到的证据等级。不要只写“补文档”。 ## 输出路径 若用户或仓库未规定位置，默认生成： ```text docs/design/-software-design.md docs/evidence/-career-evidence.md docs/evidence/-traceability.md ``` 允许把追踪矩阵合并进前两份文档，但不得删除证据链接和缺口。 ## 完成检查 交付前逐项检查 `references/assessment-rubric.md`，并验证： 1. 所有引用的 commit、文件、symbol、测试和结果路径存在； 2. 4+1 视图与横切质量设计没有互相矛盾； 3. GoF 模式数量写为 23，且没有为凑数虚构模式； 4. 安全、可靠性、性能和体验结论均有场景与证据边界； 5. 功能安全适用性已有明确裁剪结论； 6. 任职结论未超过证据等级，团队与个人贡献已分开； 7. 缺口清单可以直接转成设计、代码、测试或治理任务； 8. Markdown、链接和仓库校验通过。 最终交付说明：文档路径、分析边界、覆盖的 commits、E0-E3 数量、充分/部分/缺失能力项、最高优先级缺口、验证动作和仍需责任人确认的问题。