リポジトリにAI向けの指示書を置くときの書き方｜書く項目と更新の進め方

AIコーディングツールに作業を頼むたびに、「このプロジェクトではテストをこのコマンドで実行する」「この書き方に合わせる」と説明していないでしょうか。毎回の説明は手間がかかるうえ、人によって伝える内容も変わりがちです。

そこで役立つのが、プロジェクトの前提をまとめてリポジトリの中に置く指示書です。多くのAIコーディングツールには、決まった場所のファイルを作業の前に読み込む仕組みが用意されています。ただし、ファイル名や置き場所・読み込まれ方はツールごとに異なり、変更されることもあります。使うツールの公式情報を確認してから作成してください。

この記事では、特定のツールに依存しない形で、指示書に書く項目と書き方・更新の進め方を説明します。

指示書に書く内容は、新しいメンバーに伝えたいこと

指示書に何を書けばよいか迷ったら、新しいメンバーがチームに加わったときに伝えることを思い浮かべてください。プロジェクトの目的やディレクトリの構成、開発環境の起動方法、テストの実行方法などです。人が知りたいことの多くは、AIに作業を頼むときにも必要になります。

一般的なプログラミングの知識は、書かなくてかまいません。言語の文法や広く知られた設計の考え方は、指示書がなくてもツールが扱えることが多いからです。このプロジェクトに固有のこと、外から見ても分からないことに絞ると、指示書を短く保てます。

指示書を書く前に、最近AIに頼んだ作業をチームで振り返ってみるのも一つの方法です。毎回説明していたこと、AIが間違えやすかったことを書き出すと、指示書に入れるべき内容が見えてきます。最初の版は短くてかまいません。

書いておきたい項目

指示書に書く項目の例を挙げます。すべてを最初からそろえる必要はなく、困った場面が出てきたら追加していけば十分です。

• プロジェクトの目的と、主な利用者
• ディレクトリの構成と、それぞれの役割
• 開発環境の起動、テスト、ビルドのコマンド
• コードの書き方の約束（命名、エラー処理、ログの出し方など）
• 変更してよい範囲と、触る前に相談が必要な範囲

コマンドは、そのまま実行できる形で書きます。「テストを実行する」と書くより、実際のコマンドを一行で書くほうが、人にもツールにも伝わりやすいでしょう。作業の最後に実行してほしい確認の手順も、コマンドの形で書いておきます。

変更してよい範囲を書くことも欠かせません。自動生成されるファイルや外部から取り込んだコード、本番の設定など、触ってほしくない場所は明記しておきましょう。秘密情報については具体的な値を書かず、置き場所と「読み取らないこと」だけを書くようにしてください。秘密情報の扱い全般は、AIコーディングで気をつけたい秘密情報の扱いで整理しました。

書き方のコツ

指示書は短く、具体的に書きます。長い文書は人が読まなくなり、更新もされなくなるからです。ツールによっては読み込める量に限りがある場合もあり、要点に絞るほうが扱いやすくなります。

あいまいな表現は避けましょう。「きれいなコードを書く」「適切にテストする」では、何をすればよいかが伝わりません。「関数は一つの役割に絞る」「新しい関数には単体テストを追加する」のように、守れたかどうかを確かめられる形で書きます。

理由を一言添えるのも役立ちます。「この古いモジュールは別システムから呼ばれているため、引数を変えない」と書けば、ツールも人も例外的な場面で判断しやすくなるはずです。理由が書かれていないルールは、守られなくても誰も気づかないかもしれません。

大きなリポジトリでは、全体の指示書と、ディレクトリごとの補足を分ける方法もあります。分けられるかどうか、どう読み込まれるかはツールによって違います。公式情報で確かめてから構成を決めてください。

人向けの文書との関係

指示書と、人向けのREADME（リポジトリの説明書）や開発ガイドは、内容が重なります。同じことを二か所に書くと、片方だけ更新されて食い違いが起きやすくなるでしょう。

重なる部分は人向けの文書を基準にし、指示書からは参照するだけにする方法があります。反対に、指示書を基準にして人も読む形にするチームもあります。どちらを選ぶにしても、同じ情報を管理する場所は一つに決めておきましょう。

指示書は、人が読んでも分かる文章で書くのがおすすめです。AIだけが読む前提で書くと、記号や略語が増えて、チームのメンバーが内容を確かめにくくなります。人が読んで正しいと思える内容になっていれば、AIに読ませる情報としても扱いやすいはずです。

指示書を更新し続けるために

指示書は、作って終わりにすると内容が古くなります。コマンドが変わった、ディレクトリを整理したといった変更があれば、同じプルリクエストで指示書も直しましょう。指示書の変更もレビューの対象にすると、チームで内容を共有しやすくなるでしょう。

