eng-docs

原則

11 min read

原則

AI に委譲できない判断はどれか。 既存の原則は7項目あるが、 AI に実装を任せると難しさの分布が変わる。楽になる項目と、逆に重くなる項目がある。

元の規範

原則と、 ソフトウェアエンジニアリングとは何か。

そのうち、AI 相手で扱いが変わるのはこの4つ。

元の項目AI 駆動での扱い
推測ではなく実際にどうなるか**重くなる。**この文書で最も重要な項目
シンプルが一番**重くなる。**削る判断は委譲できない
なんのためか目的を考える**重くなる。**AI は目的を問い直さずに完遂する
全体を俯瞰してみる**重くなる。**渡していない範囲は存在しないのと同じ

逆に、スケールするかと 変化への対応をしやすくするは 変わらない。設計の性質の話であって、誰が書いたかに依存しない。

何が崩れるか

推測が、高速に、大量に出てくる

元の規範はこう書いてある。

推測だけで物事を考えると、実際に実行したときに推測と違うことが多々起こる
簡単に実行できるものは実行してみて、どうなるか挙動を確認する

これは元々「人間が推測を出す速さ」を前提にした規範だった。 自分で書いた1つの推測を自分で確かめる、という比率で釣り合っていた。

AI は推測を桁違いに速く、しかも自信のある文体で出す。 確かめる側の速さは変わっていないので、比率が崩れる。

崩れ方は3つの形で出る。

形何が起きるか
動かしていないものを「動く」と書く実行していないコードに対する説明が、実行した結果と同じ文体で来る
存在しない API・オプションを使う名前として自然なので、読んだだけでは気づけない
確かめた範囲を明示しない「テストを追加しました」が、書いただけなのか通したのかで区別されない

対処の方向は1つしかない。実行結果そのものを出させて、それを見る。 説明文は根拠にならない。 コード側の 「実際のユースケースやパターンのデータで確かめる」もそのまま効く。 手で作った都合のよい入力を AI が用意しても、推測を確かめたことにはならない。

頼んだものを全部作る

シンプルが一番は、 人間には自然にブレーキがかかっていた規範でもある。 面倒だから作らない、という形で。

AI にはそのブレーキがない。設定項目、抽象化の層、将来のための拡張点、 エラーハンドリングの分岐が、頼まなくても付いてくる。 コードレビューの進め方が アンチパターンとして挙げているものが、既定値として出てくるということ。

削る判断は人間にしか残らない。 しかも削る作業自体は AI に頼めるので、難しいのは「削ると決めること」だけになる。

目的が問い直されない

書くことが目的になっていないか

人間なら、面倒な依頼に対して「それ本当に要る?」が自然に出る。 AI は出さない（訊くように指示すれば訊くが、既定では完遂する側に寄る）。

依頼が間違っていても、間違ったものが完成する。 しかも速く完成するので、間違いに気づく機会が減る。

決定の根拠が 挙げる2つの理由 —— 要件だからやる / 現時点のエビデンスで最良だから —— のどちらでもない実装が、一番増えやすいのがここ。

渡していない文脈は存在しない

全体を俯瞰してみるは 「どこからどのように使われているか調べる」と書いてある。

AI は渡された範囲の中ではよく調べる。範囲の外は見ない。 だから「呼び出し元が3つあることを知らずに、シグネチャを変える」が起きる。

これは Hyrum の法則の 問題と同じ場所に出る。観察可能な挙動には依存者が現れるが、 その依存者はコードベースの別の場所にいて、渡していなければ見えない。

どう仕掛けるか

注意力ではなく、出力の形式で縛る。 「気をつける」は、相手が速いほど効かなくなる。

崩れ方仕掛け
推測が出る**実行したコマンドと、その出力を報告に含めさせる。**含まれていない主張は未確認として扱う
全部作る頼んでいないものを足したら、足したことと理由を明示させる
目的が問われない**前提が食い違うと成果物が無駄になる場合だけ、着手前に訊かせる。**それ以外は進ませる
文脈の外を見ない変更したシンボルの呼び出し元を全部探してから変えさせる

4つ目は左への移動そのもので、 AI に任せるほど価値が上がる。人間のレビュー帯域が律速になるので、 そこへ届く前に落とせる欠陥の価値が相対的に上がるため。

そして最後に、取り消せることを担保する。 決定を覆せることは 元々リーダーシップの話として書かれているが、AI 駆動では実務の話になる。 速く大量に変更が入るので、個々の変更の正しさを事前に保証するのは無理になる。 戻せる単位で刻むことだけが、まともに効くブレーキになる。

そのまま貼る

CLAUDE.md の冒頭に置く。このツリーで最初に貼るべきはこれ。 以下の各ページのブロックは、これに足していく形になる。

## 判断の原則
 
- **推測を書かない。** 動かしていないものを「動く」と書かない。
  確かめたことと確かめていないことを、報告の中で区別する
- **実行できるものは実行してから報告する。** 実行したコマンドとその出力を報告に含める。
  出力が無い主張は、未確認のものとして扱われる
- **実際のデータで確かめる。** 都合のよい入力を自分で作って通しても、確かめたことにならない
- **頼まれていないものを足さない。** 設定項目・抽象化の層・将来のための拡張点・
  使われないエラー分岐を、依頼に無いのに足さない。
  足すべきだと判断したら、足す前にそう言う
- **シンボルを変えるときは、呼び出し元を全部探してから変える。**
  渡されていない範囲にも呼び出し元がありうる
- **前提が食い違うと成果物が丸ごと無駄になる場合だけ、着手前に確認する。**
  それ以外は進めてよい。判断のたびに止まらない
- **取り消せる単位で進める。** 1つの変更が1つのことだけをしている状態を保つ

関連

バックリンク