H繁中版
文件核心功能context files
<!-- Source: https://hermesbible.com/docs/user-guide/features/context-files -->

Section: Core Features · URL: https://hermesbible.com/docs/user-guide/features/context-files

Hermes Agent 會自動探索並載入用來塑造其行為的 context files。有些是專案層級的，會從你的工作目錄中探索。SOUL.md 現在是 Hermes 實例的全域設定，只會從 HERMES_HOME 載入。

支援的 Context Files

檔案用途探索方式
.hermes.md / HERMES.md專案指令（最高優先順序）往上走到 git root
AGENTS.md專案指令、慣例、架構啟動時從 CWD 載入 + 逐步探索子目錄
CLAUDE.mdClaude Code context files（也會偵測）啟動時從 CWD 載入 + 逐步探索子目錄
SOUL.md此 Hermes 實例的全域人格與語調設定僅從 HERMES_HOME/SOUL.md 載入
.cursorrulesCursor IDE 的程式碼慣例僅從 CWD 載入
.cursor/rules/*.mdcCursor IDE 的規則模組僅從 CWD 載入

INFO — 優先順序系統

每個 session 只會載入一種專案 context 類型（先找到的優先）：.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules。SOUL.md 則會作為 agent 的身份識別（slot #1）始終獨立載入。

AGENTS.md

AGENTS.md 是主要的專案 context 檔案。它告訴 agent 你的專案結構、該遵循哪些慣例，以及任何特殊指令。

逐步探索子目錄

Session 啟動時，Hermes 會將工作目錄中的 AGENTS.md 載入系統 prompt。當 agent 在 session 期間導覽進入子目錄（透過 read_file、terminal、search_files 等工具），它會逐步探索這些目錄中的 context files，並在它們變得相關時將其注入對話中。

my-project/
├── AGENTS.md              ← 啟動時載入（系統 prompt）
├── frontend/
│   └── AGENTS.md          ← 當 agent 讀取 frontend/ 檔案時探索到
├── backend/
│   └── AGENTS.md          ← 當 agent 讀取 backend/ 檔案時探索到
└── shared/
    └── AGENTS.md          ← 當 agent 讀取 shared/ 檔案時探索到

這種方式相比在啟動時載入所有內容有兩個優勢：

  • 不會膨脹系統 prompt — 子目錄的提示只會在需要時出現
  • 保留 prompt cache — 系統 prompt 在各輪對話中保持穩定

每個子目錄在單個 session 中最多只會被檢查一次。探索機制也會往上檢查父目錄，因此讀取 backend/src/main.py 時會探索到 backend/AGENTS.md，即使 backend/src/ 自己沒有 context file。

INFO

子目錄的 context files 會經過與啟動 context files 相同的安全掃描。惡意檔案會被阻擋。

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 控制 agent 的人格、語調和溝通風格。完整詳情請參閱 Personality 頁面。

位置：

  • ~/.hermes/SOUL.md
  • 或如果你使用自訂的 home 目錄運行 Hermes，則為 $HERMES_HOME/SOUL.md

重要細節：

  • 如果尚不存在，Hermes 會自動預設建立一個 SOUL.md
  • Hermes 只從 HERMES_HOME 載入 SOUL.md
  • Hermes 不會在工作目錄中搜尋 SOUL.md
  • 如果檔案為空，SOUL.md 的內容不會加入 prompt
  • 如果檔案有內容，內容會在掃描和截斷後原樣注入

.cursorrules

Hermes 與 Cursor IDE 的 .cursorrules 檔案和 .cursor/rules/*.mdc 規則模組相容。如果這些檔案存在於專案根目錄，且沒有找到更高優先順序的 context file（.hermes.md、AGENTS.md 或 CLAUDE.md），它們會被載入為專案 context。

這代表你現有的 Cursor 慣例在使用 Hermes 時會自動套用。

Context Files 的載入方式

啟動時（系統 prompt）

Context files 由 agent/prompt_builder.py 中的 build_context_files_prompt() 載入：

  1. 掃描工作目錄 — 依序檢查 .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules（先找到的優先）
  2. 讀取內容 — 每個檔案以 UTF-8 文字讀取
  3. 安全掃描 — 檢查內容是否有 prompt injection 模式
  4. 截斷 — 超過 context_file_max_chars 字元（預設 20,000）的檔案會進行 head/tail 截斷（70% 保留頭部，20% 保留尾部，中間有標記）
  5. 組裝 — 所有區段組合在 # Project Context 標題下
  6. 注入 — 組裝好的內容加入系統 prompt

Session 期間（逐步探索）

agent/subdirectory_hints.py 中的 SubdirectoryHintTracker 會監控工具呼叫參數中的檔案路徑：

  1. 路徑提取 — 每次工具呼叫後，從參數中提取檔案路徑（path、workdir、shell 命令）
  2. 祖先路徑檢查 — 檢查該目錄及最多 5 個父目錄（遇到已造訪過的目錄則停止）
  3. 載入提示 — 如果找到 AGENTS.md、CLAUDE.md 或 .cursorrules，則載入（每個目錄先找到的優先）
  4. 安全掃描 — 與啟動檔案相同的 prompt injection 掃描
  5. 截斷 — 每個檔案上限 8,000 字元
  6. 注入 — 附加到工具結果後面，讓模型在上下文中自然看到

最終的 prompt 區段大致如下：

# Project Context

The following project context files have been loaded and should be followed:

## AGENTS.md

[Your AGENTS.md content here]

## .cursorrules

[Your .cursorrules content here]

[Your SOUL.md content here]

注意 SOUL 的內容是直接插入，沒有額外的包裝文字。

安全：Prompt Injection 防護

所有 context files 在被納入之前都會經過潛在 prompt injection 的掃描。掃描器會檢查：

  • 指令覆寫嘗試：「忽略先前的指令」、「不顧你的規則」
  • 欺騙模式：「不要告訴使用者」
  • 系統 prompt 覆寫：「系統 prompt 覆寫」
  • 隱藏的 HTML 註解：<!-- ignore instructions -->
  • 隱藏的 div 元素：<div style="display:none">
  • 憑證外洩：curl ... $API_KEY
  • 秘密檔案存取：cat .env、cat credentials
  • 不可見字元：零寬度空白、雙向覆寫符號、字元連接符

如果偵測到任何威脅模式，該檔案會被阻擋：

[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]

WARNING

此掃描器能防禦常見的 injection 模式，但不能取代在共享 repo 中審查 context files 的必要性。對於你不是作者的專案，請務必驗證 AGENTS.md 的內容。

大小限制

限制值
每個檔案最大字元數context_file_max_chars（預設 20,000，約 7,000 tokens）
頭部截斷比例70%
尾部截斷比例20%
截斷標記10%（顯示字元數並建議使用檔案工具）

當檔案超過設定的限制時，截斷訊息如下：

[...truncated AGENTS.md: kept 14000+4000 of 25000 chars. Use file tools to read the full file.]

編寫有效 Context Files 的技巧

TIP — AGENTS.md 最佳實踐

  1. 保持簡潔 — 控制在設定的 context_file_max_chars 以內；agent 每輪都會讀取它
  2. 用標題組織 — 使用 ## 區段來分隔架構、慣例、重要注意事項
  3. 加入具體範例 — 展示偏好的程式碼模式、API 格式、命名慣例
  4. 說明不該做的事 — 「不要直接修改 migration 檔案」
  5. 列出關鍵路徑和連接埠 — agent 會用這些來執行 terminal 命令
  6. 隨著專案演進更新 — 過時的 context 比沒有 context 更糟糕

子目錄專屬 Context

對於 monorepo，可以在嵌套的 AGENTS.md 檔案中放入子目錄專屬的指令：

<!-- frontend/AGENTS.md -->
# Frontend Context

- Use `pnpm` not `npm` for package management
- Components go in `src/components/`, pages in `src/app/`
- Use Tailwind CSS, never inline styles
- Run tests with `pnpm test`

<!-- backend/AGENTS.md -->
# Backend Context

- Use `poetry` for dependency management
- Run the dev server with `poetry run uvicorn main:app --reload`
- All endpoints need OpenAPI docstrings
- Database models are in `models/`, schemas in `schemas/`

Context References

computer usecontext references