很多技术债不是因为当初的选择一定错了，而是后来的人只看见了“现在这样”，却找不到“当时为什么这样”。ADR（Architecture Decision Record，架构决策记录）要解决的不是写更多文档，而是把关键选择、约束和取舍放进代码仓库，让团队在修改系统前能先理解背景。
把缓存用稳：Cache-Aside、TTL 与一致性取舍清单
缓存不是“给慢接口加一层 Redis”这么简单。它能降低数据库压力、缩短高频读取的响应时间，也会引入过期数据、穿透、击穿、雪崩和回源放大。要把缓存用稳，关键是先承认它只是数据副本，再围绕读写路径、过期策略和故障边界做工程约束。
把质量检查前移：pre-commit Hooks 的渐进落地清单
代码质量问题越晚发现，修复成本越高。等 CI 跑红时，开发者已经切到下一个任务；等评审者指出格式、拼写、导入顺序或误提交密钥时，讨论也会被低价值噪声占满。pre-commit 的价值不是替代 CI，而是把确定、低成本、可自动修复的检查提前到 git commit 之前。
用 Feature Flag 控制发布风险：开关、灰度与回滚清单
一次发布真正危险的部分，往往不是代码合并，而是新逻辑第一次面对真实流量。Feature Flag 的价值，就是把“部署”和“启用”拆开：代码可以先安全上线，功能再按用户、环境、比例逐步打开；一旦指标异常，也能在不重新发版的情况下关闭入口。
依赖更新别靠手感：锁文件、版本范围与 CI 闸口清单
项目刚启动时，依赖更新看起来只是顺手执行一次 npm update、pip install -U 或 go get -u。但项目一旦进入多人协作和持续发布，依赖就会变成一条隐形供应链：版本范围决定会装到什么，锁文件决定实际运行什么，CI 决定能不能把变化放进主干。把这三件事管住，依赖更新才不会从“维护动作”变成“随机事故”。
把 E2E 测试写稳：Playwright 的选择器、等待与 CI 诊断清单
端到端测试最容易被团队嫌弃，因为它一旦不稳定，就会在 CI 里反复制造红灯：本地能过、线上偶发失败、截图看不出原因。问题通常不在 Playwright 本身，而在用例把页面动画、接口耗时、测试数据和外部状态都当成了“刚好会按时出现”。要让 E2E 真正保护发布，需要先把它写成可预测的工程资产。
把密钥管住：从 .env 到 CI Secrets 的配置安全清单
很多项目的第一份配置都很简单：复制一份 .env，填上数据库地址、API Key 和调试开关，应用就能跑起来。但项目一旦进入多人协作、CI 构建和线上发布，配置就不再只是“读几个环境变量”。真正要管住的是边界：哪些值可以进仓库，哪些只能留在本机，哪些必须由 CI 或运行时注入，以及密钥泄露后如何快速轮换。
用 API 契约测试守住前后端协作边界
前后端联调最怕的不是接口还没写完，而是大家以为已经说清楚了：字段名临时改了、枚举多了一个值、错误结构不一致、分页参数含义不同。API 契约测试的价值，就是把这些口头约定变成可执行的检查，让接口变更在进入主干和发布前就暴露出来。
用 Docker Compose 打造可维护的本地开发环境
本地环境最怕两件事：新同事跑不起来，老项目没人敢动。Docker Compose 的价值不只是“一条命令启动数据库”，而是把应用、依赖、端口、数据卷和调试入口写成可以审查的工程契约。下面这份清单适合中小型 Web 项目，也适合把散落的 README 步骤收敛成稳定入口。
把日志写到能排障：结构化日志、Trace ID 与脱敏清单
很多系统不是没有日志，而是日志只能证明“代码曾经跑过”。真正能排障的日志，应该在事故发生时回答三个问题：这是谁的请求、走到了哪一步、为什么变慢或失败。把日志从散乱句子升级为结构化事件，再配合 Trace ID、字段规范和脱敏策略，排查效率会比临时翻字符串高很多。