AI SDD 开发规范-17-AI 执行上下文快照（AI Execution Context Snapshot）
2025/12/27大约 4 分钟
AI 执行上下文快照（AI Execution Context Snapshot）
把分散的认知模块“合并”为一个 AI 执行上下文快照（AI Execution Context Snapshot），本质上是在做一件事：
在 AI 开始动手写代码之前，把“一个资深工程师此刻脑子里该有的全部关键信息”，冻结成一次可校验、可审计、可复用的状态。
下面我会给你一个 工程级、可直接落地的完整 Markdown 模板，并解释它的设计逻辑。
AI_EXECUTION_CONTEXT_SNAPSHOT.md
用途说明（给 AI + 人看）
本文档用于在 AI 执行任何代码修改前，提供完整、准确、当前时刻有效的工程上下文快照。
AI 必须以本文档为最高优先级约束进行理解、推理与实现。
0. 快照元信息（Snapshot Metadata）
Snapshot ID: ECS-2025-01-001
生成时间: 2025-01-15
适用分支: main
适用范围: 本次功能 / Bugfix / 重构
有效期: 仅对本次任务有效强约束：
- 不得将本快照的假设外推到其他任务
- 不得复用到其他分支或阶段
1. 项目与仓库感知（Repository Awareness）
1.1 项目定位
项目类型：
- [ ] 核心业务系统
- [ ] 辅助系统
- [ ] 基础设施 / 中间件
- [ ] PoC / 实验性项目
当前主要目标：
- 稳定性 / 功能交付 / 性能 / 成本 / 清理技术债1.2 仓库结构速览（只列关键）
/src
/domain # 核心业务模型（高风险）
/service # 业务服务层
/infra # 外部依赖 / DB / MQ / RPC
/api # 对外接口（兼容性敏感）1.3 高风险目录 / 文件
以下路径修改需要极度谨慎：
- src/domain/**
- src/api/public/**2. 演化阶段上下文（Evolution Context）
当前演化阶段：维护期 / 迭代期 / 探索期 / 冻结期2.1 阶段目标
优先级排序：
1. 稳定性
2. 向后兼容
3. 可维护性
4. 性能2.2 明确禁止行为
禁止事项：
- ❌ 结构性重构
- ❌ 技术栈升级
- ❌ 接口语义变更3. 需求与设计意图（Design Intent）
3.1 本次任务目标（WHAT）
要解决的问题：
- 问题描述（业务 + 技术）
非目标（明确不做）：
- 不涉及 XX
- 不优化 YY3.2 设计约束（HOW）
关键设计决策：
- 使用现有 A 方案，而不是 B
- 保持与旧逻辑完全一致的行为3.3 设计不确定点（AI 需主动提示）
以下点如在实现中遇到歧义，必须中断并反馈：
- XXX 是否允许为空？
- YYY 是否允许重试？4. 隐性知识显性化（Tacit Knowledge）
历史经验：
- 这个模块曾因并发问题多次出事故
- 不要信任下游返回的数据完整性
工程潜规则：
- 宁可多写校验，也不要相信“理论上不会发生”5. 责任、回滚与影响面（Ownership & Rollback）
5.1 责任人
业务 Owner：
技术 Owner：5.2 回滚能力评估
是否支持快速回滚：是 / 否
回滚方式：
- 代码回滚
- 配置回滚
- 数据不可逆（必须极度谨慎）5.3 影响面分析
可能受影响的系统：
- 上游：
- 下游：
是否涉及历史数据：是 / 否6. 失败预算与风险容忍度（Failure Budget）
6.1 可接受失败
- 异步任务失败
- 非核心日志丢失6.2 不可接受失败
- 数据丢失
- 状态不一致
- 接口语义变化6.3 冲突裁决原则
当发生权衡冲突时，优先级为：
数据安全 > 兼容性 > 稳定性 > 性能 > 优雅性7. AI 执行前强制校验（Preflight Check）
AI 在编码前必须逐条确认：
- [ ] 已完整理解任务目标
- [ ] 未触碰禁止事项
- [ ] 修改范围受控且可回滚
- [ ] 不确定点已明确或已反馈
- [ ] 风险与失败后果已评估若任一项无法确认，必须停止编码并请求澄清。
8. AI 执行承诺（Execution Contract）
AI 承诺：
- 不进行未授权的重构
- 不引入额外技术债
- 不扩大修改范围
- 所有行为均可解释、可回滚设计层面的关键说明（非常重要）
为什么要“合并”而不是“引用多个文档”？
因为：
- AI 的推理不是长期记忆，而是一次性决策
- 人类工程师靠“脑内状态”，AI 只能靠“输入状态”
- 分散文档 = 隐性优先级
- 单一快照 = 显式决策环境
这个 Snapshot，相当于 AI 的“工程态 CPU Register”