なぜドキュメントを書く力はAI時代にコード力より効くのか

READMEを書こうとして、キーボードが止まる。機能の説明は一分で書けるのに、「なぜこの実装にしたか」の段になると、言葉が出てこない。多くの人はこれを文章力の問題だと思って、次の優先タスクに戻ってしまう。だがこの手詰まりは、文章力の不足ではなく、設計そのものがまだ固まっていないことの合図だ。

コードはAIが量産できる時代になった。関数も、テストも、ちょっとしたリファクタリングも、プロンプト一つで形になる。そうなると「コードを書く力」の相対的な重みは下がり、代わりに何が残るのかという問いが浮かぶ。答えはおそらく、ドキュメントを書く力だ。ただしこれは「コードがAIに書かれるから、人間は文章を書け」という単純な役割分担の話ではない。コードとドキュメントが語れることの非対称性の話だ。

コードが語れないもの

コードは「何をするか」「どう動くか」を正確に語る。実行すれば振る舞いが確かめられるし、型やテストが保証も与えてくれる。だがコードは「なぜその判断をしたか」を語らない。なぜこのライブラリを選んだのか、なぜこの分岐をここで切ったのか、なぜもっと単純な実装を採らなかったのか。これらの理由は、コードの外側、つまり書いた人の頭の中にしか存在しない。

半年後にそのコードを読み返すのは、だいたい自分自身か、入れ替わった別のメンバーだ。彼らが詰まるのは「どう動くか」ではなく「なぜこうなっているか」の方である。whatとhowはコードが答えてくれる。whyに答えられるのはドキュメントだけであり、ここだけはAIにコードを書かせても自動では埋まらない。だからこそ、whyを残す文章は、コードの付属品ではなく独立して価値を持つ成果物に格上げされる。

書けないという事実そのものが情報になる

ここで見方をもう一段ひっくり返したい。ドキュメントを「あとで書く雑務」として扱っていると、書けない瞬間を単なる面倒事としてやり過ごしてしまう。だが実際には、設計の理由をうまく言葉にできないという感触は、設計そのものにまだ穴があることの検知結果だ。

たとえば「この処理を共通化しなかった理由」を一文で書こうとして詰まるとき、それは文章力の問題である以前に、本当にその分岐を分けるべきだったのかを自分がまだ説明できていないという事実を教えてくれている。書く作業を設計の最後に置くのではなく、設計を検証する手段として最中に挟み込むと、実装が固まる前に穴が見つかる。順番を逆転させるだけで、ドキュメントは成果物の記録から、設計そのものの検査工程に変わる。

この逆転に気づくと、「ドキュメントを書く時間がない」という言い方の中身も変わって見える。時間がないのではなく、まだ自分の判断を言語化できる段階まで理解が到達していない、というケースが少なくない。

何から鍛えるか

独立したスキルとして鍛えるなら、分厚い設計書を書く練習より先に、小さな習慣から始める方が効く。判断に迷った箇所が出たら、ADR(Architecture Decision Record。「何を決めたか」ではなく「なぜそれに決め、他の何を選ばなかったか」だけを数行で残す簡易記録)の形で一つ書いてみる。大掛かりな文書を作る必要はなく、該当コードのすぐ近くに「なぜ」を一行コメントで足すだけでもいい。この短い反復の積み重ねが、半年後の自分やチームの保守速度を決めている。

コードを書く速さを鍛える時間の一部を、判断の理由を書く練習に振り分けてみる価値はある。土台として、設計の考え方そのものを扱った定番の技術書を読み直すのも、遠回りに見えて近道になる。

https://s-tasklog.com/books/general

tasklogは、現場で実際に読まれ引用されている技術書を集めて置いてある場所だ。設計の土台になる一冊を探すときの、手がかりの一つに使ってもらえれば。