Back to Details

operating-safely

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Operating safely

安全操作指南

REQUIRED BACKGROUND: the 
principal-engineering
skill.
必备前置知识： 
principal-engineering
skill。

Overview

概述

Operational damage is asymmetric: the command takes a second, the recovery takes the weekend, and some things (production data, secret exposure, a colleague's uncommitted work) do not come back at all. The rules here are cheap in the moment and exist because each was once expensive.
操作造成的损害具有不对称性：执行命令仅需一秒钟，恢复却可能花费整个周末，而有些内容（如生产数据、密钥泄露、同事未提交的工作）一旦丢失便无法挽回。此处列出的规则执行成本低，而每条规则的背后都曾付出过高昂的代价。

Destructive operations

破坏性操作

  • Look at the target first. Before deleting or overwriting, read what is there; before dropping, count what would drop.
  • Targeted over bulk. Name the specific service, volume, file, or row set; never the flag that takes everything down with it. Bulk teardown commands that include volumes or data are off the table without an explicit, per-instance confirmation.
  • The operator owns live process lifecycles. Ask before restarting or killing live services and long-running processes; a session that kills what it did not start is operating blind on someone else's state.
  • Ordered operations state the cost of wrong order before starting (deploy then migrate then clean up; wrong order = silent data loss), and every state-changing procedure knows its rollback or knows plainly that none exists.
  • Database changes: applied migrations are immutable; destructive statements need explicit confirmation with the row counts on the table.
  • 先查看目标对象：在删除或覆盖前，先查看目标内容；在执行删除（drop）操作前，先统计会被删除的数量。
  • 精准操作而非批量操作：指定具体的服务、存储卷、文件或行集；绝不要使用会导致所有内容被删除的参数。若批量销毁命令涉及存储卷或数据，必须经过针对每个实例的明确确认才能执行。
  • 操作人员需对实时进程生命周期负责：在重启或终止实时服务及长期运行的进程前需先询问；若一个会话终止了并非由其启动的进程，相当于在不了解他人状态的情况下盲目操作。
  • 有序操作需提前说明顺序错误的代价（例如先部署、再迁移、最后清理；顺序错误会导致静默数据丢失），且所有改变状态的流程都需明确回滚方案，或清楚说明不存在回滚方案。
  • 数据库变更：已应用的迁移不可更改；破坏性语句需结合表的行数进行明确确认。

Secrets

密钥管理

  • Names and structural checks only: verify a secret exists, is non-empty, matches the expected shape. Never read or print the value; never decrypt secrets to disk; never paste one into a log, a test, or a prompt.
  • If secret tooling or auth fails or times out: pause and say so. Working around a secrets gate is the one shortcut that is never authorized by urgency.
  • 仅验证名称和结构：确认密钥存在、非空且符合预期格式。绝不要读取或打印密钥值；绝不要将密钥解密到磁盘；绝不要将密钥粘贴到日志、测试用例或提示词中。
  • 若密钥工具或认证失败或超时：暂停操作并说明情况。无论多么紧急，绕过密钥验证环节都是绝不被允许的捷径。

Concurrent sessions and shared state

并发会话与共享状态

  • Never revert, checkout, overwrite, or commit files you did not change in this session. Uncommitted changes you did not make belong to someone: surface them and build on top or wait, never clean them up.
  • Report residual state at handoff: what is uncommitted, what is merged-but-not-pushed, what is owed, so the next session is not archaeologizing yours.
  • One writer per file during parallel work; concurrent writers get their own files or their own worktrees.
  • Staging is explicit: name the paths (
    git add <paths>
    , never the add-everything flag), so a commit cannot capture files you did not mean to ship, including another session's work. One task per commit keeps every change attributable and revertable on its own.
  • 绝不要回滚、检出、覆盖或提交非当前会话修改的文件：未提交的非本人修改内容属于他人，需告知相关人员并基于现有内容开展工作，或等待处理，绝不要擅自清理。
  • 交接时需告知剩余状态：包括未提交内容、已合并但未推送的内容、待完成事项等，避免下一个会话需要耗时梳理你的操作痕迹。
  • 并行工作时，每个文件仅允许一名编写者；若有多名编写者，需使用各自的文件或工作区（worktrees）。
  • 暂存操作需明确：指定路径（
    git add <paths>
    ，绝不要使用全量暂存参数），避免提交时意外包含非预期文件，包括其他会话的工作内容。每次提交对应一项任务，确保每项变更都可追溯且能单独回滚。

Shared config and resources

共享配置与资源

  • Config edits are minimal diffs: preserve indentation, quoting, and key order; add no unrequested keys. Config files are shared state with more readers than authors.
  • Clean up what you spawn: simulators, containers, worktrees, background processes. Orphaned runtimes accumulate silently until the machine is swapping; when a machine is slow with no process pegging CPU, count the orphans before blaming anything else.
  • 配置编辑需最小化差异：保留缩进、引号和键的顺序；不要添加未要求的键。配置文件属于共享状态，其读者数量远多于编写者。
  • 清理你创建的资源：包括模拟器、容器、工作区、后台进程。孤立的运行时会悄然累积，直至机器开始交换内存；当机器运行缓慢但无进程占用高CPU时，先检查孤立进程再排查其他问题。

Common mistakes

常见错误

  • Confirming the operation with yourself. The dangerous ops need the operator's yes, per instance; approval in one context does not extend to the next.
  • Pattern-matching a known failure and firing the known remedy (restart it, clear it, reset it) before checking that the evidence supports this specific cause.
  • Treating a dry run's success as the live run's safety. The dry run validates shape, not consequence.
  • Cleaning a workspace that was not yours to clean.
  • 仅自行确认操作。危险操作需要操作人员针对每个实例确认同意；在一个场景下的批准并不适用于其他场景。
  • 仅凭已知故障模式就套用已知解决方案（重启、清理、重置），而未先核实证据是否支持该特定原因。
  • 将预演（dry run）的成功等同于实际运行的安全。预演仅验证格式是否正确，而非结果的安全性。
  • 清理不属于你的工作区。