仕様は明確なのに出力に漏れがある：暗黙知の外部化

仕様は構造的に完全で、受入基準は明示的で、Doc Testingも通過した。それでもAgentの出力に予期しない問題がある。チームがずっと前に非推奨にしたライブラリを使っていたり、既知のバグがあるAPIエンドポイントに触れていたり、パフォーマンスが重要なパスで最も単純だが最も遅い実装を採用していたりする。

これらの問題の根本原因は仕様の明確さにあるのではなく、完全性にある。チームは大量の文書化されていない暗黙知を抱えている。どのドキュメントにも書かれたことがないが、経験豊富なチームメンバー全員が知っている知識だ。

暗黙知の典型的な類型には以下がある。

アーキテクチャ判断の歴史的理由。「なぜこのモジュールはRPCではなくイベント駆動を使っているのか？2年前にカスケード障害に見舞われ、疎結合にすることを決めたからだ。」この判断の理由はコードにもアーキテクチャドキュメントにも書かれていない。そのインシデントに関わったエンジニアの記憶の中に存在する。Agentがコード内で2つの通信パターンが混在しているのを見ると、それらを1つに「統一」するかもしれない。そして、たまたま我々がすでに非推奨にすると決めた方を選ぶかもしれない。

モジュールの脆弱ポイント。「このサービスは同時接続数が200を超えるとデータベースのコネクションプールが枯渇する。呼び出し側はレートリミットを実装する必要がある。」この制約はAPIコントラクトの一部として正式化されたことがないが、インテグレーションコードを書いたチームメンバー全員が知っている。Agentのインテグレーションコードは機能テストでは完璧に動作するが、負荷テストで初めて問題が露呈する。

特定顧客への特殊対応。「顧客Xのデータフォーマットには既知の異常がある。日付フィールドがnullではなく空文字列になりうる。我々のパーサーにはこれ専用の互換レイヤーがある。」この情報は過去のインシデントのポストモーテムドキュメントに存在するが、データパースモジュールの仕様にリンクされたことはない。

暗黙知を体系的に外部化するには、能動的な情報収集プロセスが必要である。効果的なアプローチの1つは、仕様作成段階で構造化された質問を組み込むことだ。このモジュールの既知の落とし穴は何か？コードやドキュメントに書かれていない制約は何か？新入社員がこのタスクを行うなら、何を特に注意するよう伝えるか？これらの質問への回答を捕捉し、仕様のcontextフィールドやinvariantsフィールドに書き込む必要がある。

暗黙知の外部化は継続的なプロセスである。Agentの出力が文書化されていない暗黙知を明らかにするたびに、その知識を捕捉し仕様システムに蓄積すべきである。時間の経過とともに仕様はより完全になり、Agentが未知の地雷を踏む確率は低下する。これが仕様レベルにおける進化原則の具体的な現れである。