Hermes Agentにプロジェクト規約を渡す｜AGENTS.mdの優先順位と継承を確かめる

2026年9月4日

約12分で読めます

#Hermes Agent #AIエージェント #AGENTS.md #モノレポ

リポジトリ直下ではpnpm、API 配下ではuvを使います。こうした規約を毎回チャットへ貼ると、長い会話ほど抜けが増えます。私は、作業場所と一緒に読めるAGENTS.mdへ置きます。

2026 年 9 月 4 日、Hermes Agent v0.20.6 のソースにある 5 本のテストを実行しました。Git ルートから作業ディレクトリまでの継承、個人用 override、.hermes.mdの優先、作業中の追加読込を確かめています。

前回から今回への差分

前回のGit worktreeによる分離では、AI エージェントごとに編集場所を分けました。今回は、その場所で守る規約を階層ごとに渡します。

前回完了時	今回完了後
branchと作業フォルダを分けます	作業フォルダごとの規約も自動で渡します
親と子へ同じ指示を貼り直します	Gitルートから現在地までの規約を継承します
個人差は会話内で調整します	`AGENTS.override.md`で個人設定を分離します

単一パッケージでAGENTS.mdが 1 枚だけなら、「最小構成」まで読めば十分です。モノレポでない場合は、「親子の規約を重ねる」を飛ばせます。

なぜチャットではなくファイルへ置くのか

プロジェクト規約には寿命があります。採用する package manager、テストコマンド、編集禁止の directory は、1 回の会話より長く残ります。Git で管理すれば、コード変更と同じ review を通せます。

一方、口調や人格は project の設計規約ではありません。Hermes Agent ではSOUL.mdがその役目を持ち、HERMES_HOMEから独立して読み込まれます。私は、人格をSOUL.md、repository の制約をAGENTS.md、詳しい手順を Skill へ分けます。

用語表

用語	ここでの意味
project context	作業中のrepositoryで守る規約です
Gitルート	`.git`があるrepositoryの最上位directoryです
working directory	Hermesを起動した場所です
directory chain	Gitルートからworking directoryまでの階層です
override	commit済み規約の代わりに読む個人用ファイルです
progressive discovery	作業中にsubdirectoryへ触れた時、その場所の規約を追加で読む動作です

読み込みの構成

起動時と作業中では、規約を読む時点が違います。

Hermes Agentの新しいsession
│
├── HERMES_HOME/SOUL.md
│   └── 人格と話し方として独立して読み込みます
│
└── project context
    ├── 起動時
    │   ├── .hermes.md があれば最優先です
    │   └── なければ Gitルート → working directory の
    │       AGENTS.md chainを順番に読みます
    │
    └── tool実行後
        └── 新しく触れたsubdirectoryの規約を追加します

起動時の project context は、種類ごとに競合します。公式仕様の優先順は次の通りです。

.hermes.md / HERMES.md
        ↓
AGENTS.override.md
        ↓
AGENTS.md
        ↓
CLAUDE.md
        ↓
