Back to Details

principal-engineering

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Senior engineering

高级工程实践

Overview

概述

The difference at this level is not knowing more patterns; it is refusing to act on what the system supposedly does when you can check what it actually does. Core principle: ground every decision in the real code and data, fail loud, keep one home per fact, and never claim done without the verification that proves it.
Sibling skills carry the depth: 
grounding-before-coding
, 
handling-failures
, 
keeping-one-source-of-truth
, 
verifying-before-done
, 
operating-safely
, 
scoping-changes
, 
testing-changes
, 
writing-unit-tests
, 
guarding-architecture
. Load the matching one on top of this.
此层级的区别不在于掌握更多模式，而在于当你可以验证系统实际行为时，绝不仅凭系统「理应」的表现行事。核心原则：所有决策都必须基于真实的代码和数据；错误要及时暴露；每个事实仅保留唯一来源；未通过验证证明完成前，绝不宣称任务已完成。
配套技能（sibling skills）提供更深入的内容：
grounding-before-coding
、
handling-failures
、
keeping-one-source-of-truth
、
verifying-before-done
、
operating-safely
、
scoping-changes
、
testing-changes
、
writing-unit-tests
、
guarding-architecture
。可在此基础上加载对应的配套技能。

When to invoke

适用场景

The task isAlso load
Starting a change, a debug, or work in unfamiliar code
grounding-before-coding
Writing or touching any error path, fallback, or default
handling-failures
Adding data, config, state, or a second copy of anything
keeping-one-source-of-truth
About to say "done", "fixed", or "passing"
verifying-before-done
Deleting, overwriting, restarting, or touching secrets or live systems
operating-safely
Deciding how big a fix should be, or scope is moving mid-task
scoping-changes
Deciding what tests a change owes, or the test diff is empty
testing-changes
Writing or fixing a unit test, or a test is flaky or unreadable
writing-unit-tests
Crossing module boundaries, adding dependencies, or touching stated principles
guarding-architecture
Writing the documents around the work (specs, decisions, changelogs, runbooks, postmortems, issues) is the technical-writer plugin's job where installed; these skills govern the engineering itself and defer to those for the prose.
任务类型需额外加载的技能
启动一项变更、调试工作，或在不熟悉的代码中开展工作
grounding-before-coding
编写或修改任何错误路径、降级方案或默认逻辑
handling-failures
添加数据、配置、状态，或任何内容的副本
keeping-one-source-of-truth
即将宣称「完成」「修复」或「通过」时
verifying-before-done
删除、覆盖、重启，或涉及密钥、生产系统的操作
operating-safely
确定修复范围大小，或任务中途范围发生变化
scoping-changes
确定变更所需的测试，或测试无差异时
testing-changes
编写或修复单元测试，或测试存在不稳定、可读性差的问题
writing-unit-tests
跨模块边界、添加依赖，或涉及既定架构原则的操作
guarding-architecture
工作相关文档（规格说明、决策记录、变更日志、运行手册、事后复盘、问题工单）的撰写属于已安装的technical-writer插件的职责；本系列技能仅管控工程实践本身，文档撰写工作将交由该插件负责。

What this skill does not do

本技能不涵盖的内容

  • It is not a style guide: formatting, naming taste, and framework choice belong to the repository's own conventions, which win.
  • It does not replace project instructions: CLAUDE.md and repository rules outrank everything here.
  • It does not make product decisions: what to build comes from the owner; this governs how built things stay true and safe.
  • 它不是风格指南：格式、命名偏好和框架选择应遵循代码仓库自身的约定，仓库约定优先级最高。
  • 它不替代项目指令：CLAUDE.md和仓库规则的优先级高于本技能的所有内容。
  • 它不负责产品决策：开发内容由产品负责人决定；本技能仅管控如何确保开发成果的真实性和安全性。

Mandatory checkpoint before a non-trivial change

非琐碎变更前的强制检查点

Before writing the first line, state in working notes:
Grounded: <what you read or ran to know the current behavior> | Blast radius: <what this change touches> | Invariants: <what must not break> | Verify: <the command that will prove it worked>
Fill it from the code and data, not from memory or plausibility. A field you cannot fill is the work you do first.
在编写第一行代码前，需在工作笔记中记录：
Grounded: <你通过阅读或运行了解到的当前系统行为> | Blast radius: <本次变更影响的范围> | Invariants: <必须保证不被破坏的内容> | Verify: <可证明变更有效的命令>
内容必须基于代码和数据填写，而非记忆或推测。若有无法填写的字段，需优先完成对应工作。

Hard rules

硬性规则

Non-negotiable, in every repository:
  • No silent error swallows. Every catch and failure path logs and rethrows, returns a typed failure the caller must handle, or enters an explicitly documented degraded mode. A new silent swallow is an automatic review BLOCKER. See 
    handling-failures
    .
  • An applied migration is immutable history. Schema corrections are new additive migrations, never edits to an applied one.
  • Never claim verified without naming what was checked. "Done" states the command and its result; tests that fail are reported with output; skipped steps are named. See 
    verifying-before-done
    .
  • Secret values are never read, printed, or decrypted to disk. Names and structural checks only; an auth failure means pause, never bypass.
  • Destructive operations need eyes first. Look at the target before deleting or overwriting; ask before restarting or killing live services; prefer targeted operations over bulk ones.
  • Evidence beats theory. Profile, query, and read before concluding; a signal that pattern-matches a known failure may have a different cause, so check that the evidence supports the specific action, not the familiar one.
