use-git-agent

Git Agent CLI

このスキルが読み込まれたら、状況に合った git-agent コマンドを選んでください。 git-agent commit を既定で使ってはいけません。以下のトリガーテーブルを使って、 現在の状況に適したコマンドを選んでください。

git-agent を使うタイミング

次のような場面で git-agent を使います。それぞれの状況に対応するコマンドは次のとおりです。

状況	コマンド
複数ファイルにまたがる作業や機能の変更を始める前に、ほかに何が変わるか確認する	git-agent graph impact [files...]
特定の関数／型を変更する際に、その呼び出し元（依存しているもの）を確認する	git-agent graph impact --symbol <name> または git-agent graph callers <symbol>
関数を変更する際に、その関数が呼び出すものを確認する	git-agent graph callees <symbol>
シンボルを見つけて、そのソースと直接隣接する要素を確認する	git-agent graph node <name> または git-agent graph query <search>
変更後に実行するテストを決める	git-agent graph affected [files...]
テスト／リグレッションが失敗したときに、それを引き起こしたエージェントの操作を特定する	git-agent graph diagnose [symptom] --file <source>
「エージェント（または人間）が最近何を変更したか」を確認する／セッションを監査する	git-agent graph timeline（--file／--source／--since）
ファイルの全履歴を、名前変更を考慮して確認し、範囲外の編集にフラグを付ける	git-agent graph provenance <file>
グラフクエリが何も返さない、または古いように見える	git-agent graph status → git-agent graph sync（または全体を再構築する場合は git-agent graph index）
Event Log が改ざんされた疑いがある	git-agent graph verify
ステージ済みの変更をコミットする準備ができた	git-agent commit --intent "..."
新しいリポジトリ、またはスコープが設定されていない	git-agent init
プロバイダー／API キー／モデルの設定	git-agent config show ／ config set <key> <value>

状況が一覧にない場合は、git-agent --help または git-agent graph --help を実行してください。 すべての graph クエリは読み取り専用でオフラインで動作します（LLM、API キーは不要です）。プロバイダーが必要なのは commit と init --scope だけです。

機能を変更する前に関連ファイルを見つける

機能を変更しようとしているとき、または編集中のときは、git グラフに問い合わせて、 変更するファイルに関連するほかのファイルを確認してください。これらのファイルは、 更新が必要になる可能性が最も高いファイル（テスト、呼び出し元、兄弟モジュール）であり、 忘れやすいものです。分析モードは 2 種類あります。

共変更モード（デフォルト）— 過去に一緒に変更されたファイル

# Given the files of a feature, rank the files that usually change with them:
git-agent graph impact application/commit_service.go cmd/commit.go --json

# Given a directory (a whole module/feature area):
git-agent graph impact infrastructure/hook --json

# No arguments: use your CURRENT uncommitted edits as the seeds —
# "given what I've already changed, what else usually moves with it?"
git-agent graph impact --json

JSON を確認して優先順位を付けてください。各エントリには seed_matches（シードファイルと一緒に 変更される数。数が多いほど機能の中心に近い）、related_to（関連するシード）、 coupling_strength、score（順位付け）が含まれます。 seed_matches がシードの数と同じファイルは、機能全体と結び付いています。作業を終える前に そのファイルを開いてください。初回実行時に git の履歴が自動でインデックス化されます。 クエリはオフラインで動作し、LLM や API キーは不要です。

構造モード — 指定したシンボルを呼び出す、または参照するシンボル

変更する関数、struct、または型が分かっている場合、構造モードでは AST をたどって 直接の呼び出し元と参照（入力エッジ — 依存しているもの）を見つけます。履歴は不要です。 --symbol <name> を指定します（モードの既定値は structural です）。

# Find all symbols structurally linked to CommitService:
git-agent graph impact --symbol CommitService --json

# Combine both signals — co-change AND structural — for the richest view:
git-agent graph impact --symbol CommitService --mode combined --json

JSON の構造は共変更モードとは異なります。seed_node オブジェクト（シンボルの kind、 qualified_name、file_path、行、列、is_exported、return_type）と、 構造的につながりのあるシンボルの impacted 配列が含まれます。特定の関数や型を変更するときに、 それに直接依存するものを確認するには、このモードを使ってください。

モードの使い分け

