poteto-principles

poteto-principles

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

この 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。不正な状態を型で表せなくし、境界で解析し、コンパイラに嘘をつかない