# 自然言語を捨てろ、コードを育てろ

## 自然言語に任せて思考停止するな

生成AIがコードを書くようになって、自然言語で指示を出す場面が増えた。だが、これはAIだけの問題ではない。

人間同士の開発でも同じだ。「こういう感じで」「いい感じに」「既存の設計に合わせて」。便利だが、仕様としては弱い。自然言語は伝達手段であって、制約ではない。

会話なら背景を補完できる。空気も読める。多少の矛盾もその場で丸め込める。しかし、ソフトウェアは丸め込めない。曖昧な言葉は、曖昧な実装として返ってくる。相手が人間でもAIでも同じだ。

## 自然言語を捨てろ

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

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

### ドキュメントはドリフトする

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

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

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

ドリフトしたドキュメントは、ないより悪い。存在するから読まれる。読まれるから信じられる。信じられるから、実装と違う前提がチームに再注入される。

## コードを育てろ

形式言語は嘘をつかない。プログラムは書いた通りに動く。忖度もしないし、空気も読まない。だからこそ、思った通りに制御できる。

もちろんコードにもバグはある。しかし、コードは実行できる。テストできる。型で制約できる。差分としてレビューできる。自然言語よりも、壊れたことを検知しやすい。

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が入ってきたことで、今まで人間同士で曖昧に済ませていた部分が露呈しただけだ。

## まとめ

自然言語は便利だ。人間が読むドキュメントも必要だ。しかし、仕様の中心に置くには弱すぎる。解釈が揺れる。更新されない。間違っていても壊れない。

コードは壊れる。テストは落ちる。型は怒る。だから信頼できる。自然言語で祈るな。実行できる形で残せ。