Hermes Agentの@参照を試す｜必要な行とGit差分だけを会話へ渡す

2026年9月9日

約14分で読めます

#Hermes Agent #AIエージェント #コンテキスト管理 #セキュリティ

設定ファイルの 3 行だけを見てほしいのに、ファイル全体を貼る。Git の変更点を聞きたいだけなのに、リポジトリを最初から探索させる。小さな確認でも、渡す情報が広いと会話はすぐ重くなります。

Hermes Agent の context references は、入力欄の@からファイル、行範囲、Git 差分を直接添付します。2026 年 9 月 9 日、私は 3 行の YAML と 1 行の変更を使い、@file:と@diffの展開を試しました。.envと作業範囲外のパスは内容を返さず、警告になりました。

私は、AI エージェントへ「全部読んで」と頼む前に、判断に必要な証拠を狭く渡す方が好きです。入力を減らす目的だけではありません。秘密や無関係な変更が、会話へ紛れ込む面積も小さくできます。

前回完了時から今回完了後まで

前回の「Hermes Agentの過去セッションを名前で引き継ぐ」では、workspace とセッション ID を照合し、戻る会話を限定しました。今回は、再開した会話へ渡すファイルと差分を限定します。

時点	状態
前回完了時	workspaceとIDで再開対象を固定できます
今回開始時	再開後にファイル全体やリポジトリ全体を読ませがちです
今回完了後	行範囲、未stage差分、stage済み差分を選んで添付できます

セッションの取り違え対策が必要なら、前回の記事から進めます。@file:と@diffをすでに使っている場合は、「拒否される境界を確かめる」まで飛ばせます。

なぜツールで探させる前に添付するのか

read_fileやgit diffを Hermes Agent 自身に実行させる方法もあります。複数ファイルから原因を探す仕事には、その方が向いています。

一方、確認したい場所が分かっているなら、探索を 1 回挟む必要はありません。たとえば、設定変更のレビューで必要なのが 2 行だけなら、入力時点でその 2 行を指定できます。

人が対象を把握している
        │
        ├── 1ファイルの一部 ── @file:path:開始-終了
        ├── 未stageの変更 ──── @diff
        ├── stage済みの変更 ── @staged
        └── 直近のcommit ───── @git:N
                                  │
                                  ▼
                        Attached Contextへ展開
                                  │
                                  ▼
                         モデルが対象だけを読む

context references は、元の文字列を消して置き換えるのではありません。入力文を残し、その後ろへ--- Attached Context ---として内容を加えます。何を頼み、何を添えたかを同じメッセージで追えます。

用語を揃える

用語	この回での意味
context reference	入力中の`@file:`や`@diff`を、送信前に内容へ展開するCLI機能です
working directory	相対パスとGitコマンドの基準になる作業場所です
allowed workspace	`@file:`で参照を許すパスの根です
line range	`:2-3`のように指定する、1始まりで両端を含む行範囲です
unstaged diff	`git diff`で得る、まだstageしていない変更です
staged diff	`git diff --staged`で得る、commit候補へ入れた変更です
Attached Context	展開したファイルや差分を追加するメッセージ内の区画です

小さな検証用リポジトリを作る

既存の作業を汚さないように、3 行だけの一時リポジトリを使います。

LAB="$(mktemp -d)"
cd "$LAB"
git init -q
git config user.email "[email protected]"
git config user.name "Context Lab"
printf '%s\n' \
  'mode: safe' \
  'retries: 2' \
  'publish: false' \
  > settings.yaml
git add settings.yaml
git commit -qm 'initial'
printf '%s\n' \
  'mode: safe' \
  'retries: 3' \
  'publish: false' \
  > settings.yaml
git diff -- settings.yaml

最後のコマンドでは、retriesだけが変わります。実行時に確認した差分の中心部分です。

-retries: 2
+retries: 3

この一時リポジトリには、本物の API key や token を置きません。参照機能の試験に実在する資格情報は不要です。