.cursorrules / .cursor/rules/*.mdc

最初に見つかった種類だけが採用されます。たとえば.hermes.mdが見つかると、AGENTS.mdの chain は起動時の project context に入りません。互換性のためにAGENTS.mdを選ぶのか、Hermes 専用規約を最優先するのかを先に決めます。

最小構成はrepository直下の1枚

小さな project では、repository 直下にAGENTS.mdを 1 枚置きます。抽象的な方針より、実行できる command と禁止事項を短く書きます。

# Project rules

## Runtime
- Node.js 24とpnpmを使います。
- dependencyは`pnpm install --frozen-lockfile`で入れます。

## Quality gates
- 変更後に`pnpm test`を実行します。
- release前に`pnpm build`を実行します。

## Safety
- `.env`をcommitしません。
- migration fileを手で書き換えません。

規約は system prompt へ入るため、長さにも費用があります。公式実装はcontext_file_max_charsの明示値を優先し、未指定なら model の context window に合わせて上限を決めます。長い運用手順は Skill へ移し、AGENTS.mdには入口と不変条件を残す方が追いやすいです。

親子の規約を重ねる

モノレポでは、共通規約と package 固有規約を分けます。working directory をpackages/webappにすると、Hermes は次の順で読みます。

shop-platform/
├── AGENTS.md                  1. repository全体
└── packages/
    ├── AGENTS.md              2. package共通
    └── webapp/
        └── AGENTS.md          3. webapp固有

深い場所の内容が後に入るため、固有規約を最後に効かせられます。同一内容の file が chain 内に複数ある場合は、重複を除きます。

packages/webapp/AGENTS.mdには、その場所だけで必要な差分を書きます。

# Web application rules

- package managerはpnpmだけを使います。
- componentは`src/components/`へ置きます。
- 変更後に`pnpm test`と`pnpm build`を実行します。

repository の外では親 directory を探索しません。/tmpや home directory へ置かれた無関係なAGENTS.mdが、別 project へ入り込むのを防ぐ境界です。

個人設定はoverrideへ逃がす

commit 済みのAGENTS.mdを個人だけ変えたい場合は、同じ directory にAGENTS.override.mdを置きます。その directory では override がAGENTS.mdの代わりに読まれます。

packages/webapp/
├── AGENTS.md
└── AGENTS.override.md    ← 同じ階層ではこちらを採用します

個人用 override は通常、.gitignoreへ追加します。team 全体で守る test や security rule を個人用 file へ移すと、ほかの作業者へ届きません。override には local の実験 command や表示上の好みだけを置くのが安全です。

作業中に別packageへ移った場合

Hermes は、read_file、search_files、terminalなどの引数から新しいパスを見つけます。起動後にbackend/src/main.pyへ触れた場合、backend/AGENTS.mdをその tool 結果へ追加します。

これは system prompt を途中で作り替えない設計です。subdirectory の規約は必要になった時だけ入り、同じ directory はセッション内で 1 回だけ確認されます。node_modules、.git、vendor、backup directory などは探索対象から外れます。

5本の実テストで挙動を確かめる

Hermes Agent の source directory で、読み込み順に関係する test だけを実行しました。初回はpytestなどを一時環境へ入れます。

cd hermes-agent
uv run --with pytest --python venv/bin/python pytest -q \
  tests/agent/test_prompt_builder.py::TestBuildContextFilesPrompt::test_agents_md_chain_merges_root_to_cwd \
  tests/agent/test_prompt_builder.py::TestBuildContextFilesPrompt::test_agents_override_md_wins_over_agents_md \
  tests/agent/test_prompt_builder.py::TestBuildContextFilesPrompt::test_hermes_md_still_wins_over_agents_override \
  tests/agent/test_subdirectory_hints.py::TestSubdirectoryHintTracker::test_discovers_claude_md \
  tests/agent/test_subdirectory_hints.py::TestSubdirectoryHintTracker::test_no_duplicate_loading

2026 年 9 月 4 日の実行結果です。

.....                                                                    [100%]
5 passed in 0.52s

この 5 本で確認できた範囲は、root から working directory までの順序、override、.hermes.mdの優先、subdirectory の追加読込、重複防止です。model が規約どおりに判断する品質までは、この unit test だけでは測れません。

規約を読んでいるか切り分ける

設定や plugin の影響を外したい場合、--ignore-rulesを付けて比較できます。

hermes --ignore-rules

v0.20.6 のhermes --helpでは、次の説明を確認しました。

--ignore-rules        Skip auto-injection of AGENTS.md, SOUL.md,
                      .cursorrules, memory, and preloaded skills

この flag はAGENTS.mdだけでなく、SOUL.md、memory、起動時に指定した Skill も外します。通常運用の設定として固定するより、原因調査の 1 回に限って使います。

よくあるエラー

症状	原因	対処
rootの`AGENTS.md`が効きません	`.hermes.md`など上位の種類が先に見つかっています	優先順を確認し、project contextの種類を1つに寄せます
parentの規約を読みません	Git repositoryの外で起動しています	`.git`の位置とworking directoryを確認します
local設定をcommitしてしまいます	`AGENTS.override.md`を追跡対象にしています	`.gitignore`へ追加し、team規約は`AGENTS.md`へ戻します
subdirectory規約が効きません	そのdirectoryのfileやcommandへまだ触れていません	対象パスを読むか、最初からそのdirectoryで起動します
同じ規約が何度も入ると思います	内容のdigestと訪問済みdirectoryで重複を防ぎます	重複より、似ている別文面が複数ないか確認します
`--ignore-rules`後に人格まで変わります	flagが`SOUL.md`とmemoryも外します	調査後はflagなしで新しいセッションを始めます

私は、AI エージェントの規律を長い prompt だけに任せません。Git ルートに共通規約を置き、深い directory には差分だけを置きます。そして、実行した test の結果を完了条件にします。これなら規約が会話から消えても、repository 側に戻る場所が残ります。

一次情報

資料	確認した内容
Hermes Agent公式ドキュメント: Context Files	対応file、優先順、AGENTS.md chain、progressive discovery、size上限、security scan
Hermes Agent公式source: prompt_builder.py	起動時のproject context選択と読み込み処理
Hermes Agent公式source: subdirectory_hints.py	tool実行後のsubdirectory探索、重複防止、対象外directory
Agent Skills仕様	長い手順を必要時に読み込むSkillの公開仕様

この記事を書いた人

hibana

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