プロンプトからコンテキストへ：リポジトリにドキュメントを組み込む方法

背景と課題

筆者は約一年間、長いプロンプトや丁寧な表現で質問の精度を上げてきました。しかし、同じリクエストでも月曜は良好な結果が得られ、木曜になると平凡な結果になるという不整合が生じました。その原因は、月曜は既にコードベースを把握した状態で作業していたのに対し、木曜は新しいリポジトリを開いたばかりだったためです。つまり、問題となっていたのはプロンプト自体ではなく、コンテキストの欠如でした。

コンテキストエンジニアリングへの転換

この現象は「プロンプトエンジニアリング」から「コンテキストエンジニアリング」へのシフトとして認識されます。個々の要求を調整するよりも、全体の情報環境を整備することが重要だと指摘されています。

README の役割

筆者は最も効果的だったプロンプトとして README を挙げ、その内容が投稿作成のガイドラインとして機能していると述べています。README には投稿のテンプレート、画像配置のルール、アンカー使用の推奨などが記載され、これがプロジェクト内で最高レバレッジを持つファイルとなっています。

ドキュメントをコードと同様に扱う

標準的なアドバイスはリポジトリのルートに単一の指示ファイルを置くことですが、筆者は対象ごとに適切な場所にドキュメントを分散させています。例えば、執筆規則は content/blog/ に、貢献手順は CONTRIBUTING.md に、アーキテクチャやデプロイ設定はルートの README に記述しています。

実践的なポイント

• **理由を書き残す**：単なるルールではなく、なぜそのルールが必要なのかを明示すると、後からの誤解が減ります。
• **失敗させる仕組み**：ビルドが失敗するように制約を設けることで、ドキュメントの更新漏れを防ぎます。例として、存在しないファイルが参照された場合にビルドが止まります。
• **危険性を直接記述**：プライバシーポリシーの URL が外部サービスで参照されていることなど、コードだけでは判断できない重要な注意点を明示します。
• **古いドキュメントは負債**：エージェントは最新のドキュメントを前提に動作するため、古い情報はむしろ危険です。変更があれば同時にドキュメントも修正します。

まとめ

プロンプトを短くし、必要な情報をリポジトリ内に整理することで、毎回同じ質問を繰り返す必要がなくなります。README や関連ドキュメントを充実させることで、エージェントは正しいコンテキストを取得し、安定した成果を提供できるようになります。

元記事: https://dev.to/indiecoredev/i-stopped-writing-prompts-i-write-the-repo-o6