2行だけを@fileで渡す

一時リポジトリで Hermes Agent を起動します。

hermes

入力欄で次を送ります。

再試行回数と公開状態を確認してください。@file:settings.yaml:2-3

@file:の行番号は 1 から始まり、終了行も含みます。この指定で添付される本文は次の 2 行です。

retries: 3
publish: false

mode: safeは 1 行目なので入りません。実機の展開処理を直接検査した結果も、同じ境界でした。

[line-range] refs=1 expanded=True blocked=False warnings=0 tokens=20
contains retries: True
contains publish: True
contains mode: False

モデルの返答文は、利用するモデルや会話履歴で変わります。ここで固定して確認するのは返答の言い回しではなく、添付された行です。

ファイルが小さく、全文が必要なら行範囲を省けます。

設定全体を確認してください。@file:settings.yaml

大きなファイルでは、先に対象行を絞ります。公式仕様では、添付量が context length の 4 分の 1 を超えると警告し、半分を超えると展開を拒否します。

未stageの変更だけを@diffで渡す

同じ一時リポジトリには、retries: 2からretries: 3への未 stage 変更があります。入力欄で次を送ります。

この変更が公開状態を変えていないか確認してください。@diff

@diffは内部でgit diffを実行し、差分を添付します。今回の実測では、新旧の値を両方確認できました。

[diff] refs=1 expanded=True blocked=False warnings=0 tokens=55
contains old value: True
contains new value: True

変更をgit add settings.yamlで stage した後は、@diffではなく@stagedを使います。前者は未 stage、後者は stage 済みです。レビュー対象を取り違えないように分けます。

直近の commit を patch 付きで見る場合は、件数を指定します。

直近2件の変更目的を比べてください。@git:2

@git:Nの上限は 10 件です。大きな履歴を一度に渡すより、対象 commit を絞る方が確認しやすくなります。

Git 管理外のディレクトリで@diffを使うと、Git のエラーが警告として添えられます。差分がない場合は(no output)です。空の差分を、検査成功と取り違えないようにします。

フォルダ構成だけを渡す

実装を読む前に配置を共有したい場合は、@folder:を使います。

このディレクトリの責務を分けてください。@folder:src

添付されるのはディレクトリツリーとファイルのメタデータです。ファイル本文を全部連結する機能ではありません。公式仕様では最大 200 件で、それを超えた部分は- ...になります。

構成だけで判断できる質問なら、@folder:で始めます。関数の中身が必要になった時点で、該当ファイルの行範囲を追加します。

すでに確認対象のファイルと行が分かっている場合、この章は飛ばせます。

拒否される境界を確かめる

便利な添付記法ほど、秘密ファイルを簡単に読めてはいけません。Hermes Agent は、.env、SSH 鍵、AWS や Kubernetes の設定などを参照対象から外します。

検証では、一時リポジトリ内の.envを指定しました。中身は添付されず、警告は 1 件です。

[sensitive] refs=1 expanded=True blocked=False warnings=1 tokens=0
warning: @file:.env: path is a sensitive credential or internal Hermes path and cannot be attached

blocked=Falseは、メッセージ全体が context 量の上限で拒否されていないという意味です。秘密ファイル自体は警告になり、添付 token は 0 でした。

作業範囲の外へ出る相対パスも拒否されます。

[outside] refs=1 expanded=True blocked=False warnings=1 tokens=0
warning: @file:../outside.txt: path is outside the allowed workspace

この境界は、すべての情報漏えいを防ぐ防火壁ではありません。許可された通常ファイルに秘密を書けば、そのファイルは添付される可能性があります。資格情報は最初から Secret Manager や.envへ分け、通常のソースへ置かない運用が前提です。

また、@file:は CLI での添付を安全側に絞る機能です。terminal tool や別の process へ与えた OS 権限まで狭める sandbox ではありません。

CLIとSlackでは動きが違う

