初めに
以前、開発で使用している便利ツールの記事を書いたときにも生成AIを紹介しました。
あれから業務アプリの開発でも使うようになり、コードだけでなく、設計やテスト、ドキュメントの整理も手伝ってもらっています。
便利です。もう大変お世話になっています。
ただ、使う範囲が広くなると「これ、どうやってチームで管理すればいいんだ・・・?」という話も出てきます。
今回は、コードの書かせ方ではなく、その周辺で整理したことを備忘録的にまとめます。
これからチームでAIを使いたい方の参考になれば幸いです!
※業務固有の情報は載せず、以下の例は説明用に置き換えています。
目次
- 毎回全部説明するの、しんどくない?
- AGENTS.mdには何を書くのか
- 資料がたくさんある問題
- AIに任せること、人が決めること
- 「できました!」の中身を確認する
1. 毎回全部説明するの、しんどくない?
こんな依頼を考えてみます。
ファイルをアップロードするAPIを作ってください。
作るものは分かります。でも、これだけだと情報が足りません。
- 認証は今のアプリのどの仕組みに合わせる?
- ファイルの保存先は?
- 同じリクエストが2回来たら?
- エラーはどんな形式で返す?
・・・説明すること、結構ありますね。
しかも別の機能をお願いするときにも、同じ説明が必要になります。
そこで、毎回会話へ書くのではなく、今のルールを読める場所に置いて、そこを見てもらうようにします。
人に引き継ぐときと、考え方は似ていますね。
2. AGENTS.mdには何を書くのか
AI向けの案内として、リポジトリにAGENTS.mdを置きます。
ここでは、AIが最初に読む案内板のような役割にしています。
「じゃあ仕様を全部ここへ入れればよいのか!」というと、そうでもありません。
全部詰め込むと、設計書と同じ内容を二重に直すことになります。管理する自分がつらい。。。
なので、まずはこのくらいです。
# 作業を始める前に
- 今のbranchと未コミット変更を確認する
- 対象Issueの目的と受入条件を読む
- 変更する機能の設計書と、既存の実装・テストを読む
# 守ること
- 決まっていない仕様を勝手に決めない
- 無関係なファイルを変更しない
- APIを変えたら、仕様とテストも直す
- 試験には合成データを使う
# 人に確認すること
- 要件や設計の採用
- push、公開、環境変更
- マージしてよいかの判断
ポイントは、仕様そのものより、どこを読んでどう進めるかを書くことです。
もちろん、書けば必ず守ってくれるというわけではないので、差分の確認は必要です。
(ここまで含めて、便利ツールに丸投げはできないですね。)
3. 資料がたくさんある問題
さて、案内板はできました。
でもリンク先に古い仕様と新しい仕様が混ざっていたら、どれを見ればよいのでしょうか。
人間でも迷います。
情報ごとに「今はこれが正しい」という場所を決めておきます。
資料でいう「正本」です。言葉は硬いですが、要は見る先を揃えるだけです。
| 知りたいこと | 見るところの例 |
|---|---|
| 今回何を作る?何ができたら完了? | Issue |
| 誰が担当していて、どこまで進んだ? | Project |
| 今の仕様は? | 設計書 |
| なぜこの方法にした? | 設計判断のメモ |
| APIやDBは具体的にどうなっている? | OpenAPIやMigration |
| 何を変更して、どう確認した? | PR |
| 止まったらどうする? | 復旧手順書 |
特に残しておきたいのが「なぜこの方法にした?」です。
例えば、ある処理を自動再実行しないことにしたとします。
「自動再実行しない」だけだと、後から見た人は「自動化した方が便利では?」となりますよね。
「二重登録を避けるため、利用者が確認してから再実行する」まで書いてあると、判断を追いやすくなります。
採用した案だけでなく、採用しなかった理由も一言残す。
ここ、後から結構効いてきます。
4. AIに任せること、人が決めること
AIには調査、設計案、実装、テスト、差分の確認を手伝ってもらいます。
ただし、業務上どうするか、残ったリスクを受け入れるか、マージしてよいかは人が判断します。
こんな流れです。
人:目的と受入条件を決める
AI:既存実装を調べ、設計案を出す
人:採用する方針を決める
AI:実装・テスト・自己レビューをする
人:差分と結果を確認し、マージ可否を判断する
「自己レビューもしてもらうなら、人のレビューいらなくない?」とも思うのですが。
同じ勘違いから実装とテストを作っていたら、どちらも通ってしまうことがあります。
なので、自己レビューは確認を助けるもの。人の承認とは分けます。
あと、コードやログを何でもAIへ貼ってよいわけではありません。
利用できる環境や社内ルールを確認し、認証情報や実データは入れない。これは最初に揃えておきたいです。
5. 「できました!」の中身を確認する
最後にもう一つ。
「できました」という報告、何ができたのか確認したいです。
- コードを書いた
- ローカルのテストが通った
- 対象環境へ反映した
- 対象環境で期待どおりに動いた
全部、違う段階です。
例えばDBをmockしたテストが通っても、本物のDBへ接続できるかは分かりません。
なので、依頼や報告でも「確認できたこと」「まだ確認していないこと」を分けてもらいます。
依頼文も、こんな感じです。
入口資料とIssueを読み、対象範囲と未決事項を整理してください。
既存実装に沿って変更し、合成データでテストしてください。
確認できたことと、まだ確認していないことを分けて報告してください。
pushや環境操作は、人の承認前に行わないでください。
最後に
長々書きましたが、整理したいのはこの三つです。
- 何を見て作ってもらうか
- 何を人が決めるか
- どこまで確認したら完了なのか
AIにコードを作ってもらう前に、ここを少し揃えておく。
派手な話ではないですが、チームで使うなら大事だと思いました。
皆さんのところではどう使い分けていますか?
こんなやり方もあるよ、という話があれば嬉しいです。
ではでは。
※生成AIを活用して作成・推敲した記事です。例は一般化しています。