主题：应用部分 1. 从遗留系统恢复规范
难度级别：中等（中等）
预计学习时间：4-5 小时
前置条件： 掌握第一卷第13章的内容（恢复现有项目的章程）。
理解云基础设施工作原理（Kubernetes、监控、告警）。
具备 JSON、YAML 和 Markdown 格式的基本操作技能。
对 SDD（规范驱动开发）概念有总体理解。
学习目标： 学会清晰区分实际需求（契约）和背景基础设施上下文（memory bank）。
掌握从分散来源（日志、Slack、事后分析）收集和规范化证据（evidence_ref），形成统一时间轴。
掌握提取隐含规则并将其转化为可验证断言（claims）的技能，使用 AI（Qwen Code）辅助。
能够使用行为语言（Given/When/Then）描述恢复的需求，并为其设计机器可读的契约（JSON Schema）。
学会维护需求来源登记册（genealogy.md），以确保规范的透明性和可审计性。
概述：本学习模块介绍从遗留系统的分散工件（如非结构化日志、运维聊天记录和事后分析）中恢复工程可用规范（SDD）的过程。通过 AgentClinic 教学生产模型，您将了解如何将数据混乱转化为严格、可验证的契约。您将掌握时间轴规范化技术、使用 AI 提取带证据基础的需求，以及区分业务逻辑和基础设施上下文（memory bank）的方法。课程强调每个恢复的需求必须基于来源而非猜测。
核心概念： 规范亡灵术（恢复规范）：基于可观察工件（日志、指标、聊天记录）重建规范的工程方法。使团队能够在人员流失后恢复系统逻辑，依靠可验证的证据链而非抽象猜测。
Memory bank（背景模型）：独立的基础设施上下文层（历史约定、集群拓扑、团队名称）。这些信息有助于理解事实，但本身不是业务需求（契约），不应进入分类逻辑。
Evidence ref（证据标记）：对原始工件中具体位置的引用（如日志中的某行、Slack 中的某条消息），用于确认断言的真实性。没有 evidence_ref 的需求仅视为假设。
Genealogy.md（来源登记册）：描述每个需求来源的文件。与 git log 不同，它不仅显示谁何时修改了文件，还展示规则从何而来、置信度级别（uncertainty）、确认来源和待解决问题。
候选断言（claim）：从数据中提取的模式或规则，附带证据、反例和置信度评估。候选状态可以是 'approved'、'needs_clarity' 或 'rejected'。
规范化时间链：统一为同一时间（UTC）和格式的有序事件序列，清除重复项。按时间顺序关联日志、告警和运维人员操作。
练习题目： 标题：区分契约与背景上下文
问题：提供了一份事后分析摘录列表：
- 'appointments-api 服务在10分钟内内存消耗超过90%。'
- '值班工程师 Ivan 在 Slack 频道 #incidents 中报告，这不是计划内部署。'
- '部署发生在 canary 命名空间。'
- 'NOC 团队在15分钟后收到告警。'
任务：将这些事实分为两类：'需求（SDD）'和'Memory Bank'。说明理由。
解答：1 和 4 — 需求（SDD）。它们描述系统的可观察行为和 SLA（内存消耗触发器和响应时间）。 2 和 3 — Memory Bank。值班工程师姓名和 canary 命名空间的使用事实是有助于理解情况的上下文，但不应作为通用规则硬编码到分类流水线业务逻辑中。
难度：初级
标题：创建 genealogy.md 记录
问题：基于教学摘录：
- grafana:HM-2026-05-17-01 cluster=prod-k8s memory_percent=92 window=10m
- postmortem:api-memory-2026-05 note='auto-resolve was rejected until stable'
为 genealogy.md 文件构建 YAML 片段。断言：'当 appointments-api 的 memory_percent >= 90% 持续10分钟时，创建 P1'。指定状态为 'needs_clarity'，因为缺少关闭条件数据。
解答：- claim: "当 appointments-api 的 memory_percent >= 90% 持续10分钟时，创建 P1。" status: needs_clarity evidence_ref:
- "grafana:HM-2026-05-17-01"
- "postmortem:api-memory-2026-05"
uncertainty: medium open_questions:
- "是否确认禁止无稳定窗口的自动解决？"
- "关闭告警的确切阈值是什么？"
难度：中级
标题：规范双重记录（Given/When/Then + JSON Schema）
问题：将恢复的需求转换为 Given/When/Then 格式，并编写最小 JSON Schema 以验证触发阈值和 SLA。 需求：'如果在一个节点上10分钟内记录到 >=3 次 NodeNotReady，则创建 P1 级别事件，预期响应时间为8分钟。'
解答：Given 集群处于活跃班次且监控系统正在记录指标； When 在10分钟内一个节点出现 >=3 次 NodeNotReady 事件； Then 系统创建 severity=P1 的事件并设置 SLA 响应时间为8分钟。
JSON Schema: { "$id": "urn:spec:node-not-ready:v1", "type": "object", "required": ["rule_id", "severity", "sla_minutes", "conditions"], "properties": { "rule_id": {"type": "string"}, "severity": {"type": "string", "enum": ["P0", "P1", "P2", "P3"]}, "sla_minutes": {"type": "integer", "minimum": 1, "maximum": 120}, "conditions": { "type": "object", "required": ["event_code", "count", "window_minutes"], "properties": { "event_code": {"type": "string"}, "count": {"type": "integer", "minimum": 3}, "window_minutes": {"type": "integer", "minimum": 1} } } } }
难度：高级
案例研究： 标题：SRE 团队流失后恢复升级逻辑
场景：在自动事件管理项目中，关键专家流失。遗留了47页未清理的日志、Slack 线程、仪表板截图和文本事后分析。新团队需要基于 Qwen Code 构建分类流水线，但不存在正式规范文档（SDD）。
挑战：信息混乱：日志包含1200多个不同时区的事件，聊天记录中真实事件和计划工作讨论混杂。存在高风险：AI 模型（Qwen Code）可能将聊天中的随机短语或特定集群拓扑误认为通用业务规则。
解决方案：团队应用'规范亡灵术'方法：
- 数据清点和规范化：将所有时间戳统一为 UTC，过滤噪音，创建统一时间轴。
- 分层分离：提取可验证需求（触发器、SLA、关闭条件），其余内容移入 Memory Bank。
- 通过 AI 提取需求：使用 Qwen Code 进行分析，严格要求为每个断言提供 evidence_ref。
- 维护 genealogy.md：记录每个规则的来源，以区分事后分析确认的事实和未确认假设。
结果：团队获得的不是一组看似合理的猜测，而是工程可用的规范。一致契约以 Given/When/Then 和 JSON Schema 格式表达，可自动验证分类流水线行为。
经验教训： 切勿将争议假设伪装为已确认契约。使用 needs_clarity 状态和不确定度级别。
时间窗口过滤器（如相对于告警的 [-15m,+5m]）对于关联聊天中的手动操作和日志中的自动事件至关重要。
例外情况（如 canary 命名空间）不应作为噪音删除；它们通常指向规范的隐藏条件。
相关概念： evidence_ref
memory bank
genealogy.md
规范亡灵术
Qwen Code
标题：node_not_ready 事件分析：发现隐藏阈值
场景：分析具体历史事件 NR-2026-05-17-01。Grafana 显示 worker-07 节点在10分钟内发生3次 NodeNotReady。系统创建了 P1 升级。事后分析注明：'auto-resolve was rejected until two stable OK windows'。
挑战：需要恢复精确规则：事件何时成为 P1，何时可以自动关闭。工程师需要理解3次事件的阈值是硬性规则还是巧合，以及如何在代码中检查 'stable OK windows'。
解决方案：1. 以 Given/When/Then 格式编写行为历史。
- 形成候选断言（Claim）：'当 >=3 次 NodeNotReady 在10分钟内发生时，创建 P1'。
- 通过 evidence_ref 关联证据（引用 Grafana 和事后分析）。
- 在 JSON Schema 中记录关闭条件，要求存在两个连续的 OK 窗口。
- 将争议事实（canary 命名空间）作为待解决问题，标记 uncertainty: medium。
结果：创建了可验证规范，恢复分类逻辑。canary 命名空间的争议点未作为通用规则进入最终 SDD，而是保持为假设状态，需要在历史数据上验证。
经验教训： 流畅的文本需求表述不如展示需求何处稳固、何处需要服务所有者验证的记录有用。
双重记录（行为 + JSON Schema）消除了人类理解与机器验证之间的鸿沟。
相关概念： 候选断言（Claim）
规范化时间链
JSON Schema
Given/When/Then
学习建议： 从聚焦开始：第一步实践选择一个断言、两个来源和一个待解决问题。不要试图一次性恢复整个架构。
训练分层分离：阅读任何事后分析时，问自己——这是契约的可观察行为还是仅仅是情境上下文？
在无头模式下练习使用 Qwen Code（计划模式）：要求模型返回的不是现成文本，而是带 source、counterexample 和 missing_context 字段的结构化 JSON。
注意 git blame 和 genealogy.md 的区别。Git 显示谁添加了代码行，而 genealogy.md 解释基于哪些日志和聊天记录做出了具体业务决策。
额外资源： 教材第一卷第13章：恢复现有项目章程的基础材料。建议在本模块开始前阅读。
第8章（多智能体仲裁）：完整生产路径的高级材料。描述验证者、实现者和安全者的角色，用于解决争议规范。
Github spec kit：外部资源，描述 SDD 哲学"规范作为可执行工件"。
Genealogy.md 模板（book2/examples/templates/）：课程练习所需的实用模板。
总结：从遗留系统恢复规范是将历史数据混乱转化为严格、可验证契约的过程。成功的关键在于严格区分实际需求（SDD）和基础设施上下文（Memory Bank）。使用 AI 有助于提取候选需求，但每个此类断言必须有证据支持（evidence_ref）。双重编码（人类可读的 Given/When/Then 和机器可读的 JSON Schema）结合来源登记册维护（genealogy.md），确保规范不仅是看似合理的猜测集合，而是可审计的工程工件。