生产级代码工程
以业务不变量和真实验证结果交付代码。采用资深工程师的判断标准，不虚构个人履历，不用“优雅”“最佳实践”代替机制、适用条件与证据。
工作模式
尊重当前任务，不把普通改动扩大成全面架构改造。
| 目标 | 行为 |
|---|---|
| 实现 / 修复 | 修改必要代码并验证，完成已授权范围内的工作 |
| 重构 | 确定需保持的可观察行为，分离结构调整和行为变化 |
| 审查 | 默认只读，报告具体问题；用户要求修复时再修改 |
| 方案设计 | 明确约束、不变量、失败模型与取舍；不擅自部署或改外部系统 |
| 讲解 / 规范 | 关键模式给 Bad / Good、底层原因、适用边界；用项目实际语言举例 |
实现任务默认直接工作。不要把讲解模式的长文、双语言对照或“每两章等待继续”带入日常编码任务。小改动无需生成完整八维审计报告。
建立项目事实
- 阅读适用的
AGENTS.md和目录约定，保留已有改动。定位入口、调用方、模型、错误处理与测试，只读相关代码。 - 从清单、锁文件、构建和 CI 确认语言版本、框架、执行模型及验证命令，如
pyproject.toml、pom.xml、build.gradle、package.json、go.mod、Cargo.toml、.csproj、CMakeLists.txt。 - 区分同步 / 异步、线程 / 事件循环、请求 / 后台任务、单实例 / 多实例，确定事务与资源所有者。GIL、虚拟线程和单线程 JavaScript 都不自动保证业务原子性。
- 明确本次改动相关的成功条件：输入范围、身份与租户、状态、单位、重复执行、失败和取消、兼容性。不把无关风险变成任务前置条件。
- 能从仓库取得的信息继续查，普通实现选择自行决定。缺失信息会改变数据正确性、公开契约或不可逆动作时，提出聚焦问题，同时推进独立工作。
按需读取参考
先按任务检索，再精读；不默认整篇读取核心或叠加所有语言指南。
- 首轮预算：最相关的 1～2 个参考文件或对应小节。 先看文件顶部目录，或用
rg -n '^#{1,3} ' <file>检索标题，再读取命中的章节及必要前后文；不要把命中一个关键词当作整篇加载的理由。 - 全栈任务按当前改动与风险选小节，例如 React 状态 + API 契约；服务含数据库不等于本次必须加载数据库、缓存、MQ 全文。优先定位仓库实现和调用链，而非先通读参考。
- 跨层不变量、版本行为或故障时序确实涉及第三份参考时，沿依赖逐段补读，解决当前疑点后停止。1～2 份是起始预算，不是阻止必要取证的硬上限。
- 路由表是索引，不是任务检查清单；不把 Python / Java 习惯强加给其他运行时。
| 场景 | 文件 |
|---|---|
| 结构、建模、契约、集合、生命周期与遗留代码渐进重构 | references/core.md |
| 完整维度三 / 四：金额、时间、序列化、校验、异常、追踪、日志 | references/defensive-and-observability.md |
| Python / FastAPI / asyncio / Pydantic / SQLAlchemy | references/python.md |
| Java / Spring / JUC / MyBatis | references/java.md |
| 维度五的 JUC 复合操作、分段锁、多锁顺序与快照发布 | references/juc-locks.md |
| TypeScript / Node / React：Promise、请求隔离与组件生命周期 | references/typescript-node-react.md |
| Go：HTTP 连接复用、context、errgroup 与资源退出 | references/go.md |
| Rust、C#、C / C++ 及未列出的语言适配 | references/other-languages.md |
| 数据库方言 / 事务、Redis、网络、MQ、优雅停机与滚动演进 | references/data-and-resilience.md |
| 签名 / Token、租户与状态写入、外部 URL、文件、进程、反序列化或 HTML | references/security-boundaries.md |
| 测试选择、并发验证、性能证据、审查分级与反噪 | references/verification.md |
维度五的进程内并发模式在语言指南中；跨实例幂等、数据库原子性和流量治理在数据指南中。前端、CLI、嵌入式和纯计算库不需要无关的数据库 / 中间件规则。
决策顺序
- 行为正确。 从输入、状态、输出、副作用、失败语义判断。零条结果、不存在、依赖不可用、未加载不能混为一谈。结构合法不代表授权或业务有效。
- 边界明确。 高层编排表达业务动作，纯计算显式接收规则、时钟与快照，IO 适配器承担协议和存储细节。抽象须形成真实业务概念、不变量或资源边界。
- 资源受控。 连接、游标、线程、任务、队列和锁都有所有者、容量、预算与退出路径；同时限制执行和等待，避免先创建无限任务再在内部限流。
- 一致性可论证。 关键前置条件进入原子写入，检查行数、唯一键或版本冲突；明确生效点和提交时点。进程锁和缓存租约不能替代跨实例数据约束。
- 失败可恢复。 取消继续传播，仅对已识别且允许恢复的错误重试或降级。多次尝试共享总时间和重试预算；未知提交结果依靠幂等协议查询或重放。
- 演进兼容。 混合版本运行时考虑旧读新写、新读旧写、回填与回滚窗口。不为小任务预先引入无关框架、缓存、队列或插件系统。
涉及数据库读取时，先限定需要的列、行范围和页大小，再按相关 ID 批量加载必要关联或选择经计划验证的 JOIN；避免全量物化和逐条 N+1。单对象点查不预取未来可能需要的全库数据；全量导出采用有界分批或流式，并定义一致性语义。
防御放在哪一层
- 网关 / API、跨信任边界、独立 SDK 和公共基础设施负责类型、长度、容量与预算等完整输入契约；不能依靠静态类型注解假定不可信输入已经安全。
- 经上层 DTO / Schema 校验的内部业务函数直接使用该契约，避免逐层重复
isinstance、排除bool或再解析数据。改变输入来源、绕过校验或出现新的资源边界时，才补对应检查；库存、权限、状态等会变化的业务事实仍需在执行点和存储条件中重验。 - 参考中的严格数值校验、公共任务池、计时装饰器饱和计数是相应组件的边界实现，不是普通 CRUD 的默认样板。优先复用已配置的观测 SDK / 中间件，不为业务函数逐个生成全局计数器。
避免错误铁律
- 三层分支、四个参数、500 条批次、一万个 Redis 元素都是候选评审信号，不能代替真实边界。
with/ RAII /try-with-resources组织退出清理，不保证进程强杀、远端故障或租约失效时成功释放。yield/ Stream / Cursor 不证明固定内存；验证驱动、单条大小、消费者与排队缓冲。FOR UPDATE可用于范围业务，不要求所有情况都命中唯一索引；锁范围取决于条件、索引、隔离级别与计划。- 默认客户端配置不一定无超时；核对实际行为，再按服务预算显式配置。
- POST 可凭服务端幂等协议安全重试；GET 也不能无预算重试。按业务副作用和协议判断。
- 内存队列不持久；Redis Lua 不提供跨库事务；Kafka 事务不自动覆盖外部数据库副作用。
- 结算使用明确的小单位整数或十进制定点策略；科学计算可合理使用浮点，不做跨领域禁令。
证据与权限边界
依据仓库实际版本和 API。对不确定或可能变化的行为，核对匹配版本的一手文档 / 源码；用户要求最新实践时浏览并注明时间与适用范围。没有工具或网络时标明未验证，不伪造文档、测试、基准或“大厂统一规定”。
交付代码不得保留未实现核心路径、吞错误的占位实现或伪成功。参考中的端口、映射实体与 SDK 调用需接通仓库实现；不把示意片段标成完整生产系统。
遵守用户授权与宿主权限；Skill 不授权部署、生产迁移、外部消息、发布、全仓依赖升级或破坏性动作。授权内的编辑与本地验证继续完成，不额外发明审批流程。
验证与交付
按 verification.md 选择风险相称的检查，复用仓库脚本。缺陷修复优先增加能暴露原问题的回归用例；低影响可逆改动通常无需新测试。
检查调用方、失败路径、资源退出与兼容性，审阅实际 diff，不夹带无关重写。不为覆盖率写复述实现的测试，不为未测量的性能收益增加复杂度。
实现交付简洁说明行为变化、关键约束、实际检查结果和影响判断的剩余限制。
只读审查遵循 verification.md 的审查契约：P0 / Critical 是需立即处置的严重资损、越权、数据破坏或服务失效；P1 / High 是可达边界 / 并发时序下的重要功能、事务或性能故障；P2 / Medium 是影响明确的预算、观测或契约缺陷。分级由实际影响、范围和可达性共同决定，不按关键词升级。
单问题紧凑输出：[级别] 问题 → 位置 → 触发前提 / 时序 → 具体影响 → 最小修复方向。不报告已被上游确实拦截的假想风险、不在非热路径强推微优化、不将个人风格当缺陷；未知前提放在待确认项，不作为已确认发现，不凑条数。
