交付前的功能检查翻看最近三个月的 Git Commit 日志几个极为眼熟的提交说明频频出现fix concurrent map write crash、fix memory leak again、resolve API timeout lock issue。相同的并发竞争死锁漏洞在三个不同的业务模块中重复触发了三次每次都消耗掉了整个半夜的排障时间。独立开发者因为缺乏团队内部的代码审查Code Review机制最容易陷入“踩坑-临时修复-遗忘-再次踩坑”的死循环。大多数人写的复盘记录和 Readme最后都沦为了保存在文件夹深处的摆设。如何让复盘记录真正转化为代码库里的物理约束与架构决策记录ADR是提高独立开发效率的关键。1. 为什么传统的项目复盘总是失效分析过数十份独立开发者的排障笔记后我们发现了复盘失效的三个常见根因只有情感归因没有技术根因复盘里写满了“这次是我大意了”、“忘记加超时控制了”却没有回答“为什么架构层没有强制限制超时参数”。复盘文档与代码仓库物理脱节复盘记在外部笔记软件里半年后重构代码时完全记不起当初为什么使用这个变通方案Workaround。缺乏自动化防线落地复盘得出的结论没有转化为单元测试、ESLint / Static Check 规则或 CI 校验脚本。真正有价值的复盘应产出两样东西一份合并进代码库的 ADR 架构决策记录以及一条新增的 CI 自动化拦截规则。2. ADR 与 5-Whys 物理闭环机制我们将线上故障与架构变更统一纳入 ADR 决策演化闭环每一个 ADR 文档记录了“当时面对的上下文”、“做出的决定”以及“该决定带来的副作用Consequences”为未来的代码重构留下了清晰的物理证据。3. ADR 标准模板与自动化规则校验 CLI 代码我们在 Git 仓库的doc/adr/目录下统一管理决策文件。以下是用 TypeScript 编写的 ADR 格式与合规校验 CLI 工具确保每一次复盘和决策都符合物理规范import * as fs from fs; import * as path from path; export interface ADRHeader { id: number; title: string; status: PROPOSED | ACCEPTED | REJECTED | SUPERSEDED; date: string; } export class ADRChecker { /** * 检查仓库中 doc/adr/ 下的所有 Markdown 是否符合规范 */ public static checkDirectory(adrDir: string): boolean { if (!fs.existsSync(adrDir)) { console.error([ADR Error] ADR 目录不存在: ${adrDir}); return false; } const files fs.readdirSync(adrDir).filter(f f.endsWith(.md)); let hasError false; for (const file of files) { const filePath path.join(adrDir, file); const content fs.readFileSync(filePath, utf-8); // 验证元数据头信息 if (!content.includes(## 上下文与问题陈述)) { console.error([ADR Lint Failed] 文件 ${file} 缺少 ## 上下文与问题陈述 章节); hasError true; } if (!content.includes(## 决策结果)) { console.error([ADR Lint Failed] 文件 ${file} 缺少 ## 决策结果 章节); hasError true; } if (!content.includes(## 自动化防护验证)) { console.error([ADR Lint Failed] 文件 ${file} 缺少 ## 自动化防护验证 章节应指定 CI 拦截规则); hasError true; } } if (!hasError) { console.log([ADR Check Success] 所有 ${files.length} 份 ADR 记录规范校验通过); } return !hasError; } }配套的标准 ADR 架构决策记录模板文件doc/adr/0004-use-jitter-backoff-for-api.md# 4. 模型 API 调用统一采用 Jitter 指数退避与硬超时 * 状态ACCEPTED * 日期2026-08-21 ## 上下文与问题陈述 在上周的线上故障中主模型 API 触发 504 超时导致 Worker 线程死锁归因于 API 客户端未显式配置 timeout 与重试退避。 ## 决策结果 放弃原生的 fetch/axios 默认调用统一改用封装好的 ModelFallbackProxy 代理类。所有 LLM 请求硬超时设为 4500ms重试时引入随机 Jitter 抖动。 ## 自动化防护验证 已新增单元测试 tests/proxy_timeout.test.ts并设置 ESLint 规则禁用直接 axios.post 调用第三方 API。4. 终端日志分析与复盘结果挖掘命令在定期复盘时使用终端工具快速提取项目历史提交与故障平均恢复时间MTTR# 1. 统计过去 30 天内包含 fix 关键词的 Commit 频次与影响文件 git log --since30 days ago --oneline --grepfix | awk {print $1} | xargs -I {} git show --stat {} # 2. 使用 adr-tools 或自定义 CLI 扫描当前仓库的 ADR 决策列表 npx ts-node ./scripts/check_adr.ts doc/adr/ # 3. 统计线上故障日志中的平均修复耗时与异常分布 cat /var/log/app/postmortem-events.json | jq -r .[] | [.incident_id, .mttr_minutes, .root_cause] | tsv利用这些命令行输出独立开发者可以在每月总结时清楚地看到哪些模块引发了最多的重复 Bug以及新增的 ADR 规则是否成功阻止了类似问题的二次发生。5. 可复制的项目复盘 5-Whys 卡片在每次线上故障解决后 24 小时内按照以下模版完成 5-Whys 分析并写入 ADR现象描述发生了什么影响范围有多大例API 延迟飙升到 5s影响 20% 用户。第一重 Why为什么延迟会飙升大模型 API 未在 4s 内返回。第二重 Why为什么没有断开HTTP 客户端未设置 Timeout 参数。第三重 Why为什么未设置 Timeout开发时直接使用了默认的 axios 实例。第四重 Why为什么默认实例能通过 Code Base 校验缺乏针对 API 调用的全局封装规范与 Linter 拦截。第五重 Why根因与落地如何确保再也不犯编写全局ModelFallbackProxy并在 CI 中禁止直接 import 原生 axios。 交付前的功能检查
交付前的功能检查翻看最近三个月的 Git Commit 日志几个极为眼熟的提交说明频频出现fix concurrent map write crash、fix memory leak again、resolve API timeout lock issue。相同的并发竞争死锁漏洞在三个不同的业务模块中重复触发了三次每次都消耗掉了整个半夜的排障时间。独立开发者因为缺乏团队内部的代码审查Code Review机制最容易陷入“踩坑-临时修复-遗忘-再次踩坑”的死循环。大多数人写的复盘记录和 Readme最后都沦为了保存在文件夹深处的摆设。如何让复盘记录真正转化为代码库里的物理约束与架构决策记录ADR是提高独立开发效率的关键。1. 为什么传统的项目复盘总是失效分析过数十份独立开发者的排障笔记后我们发现了复盘失效的三个常见根因只有情感归因没有技术根因复盘里写满了“这次是我大意了”、“忘记加超时控制了”却没有回答“为什么架构层没有强制限制超时参数”。复盘文档与代码仓库物理脱节复盘记在外部笔记软件里半年后重构代码时完全记不起当初为什么使用这个变通方案Workaround。缺乏自动化防线落地复盘得出的结论没有转化为单元测试、ESLint / Static Check 规则或 CI 校验脚本。真正有价值的复盘应产出两样东西一份合并进代码库的 ADR 架构决策记录以及一条新增的 CI 自动化拦截规则。2. ADR 与 5-Whys 物理闭环机制我们将线上故障与架构变更统一纳入 ADR 决策演化闭环每一个 ADR 文档记录了“当时面对的上下文”、“做出的决定”以及“该决定带来的副作用Consequences”为未来的代码重构留下了清晰的物理证据。3. ADR 标准模板与自动化规则校验 CLI 代码我们在 Git 仓库的doc/adr/目录下统一管理决策文件。以下是用 TypeScript 编写的 ADR 格式与合规校验 CLI 工具确保每一次复盘和决策都符合物理规范import * as fs from fs; import * as path from path; export interface ADRHeader { id: number; title: string; status: PROPOSED | ACCEPTED | REJECTED | SUPERSEDED; date: string; } export class ADRChecker { /** * 检查仓库中 doc/adr/ 下的所有 Markdown 是否符合规范 */ public static checkDirectory(adrDir: string): boolean { if (!fs.existsSync(adrDir)) { console.error([ADR Error] ADR 目录不存在: ${adrDir}); return false; } const files fs.readdirSync(adrDir).filter(f f.endsWith(.md)); let hasError false; for (const file of files) { const filePath path.join(adrDir, file); const content fs.readFileSync(filePath, utf-8); // 验证元数据头信息 if (!content.includes(## 上下文与问题陈述)) { console.error([ADR Lint Failed] 文件 ${file} 缺少 ## 上下文与问题陈述 章节); hasError true; } if (!content.includes(## 决策结果)) { console.error([ADR Lint Failed] 文件 ${file} 缺少 ## 决策结果 章节); hasError true; } if (!content.includes(## 自动化防护验证)) { console.error([ADR Lint Failed] 文件 ${file} 缺少 ## 自动化防护验证 章节应指定 CI 拦截规则); hasError true; } } if (!hasError) { console.log([ADR Check Success] 所有 ${files.length} 份 ADR 记录规范校验通过); } return !hasError; } }配套的标准 ADR 架构决策记录模板文件doc/adr/0004-use-jitter-backoff-for-api.md# 4. 模型 API 调用统一采用 Jitter 指数退避与硬超时 * 状态ACCEPTED * 日期2026-08-21 ## 上下文与问题陈述 在上周的线上故障中主模型 API 触发 504 超时导致 Worker 线程死锁归因于 API 客户端未显式配置 timeout 与重试退避。 ## 决策结果 放弃原生的 fetch/axios 默认调用统一改用封装好的 ModelFallbackProxy 代理类。所有 LLM 请求硬超时设为 4500ms重试时引入随机 Jitter 抖动。 ## 自动化防护验证 已新增单元测试 tests/proxy_timeout.test.ts并设置 ESLint 规则禁用直接 axios.post 调用第三方 API。4. 终端日志分析与复盘结果挖掘命令在定期复盘时使用终端工具快速提取项目历史提交与故障平均恢复时间MTTR# 1. 统计过去 30 天内包含 fix 关键词的 Commit 频次与影响文件 git log --since30 days ago --oneline --grepfix | awk {print $1} | xargs -I {} git show --stat {} # 2. 使用 adr-tools 或自定义 CLI 扫描当前仓库的 ADR 决策列表 npx ts-node ./scripts/check_adr.ts doc/adr/ # 3. 统计线上故障日志中的平均修复耗时与异常分布 cat /var/log/app/postmortem-events.json | jq -r .[] | [.incident_id, .mttr_minutes, .root_cause] | tsv利用这些命令行输出独立开发者可以在每月总结时清楚地看到哪些模块引发了最多的重复 Bug以及新增的 ADR 规则是否成功阻止了类似问题的二次发生。5. 可复制的项目复盘 5-Whys 卡片在每次线上故障解决后 24 小时内按照以下模版完成 5-Whys 分析并写入 ADR现象描述发生了什么影响范围有多大例API 延迟飙升到 5s影响 20% 用户。第一重 Why为什么延迟会飙升大模型 API 未在 4s 内返回。第二重 Why为什么没有断开HTTP 客户端未设置 Timeout 参数。第三重 Why为什么未设置 Timeout开发时直接使用了默认的 axios 实例。第四重 Why为什么默认实例能通过 Code Base 校验缺乏针对 API 调用的全局封装规范与 Linter 拦截。第五重 Why根因与落地如何确保再也不犯编写全局ModelFallbackProxy并在 CI 中禁止直接 import 原生 axios。