AIは「読めるもの」しか理解できません。
だから私たちは、プロジェクトの情報をほぼすべてリポジトリに集めることから始めました。シリーズ第1回は、AIが力を発揮するための「準備」のお話です。
- AIが期待どおりに動かない、いちばんの原因
- リポジトリに「置くもの」と「置かないもの」
- 設計リポジトリと、3つの言語で読める設計書
- 判断の理由まで残すドキュメント
- AIへのルールをファイルで共有する方法と、始め方のチェックリスト
AIが期待どおりに動かない、いちばんの原因
AIに実装を頼むと、もっともらしいコードは返ってきます。ところが、よく見るとプロジェクトの決まりに合っていない、既存の仕組みと二重になっている、前に却下した方法が使われている——。こうした「惜しい」結果に悩まされた経験のある方は多いのではないでしょうか。
私たちも最初は、AIの性能やプロンプトの書き方を疑いました。しかし原因の多くは、もっと手前にありました。AIに渡している情報が足りなかったのです。
人のチームであれば、設計の背景や過去の経緯は、会議の記憶やチャットのやり取り、ベテランの頭の中に残っていて、必要なときに聞けば分かります。けれどもAIは、その場で読めるものしか知りません。情報があちこちに散らばっている限り、AIは足りない部分を推測で埋めるしかなく、それが手戻りの原因になっていました。
原則：プロジェクトの情報は、ほぼすべてリポジトリへ
そこで私たちが決めたルールはシンプルです。アカウント情報やアクセスキーといった秘密以外は、プロジェクトの情報をほぼすべてリポジトリに置く。
リポジトリ（ソースコードを管理する場所）を選んだ理由は3つあります。
リポジトリに置くもの
ソースコード
アプリやバッチに加え、インフラの構成もコードとして管理します。
設計書
アーキテクチャ、現状の設計、既知の課題。全体像をAIに渡すための土台です。
手順書
ビルドやデプロイ、運用の手順。実際に動かして確かめた内容を残します。
判断の理由
なぜこの構成にしたのか、どの選択肢を捨てたのか。AIが同じ議論を繰り返さないために欠かせません。
AIへのルール
コーディングの決まりや作業の進め方。誰がAIを使っても同じ前提で動くようにします。
テスト
単体テストから画面操作のテストまで。「正しく動く」の基準そのものもリポジトリに置きます。
置かないもの
アカウント情報、アクセスキー、パスワードなどの秘密は、リポジトリには置きません。専用の保管庫で管理し、万一混入しても登録の時点で自動的に止まる仕組みを入れています。この「安全の仕組み」については、次回くわしくご紹介します。
製品ごとに「設計リポジトリ」をつくる
ソースコードは製品ごとに複数のリポジトリに分かれていることが多く、1つのリポジトリだけを見ても全体像はつかめません。そこで私たちは、製品ごとに設計専用のリポジトリを用意しています。
- 1. AIが現状の設計書を起こすソースコードと、実際に動いている環境の構成（参照だけを許可）をAIが読み取り、現状の設計書の下書きを作ります。
- 2. 人がレビューする書式や禁止事項はルールとして決めておき、内容の正しさは人が確認します。
- 3. 開発のたびにAIが参照する新しい機能を作るときも不具合を直すときも、AIはまずここを読んで全体像をつかんでから作業します。
この作業の副産物として、これまで担当者の頭の中にしかなかった既知の課題が一覧になりました。製品によっては100件を超える課題が整理され、優先順位をつけて計画的に手を打てるようになっています。
設計書は「HTML」で、3つの言語に切り替えられるように
設計書は、AIのためだけのものではありません。最終的にそれを読んで判断し、実装を確かめるのは人です。そこで私たちは、設計書をHTMLで書いています。
3つの言語に対応しているのは、私たちの開発チームにインドネシアのメンバーがいるからです。設計は日本のメンバーが行い、実装はインドネシアのメンバーがAIと一緒に進める。そのとき、同じ設計書をそれぞれが母語で読めることが、読み違いや手戻りを減らす大きな助けになっています。翻訳もAIが担うので、言語ごとに別の資料を管理する必要はありません。
イメージはこんな形です（下のボタンで切り替えられます）。
注文処理の流れ
注文を受け付けると、在庫を確認してから決済を行います。在庫が不足している場合は、決済を行わずにお客様へ通知します。
Order Processing Flow
When an order is received, the system checks inventory before processing payment. If stock is insufficient, the customer is notified without processing payment.
Alur Pemrosesan Pesanan
Saat pesanan diterima, sistem memeriksa stok sebelum memproses pembayaran. Jika stok tidak mencukupi, pelanggan akan diberi tahu tanpa memproses pembayaran.
※ 内容は説明用のサンプルです。
設計を日本で行い、実装をAIとオフショアで進める体制については、次回あらためてご紹介します。
ドキュメントには「判断の理由」まで残す
手順書は「どうやるか」を書くものですが、私たちはそれに加えて「なぜそうしたのか」を残すようにしています。たとえば社内のあるプロダクトでは、リポジトリを分割せずに1つのまま運用する判断をしました。その際、分割した場合に増える手間と、分割しなくても失わないものを比べた理由を、そのままドキュメントに書いています。
理由が残っていれば、AIも人も、同じ議論を一からやり直さずに済みます。前提が変わったときに「どこを見直せばよいか」もすぐに分かります。
もうひとつ、思わぬ効果もありました。そのプロダクトでは、構成をドキュメントにまとめる過程で、開発環境の確認だけでは表に出ていなかった「本番の起動時に必ず失敗する不具合」が見つかり、事前に直すことができました。書くことそのものが、点検にもなるのです。
こうしたドキュメントは、AIへの前提情報であると同時に、新しく加わったメンバーのオンボーディング資料にもなります。人のために書いたものがAIにも役立ち、AIのために書いたものが人にも役立つ。この「兼用」が、書く手間を正当化してくれます。
AIへのルールも「ファイル」で共有する
AIへの指示を毎回チャットで伝えていると、人によって伝える内容がばらつき、結果の品質もばらつきます。そこで、コーディングの決まりや作業の進め方は、リポジトリの中のルールファイルとして書き、チーム全員で共有しています。
ポイントは、ルールを1つの巨大なファイルにまとめず、階層で管理することです。リポジトリ全体の方針は最上位に、画面や部品ごとの決まりはそれぞれのフォルダに置く。こうすると、AIは作業している場所に必要なルールだけを読めばよくなり、ルール同士の衝突も減ります。
さらに、こうしたルールの「ひな形」を全社共通のテンプレートとして用意し、新しいプロジェクトでもすぐに同じ前提でAIを使い始められるようにしています。
「何を作るか」を先に決める
情報を集めることと並んで大切なのが、実装の前に仕様を言葉にすることです。シリーズ第0回でご紹介した「12〜15倍」の案件では、期間の半分以上を設計に充て、型や役割分担といった骨組みを人が決めてからAIに実装を任せました。
社内では、インフラ担当のメンバーが「仕様を先に書き、AIがそれに沿って実装を進める」タイプのツールを試し、自分ではコードを書かずに半日で業務用のWebツールを作り上げた例もあります。仕様が明確であれば、AIは驚くほど速く、正確に動きます。
やってみて分かったこと
完璧を目指さず、まず置く
最初から整ったドキュメントを作ろうとすると止まります。走り書きでもまずリポジトリに置き、AIと一緒に育てるほうが続きます。
AIに書かせて、人が直す
現状の設計書の下書きはAIが得意な作業です。人は「正しいか」の確認に集中すれば、書く負担は大きく減ります。
「なぜ」を書く習慣が財産になる
判断の理由は、時間がたつほど誰にも分からなくなります。書いた瞬間は手間でも、後から何度も助けられます。
チェックリスト：まずはここから
- リポジトリの直下に、プロジェクトの概要を書く
何のためのシステムか、主な構成、よく使うコマンド。AIが最初に読む「入口」になります。 - 直近の大きな判断を1つ、理由ごと書き残す
「なぜこの技術を選んだか」「なぜこの方法をやめたか」。1つからで十分です。 - AIに守ってほしい決まりを、ルールファイルにまとめる
命名規則、使ってよいライブラリ、テストの書き方など。チャットで毎回伝えていたことを書き出します。 - 秘密情報の置き場所を決める
リポジトリには置かない、と決めて専用の保管場所を用意します。情報を集める前に、ここだけは先に決めておきましょう。
関連する記事
シリーズの全体像は第0回でご紹介しています。AIを活かすための情報整理やドキュメント整備のご相談もお気軽にどうぞ。
シリーズ第0回を読む次回は「第2回 仕組み：ルール・品質・セキュリティを標準化する」。AIへの指示とテストの共通化、情報漏えいを防ぐ自動の仕組み、そしてオフショア開発との相性についてご紹介します。
コメント