株式会社divxでエンジニアをしている渡部です。

エンジニアであれば誰しも、数年以上にわたって運用されている「歴史あるプロジェクト」にアサインされた経験があるのではないでしょうか。私も先日、そのような長期プロジェクトを引き継ぐ機会がありました。

そこで直面したのは、コードそのものの複雑さ以上に、その背後にある「なぜ、この形になったのか？」というコンテキスト（文脈）が霧散しているという現実でした。

今回は、私がプロジェクトを引き継ぐ過程で身をもって感じた情報の負債と、これからの情報管理のあり方について考えます。情報を残す者、情報を引き継ぐ者、そして現代の開発には欠かせないAIの三者にとって、理想的な環境とは何か。その答えの一つとしての「Gitによる情報集約」を深掘りしていきます。

私が引き継いだプロジェクトは10年以上運用が続いているものであり、過去に多くの開発者が携わってきました。幾度ものメンバー交代を経て開発が進められてきた結果、今では実装当時の状況を肌で知る人は誰も残っていません。

そんな歴史あるプロジェクトでは、どうしても「情報の負債」が生まれてしまいます。

まず直面したのは、プロジェクト内で利用するツールの変遷による「リンク切れ」です。ConfluenceからNotionへと、組織の成長に合わせてドキュメントツールが移り変わり、残された古いリンクの先は「404」か、あるいは既にログインできないページでした。

また、運良くドキュメントを見つけても、内容は設定変更前の旧環境を想定したままであったり、組織変更の影響からか情報の残し方が変わり、似たような情報が様々な階層に散乱していました。その結果、どれが現在の環境に影響を与える正解なのか、誰も確信を持てない状態に陥っていました。

さらに、タスク管理はGitHub Projectsで行われている一方で、背景知識はNotionにあるという「情報の分断」も大きな壁でした。目の前のIssueに取り組んでいる最中、関連ドキュメントがNotionにあることに気づけないまま実装を進めてしまう。この「コードと情報の物理的な距離」によって、我々もまた知らず知らずのうちに、コードと情報との乖離を新たに生み出してしまっていたのです。

こうした経験を経て、私は「なぜ外部ドキュメントツールが長期プロジェクトにおいて機能しなくなるのか」を考えました。

最大の原因は、コードとドキュメントの「距離」にあると考えます。

外部ツールは「気軽に、綺麗に」情報を残せるという利点がありますが、それは同時に「コードの変更と同期しなくても更新できてしまう」という弱点でもあります。コードと情報の管理場所が離れていると、開発プロセスの中でドキュメントを更新する強制力が働きません。結果として、親切心から残された情報は、時間の経過とともに信頼を失い、死文化していくのです。

ここで誤解してほしくないのは、過去のエンジニアたちが悪いわけではないということです。少なくとも「情報を残そうとしてくれた姿勢」には感謝すべきであり、我々もその姿勢は見習わなければなりません。

結果を知っている今の我々から見れば「ああすれば良かったのに」と指摘するのは簡単です。しかし、当時のエンジニアからすれば、不確定要素が数多くある中で「どうすれば人間が最も簡単に情報共有できるか」を考え抜いた結果、外部ツールを選択したはずです。AIが存在せず、プロジェクトがどこまで長期化するかもわからない当時であれば、それは当然の帰結と言えます。

しかし、結果として現在「情報の整合性の確認作業」という負債が生じてしまっているのは事実です。私たちはこの事実に向き合い、仕組みで解消していかねばなりません。

この負債を解消するために、私たちは「Everything as Code」という考え方に立ち返り、ドキュメントを含むすべての情報をGitリポジトリへ集約していくべきです。

具体的には、リポジトリのルートに /docs ディレクトリを作成し、すべてのドキュメントをMarkdown形式（.md）で管理する運用を推奨しています。

リンク切れの解消と検索性: /docs/setup.md のようにコードと同じリポジトリにあれば、相対パスで参照が完結します。リポジトリ内をgrepすれば、知りたい情報に即座に辿り着けます。

レビューフローへの統合: ドキュメントの修正をPull Requestの必須項目に含めることができます。チームで構築済みのコードレビューの仕組みをそのまま使い、ドキュメントの品質を担保できます。

実装と意図の同期: 「どのコミットで、どの仕様が、なぜ変わったのか」が、履歴（Git Log）として隣り合って刻まれます。実装当時の意図を追うためにブラウザを彷徨う必要はありません。

情報をGitに集約するメリットは、人間（後任者）のためだけではありません。現代の開発において重要なパートナーである「AI」にとっても、この構造は極めて重要です。

重要なのは、「コードと情報の距離をゼロにする」ことです。関連する情報が物理的に近くに配置されていることで、AIのポテンシャルを最大限に引き出すことができます。

例えば、gemini-cliなどにGitHub MCPを設定（~/.gemini/settings.json などへの追記）すると、AIは search_code や get_issue といったツールを自ら叩き、リポジトリ内を横断的に調査できるようになります。また、list_project_items を使うことでリポジトリだけでなくプロジェクト全体の調査も可能になります。
他にもGitHub MCPにはさまざまなツールがあります。GitHub MCPを活用することで、AIは単なるテキスト生成器ではなくリポジトリ内を自在に探索する「有能なアシスタント」に進化します。

しかし、AIという強力な「目」があっても、肝心のドキュメントが外部ツールに散らばっていてはその真価は発揮されません。

外部ツールにある情報はプロンプトとして渡さない限りAIが把握することはできません。しかし、/docs 配下にドキュメントが集約されていれば、AIは現在のブランチのコードとドキュメントを同時に読み取ることができ、コードの状態だけでなくその意図を知ることができます。
MCPツールとドキュメントを組みあわせることで、過去の実装内容とその意図をAIに探させることができるようになります。

このように、AIが「今、目の前にあるコードの背景」を自律的に掘り起こせる環境を作ることは、結果として「新人が最短でプロジェクトを理解できる状態」を作ることと同義なのです。

情報の管理場所をGitに変えることは、単なるツール選びの問題ではありません。「未来の自分」と「次に来る後任者」、そして「共に働くAI」への投資です。

長期プロジェクトの文脈は、コードのすぐ隣に、Gitの履歴と共に刻みましょう。コードと情報の距離を縮める一歩が、プロジェクトを負債の沼から救い出し、AIと共に加速できる土壌を作るはずです。