# 自然言語を捨てろ。いいコードはいいコードからしか生まれない

## そのドキュメント、本当に読む価値あるか

生成AIにコードを書かせるとき、自然言語のドキュメントを読ませることが増えた。README、設計メモ、Issue、Notion、過去のPRコメント。とりあえず全部渡す。

そしてAIがそれっぽく読み、方針を立て、コードを編集する。しばらく進んだところで出てくる。「重要な事実が発覚しました。ドキュメントが正しくありませんでした。方針を変更します」。

これが本当に無駄だ。間違った入力から間違った計画を作り、間違った差分を出し、最後に「前提が違いました」と言う。人間がやっても腹が立つが、AIだと速度があるぶん無駄の量も増える。

問題はAIの読解力ではない。そもそも読ませているものが仕様として弱い。自然言語は伝達手段であって、制約ではない。壊れていても壊れない。嘘でもコンパイルが通る。だから危ない。

## 自然言語を捨てろ

いきなり物騒なことを言っているが、議事録や設計メモを全部消せという話ではない。人間が読むためのドキュメントは必要だ。仕様の中心に自然言語を置くなという話である。

自然言語には解釈の余地が残る。読む人によって意味が変わる。読む時期によって前提が変わる。書いた本人でさえ、数ヶ月後には違う意味で読む。そんなものを一次情報にするな。

### ドキュメントは腐る。そして腐っても黙っている

「ユーザーが削除できるようにする」と書いたとする。論理削除なのか、物理削除なのか。管理者だけなのか、本人もできるのか。関連データはどう扱うのか。監査ログは必要なのか。

こういう情報は自然言語で書ける。書けるが、書いた瞬間から腐り始める。実装が変わり、要件が変わり、ドキュメントだけが昔の顔をして残る。しかも、腐った瞬間にCIは落ちない。

ただし、書き散らしたドキュメントを仕様の保管場所にしてはいけない。README、Wiki、Slack、Issue、Notion、PRコメント。あちこちに同じような説明が散ると、どれか一つが必ず古くなる。

ドリフトしたドキュメントは、ないより悪い。存在するから読まれる。読まれるから信じられる。信じられるから、実装と違う前提がチームに再注入される。AIに渡せば、その腐った前提を高速に増幅する。

## コードを育てろ

いいコードは、いいコードからしか生まれない。汚い設計、弱い型、落ちないテスト、古いドキュメントを渡して「いい感じにして」と言っても、出てくるのはその延長だ。

形式言語は嘘をつかない。プログラムは書いた通りに動く。忖度もしないし、空気も読まない。もちろんコードにもバグはある。しかし、コードは実行できる。テストできる。型で制約できる。差分としてレビューできる。

AI時代に本当に育てるべきなのは、長大な指示書ではない。意図が埋め込まれたコード、振る舞いを固定するテスト、壊れたらちゃんと壊れる型である。そこが弱いままAIに投げるのは、ゴミを丁寧に包装して渡しているだけだ。

### ユースケースはテストで表現しろ

テストは実行可能な仕様だ。「この機能はこう動くべき」と文章で説明するより、落ちるテストを残した方が強い。変更のたびにCIが読んで、間違っていれば落ちる。 「いい感じに直して」より、「このテストを通して」の方が人間にもAIにも明確だ。

### 実装の意図はコメントで残せ

コメント不要論もある。コードを読めば分かるように書け、という主張自体は正しい。 ただし、コードから読み取れるのは「何をしているか」であって、「なぜそうしたか」ではない。

なぜこの境界で分けたのか。なぜこのケースだけ早期 return しているのか。なぜ一見遠回りな実装を選んだのか。そういう意思決定は、コードだけでは消える。

だからコメントは、自然言語の逃げ場ではなく、コードの近くに置く設計判断のログとして使う。実装から遠い場所にある長文より、該当行の近くにある短い理由の方が強い。

### ドキュメントはリンクに寄せろ

ドキュメントを書くなら、実装から遠い場所に仕様を複製しない。詳細なルールを文章で再定義するより、テスト、型、該当コード、ADRに読者を誘導する。 自然言語で残すべきなのは、コードから復元しにくい文脈だ。なぜその制約が必要なのか。どの選択肢を捨てたのか。どの前提が変わったら見直すべきなのか。

### OSSライブラリのドキュメントはだいたいそうなっている

OSSライブラリのAPIリファレンスは、かなりの割合で自動生成だ。Rustならrustdoc、TypeScriptならTypeDoc、UIコンポーネントならStorybook Autodocs、APIならOpenAPIだ。公開API、型、引数、戻り値、props、schemaは、コードやspecから生成する。ここを手書きするとほぼ確実にドリフトする。

一方で、ガイドやチュートリアルは手書きする。なぜ使うのか、どう組み合わせるのか、どこで詰まるのか。強いOSSのドキュメントは、自然言語を頑張っているから強いのではない。機械的に出せる仕様は機械から出し、人間が書く文章を導線と文脈に集中させているから強い。

## 人間とAIに渡すべきもの

誰かに作業を任せるなら、自然言語の説明を盛るより、まずリポジトリの状態を強くする。

• 型で表現できる制約は型に寄せる
• ユースケースはテストで固定する
• 設計判断は実装に近いコメントへ残す
• ドキュメントは仕様の複製ではなく導線にする
• 壊れてほしい変更は、ちゃんと壊れるようにする

これはAI専用の作法ではない。AIが入ってきたことで、今まで人間同士で曖昧に済ませていた部分が露呈しただけだ。

## まとめ

LLMに変なコンテキスト渡すな