poteto-principles

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

poteto-principles

経験を積んだエンジニアが何度も効いた判断の観点を言葉にした、原則集である。

这是一套原则集合，将经验丰富的工程师反复运用且行之有效的判断视角表达出来。

この skill が必要な理由と達成したい状態

为什么需要这个 skill，以及希望达成的状态

この skill が必要な理由は、作業者がその場で思いつく観点でしか判断を問えないことにある。知らない観点は問いとして浮かばないので、抜けていても気づけず、同じ種類の誤りを繰り返す。経験を積んだエンジニアが、何度も効いた判断の観点を言葉にしたものを借りれば、その抜けを自分の経験を待たずに埋められる。

この skill で達成したい状態は、どの判断も、経験を積んだエンジニアが当てる観点を通っていることである。

之所以需要这个 skill，是因为作业者往往只能就当场想到的视角征求判断意见。未知的视角不会作为问题浮现出来，因此即使有所遗漏也不会察觉，进而反复犯下同类错误。借用经验丰富的工程师反复运用且行之有效的判断视角，就不必等待自己积累经验，也能补上这些遗漏。

希望达成的状态是：无论作出何种判断，都已经过经验丰富的工程师会采用的视角审视。

原則

原则

references/

はすべて読むこと。

```
attack-the-premise
```
。同じ前提を共有する修正が 2 つ以上同じ検査で落ちたら、修正ではなく前提を疑う
```
boundary-discipline
```
。検証とエラー処理は境界に集め、内部は型を信じ、ロジックは純粋関数に置く
```
build-the-lever
```
。手作業でやらず、同じ作業を再実行できる道具を作る
```
encode-lessons-in-structure
```
。同じ指示を 2 回書いたら、文ではなく lint、メタデータ、検査、スクリプトにする
```
exhaust-the-design-space
```
。前例のない設計は、競合する試作を 2 つか 3 つ作って比べてから決める
```
experience-first
```
。実装の都合より使う人の体験を選び、少なく磨いて出す
```
explain-the-number
```
。計った数字を信じる前に、何がそれを制限しているかを言う
```
fix-root-causes
```
。症状ではなく根本原因を直す。再現し、なぜを繰り返し、ガードで黙らせない
```
foundational-thinking
```
。ロジックより先にデータ構造を決め、土台になるものを先に作る
```
guard-the-context-window
```
。大きな出力はサブエージェントに回し、主スレッドには要約だけ残す
```
laziness-protocol
```
。削除に寄せ、問題を解く最小の変更にする
```
make-operations-idempotent
```
。何度実行しても、途中で落ちても、同じ終状態に収束させる
```
migrate-callers-then-delete-legacy-apis
```
。新しい API を入れたら、呼び出し元を移して旧 API を同じ波で消す
```
minimize-reader-load
```
。読み手が辿る層と頭に持つ状態を数え、どちらも減らす
```
model-the-domain
```
。分岐を散らさず、ドメインをデータ構造に表す
```
never-block-on-the-human
```
。元に戻せる作業は尋ねずに進め、結果を見せる
```
outcome-oriented-execution
```
。計画した移行では、途中の安定より最終状態の整合を優先する
```
prove-it-works
```
。完了と言う前に、代理ではなく実物で確かめる
```
redesign-from-first-principles
```
。新しい要件を継ぎ足さず、最初からあったものとして設計し直す
```
separate-before-serializing-shared-state
```
。共有される可変状態は、まず共有をなくし、本当に要るときだけ構造で直列化する
```
sequence-verifiable-units
```
。作業を検証できる小さな単位に切り、1 つずつ確かめて進める
```
subtract-before-you-add
```
。足す前に消す。不要なコード、検証、スタブを先に取り除く
```
test-behavior-not-implementation
```
。利用者と同じ呼び方でコードを呼び、利用者が見る結果そのものを検証する
```
type-system-discipline
```
。不正な状態を型で表せなくし、境界で解析し、コンパイラに嘘をつかない

references/

中的内容全部阅读。

```
attack-the-premise
```
。如果两个以上基于同一前提的修复都未通过同一项检查，就应质疑前提，而不是继续修复。
```
boundary-discipline
```
。将验证和错误处理集中在边界处；内部相信类型；将逻辑放在纯函数中。
```
build-the-lever
```
。不要手工完成，应制作能够重复执行同一作业的工具。
```
encode-lessons-in-structure
```
。如果同一指示写了两遍，就不要写成文字，而应转化为 lint、元数据、检查或脚本。
```
exhaust-the-design-space
```
。对于没有先例的设计，先构建 2 个或 3 个相互竞争的原型，比较后再决定。
```
experience-first
```
。选择使用者的体验，而非实现上的便利；减少打磨并交付。
```
explain-the-number
```
。在相信测量结果之前，说明是什么限制了它。
```
fix-root-causes
```
。修复根本原因而非症状。复现问题，反复追问为什么，不要只用 guard 加以掩盖。
```
foundational-thinking
```
。先于逻辑决定数据结构，优先构建基础部分。
```
guard-the-context-window
```
。将大块输出交给子 Agent 处理，主线程只保留摘要。
```
laziness-protocol
```
。偏向删除，以解决问题所需的最小改动为准。
```
make-operations-idempotent
```
。无论执行多少次，或中途失败，都应收敛到相同的最终状态。
```
migrate-callers-then-delete-legacy-apis
```
。引入新 API 后，迁移调用方，并在同一轮变更中删除旧 API。
```
minimize-reader-load
```
。统计读者需要贯穿的层次以及需要在脑中记住的状态，并同时减少两者。
```
model-the-domain
```
。不要让分支散落各处，应使用数据结构表达领域。
```
never-block-on-the-human
```
。可回退的工作无需询问即可推进，并展示结果。
```
outcome-oriented-execution
```
。在有计划的迁移中，相比中间过程的稳定，更应优先保证最终状态的一致性。
```
prove-it-works
```
。在宣布完成之前，使用实际成果而非替代物进行验证。
```
redesign-from-first-principles
```
。不要拼凑新需求，而是将其视为一开始就存在的需求并重新设计。
```
separate-before-serializing-shared-state
```
。共享的可变状态应先消除共享；仅在确有必要时，再通过结构进行串行化。
```
sequence-verifiable-units
```
。将工作切分为可验证的小单元，逐一验证并逐步推进。
```
subtract-before-you-add
```
。添加之前先删除。移除不必要的代码、检查和 stub。
```
test-behavior-not-implementation
```
。像使用者一样调用代码，并验证使用者实际看到的结果。
```
type-system-discipline
```
。让非法状态无法由类型表示，在边界处进行解析，不向编译器说谎。