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