AI生成コードを説明できる変更にするDiátaxis運用

AI生成コードを「説明できる変更」に変えるには

CodexやClaude Codeは実装速度を上げる。しかし、生成された差分だけを読むレビューでは、「誰が、どの場面で、どう使う機能か」が抜け落ちやすい。保守で必要なのは、動くコードだけではなく、意図をたどれる変更だ。

受け入れ基準を厳しくする動きもある。GCC開発チームは2026年7月29日、LLMで生成されたもの、またはそこから派生した法的に重要な貢献を拒否するAIポリシーを採択した。GNUのメンテナー向け指針では、約15行を超えるコードやテキストを法的に重要な貢献として扱う。コンパイラ「GCC」の開発チームがAI生成コードの受け入れポリシーを公開、15行以上のAI生成コードは受け入れ拒否

この方針を小規模開発へそのまま適用する必要はない。ただし、生成物の由来、設計判断、利用方法を変更単位で残す姿勢は、将来の修正コストを抑える。

Diátaxisの4分類で更新先を決める

Diátaxisは、技術文書を利用者の目的別に整理する方法論だ。文書をチュートリアル、ハウツーガイド、技術リファレンス、解説の4形式に分ける。内容だけでなく、書き方や情報の整理方法も対象にする。

• 初めて使う導線が変わるなら、チュートリアルを更新する。
• 作業手順が変わるなら、ハウツーガイドを更新する。
• 引数、戻り値、設定値が変わるなら、技術リファレンスを更新する。
• 設計理由や制約が変わるなら、解説を更新する。

AIへの指示も、この分類で具体化できる。「コードを書いて」で終えず、変更後に必要な4形式を判定させる。該当しない文書は「更新不要」とした理由をPR（プルリクエスト）本文に残す。文書の量ではなく、利用者の問いに答えられるかで更新を判断する運用になる。

実装と文書を同時に生成・レビューする流れ

まず人が変更の境界を決める。目的、変更しない範囲、利用者、受け入れ条件を短く書く。次にAIへ実装案とテスト案を出させ、同じ入力から文書更新候補をDiátaxisの4分類で列挙させる。

レビューでは、コードの差分と文書の差分を別々に眺めない。たとえば新しい設定値なら、実装、検証、リファレンス、設定変更時の手順が矛盾していないかを一組で確認する。設計上のトレードオフがあるなら、解説へ残す。将来の担当者がAIとの会話履歴なしで判断できることを完了条件にしたい。

Diátaxisの原則は数百件の文書プロジェクトで採用され、GatsbyやCloudflareの文書再編でも活用されている。

どの変更から導入すべきか

先に対象にすべきなのは、外部利用者が触れるAPI、設定、運用手順の変更だ。コードだけでは利用方法が確定しないため、文書の欠落がそのまま問い合わせや障害対応につながる。

一方、内部だけで完結し、挙動も利用手順も変えないリファクタリングでは、4形式すべてを更新する必要はない。更新不要の判断と根拠を残せばよい。小さな変更に過剰な文書を足すより、変更された契約を確実に記録するほうが保守に効く。

まとめ

AI生成コードを受け入れるときは、実装、テスト、用途別の文書を同じ変更としてレビューする。次のPRでは、Diátaxisの4分類で「誰のどの問いが変わったか」を確認したい。文書を更新しない場合にも理由を付ける。その一行が、生成速度を保守可能な開発速度へ変える。