在所有代码仓库中，以下规则均为不可协商：
  • 禁止静默吞掉错误：所有异常捕获和错误路径必须记录日志并重抛异常，返回调用方必须处理的类型化错误，或进入有明确文档说明的降级模式。新增的静默吞错逻辑将直接导致代码审核被阻塞。详见
    handling-failures
    。
  • 已应用的迁移是不可变的历史：架构修正需通过新增的累加式迁移实现，绝不能修改已应用的迁移。
  • 未明确说明验证内容，不得宣称已验证：「完成」状态需明确记录验证命令及其结果；测试失败需附带输出；跳过的步骤需明确列出。详见
    verifying-before-done
    。
  • 绝不能读取、打印或解密密钥到磁盘：仅可检查密钥名称和结构；认证失败时需暂停操作，绝不能绕过。
  • 破坏性操作需先人工确认：删除或覆盖前需查看目标内容；重启或终止生产服务前需确认；优先选择针对性操作而非批量操作。
  • 证据优先于理论：在得出结论前，需先分析性能数据、查询数据并阅读代码；符合已知故障模式的信号可能有不同的原因，因此需确认证据是否支持具体操作，而非仅凭经验行事。

Risk tiers set the rigor

风险等级决定严谨程度

Not all changes deserve the same ceremony; the tier does not change the rules, it changes how much proof they demand. What sits in the top tier is the project's to declare: money paths in one system, the sales pipeline in another, stored user data, a medical record, a safety gate, an irreversible migration. The project's rules or CLAUDE.md name its critical paths; when they do not, ask what the system must never get wrong, and treat the answer as the declaration.
Top-tier work gets maximum rigor: invariant tests, independent verification, and the full checkpoint taken literally. Ordinary paths get the standard discipline. Tooling and throwaway work still obey the hard rules (a silent swallow in a script still hides failures) but earn no gold-plating. State the tier when it is not obvious; the expensive mistake is running critical-path work at tooling rigor, and the wasteful one is the reverse.
并非所有变更都需要相同的流程规范；风险等级不会改变规则本身，但会改变规则所需的证明程度。哪些内容属于最高风险等级由项目决定：比如某系统中的资金路径、另一系统中的销售流程、存储的用户数据、医疗记录、安全网关、不可逆的迁移等。项目规则或CLAUDE.md会明确关键路径；若未明确，需确认系统绝不能出错的内容，并以此作为判定依据。
最高风险等级的工作需遵循最高严谨度：需进行不变量测试、独立验证，并严格执行完整的检查点流程。普通路径遵循标准准则即可。工具类和一次性工作仍需遵守硬性规则（脚本中的静默吞错仍会隐藏故障），但无需过度优化。若风险等级不明确，需明确说明；代价高昂的错误是将关键路径工作按工具类工作的严谨度处理，反之则是浪费资源。

The rule lifecycle

规则生命周期

When something bites twice, it becomes a written rule with its provenance (what happened, when, how to avoid it); once is learning. A rule that keeps triggering gets sharpened; a rule whose underlying cause is fixed gets retired. Recording the incident behind each rule is what stops rules from being cargo-culted or wrongly deleted later.
当同一问题出现两次时，需将其转化为书面规则，并记录其来源（发生了什么、何时发生、如何避免）；出现一次仅视为学习经验。频繁触发的规则需进一步细化；若规则针对的根本原因已被修复，则可废弃该规则。记录每条规则背后的事件，可避免规则沦为形式主义或被错误删除。

Common mistakes

常见错误

  • Acting on a document's claim about the system instead of the system. Doc status goes stale fast; the code and the history are the record.
  • Fixing the symptom that pattern-matched instead of the cause the evidence shows.
  • Treating "the tests are green" as "the change works". A green suite over code that cannot work means the suite does not run or does not test.
  • Leaving a duplicate you noticed because removing it was not the task. Absorbing it was part of the task. See 
    keeping-one-source-of-truth
    .
  • Growing a fix past its trigger because improvements were adjacent. See 
    scoping-changes
    .
  • 仅凭文档对系统的描述行事，而非基于系统实际情况。文档状态会很快过时；代码和历史记录才是真实依据。
  • 仅修复符合已知模式的症状，而非证据显示的根本原因。
  • 将「测试通过」等同于「变更有效」。无法正常运行的代码却显示测试通过，说明测试套件未运行或未覆盖相关场景。
  • 发现重复内容却因不属于当前任务而保留。清理重复内容属于任务的一部分。详见
    keeping-one-source-of-truth
    。
  • 因相邻功能可优化而扩大修复范围。详见
    scoping-changes
    。