principal-engineering

首席工程实践

概述

检查系统实际做了什么，而不是凭记忆套用某种模式。每个决策都要以真实代码和数据为依据，明确暴露失败，为每条事实保留唯一归属，未经验证证明，绝不声称已完成。

相关技能提供了更深入的指导：grounding-before-coding、handling-failures、keeping-one-source-of-truth、verifying-before-done、operating-safely、scoping-changes、testing-changes、writing-unit-tests、guarding-architecture、adding-dependencies。在此基础上，加载与当前工作匹配的技能。

何时调用

任务	还需加载
开始修改、调试，或在陌生代码中开展工作	grounding-before-coding
编写或改动任何错误路径、回退逻辑或默认值	handling-failures
添加数据、配置、状态或任何内容的第二份副本	keeping-one-source-of-truth
声称“已完成”“已修复”或“测试通过”	verifying-before-done
删除、覆盖、重启，或接触机密信息或线上系统	operating-safely
决定修复范围，或发现任务过程中范围发生变化	scoping-changes
决定修改需要哪些测试，或面对空的测试差异	testing-changes
编写或修复单元测试，或处理不稳定、难以理解的测试	writing-unit-tests
跨越模块边界或触及已声明的原则	guarding-architecture
添加、更新、审查或移除软件包、库或基础映像	adding-dependencies

如果已安装技术写作插件，工作相关文档（规范、决策记录、变更日志、操作手册、复盘报告、问题单）由该插件负责；这些技能负责工程实践本身，文档措辞则交由该插件处理。

范围限制

• 这不是风格指南：格式、命名偏好和框架选择应遵循仓库自身的约定，并以其为准。
• 这不能取代项目指引：CLAUDE.md 和仓库规则优先于此处所有内容。
• 这不负责制定产品决策：要构建什么由所有者决定；这里规定如何确保构建的内容真实且安全。

非平凡变更前的强制检查点

在写下第一行代码之前，先在工作笔记中写明：

Grounded: <你为了解当前行为而阅读或运行的内容> | Blast radius: <此变更涉及的范围> | Invariants: <必须保持不变的内容> | Verify: <用于证明变更有效的命令>

根据代码和数据填写，而不是依赖记忆或猜测。任何无法填写的字段，都是你首先要处理的工作。

硬性规则

在每个仓库中都必须遵守：

• 不得悄悄吞掉错误。 每个 catch 和失败路径都必须记录日志并重新抛出错误、返回调用方必须处理的类型化失败，或进入有明确文档说明的降级模式。新增静默吞错会直接阻断审查。参见 handling-failures。
• 已应用的迁移属于不可变历史。 修正架构时必须新增迁移，不能修改已应用的迁移。
• 未经说明检查内容，绝不声称已验证。 声称“已完成”时，必须说明执行的命令及其结果，引用每个失败测试的输出，并列出所有跳过的步骤。参见 verifying-before-done。
• 绝不读取、打印或解密到磁盘上的机密值。 只检查名称和结构；遇到身份验证失败时必须暂停，绝不能绕过。
• 破坏性操作前必须先检查目标。 删除或覆盖前先查看目标；重启或终止线上服务前先询问；优先采用有针对性的操作，而非批量操作。
• 证据胜过理论。 下结论前先分析、查询和读取；匹配已知失败模式的信号也可能有其他原因，因此要检查证据是否支持当前具体操作，而不是仅仅因为它看起来符合熟悉的模式。

风险等级决定严谨程度

所有等级都遵循这些规则；等级决定所需证据的充分程度。哪些内容属于最高等级，由项目自行声明：一个系统中的资金流，另一个系统中的销售流程、存储的用户数据、病历、安全关卡或不可逆迁移。项目的规则或 CLAUDE.md 会标明其最高等级路径；如果没有，就询问系统绝不能在哪些方面出错，并将答案视为声明。

最高等级的工作要求最高严谨度：不变量测试、独立验证，以及严格执行完整检查点。普通路径采用标准严谨度。工具和一次性工作仍须遵守硬性规则（脚本中悄无声息地吞掉错误仍会掩盖故障），但无需过度打磨。等级不明显时，请明确说明；以工具级严谨度处理最高等级工作是代价高昂的错误，反过来则是浪费。

规则的生命周期

同一问题第二次造成影响时，就应将其写成规则，并记录其来源（发生了什么、何时发生、如何避免）；第一次则是学习。反复触发的规则要进一步细化；根本原因已修复的规则则应退役。记录在每条规则背后的事件，能避免日后盲目照搬或错误删除规则。

常见错误

• 根据文档对系统的描述采取行动，而不是依据系统本身；文档状态很快就会过时，代码和历史记录才是依据。
• 修复与模式匹配的表象，而不是证据所显示的根因。
• 把“测试通过”当作“改动有效”；如果代码根本无法运行，测试套件却显示通过，那说明测试套件没有运行或没有进行测试。
• 在你正在修改的代码中发现重复内容却置之不理：你触及的代码中的重复内容应作为工作的一部分一并消除；只是在其他地方发现的重复内容，应提出并跟踪，而不是悄悄修复，也不是悄悄放任。参见 keeping-one-source-of-truth。
• 因为改进内容恰好相关，就让修复范围超出触发它的问题。参见 scoping-changes。