Hermes エージェント入門 : コンテキストファイル (AGENTS.md, SOUL.md, .cursorrules)

Posted on by Masashi Okumura

Hermes エージェントは、その動作を規定するコンテキストファイルを自動的に検出してロードします。一部のファイルはプロジェクト固有のもので、作業ディレクトリから検出されます。SOUL.md は Hermes インスタンス全体でグローバルとなり、HERMES_HOME からのみロードされます。

Hermes エージェント☤ 入門 : 機能 – コア : コンテキスト・ファイル

作成 : Masashi Okumura (@classcat.com)
作成日時 : 08/24/2026
バージョン : Hermes Agent v0.20.5 (v2026.8.19)

* 本記事は hermes-agent.nousresearch.com/docs の以下のページを参考にしています :

* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。

 

 

Hermes エージェント☤ 入門 : 機能 – コア : コンテキスト・ファイル

Hermes エージェントは、その動作を規定するコンテキストファイルを自動的に検出してロードします。一部のファイルはプロジェクト固有のもので、作業ディレクトリから検出されます。SOUL.md は Hermes インスタンス全体でグローバルとなり、HERMES_HOME からのみロードされます。

 

サポートされるコンテキストファイル

  • (ファイル – 目的 – 検出)

  • .hermes.md / HERMES.md – プロジェクト指示 (最優先事項) – git root まで移動

  • AGENTS.md – プロジェクトの指示、慣例、アーキテクチャ – スタートアップ時の CWD + サブディレクトリを段階的に

  • CLAUDE.md – Claude Code のコンテキストファイル (これも検出されます) – スタートアップ時の CWD + サブディレクトリを段階的に

  • SOUL.md – この Hermes インスタンスのグローバルなパーソナリティとトーンのカスタマイズ – HERMES_HOME/SOUL.md only

  • .cursorrules – Cursor IDE コーディング規約 – CWD only

  • .cursor/rules/*.mdc – Cursor IDE ルール・モジュール – CWD only

ℹ️ プライオリティ (優先順位) システム
セッションごとにロードされるプロジェクト・コンテキストタイプは 1つ のみです (最初に一致したものが優先されます) : .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules。SOUL.md は常にエージェント・アイデンティティ (スロット #1) として独立してロードされます。

 

AGENTS.md

AGENTS.md は、プロジェクトの主要なコンテキストファイルです。プロジェクトの構造、従うべき規約、および特別な指示をエージェントに伝えます。

 

ディレクトリチェーン (git root → 作業ディレクトリ)

作業ディレクトリが git リポジトリ内にある場合、Hermes はセッション開始時に AGENTS.md ファイルのマージされたチェーンをロードします: 最初に git-root の AGENTS.md、次に作業ディレクトリまでのすべての中間ディレクトリの AGENTS.md がロードされます。より深い階層のファイルはプロンプトの後半に表示されるため、より具体的なガイダンスが優先されます。各ファイルには独自のプロベナンス・ヘッダー (e.g. ## ../../AGENTS.md) が付与され、チェーンに沿って同一のコピーは重複除去されます。

monorepo/                   (git root, cwd = packages/webapp/)
├── AGENTS.md              ← 最初にロード (リポジトリ全体の規約)
└── packages/
    ├── AGENTS.md          ← 2 番目にロード
    └── webapp/
        └── AGENTS.md      ← 最後にロード (最も具体的、優先されます)

git リポジトリの外では、作業ディレクトリ自体のみがチェックされます – 親ディレクトリは参照されないため、/tmp や $HOME に配置された AGENTS.md が無関係なセッションに影響することはありません。

 

段階的なサブディレクトリ検出

セッション開始時、Hermes は作業ディレクトリから AGENTS.md ファイルをシステムプロンプトにロードします。セッション中にエージェントが (read_file、`terminal`、search_files 等を介して) サブディレクトリに移動するとき、それらのディレクトリ内のコンテキストファイルを 段階的に検出 し、関連性が生じた時点で会話に注入します。

my-project/
├── AGENTS.md              ← Loaded at startup (system prompt)
├── frontend/
│   └── AGENTS.md          ← Discovered when agent reads frontend/ files
├── backend/
│   └── AGENTS.md          ← Discovered when agent reads backend/ files
└── shared/
    └── AGENTS.md          ← Discovered when agent reads shared/ files

このアプローチには、起動時にすべてをロードする場合よりも2つの利点があります :

  • システムプロンプトが膨張しない ― サブディレクトリのヒントは必要なときにのみ現れます

  • プロンプトキャッシュの保全 ― システムプロンプトはターンをまたいでもステーブルです

各サブディレクトリは、セッションごとに最大1回はチェックされます。検出は親ディレクトリも遡って行われるため、backend/src/main.py を読み込むと、backend/src/ 自体にコンテキストファイルがない場合でも backend/AGENTS.md が検出されます。

ℹ️ info : サブディレクトリのコンテキストファイルは、起動コンテキストファイルと同様の セキュリティスキャン を受けます。悪意のある (Malicious) ファイルはブロックされます。

 

例: AGENTS.md

# Project Context

This is a Next.js 14 web application with a Python FastAPI backend.

## Architecture
- Frontend: Next.js 14 with App Router in `/frontend`
- Backend: FastAPI in `/backend`, uses SQLAlchemy ORM
- Database: PostgreSQL 16
- Deployment: Docker Compose on a Hetzner VPS

## Conventions
- Use TypeScript strict mode for all frontend code
- Python code follows PEP 8, use type hints everywhere
- All API endpoints return JSON with `{data, error, meta}` shape
- Tests go in `__tests__/` directories (frontend) or `tests/` (backend)

## Important Notes
- Never modify migration files directly — use Alembic commands
- The `.env.local` file has real API keys, don't commit it
- Frontend port is 3000, backend is 8000, DB is 5432

 

SOUL.md

SOUL.md は、エージェントのパーソナリティ、口調 (tone)、コミュニケーションスタイルを制御します。See the Personality page for full details.

位置 :

  • ~/.hermes/SOUL.md

  • あるいは、Hermes をカスタムホームディレクトリで実行している場合は、$HERMES_HOME/SOUL.md

 
重要な詳細 :

  • Hermes は、SOUL.md が存在しない場合、自動的にデフォルトの SOUL.md ファイルを初期生成します。

  • Hermes は、HERMES_HOME ディレクトリからのみ SOUL.md をロードします。

  • Hermesは、作業ディレクトリ内で SOUL.md ファイルを探索しません。

  • ファイルが空の場合、SOUL.md からはプロンプトに何も追加されません。

  • ファイルにコンテンツがある場合、コンテンツはスキャンと切り捨て処理の後、逐語的に注入されます。

 

.cursorrules

Hermes は、Cursor IDE の .cursorrules ファイルおよび .cursor/rules/*.mdc ルールモジュールと互換性があります。これらのファイルがプロジェクトルートに存在し、優先度の高いコンテキストファイル (.hermes.md, AGENTS.md, or CLAUDE.md) が見つからない場合、それらはプロジェクトコンテキストとしてロードされます。

これは、Hermes を使用するときに既存の Cursor 規則が自動的に適用されることを意味します。

 

以上