Hermes AgentのSOUL.mdとAGENTS.mdを混ぜない｜人格と作業規約の境界

2026年9月23日

約11分で読めます

「常に短く答える」と「このリポジトリではテストを必ず実行する」は、似たような指示に見えても置き場所が違います。前者はエージェントの人格です。後者は作業場所だけで守る規約です。1 枚のファイルへ集めると、別の仕事を始めた時に不要な命令まで付いてきます。

Hermes Agent では、恒久的な人格をSOUL.mdへ置き、プロジェクト固有の規約は.hermes.mdまたはAGENTS.mdへ置きます。公式仕様は、SOUL.mdを system prompt の最初の枠として常に独立して読みます。一方でプロジェクト側は優先順位を持ち、見つかった種類だけを読みます。この境界を先に決めると、人格の変更と作業規約の変更を別々にレビューできます。

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

前回の「Hermes Agentのcronをつなぐ」では、定期 job 間で結果を渡すcontext_fromの境界を扱いました。今回は、job が始まる前に何を読むかを整理します。

時点	状態
前回完了時	jobごとに必要な出力だけを次のjobへ渡せます
今回開始時	人格、リポジトリ規約、実行手順を同じファイルへ書くと、変更範囲が読みにくくなります
今回完了後	恒久的な判断姿勢は`SOUL.md`、projectだけの規約はcontext fileへ分けて確認できます

人格を profile 単位で分ける運用をすでに使っている場合は、「どのファイルがどこまで効くか」から読めば足ります。

なぜファイルを分けるのか

SOUL.mdは、利用者との向き合い方や判断の姿勢を決める場所です。根拠のない断定を避けます。秘密を会話へ出しません。完了前に検証します。特定 repository の lint command や release 手順は、そこへ入れません。

repository 固有の規約は、別の作業 directory では意味を失います。AGENTS.mdへ「この変更ではpnpm testを実行する」と書けば、その repository でだけ読めます。別の project で同じ agent を使っても、無関係な command を実行しようとしません。

私は、次の質問で置き場所を決めます。

この指示は、別の repository でも変わらず必要か
指示の所有者は利用者か、project か
指示を直した後、影響を受ける仕事はどこまでか

最初の答えが「はい」ならSOUL.mdです。特定 project だけなら context file です。手順を何度も再利用するなら Skill へ切り出します。

用語を揃える

用語	この回での意味
`SOUL.md`	Hermes instanceの主な人格です。system promptのslot #1へ入ります
`HERMES_HOME`	設定、人格、Memory、Skill、cronを持つHermesの状態directoryです
`.hermes.md` / `HERMES.md`	project固有の指示です。Git rootまで探索します
`AGENTS.md`	projectの作業規約です。directory階層に沿って複数を組み合わせられます
context file	起動時にpromptへ加わる、人格以外のproject文脈です
Skill	調査、実装、検証を再利用するための手順書です

読み込みを二つの流れに分ける

SOUL.mdと project context は、同じ優先順位で競争しません。人格は独立して入り、project 側だけが種類ごとの優先順位を持ちます。

[HERMES_HOME/SOUL.md]
  いつもの人格と判断姿勢
          │ 常に独立して読み込む
          ▼
[project contextの探索]
  .hermes.md / HERMES.md
       └─ 見つかればこの種類を採用
  AGENTS.md
       └─ 上がなければ階層ごとに結合
  CLAUDE.md / .cursorrules
       └─ さらに上がなければ候補
          │
          ▼
[Skills・Memory・今回の依頼]
          │
          ▼
       agentの実行

公式仕様では、project context の型は.hermes.md、AGENTS.md、CLAUDE.md、.cursorrulesの順で選ばれます。上位の型が見つかると、下位の型を「念のため」には読みません。SOUL.mdはこの選択とは別に常に読み込まれます。

ここでよく起きる誤解は、AGENTS.mdと.hermes.mdを同じ directory へ並べれば内容が合体する、というものです。型どうしは合体しません。両方の規約が必要なら、上位の.hermes.mdへ必要な内容を統合するか、片方だけを正本にします。

まず現在のproject contextを確認する

変更前に、どのファイルがあるかを読みます。次の command は内容を変更しません。

cd hibanas-net
git rev-parse --show-toplevel
find .. -name AGENTS.md -o -name .hermes.md -o -name HERMES.md -o -name CLAUDE.md -o -name .cursorrules

最初の出力は repository root です。続く出力には、探索対象の context file がパスとして並びます。表示されたファイルが即座に全て読まれるわけではありません。.hermes.mdがあれば、同じ project 内のAGENTS.mdより優先されます。

Hermes 自体の現在の設定先は、次で確認できます。

hermes config path

