应采用「触发→表现→定位→修复→验证」五段式结构，每段只保留产生信息差的关键事实：触发需明确条件，表现列可观测现象，定位含最小复现代码与证据链，修复精确到行级修改，验证提供可一键执行的命令。
事后总结报告该用什么结构才不会被当流水账
Python 项目出问题后写的总结报告，核心不是复盘过程，而是让下一个人（包括未来的你）能快速定位、复现、验证修复。结构松散或堆砌日志，等于没写。
推荐按「触发 → 表现 → 定位 → 修复 → 验证」五段组织，但只保留其中真正产生信息差的部分。比如：如果错误是 KeyError 且只发生在 prod 环境，那“触发”段必须明确写出触发条件（如：调用 get_user_profile() 时传入了未初始化的 user_config 字典），而不是笼统说“用户请求失败”。
- 删掉所有“当时很着急”“沟通不畅”这类主观描述，它们不帮助下次避坑
- “表现”段只列可观察现象：
500 Internal Server Error、Traceback最顶行错误类型、监控图表突刺时间点（带时区） - “定位”段必须包含最小复现代码片段，例如：
config = {} # 缺少 default 字段<br>get_user_profile(config) # 触发 KeyError: 'default'
怎么写“根因分析”才不被质疑是拍脑袋
根因不能靠猜测，得靠证据链闭环。Python 里最常被误判的是“看起来像 A，其实是 B”，比如把 ImportError 归因为模块名写错，实际是 sys.path 被 os.chdir() 搞乱了路径。
验证根因的三步动作必须写进报告：
立即学习“Python免费学习笔记（深入）”；
- 在相同环境执行
python -c "import sys; print(sys.path)"，确认路径顺序 - 用
strace -e trace=openat python your_script.py 2>&1 | grep 'your_module'（Linux）看真实加载路径 - 临时加
print(__file__)在疑似模块头部，确认加载的是不是预期文件
只要缺其中一步，根因就存疑——尤其当错误只在 CI 或容器里出现时。
修复方案要具体到哪一行代码改什么
“已修复”三个字毫无信息量。“修复”段必须精确到函数、参数、赋值动作，否则别人合并 PR 时还得再花半小时读上下文。
例如，不要写：“优化了配置加载逻辑”。要写：
- 修改
load_config()函数，在第 42 行增加默认值兜底：config.setdefault('default', {}) - 删除第 67 行手动
os.chdir()，改用pathlib.Path(__file__).parent构造相对路径 - 在
requirements.txt中锁定requests==2.31.0（原为requests>=2.20.0），规避Session.close()在 2.32.0+ 的资源释放变更
验证步骤必须能被 QA 或运维一键跑通
写“已验证”不如直接给命令。验证不是截图，是可重复的动作。Python 项目最容易漏的是环境隔离和状态残留。
- 验证前先运行：
python -m venv /tmp/verify_env && /tmp/verify_env/bin/pip install -r requirements.txt - 验证命令必须带完整上下文：
cd /tmp/verify_env && PYTHONPATH=../src python -m pytest tests/test_config_load.py::test_missing_default -v - 关键状态检查不能靠肉眼：
curl -s http://localhost:8000/health | jq '.status'必须返回"ok"，否则算失败
复杂点在于：很多“修复”其实只是掩盖症状，比如用 try/except KeyError 吞掉错误却不补数据来源。这种报告里看不出问题，但下次出事会更难查——它绕过了数据契约检查。