質問	モード
「これらのファイルを編集中です。ほかに通常変更されるものは？」	cochange（デフォルト）
「この関数を変更します。何がこれを呼び出す、または参照していますか？」	--symbol <name>（構造モード）
「すべてを確認したいです。履歴と AST の両方を見せてください」	--symbol <name> --mode combined

複数ファイルにまたがる作業の開始時とコミット前に、事前に impact を使ってください。 そうすれば、変更と関連するものを取りこぼさずに済みます。

コミットのワークフロー

1. 意図 — 会話から意図を一文で導き出します。判断材料がない場合は、git diff --stat を実行して変更内容を把握し、それをもとに意図をまとめます。

2. コミット — 次を実行します。

   git-agent commit --intent "..."
   

   最初の試行ではプロバイダーのフラグを指定しないでください。

3. 認証エラー（401／キーがない）の場合 — --free を付けて一度だけ再試行します。

   git-agent commit --intent "..." --free
   

4. --free でも失敗する場合 — ~/.config/git-agent/config.yml を作成するようユーザーに案内します。

   base_url: https://api.openai.com/v1
   api_key: sk-...
   model: gpt-4o
   

   その他にサポートされているプロバイダー：Cloudflare Workers AI、ローカル Ollama。

便利なフラグ

フラグ	使用する場面
--dry-run	ユーザーがコミットせずにメッセージをプレビューしたい場合
--no-stage	ユーザーがすでに特定のファイルをステージしており、自動ステージングを望まない場合
--amend	ユーザーが直近のコミットメッセージを書き換えたい場合
--intent "..."	常に指定します。生成されるメッセージの焦点を保てます
--co-author "Name <email>"	共同作成者を記録します（複数指定可）。設定で no_model_co_author が設定されている場合は省略されます
--trailer "Key: Value"	任意の Git トレーラーを追加します（複数指定可）
--no-attribution	デフォルトの Co-Authored-By: Git Agent トレーラーを省略します
--max-diff-lines N	モデルに送信する差分のサイズに上限を設定します（0 = 上限なし）

--amend と --no-stage は同時に指定できません。

複数コミットへの分割

AI プランナーが論理的に異なる変更を検出すると、git-agent はステージ済みの変更を複数のアトミックなコミット（最大5グループ）に自動で分割します。各グループは個別にステージされ、コミットされ、フックによる検証を受けます。ユーザーによる操作は不要で、これがデフォルトの動作です。

スコープの自動設定

プロジェクトにスコープが設定されていない場合、git-agent は計画の作成前に Git の履歴からスコープを自動生成します。各スコープは name と任意の description を持つ構造化オブジェクトです（コミットメッセージ生成時に LLM コンテキストとして使用されます）。スコープを手動で生成するには、git-agent init --scope を実行します。

モデルの共同作成者を必須にする

.git-agent/config.yml（またはユーザー／ローカルのスコープ）で require_model_co_author: true を設定すると、すべてのコミットに、既知の AI プロバイダードメインに属する Co-Authored-By トレーラーを必須にできます。デフォルトの Git Agent 帰属トレーラーだけでは条件を満たしません。anthropic.com、openai.com、google.com に加え、model_co_author_domains: に列挙されたドメインのみが対象です。

このフラグが有効な場合、呼び出し元は --co-author "Model Name <email@domain>" を明示的に渡す必要があります。git-agent は LLM を呼び出す前に CLI 層でこれを検証し、フラグが指定されていない場合は、明確なヒントを表示して終了コード 1 で終了します。トレーラーの生成をモデルに任せることはありません（大文字・小文字や配置を間違えるためです）。例：

git-agent commit --co-author "Claude Opus 4.7 <[email protected]>"

フックの失敗

コミットがブロックされた場合（終了コード 2）、より具体的な --intent を指定して再試行します。

git-agent commit --intent "update module path"

フックの終了コード：0 = 許可、0以外 = ブロック。

コミット形式

<type>(<scope>): <description>

- <Bullet one>
- <Bullet two>

<Explanation paragraph>

Co-Authored-By: Git Agent <[email protected]>