表示された設定 directory と同じHERMES_HOME配下にSOUL.mdがあります。project root に置いたSOUL.mdは、主な人格としては使われません。人格を直したいのか、repository の規約を直したいのかを、この command の前に決めます。

SOUL.mdへ残すものを小さくする

SOUL.mdへ書くのは、仕事が変わっても持ち越したい規律です。長い手順を貼り付けるより、判断基準を短く書く方が更新しやすくなります。

# 方針

- 検証できない事実を断定しない。
- 秘密や個人情報を会話、ログ、commitへ出さない。
- 外部へ変更する前に対象と影響範囲を確認する。
- 終了時は実行結果に基づいて報告する。

この例には、特定の package 名、branch 名、URL を入れていません。別の repository でも同じ方針が働くためです。人格を編集した後は、新しいセッションで確認します。すでに始まったセッションは、開始時に組み立てた prompt を持っているためです。

AGENTS.mdへ置くものを具体化する

AGENTS.mdには、その project で守る実行可能な規約を置きます。曖昧な「品質に注意する」より、対象と確認方法を明記します。

# 作業規約

- 変更前に`git status --porcelain`でworktreeを確認する。
- JavaScriptを変更したら`pnpm lint`と`pnpm test`を実行する。
- `main`へ直接pushしない。
- `docs/decisions/`の既存記録は削除しない。

この内容なら、レビュー時に「どの規約を守ったか」を command と diff で確認できます。別の project へ移れば、このファイルは持ち越されません。特定 subdirectory だけに違う規約がある場合は、その subdirectory へ追加のAGENTS.mdを置きます。公式仕様では、該当する階層のAGENTS.mdが結合されます。

Skillへ移す基準を決める

同じ作業を 3 回以上繰り返し、調査、編集、検証、失敗時の戻り方まで必要になったら、context file ではなく Skill を検討します。Skill は「何を守るか」だけでなく「どう進めるか」を保存する場所です。

たとえば、PR を作る仕事なら、repository の branch 規約はAGENTS.mdに置きます。PR 作成から CI 確認までの汎用手順は GitHub Skill に置きます。人格は、検証なしに完了と報告しないという姿勢だけを受け持ちます。

この分担なら、手順の改善で人格を編集せずに済みます。逆に、口調や判断基準を直すだけなら、project の規約へ触れません。

飛ばしてよい確認

単一 repository だけを一度限りで扱い、既存のAGENTS.mdもない場合は、階層結合の設計を急ぐ必要はありません。その場合も、作業固有の長い手順をSOUL.mdへ足さず、repository root の規約として小さなAGENTS.mdを用意する方が後から見直しやすくなります。

複数の agent や IDE を併用しないなら、CLAUDE.mdや.cursorrulesの優先順位も後回しにできます。ただし、後から別のツールを導入する時は、同じ directory に複数の型を増やす前に正本を決めます。

よくあるエラー

症状	原因	対応
repositoryの規約が別の仕事にも効きます	規約を`SOUL.md`へ書いています	project固有の行を`AGENTS.md`か`.hermes.md`へ移します
`AGENTS.md`と`.hermes.md`の両方を書いたのに片方が効きません	project contextは型の優先順位で一種類を選びます	上位の型へ統合するか、正本でない方を削除します
subdirectoryの規約を読まないように見えます	上位の`.hermes.md`が見つかり、`AGENTS.md`型が選ばれていません	project内のcontext file型を確認し、混在を解消します
人格を変えた直後の返答が変わりません	進行中のセッションが古いpromptを持っています	新しいセッションを開始します
設定を直したのに別の人格が使われます	別profileの`HERMES_HOME`を編集しています	`hermes config path`で起動中の設定先を照合します
手順が毎回長くなります	context fileへ再利用手順を蓄積しています	反復する工程をSkillへ移します

境界を決めるとレビューが速くなる

人格、project 規約、再利用手順を分けると、変更の意味が小さくなります。SOUL.mdの diff なら、どんな仕事にも影響する判断姿勢の変更だと分かります。AGENTS.mdの diff なら、特定 repository の作業条件だけが変わったと分かります。Skill の diff なら、繰り返し作業の手順を改善したと追えます。

私は、人格へ command を詰め込まず、project 規約へ人生観を書きません。どこまで効く指示かを先に決め、短い正本を 1 つにします。その方が、agent を長く使っても修正の理由を失いません。

一次情報

資料	確認した内容
Hermes Agent Configuration: Context Files	`SOUL.md`の役割、project contextの優先順位、`AGENTS.md`の階層結合、読み込み上限
Personality & SOUL.md	主な人格の保存先とセッションをまたぐ扱い
Context Files	project context fileの探索と優先順位
Hermes Agent Skills	再利用手順をSkillとして管理する考え方
NousResearch/hermes-agent	公式source repositoryとrelease情報

この記事を書いた人

hibana

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