Hermes Agent 전역 설치 vs 프로젝트별 설치: 완벽 가이드
문서 성격: Hermes Agent 설치 방식(전역/프로젝트)에 대한 기술적 분석 및 권장사항 목적:
agent.md,system.md,design.md, Skill 등을 전역에서 공유할지, 프로젝트별로 분리할지 결정 최종 갱신: 2026-07-08
1. 핵심 답변 (요약)
"전역 CLI 설치는 하나, 프로젝트별 컨텍스트는 각 프로젝트에 분산"
Hermes Agent는 전역에 한 번 설치하고, 각 프로젝트의 컨텍스트 파일(AGENTS.md 등)은 프로젝트 루트에 배치하는 방식이 가장 효율적입니다. 이는 Hermes의 설계 철학이기도 합니다 .
2. Hermes의 컨텍스트 파일 로딩 메커니즘
Hermes는 세션 시작 시 현재 작업 디렉토리(CWD) 를 기준으로 컨텍스트 파일을 자동으로 탐색합니다 .
2-1. 우선순위 시스템 (First Match Wins)
| 우선순위 | 파일명 | 설명 |
|---|---|---|
| 1순위 | .hermes.md / HERMES.md |
프로젝트별 최우선 지침 |
| 2순위 | AGENTS.md |
프로젝트 구조, 컨벤션, 아키텍처 정의 |
| 3순위 | CLAUDE.md |
Claude Code 호환 컨텍스트 파일 |
| 4순위 | .cursorrules |
Cursor IDE 규칙 파일 |
⚡ 중요: 우선순위가 높은 파일이 발견되면, 그 파일만 로드되고 나머지는 무시됩니다.
2-2. SOUL.md (전역 페르소나)
SOUL.md는 전역 파일입니다. 위치는 ~/.hermes/SOUL.md이며, 프로젝트 디렉토리를 탐색하지 않습니다 .
- 용도: 에이전트의 성격, 말투, 커뮤니케이션 스타일 정의
- 모든 프로젝트에 일관되게 적용됨
3. 전역 설치 vs 프로젝트별 설치: 비교 분석
3-1. 전역 설치 (권장)
# 전역 설치 (한 번만)
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes setup --portal
항목 설명
설치 위치 ~/.hermes/ (Linux/macOS) 또는 /usr/local/lib/hermes-agent/ (root 설치)
명령어 전역 hermes 명령어 사용 가능
전역 설정 ~/.hermes/config.yaml, ~/.hermes/.env, ~/.hermes/SOUL.md
전역 Skill ~/.hermes/skills/ - 모든 프로젝트에서 사용 가능
전역 Memory ~/.hermes/MEMORY.md, ~/.hermes/USER.md - 모든 세션에 주입
3-2. 프로젝트별 컨텍스트 (권장 방식)
각 프로젝트 루트에 컨텍스트 파일을 배치합니다:
text
my-project/
├── AGENTS.md # 프로젝트 구조, 규칙, 아키텍처
├── .hermes.md # (선택) 프로젝트별 최우선 지침
├── src/
│ ├── backend/
│ │ └── AGENTS.md # 서브디렉토리별 컨텍스트 (진행 중 자동 발견)
│ └── frontend/
│ └── AGENTS.md # 서브디렉토리별 컨텍스트
└── .git/
Hermes는 서브디렉토리 컨텍스트를 점진적으로 발견합니다 :
세션 시작 시: 현재 디렉토리의 AGENTS.md를 시스템 프롬프트에 로드
파일 읽기/터미널 실행 시: 해당 디렉토리의 AGENTS.md를 도구 결과에 추가하여 자연스럽게 컨텍스트에 포함
3-3. 프로젝트별 설치 (선택적, Ankh.md 활용)
프로젝트별로 완전히 독립된 Hermes 인스턴스를 실행하려면 Ankh.md를 사용합니다 :
bash
# Ankh.md 설치
npm install -g ankh.md
# 프로젝트 디렉토리에서 Ankh 초기화
cd my-project
ankh init
특징 설명
로컬 설정 .agent/config.yaml - 프로젝트별 모델, 도구 설정
로컬 Skill .agent/skills/ - 프로젝트 전용 Skill
로컬 Memory .agent/memory/ - 프로젝트 전용 메모리
전환 방식 프로젝트 디렉토리에서 hermes 실행 시 로컬 Ankh Agent가 우선 실행
4. 추천 아키텍처 (Best Practice)
4-1. 계층별 구성
text
┌─────────────────────────────────────────────────────────────────┐
│ 🌍 글로벌 계층 (전역 설치) │
│ • ~/.hermes/config.yaml - LLM 제공자, 모델, 도구 설정 │
│ • ~/.hermes/.env - API 키, 봇 토큰 │
│ • ~/.hermes/SOUL.md - 전역 페르소나/말투 │
│ • ~/.hermes/skills/ - 모든 프로젝트 공통 Skill │
│ • ~/.hermes/MEMORY.md - 글로벌 메모리 ([global] 태그) │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 📁 프로젝트 계층 (프로젝트 루트) │
│ • AGENTS.md / CLAUDE.md - 프로젝트 구조, 규칙, 의존성 │
│ • .hermes.md - (선택) 최우선 프로젝트 지침 │
│ • src/backend/AGENTS.md - 서브디렉토리별 컨텍스트 │
│ • src/frontend/AGENTS.md - 서브디렉토리별 컨텍스트 │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 🔧 프로젝트 스코프 메모리 (선택) │
│ • MEMORY.md 내 [project:my-project] 태그 사용 │
│ • 또는 Ankh.md로 완전 분리 │
└─────────────────────────────────────────────────────────────────┘
4-2. AGENTS.md 템플릿 (프로젝트 루트)
markdown
# 프로젝트: 진승정보기술 ERP/POS 시스템
## 프로젝트 개요
- 목적: ERP/POS 통합 시스템 개발 및 유지보수
- 기술 스택: PHP 8.2, PostgreSQL, React, Node.js
## 디렉토리 구조
/api/ - 백엔드 API (PHP)
/frontend/ - React 프론트엔드
/database/ - 마이그레이션 스크립트
/docs/ - 설계 문서 (system.md, design.md)
text
## 코딩 규칙
- PSR-12 코딩 스타일 준수
- 모든 함수에 PHPDoc 주석 필수
- PR 전에 `composer test` 통과 필수
## AI 협업 규칙
- Claude Opus: 아키텍처 설계
- Codex: 세부 구현
- Gemini: QA/크로스체크
5. 전역 vs 프로젝트별: 선택 기준
시나리오 추천 방식 이유
다수 프로젝트 동시 작업 전역 설치 + 프로젝트별 AGENTS.md 컨텍스트 파일 자동 탐색으로 각 프로젝트에 최적화
동일 프로젝트 병렬 작업 Git Worktrees + hermes -w 각 에이전트가 독립된 워킹디렉토리와 브랜치 사용
완전히 다른 용도의 에이전트 Hermes Profiles (hermes profile create) 각 프로필이 독립된 config, 메모리, Skill 보유
프로젝트별 완전 격리 필요 Ankh.md (ankh init) .agent/ 디렉토리에 모든 설정을 프로젝트에 국한
글로벌 페르소나 + 프로젝트 규칙 전역 SOUL.md + 프로젝트 AGENTS.md SOUL은 일관된 말투, AGENTS는 프로젝트별 지침
6. 프로젝트 스코프 메모리 활용 (고급)
Hermes의 MEMORY.md는 기본적으로 모든 메모리를 모든 세션에 주입합니다. 이는 토큰 낭비와 컨텍스트 오염을 유발할 수 있습니다 .
해결책: 태그 기반 필터링
MEMORY.md에 태그를 추가합니다 :
text
[global] SSH alias aliyun-hermes
[global] Custom provider must use chat_completions
[project:cert-manager] Local port 8650, cloud 8660
[project:invoice] Script at ~/.hermes/scripts/process_invoices.py
Hermes는 현재 작업 디렉토리를 기준으로 [global] + [project:<scope>] 태그만 필터링합니다 .
효과:
토큰 낭비 ~65% 감소
프로젝트 관련 메모리만 컨텍스트에 포함
7. 결론
질문 답변
전역 설치 vs 프로젝트별 설치? 전역 설치 1회 + 프로젝트별 컨텍스트 파일 권장
agent.md, system.md는 어디에? 프로젝트 루트의 AGENTS.md에 통합
design.md는? AGENTS.md에 디자인 시스템 섹션으로 포함
Skill은 전역? 프로젝트? 공통 Skill은 전역(~/.hermes/skills/), 프로젝트 전용은 Ankh.md로 분리
여러 프로젝트 동시 작업? Git Worktrees + hermes -w 사용
완전히 다른 에이전트? Hermes Profiles 사용 (hermes profile create)
🎯 최종 권장: Hermes는 전역에 한 번 설치하고, 각 프로젝트의 루트에 AGENTS.md를 배치하세요. SOUL.md로 전역 페르소나를 정의하고, 프로젝트별 규칙은 AGENTS.md로 분리합니다. 필요 시 Ankh.md나 Profiles로 완전 분리할 수 있습니다.
부록: 빠른 설정 명령어
bash
# 1. 전역 설치
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc
# 2. 기본 설정 (Nous Portal)
hermes setup --portal
# 3. 전역 페르소나 설정
echo "당신은 진승정보기술의 AI 개발 어시스턴트입니다.
전문적이고 정확한 답변을 제공합니다." > ~/.hermes/SOUL.md
# 4. 프로젝트 컨텍스트 파일 생성
cd /path/to/your/project
cat > AGENTS.md << 'EOF'
# 프로젝트명: 진승 ERP
## 기술 스택: PHP 8.2, PostgreSQL, React
## 코딩 규칙: PSR-12, PHPDoc 필수
EOF
# 5. Hermes 실행 (프로젝트 디렉토리에서)
hermes
댓글 0