context references は主に対話 CLI の機能です。CLI では@を入力すると候補が出て、@file:と@folder:ではパス補完も使えます。

Slack などの messaging platform では、同じ@記法を gateway が展開しません。文字列はそのままメッセージとして渡ります。遠隔チャネルからファイルを調べる場合は、エージェントがread_fileやsearch_filesを使い、権限と対象を別に確認します。

私は、ローカル CLI では「分かっている証拠を添付する」、Slack では「対象パスと確認条件を依頼に書く」と分けます。入力面の違いを無視して同じプロンプトを配ると、片方だけ情報不足になります。

よくあるエラー

表示・症状	主な原因	対応
`file not found`	working directoryと相対パスが合っていません	`pwd`を確認し、作業rootからの相対パスへ直します
`path is outside the allowed workspace`	`..`や絶対パスで作業範囲外を指しました	workspace内へ対象を置くか、添付せず別の安全な読取手順を使います
`sensitive credential ... cannot be attached`	`.env`や資格情報ディレクトリを指定しました	値を貼らず、変数名や設定状態だけを確認します
`git command failed`	Git管理外か、repositoryの状態に問題があります	`git status --short --branch`を先に確認します
`@diff`が`(no output)`です	未stage変更がありません	stage済みなら`@staged`、履歴なら`@git:N`へ切り替えます
指定外の行まで入ります	行範囲の書式が無効です	`@file:settings.yaml:2-3`の形へ直します
添付が上限で拒否されます	context length の半分を超えています	行範囲、commit 件数、対象ファイルを減らします
Slackで`@file:`が展開されません	gatewayはCLIの参照展開を行いません	読取ツールを使う依頼へ変えます
画像やbinaryをそのまま読めません	text添付の対象ではありません	画像は対応するvision経路を使います

一時リポジトリを片付ける

検証が終わったら、作成した一時ディレクトリだけを削除します。移動先とパスを確認してから実行します。

cd /
case "$LAB" in
  "${TMPDIR:-/tmp}"/tmp.*) rm -rf -- "$LAB" ;;
  *) printf '%s\n' 'unexpected LAB path' >&2; exit 1 ;;
esac
test ! -e "$LAB" && printf '%s\n' 'cleanup: OK'

期待する出力です。

cleanup: OK

既存のリポジトリや Hermes Agent の設定は削除しません。検証用に作った一時ディレクトリだけが対象です。

私は添付を小さなレビュー境界として使う

ファイルを読めることと、毎回ファイル全体を渡すことは別です。確認場所が分かっているなら@file:の行範囲、作業中の差分なら@diff、commit 候補なら@stagedを使えます。

今回の実機検査では、2 行の指定に 1 行目は混ざらず、Git 差分には新旧の値が入りました。.envと workspace 外は内容を返していません。成功条件を「モデルが良い返答をした」ではなく、「意図した証拠だけが添付された」に置くと、再検査できます。

AI エージェントの入力は、多いほど親切とは限りません。私は、判断に必要な範囲を人が分かっている場面では、その範囲を明示します。探索は必要なときに任せ、既知の証拠は小さく渡します。

一次情報

出典	確認した内容
Hermes Agent Context References	対応記法、行範囲、Git差分、量の上限、秘密パス、CLIとgatewayの差
Hermes Agent CLI Interface	対話CLIの起動方法、入力補完、working directoryの扱い
NousResearch/hermes-agent	context referenceの実装と公式source repository
Git Documentation: git-diff	未stage差分とstage済み差分を取得するコマンド

実機検査は Hermes Agent v0.21.0 で行いました。公式 docs と手元の CLI には版差があり得るため、利用時点のhermes --versionも確認します。

※直近 28 日間の GSC では、この機能名に直接一致する検索語は確認できませんでした。「AI エージェント / Hermes Agent」の関心テーマから、入力を狭くして安全に渡す実務を選んでいます。

この記事を書いた人

hibana

技術ブログを運営しています。日々の学びや発見を発信中。