본문으로 건너뛰기

컨텍스트 파일

anchor alias​

컨텍스트 파일

Hermes Agent는 동작 방식을 정하는 컨텍스트 파일을 자동으로 발견하고 로드합니다. 일부는 프로젝트 로컬 파일이며 작업 디렉터리 기준으로 찾습니다. SOUL.md는 Hermes 인스턴스 전체에 적용되는 글로벌 파일이며 HERMES_HOME에서만 로드됩니다.

지원된 컨텍스트 파일​

파일용도발견 방식
.hermes.md / HERMES.md프로젝트 지침(최우선)git root까지 위로 탐색
AGENTS.md프로젝트 지침, 컨벤션, 아키텍처시작 시 CWD + 하위 디렉터리에서 점진적으로 발견
CLAUDE.mdClaude Code 컨텍스트 파일(감지 대상)시작 시 CWD + 하위 디렉터리에서 점진적으로 발견
SOUL.md이 Hermes 인스턴스의 글로벌 성격과 톤HERMES_HOME/SOUL.md만
.cursorrulesCursor IDE 코딩 컨벤션CWD만
.cursor/rules/*.mdcCursor IDE rule moduleCWD만
Priority system

session당 프로젝트 context type은 하나만 로드됩니다(처음 일치한 항목 승리): .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules. SOUL.md는 항상 agent identity(slot #1)로 별도 로드됩니다.

AGENTS.md​

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

이 접근 방식은 시작 시 모든 것을 한꺼번에 로드하는 방식보다 두 가지 이점이 있습니다.

  • System prompt bloat 방지 - 하위 directory hint는 필요할 때만 나타납니다.
  • Prompt cache 보존 - system prompt가 turn마다 안정적으로 유지됩니다.

각 하위 directory는 session당 최대 한 번만 확인됩니다. discovery는 parent directory도 walk하므로, backend/src/main.py를 읽으면 backend/src/ 자체에 context file이 없더라도 backend/AGENTS.md를 찾을 수 있습니다.

정보

Subdirectory context file도 startup context file과 같은 security scan을 거칩니다. 악성 file은 차단됩니다.

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 에이전트의 개성, 음색, 통신 스타일을 제어합니다. Personality 페이지에 전체 세부 정보를 참조하세요.

위치:

  • ~/.hermes/SOUL.md
  • 또는 $HERMES_HOME/SOUL.md 사용자 정의 홈 디렉토리에 Hermes를 실행하면

중요한 세부사항:

  • Hermes 씨는 기본적으로 SOUL.md 자동적으로 하나가 존재하지 않는 경우에
  • Hermes 부하 SOUL.md만 HERMES_HOME
  • Hermes는 SOUL.md에 대한 작업 디렉토리를 조사하지 않습니다
  • 파일이 비어있는 경우, SOUL.md에서 아무것도 프롬프트에 추가됩니다
  • 파일이 내용이있는 경우, 내용은 스캔 및 truncation 후 verbatim을 주사합니다

##.cursorrules에 {#cursorrules}

Hermes는 Cursor IDE의 .cursorrules file과 .cursor/rules/*.mdc rule module과 호환됩니다. 이 file이 project root에 있고 우선순위가 더 높은 context file(.hermes.md, AGENTS.md, CLAUDE.md)이 발견되지 않으면 project context로 로드됩니다.

따라서 Hermes를 사용할 때 기존 Cursor convention이 자동으로 적용됩니다.

컨텍스트 파일이 로드되는 방법​

시작 (시스템 프롬프트)​

text file은 agent/prompt_builder.py의 build_context_files_prompt()에서 로드됩니다.

  1. 작업 디렉터리 scan - .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules 순서로 확인합니다(처음 일치한 항목 승리).
  2. Content read - 각 file을 UTF-8 text로 읽습니다.
  3. Security scan - content에서 prompt injection pattern을 검사합니다.
  4. Truncation - 20,000자를 초과하는 file은 head/tail 방식으로 자릅니다(앞 70%, 중간 marker, 뒤 20%).
  5. Assembly - 모든 section을 # Project context header 아래에 결합합니다.
  6. Injection - 조립된 content를 system prompt에 추가합니다.

세션 중 (progressive discovery)​

agent/subdirectory_hints.py의 SubdirectoryHintTracker가 tool call argument에서 file path를 관찰합니다.

  1. Path extract - 각 tool call 후 argument(path, workdir, shell command)에서 file path를 추출합니다.
  2. Ancestor walk - 해당 directory와 최대 5개의 parent directory를 확인합니다. 자세한 boundary에서 중단합니다.
  3. Hint loading - AGENTS.md, CLAUDE.md, .cursorrules 중 하나가 발견되면 로드합니다(folder당 첫 일치 항목).
  4. Security scan - startup file과 동일한 prompt injection scan을 실행합니다.
  5. Truncation - file당 8,000자로 제한합니다.
  6. Injection - tool result에 붙여 넣어 모델의 context에 자연스럽게 표시합니다.

최종 조립된 section은 다음과 비슷합니다.

# 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 content는 추가 wrapper text 없이 직접 삽입됩니다.

보안: Prompt 주입 보호​

모든 context file은 포함되기 전에 잠재적인 prompt injection 여부를 scan합니다. scanner는 다음을 확인합니다.

  • 실행 override 시도: "이전 지침을 무시해", "규칙을 무시해"
  • Deception pattern: "사용자에게 말하지 마세요"
  • System prompt override: "시스템 프롬프트 오버라이드"
  • Hidden HTML comment: <!-- ignore instructions -->
  • Hidden div element: <div style="display:none">
  • Credential exfiltration: curl... $API_KEY
  • Secret file access: cat .env, cat credentials
  • 보이지 않는 문자: zero-width space, bidirectional override, word joiner

위협 pattern이 감지되면 file이 차단됩니다.

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

이 스캐너는 일반적인 주입 패턴에 대해 보호하지만, 공유 저장소에서 컨텍스트 파일을 검토하기위한 대체가 아닙니다. 항상 AGENTS.md 콘텐츠를 검증하지 않았습니다.

크기 제한​

지원하다주요 특징
파일 당 최대 chars20,000 (~7,000 토큰)
맨 위 truncation 비율70%
꼬리 truncation 비율20%
Truncation 감적10 % ( char 카운트 표시 및 파일 도구를 사용하여 제안)

파일이 20,000 문자를 초과할 때, truncation 메시지는 읽습니다:

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

효과적인 컨텍스트 파일에 대한 팁​

Best practices for AGENTS.md {#size-limits}
  1. Keep it concise - 권장 문자 수 아래로 유지하세요. agent는 매 turn마다 이 내용을 읽습니다.
  2. Chunk with headers - architecture, convention, important note를 ## section으로 나누세요.
  3. Concrete example 포함 - 선호 code pattern, API shape, naming convention을 보여주세요.
  4. 명확한 지침 작성 - 예: "이동 file을 직접 수정하지 마세요."
  5. 주요 path와 port 나열 - agent가 terminal command에 사용할 수 있습니다.
  6. 프로젝트 변화에 맞춰 갱신 - stale context는 context가 없는 것보다 나쁠 수 있습니다.

Monorepo 설정​

monorepo에서는 subdirectory별 지침을 계층화된 AGENTS.md file에 넣으세요.

<!-- 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```markdown
<!-- 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/``