AIに頼んだ作業で同じ失敗が続くときは、指示書を見直すきっかけになります。たとえば、古い書き方でコードが作られることが続くなら、使ってほしい書き方を指示書に追記します。書いても改善しない場合は、書き方を変えるか、レビューで確認する項目に回すかを検討してください。

複数のツールを併用する場合は、それぞれのツールが読む場所に同じ内容を置く必要が出ることもあります。重複をどう管理するかは、使うツールの組み合わせによって変わるため、導入の段階で決めておくと後から迷いません。

指示書が役立っているかを確かめるには、指示書がある場合とない場合で、同じ種類の作業を頼んでみる方法があります。説明の手間が減ったか、手直しが減ったかを比べると、書いた内容の良し悪しを判断できるでしょう。役立っていない記述は削り、指示書を短く保ちます。

受注アプリの指示書に何を書くか

架空の社内受注アプリを例に、指示書の内容を考えます。画面とAPIが一つのリポジトリにあり、帳票ファイルは元データから生成している想定です。以下は内容の記入例で、特定のツールが自動で読むファイル名や書式を示すものではありません。

実際の指示書には、生成元のファイルや参照する開発ガイドへのパスを添えます。「帳票の元を直す」だけでは探す手間が残るためです。ただし、使われなくなったパスを残すと誤った変更の原因になります。配置を変える変更と同時に指示書も更新してください。

コマンドを書く際は、プロジェクトに存在するものを確認して転記します。実行するディレクトリ、必要な準備、外部サービスへ接続するかも合わせて書きます。同じ名前のコマンドでも、本番データを変更する処理を含むなら、気軽な動作確認として実行させることはできません。

曖昧な指示を、結果で確かめられる文に変える

「既存の設計を尊重する」という文だけでは、どの制約を守るか分かりません。注文番号の形式を維持する必要があるなら、その条件と理由を書きます。「テストを十分に行う」も、空の注文や取消済みの注文を対象にするなど、実際に困った条件へ落とし込みます。

ただし、過去に一度起きた問題をすべて長い禁止事項にする必要はありません。特定の機能だけに関係する詳細は、その機能の設計資料へまとめ、指示書から参照します。リポジトリ全体で毎回使う条件と、対象に応じて読む説明を分けると、必要な前提を見つけやすくなります。

「秘密ファイルを読まない」と書くだけで、アクセスが技術的に禁止されるわけではありません。読めるファイルや実行できる操作の範囲は、環境の権限設定でも制限します。指示書は作業の約束を伝える文書として扱い、権限の代わりにはしないでください。

小さな課題で指示書を確認する

指示書を作ったら、注文一覧の表示文言を変えるような、結果を確かめやすい課題で試します。対象と完了条件を伝えたうえで、変更されたファイル、実行した確認、完了報告を読みます。生成ファイルを直接直していたり、無関係なAPIを変更していたりすれば、指示の伝わり方を見直します。

うまく伝わらなかったときは、文書が実際に読み込まれていたかを先に確認します。読み込む場所を間違えた問題と、内容が曖昧な問題は別です。使うツールの読み込み規則を確認し、それでも判断が分かれる箇所に具体例を加えます。

一度成功しただけで、どの作業でも指示が守られるとは判断できません。画面変更とテスト追加など、異なる小さな課題でも試します。確認で見つかったことは、指示書の変更理由として残すと、後からそのルールを削ってよいか判断しやすくなります。

文書どうしが矛盾した場合の直し方

READMEには古いテスト手順、指示書には新しい手順が書かれていた場合、AIに都合のよいほうを選ばせず、動作する手順を担当者が確かめます。確認後は、正とする文書を一つに決めて古い説明を修正します。参照先の変更も同じレビューで確認してください。

更新の担当者は固定の一人に任せきりにせず、コードの前提を変えた人が文書も直す運用にします。レビュー担当者が「この変更で起動・確認手順も変わるか」を見るだけでも、古い指示を残しにくくなります。新メンバーが迷った箇所も、受け入れ時の調査メモから拾えます。

まとめ

リポジトリにAI向けの指示書を置くと、作業を頼むたびの説明を減らし、チームで前提をそろえられます。書く内容は新しいメンバーに伝えたいことを基準にし、短く具体的に書きましょう。ファイル名や読み込まれ方はツールごとに異なるため、公式情報を確認したうえで作成し、コードと同じように更新していきます。

e-Grantsでは、Codex・Claude Code・GitHub Copilotの導入とあわせて、指示書や運用ルールの整備を支援しています。詳しくはAI開発環境の導入・整備をご覧ください。