実装は薄く、仕事の定義を厚くする
本システムではClaude Agent SDKを利用し、TypeScriptからエージェントループを呼び出します。
実装の核となるのは、大規模なアプリケーションコードではありません。重要な要素は、適切なプロンプトの設計とツールの権限設定にあります。
for await (const message of query({
prompt: "このリポジトリを調査し、ARCHAEOLOGY_REPORT.md を生成してください",
options: {
cwd: repoPath,
systemPrompt: SYSTEM_PROMPT,
allowedTools: ["Read", "Glob", "Grep", "Bash", "Write"],
disallowedTools: ["Edit"],
permissionMode: "dontAsk",
maxTurns: 50,
},
})) {
// resultをログに出す
}
提供したコード例ではWriteやBashの実行を許可していますが、安全性を重視して読み取り中心で運用したい場合は、処理を分離することをおすすめします。具体的には、リポジトリの調査のみをエージェントに委ね、ファイルの書き出しやGitへのコミットはハーネス（プログラム）側で制御する設計が安全です。
ここで重要なのは、記述するソースコードの量ではなく、「どのようなタスクとしてAIに定義し、引き渡すか」という点にあります。
今回のシステムプロンプトでは、以下の3章構成でレポートを生成するように指示を定義しました。
- 歴史レポート：Git履歴からリポジトリの変遷を物語形式でまとめる
- オンボーディングガイド：新メンバーが最初に読むべきファイルを示す
- 技術的負債マップ：複雑なファイルと、その理由の推測を書く
この定義を行うことで、AIへの依頼は単なる「リポジトリを調べておいて」という曖昧な指示ではなくなります。入力データ、利用可能なツール、期待される成果物、そして完了条件が明確に定義された、独立した「タスク」へと昇華されるのです。
実際に出たレポート
私が個人で開発しているTypeScriptのリポジトリに対して本システムを実行したところ、約350行のMarkdownレポートが生成されました。プロダクト固有の情報は伏せますが、その冒頭部分は以下のような出力でした。
# ARCHAEOLOGY REPORT > AI考古学者による自動発掘調査レポート > 調査日: 2026-03-18 | 総コミット数: 約2,000 ## 第1章：歴史レポート ― このリポジトリはこうして今の形になった ### 序章：Create Next App から始まった冒険 `Initial commit from Create Next App` という何の変哲もないコミットから、 この物語は始まる。当時はまだ誰も、このリポジトリが数ヶ月後に 約2,000コミット・数十万行のTypeScriptを擁するプロジェクトに 成長するとは想像していなかっただろう。
興味深かったのは、エージェントがGitの履歴を分析し、リポジトリの変遷を複数の「時代」に区切って表現していた点です。
第2期：探求期
最大の爆発期。外部ライブラリを次々に乗り換えている。
migrate: switch from X to Yというコミットが何度も現れ、そのたびにアダプター層が書き換えられた。
第3期：品質追求期
怒涛の機能開発が一段落し、「負債返済」のフェーズに入る。コミットメッセージに
refactor:とYAGNIが頻出するようになる。
特に印象に残ったのは、移行期の分析でした。
プロジェクト史上最大の転換点。バックエンド基盤の全面移行が始まる。あるスキーマ定義ファイルは100回以上変更された後、ここで役目を終えた。
「100回以上変更」という具体的な数値を、エージェントがGitの履歴から正確に拾い上げていました。このような出力は、人間が読んでも非常に納得感があります。単にそれらしい文章を生成しているのではなく、リポジトリに残された具体的な痕跡を根拠に分析していることが分かります。
また、第3章の「技術的負債マップ」では、以下のような所見も出力されました。
各移行で部分的にリファクタされるも、全体構造は初期設計を引きずっている。
これは自身も課題として認識しつつ、日々の業務のなかではなかなか手が回らない領域です。自身が管理するリポジトリを客観的に発掘される体験は、さながら健康診断の結果を受け取る感覚に酷似しています。
もちろん、出力されたレポートがそのまま完全な成果物として利用できるわけではありません。エージェントによる推測が強すぎる箇所や、表現がやや誇張されている部分も見受けられます。
しかし、翌朝に目を通す設計の叩き台としては、これだけでも十分に価値があります。
初回の出力結果を確認した後は「分析の主張ごとにファイルパス、コミット数、最終更新日を明記する」「検出した負債に対して、次に確認すべき評価観点を追記する」といったプロンプトの条件を追加しました。実行結果を評価し、その内容を踏まえて次回の指示内容やツールの権限設定へとフィードバックする。
この一連のサイクルを回すことこそが、Agentic Automationを実用的に育てる作業の本質です。