• タイトル：小文字、50文字以下、末尾にピリオドを付けない
• 箇条書き：最初の文字は大文字、命令形、各項目72文字以下。LLM は JSON 配列として生成します。トレーラーが LLM コンテキストに入ることはありません
• 説明：必須、文頭を大文字にします。100文字を超える行は約72文字になるよう折り返します
• ターミナル出力に表示されるのは説明の段落のみです（箇条書きは Git コミット本文に含まれますが、CLI 出力には表示されません）

その他のコマンド

コマンド	説明
git-agent graph impact [path...]	シード（ファイル、ディレクトリ、または引数なしの場合はワーキングツリーの変更）と過去に一緒に変更されたファイルを順位付けします。機能変更時に必要になる可能性が高い他のファイルを特定します。--json で JSON を出力します
git-agent graph impact --symbol <name>	AST 構造に基づく影響分析です。指定したシンボルを呼び出す、または参照するシンボル（入力エッジ、つまり依存元）を表示します。--mode combined を指定すると、同時変更と構造上の影響を別々のフィールドで返します
git-agent graph timeline	最近のエージェント／人間の操作履歴（セッション、ツール、ファイル）を表示します。--file、--source、--since で絞り込めます
git-agent graph diagnose [symptom] --file <source>	失敗している症状を、それを引き起こした可能性が最も高いエージェント操作までたどります（疑わしい期間＋同時変更＋順位付け）。--file <source> で関連するファイル群を指定します（候補を特定するには実質的に必須です）。[symptom] は任意のコンテキストです。設定済みの diagnose LLM を使って候補を再順位付けするには、--llm を追加します
git-agent graph provenance <file>	1 つのファイルの名前変更を考慮した変更履歴を表示します。記録されたすべての変更と範囲外の変更を含み、名前変更前の識別情報も統合します
git-agent graph status	グラフインデックスの健全性と行数（コミット、ファイル、作成者、同時変更ペア、セッション、操作）を表示します
git-agent graph verify	ハッシュチェーン化された Event Log をたどり、改ざんされていないことを検証します。不整合がある場合は終了コード 4 で終了します
git-agent graph index	すべての派生インデックスを構築／更新します。Event Log をプロジェクション（セッション、操作、同時変更）に再生し、AST インデックスも確保します。--reindex を指定すると、AST インデックスを完全に再作成します
git-agent graph sync	プロジェクションを Event Log の最新状態にします（すでに最新の場合は何もせず、そうでない場合は新しいイベントのみを増分再生します）
git-agent graph callers <symbol>	シンボルを呼び出す、または参照する AST ノード（入力エッジ）を、--depth で指定した深さまで表示します
git-agent graph callees <symbol>	シンボルが呼び出す、または参照する AST ノード（出力エッジ）を、--depth で指定した深さまで表示します
git-agent graph node <name>	名前に一致するシンボルについて、それぞれの場所、シグネチャ、ソーススニペット、1 ホップ分の呼び出し元／呼び出し先の関係を表示します。一致ごとに 1 件のエントリを含む配列を返します
git-agent graph query <search>	シンボル名、修飾名、またはシグネチャを対象に、FTS5 の前方一致検索を行います（例：process は processData に一致します）。--kind で絞り込めます
git-agent graph affected [files...]	指定したファイルの変更によって推移的に影響を受けるテストファイルを表示します（標準入力：git diff --name-only）
git-agent capture	エージェントの操作をグラフに記録します。Claude Code の PostToolUse フックとして実行するように設計されています（init --agent-hook でインストール）。--help には表示されません
git-agent init	リポジトリで git-agent を初期化します（スコープと .gitignore を生成し、フックをインストールします）
git-agent init --agent-hook	エージェントによる編集をグラフに自動記録する Claude Code の PostToolUse フックをインストールします
git-agent init --scope	スコープのみを再生成します
git-agent init --user --hook <value>	プロジェクト設定とは独立して、ユーザーレベルの設定（~/.config/git-agent/config.yml）にフックを設定します
git-agent config show	解決済みのプロバイダー設定を表示します
git-agent config set <key> <value>	設定値を指定します（スコープは自動選択されます）
git-agent config get <key>	設定値と、その値が定義されているスコープを表示します
git-agent completion <shell>	シェル補完を生成します（bash/zsh/fish/powershell）
git-agent version	ビルドバージョンを表示します

CLI リファレンス

すべてのフラグ、サブコマンド、設定スコープ、フックの種類を含む完全なコマンドリファレンス：references/cli.md