본문으로 건너뛰기

팁 및 모범 사례

Hermes Agent를 더 효율적으로 쓰기 위한 실용적인 팁 모음입니다. 각 섹션은 서로 다른 사용 장면을 다룹니다. 필요한 제목을 훑어보고 관련 내용으로 바로 이동하세요.

최상의 결과 얻기​

원하는 내용을 구체적으로 설명하세요​

모호한 프롬프트는 모호한 결과를 낳습니다. "코드를 수정"이라고 하기보다 "api/handlers.py 47행의 TypeError를 수정하세요. process_request() 함수가 parse_body()에서 None을 받습니다."처럼 말하세요. 컨텍스트를 많이 줄수록 필요한 반복 횟수는 줄어듭니다.

컨텍스트를 미리 제공하세요​

파일 경로, 오류 메시지, 예상 동작 같은 관련 세부 정보를 요청 첫머리에 넣으세요. 잘 작성된 메시지 하나가 세 번의 추가 설명보다 낫습니다. 오류 traceback은 그대로 붙여넣어도 에이전트가 파싱할 수 있습니다.

반복 지침에 컨텍스트 파일 사용​

같은 지침("공백 대신 탭을 사용하세요", "pytest를 사용합니다", "API는 /api/v2에 있습니다")을 반복하고 있다면 해당 내용을 AGENTS.md 파일에 넣으세요. 에이전트는 매 세션마다 자동으로 이 파일을 읽습니다. 한 번 설정하면 매번 다시 설명할 필요가 없습니다.

에이전트가 도구를 사용하도록 허용​

모든 단계를 손으로 지정하려 하지 마세요. "tests/test_foo.py를 열고 42행을 살펴본 다음..."이라고 하기보다 "실패한 테스트를 찾아서 수정하세요"라고 말하세요. 에이전트에는 파일 검색, 터미널 접근, 코드 실행 기능이 있습니다. 직접 탐색하고 반복하게 두는 편이 좋습니다.

복잡한 워크플로에는 스킬을 사용하세요​

어떤 작업을 수행하는 방법을 긴 프롬프트로 설명하기 전에 이미 해당 스킬이 있는지 확인하세요. /skills를 입력해 사용 가능한 스킬을 찾아보거나 /axolotl, /github-pr-workflow 같은 스킬을 직접 호출하세요.

CLI 고급 사용자 팁​

다중 라인 입력​

메시지를 전송하지 않고 줄바꿈을 넣으려면 Alt+Enter, Ctrl+J 또는 Shift+Enter를 누르세요. Shift+Enter는 터미널이 이를 별도 키 입력으로 보낼 때만 작동합니다(기본적으로 Kitty/foot/WezTerm/Ghostty, Kitty 키보드 프로토콜을 활성화한 iTerm2/Alacritty/VS Code 터미널). 나머지 두 조합은 모든 터미널에서 작동합니다.

페이스트 감지​

CLI는 여러 줄 붙여넣기를 자동 감지합니다. 코드 블록이나 오류 역추적을 직접 붙여넣기만 하면 됩니다. 각 줄을 별도의 메시지로 보내지 않습니다. 붙여넣기는 버퍼링되어 하나의 메시지로 전송됩니다.

인터럽트 및 리디렉션​

에이전트의 응답을 중단하려면 Ctrl+C를 한 번 누르세요. 그런 다음 새 메시지를 입력하여 리디렉션할 수 있습니다. 강제 종료하려면 2초 이내에 Ctrl+C를 두 번 누르세요. 이는 에이전트가 잘못된 경로로 이동하기 시작할 때 매우 중요합니다.

-c로 세션 재개​

지난 세션의 맥락이 필요하다면 hermes -c를 실행하세요. 중단한 지점부터 정확히 다시 시작하고 전체 대화 기록이 복원됩니다. hermes -r "my research project"처럼 제목으로 재개할 수도 있습니다.

클립보드 이미지 붙여넣기​

클립보드의 이미지를 채팅에 직접 붙여넣으려면 Ctrl+V를 누르세요. 에이전트는 비전을 사용하여 스크린샷, 다이어그램, 오류 팝업 또는 UI 모델을 분석하므로 먼저 파일에 저장할 필요가 없습니다.

슬래시 명령 자동 완성​

/를 입력하고 Tab을 눌러 사용 가능한 모든 명령을 확인하세요. 여기에는 내장 명령(/compress, /model, /title)과 설치된 모든 스킬이 포함됩니다. 외울 필요 없이 탭 완성을 사용하면 됩니다.

팁

/verbose를 사용하면 도구 출력 표시 모드(off → new → all → verbose)를 순환할 수 있습니다. "all" 모드는 에이전트가 수행하는 작업을 관찰할 때 좋고, 간단한 Q&A에서는 "off"가 가장 깔끔합니다.

컨텍스트 파일​

AGENTS.md: 프로젝트의 두뇌​

아키텍처 결정, 코딩 규칙, 프로젝트별 지침을 담아 프로젝트 루트에 AGENTS.md를 만드세요. 이 파일은 모든 세션에 자동으로 주입되므로 에이전트가 항상 프로젝트 규칙을 알고 있습니다.

# Project Context
- This is a FastAPI backend with SQLAlchemy ORM
- Always use async/await for database operations
- Tests go in tests/ and use pytest-asyncio
- Never commit .env files

SOUL.md: 개성을 사용자 정의하세요​

Hermes가 안정적인 기본 말투를 갖게 하고 싶다면 ~/.hermes/SOUL.md를 편집하세요. 맞춤 Hermes 홈을 사용하는 경우 $HERMES_HOME/SOUL.md를 사용합니다. Hermes는 이제 시작용 SOUL을 자동으로 생성하고, 이 전역 파일을 인스턴스 전체 성격 소스로 사용합니다.

전체 연습을 보려면 Hermes와 함께 SOUL.md 사용을 참조하세요.

# Soul
You are a senior backend engineer. Be terse and direct.
Skip explanations unless asked. Prefer one-liners over verbose solutions.
Always consider error handling and edge cases.

지속적으로 유지할 성격에는 SOUL.md를 사용하세요. 프로젝트별 지침에는 AGENTS.md를 사용하세요.

.cursorrules 호환성​

이미 .cursorrules 또는 .cursor/rules/*.mdc 파일이 있나요? Hermes도 이 파일들을 읽습니다. 코딩 규칙을 복제할 필요가 없으며, 작업 디렉터리에서 자동으로 로드됩니다.

발견​

Hermes는 세션 시작 시 현재 작업 디렉터리의 최상위 AGENTS.md를 로드합니다. 하위 디렉터리의 AGENTS.md 파일은 도구 호출 중에(subdirectory_hints.py를 통해) 지연 발견되어 도구 결과에 삽입됩니다. 이 파일들은 시스템 프롬프트에 미리 로드되지 않습니다.

팁

컨텍스트 파일은 집중적이고 간결하게 유지하세요. 모든 문자가 매 메시지에 삽입되므로 토큰 예산에 포함됩니다.

메모리와 스킬​

메모리와 스킬: 무엇을 어디에 둘 것인가​

메모리는 환경, 선호도, 프로젝트 위치, 에이전트가 사용자에 대해 알게 된 사실 같은 정보를 위한 것입니다. 스킬은 다단계 작업 흐름, 도구별 지침, 재사용 가능한 레시피 같은 절차를 위한 것입니다. "무엇"에는 메모리를, "어떻게"에는 스킬을 사용하세요.

스킬을 만들어야 할 때​

5단계 이상 필요한 작업을 앞으로 다시 수행할 것 같다면 에이전트에게 해당 작업을 스킬로 만들도록 요청하세요. "방금 수행한 작업을 deploy-staging이라는 스킬로 저장하세요."라고 말하면 됩니다. 다음번에는 /deploy-staging을 입력하는 것만으로 전체 절차를 불러올 수 있습니다.

메모리 용량 관리​

메모리는 의도적으로 제한되어 있습니다(MEMORY.md는 약 2,200자, USER.md는 약 1,375자). 가득 차면 에이전트가 항목을 통합합니다. "메모리 정리" 또는 "이전 Python 3.9 노트는 현재 3.12를 쓴다는 내용으로 교체하세요."처럼 말해 정리를 도울 수 있습니다.

에이전트가 기억하도록 하세요​

생산적인 세션이 끝난 뒤 "다음번에 이것을 기억해 주세요"라고 말하면 에이전트가 핵심 내용을 저장합니다. 더 구체적으로 "우리 CI가 deploy.yml 워크플로와 함께 GitHub Actions를 사용한다는 내용을 메모리에 저장하세요."라고 지정할 수도 있습니다.

경고

메모리는 고정된 스냅샷입니다. 세션 중에 변경된 내용은 다음 세션이 시작될 때까지 시스템 프롬프트에 반영되지 않습니다. 에이전트는 즉시 디스크에 쓰지만, 세션 중 프롬프트 캐시는 무효화되지 않습니다.

성능 및 비용​

프롬프트 캐시를 깨지 마세요​

대부분의 LLM 제공자는 시스템 프롬프트 접두어를 캐시합니다. 시스템 프롬프트를 안정적으로 유지하면(같은 컨텍스트 파일, 같은 메모리) 세션의 후속 메시지에서 훨씬 저렴한 캐시 적중을 얻을 수 있습니다. 세션 중에는 모델이나 시스템 프롬프트를 불필요하게 바꾸지 마세요.

한계에 도달하기 전에 /compress를 사용하세요​

긴 세션은 토큰을 계속 축적합니다. 응답이 느려지거나 잘리기 시작하면 /compress를 실행하세요. 대화 기록을 요약해 핵심 컨텍스트를 유지하면서 토큰 수를 크게 줄입니다. 현재 상태는 /usage로 확인할 수 있습니다.

병렬 작업 위임​

세 가지 주제를 동시에 조사해야 하나요? 에이전트에게 병렬 하위 작업과 함께 delegate_task를 사용하도록 요청하세요. 각 하위 에이전트는 자체 컨텍스트에서 독립적으로 실행되고 최종 요약만 반환하므로, 기본 대화의 토큰 사용량이 크게 줄어듭니다.

일괄 작업에 execute_code 사용​

터미널 명령을 하나씩 실행하기보다 모든 작업을 한 번에 수행하는 스크립트를 작성하도록 에이전트에게 요청하세요. "모든 .jpeg 파일 이름을 .jpg로 바꾸는 Python 스크립트를 작성하고 실행하세요"가 파일 이름을 개별적으로 바꾸는 것보다 저렴하고 빠릅니다.

올바른 모델을 선택하세요​

세션 중에 모델을 전환하려면 /model을 사용하세요. 복잡한 추론과 아키텍처 결정에는 프런티어 모델(Claude Sonnet/Opus, GPT-4o)을 사용하고, 서식 정리, 이름 변경, 상용구 생성 같은 단순 작업에는 더 빠른 모델로 전환하세요.

팁

/usage를 주기적으로 실행해 토큰 소비를 확인하세요. 지난 30일 동안의 사용 패턴을 더 넓게 보려면 /insights를 실행하세요.

메시징 팁​

홈 채널 설정​

선호하는 Telegram 또는 Discord 채팅에서 /sethome을 사용해 홈 채널로 지정하세요. Cron 작업 결과와 예약된 작업 출력이 이 채널로 전달됩니다. 홈 채널이 없으면 에이전트는 사전 알림 메시지를 보낼 곳이 없습니다.

/title을 사용하여 세션 구성​

/title auth-refactor 또는 /title research-llm-quantization으로 세션 이름을 지정하세요. 이름이 있는 세션은 hermes sessions list로 쉽게 찾을 수 있고 hermes -r "auth-refactor"로 재개할 수 있습니다. 이름 없는 세션은 쌓이면 구별하기 어렵습니다.

팀 액세스를 위한 DM 페어링​

허용 목록에 넣을 사용자 ID를 수동으로 수집하지 말고 DM 페어링을 활성화하세요. 팀원이 봇에게 DM을 보내면 일회성 페어링 코드를 받습니다. hermes pairing approve telegram XKGH5N7P로 승인하면 간단하고 안전합니다.

도구 진행 표시 모드​

/verbose를 사용해 표시되는 도구 활동의 양을 제어하세요. 메시징 플랫폼에서는 보통 적게 보여주는 편이 낫습니다. 새 도구 호출만 보려면 "new"로 유지하세요. CLI에서 "all"은 에이전트가 수행하는 모든 작업을 실시간으로 보여줍니다.

팁

메시징 플랫폼에서 세션은 유휴 시간(기본값: 24시간) 이후 또는 매일 오전 4시에 자동 재설정됩니다. 더 긴 세션이 필요한 경우 ~/.hermes/config.yaml에서 플랫폼별로 조정하세요.

보안​

신뢰할 수 없는 코드에 Docker 사용​

신뢰할 수 없는 저장소로 작업하거나 낯선 코드를 실행할 때는 Docker 또는 Daytona를 터미널 백엔드로 사용하세요. .env에 TERMINAL_BACKEND=docker를 설정합니다. 컨테이너 내부의 파괴적인 명령은 호스트 시스템에 영향을 주지 않습니다.

# In your .env:
TERMINAL_BACKEND=docker
TERMINAL_DOCKER_IMAGE=hermes-sandbox:latest

Windows 인코딩 함정 방지​

Windows에서는 일부 기본 인코딩(예: cp125x)이 모든 유니코드 문자를 나타낼 수 없으므로 테스트나 스크립트에서 파일을 작성할 때 UnicodeEncodeError이 발생할 수 있습니다.

  • 명시적인 UTF-8 인코딩으로 파일을 여는 것을 선호합니다.
with open("results.txt", "w", encoding="utf-8") as f:
    f.write("✓ All good\n")
  • PowerShell에서는 콘솔 및 기본 명령 출력을 위해 현재 세션을 UTF-8로 전환할 수도 있습니다.
$OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)

이렇게 하면 PowerShell 및 하위 프로세스가 UTF-8로 유지되고 Windows에서만 발생하는 오류를 방지하는 데 도움이 됩니다.

"항상"을 선택하기 전에 검토하세요​

에이전트가 위험한 명령 승인(rm -rf, DROP TABLE 등)을 트리거하면 once, session, always, deny 네 가지 옵션이 표시됩니다. "always"를 선택하기 전에 신중하게 생각하세요. 해당 패턴을 영구 허용 목록에 추가합니다. 익숙해질 때까지는 "session"부터 시작하는 편이 안전합니다.

명령 승인은 안전망입니다​

Hermes는 실행 전에 모든 명령을 선별된 위험 패턴 목록과 비교합니다. 여기에는 재귀 삭제, SQL 삭제, curl을 셸로 파이프하는 패턴 등이 포함됩니다. 프로덕션 환경에서는 이 기능을 비활성화하지 마세요. 존재할 만한 이유가 있는 안전장치입니다.

경고

컨테이너 백엔드(Docker, Singularity, Modal, Daytona)에서 실행할 때 컨테이너가 보안 경계이기 때문에 위험한 명령 검사는 건너뛰기됩니다. 컨테이너 이미지가 제대로 잠겨 있는지 확인하세요.

메시징 봇에 허용 목록 사용​

터미널 접근 권한이 있는 봇에는 GATEWAY_ALLOW_ALL_USERS=true를 설정하지 마세요. 항상 플랫폼별 허용 목록(TELEGRAM_ALLOWED_USERS, DISCORD_ALLOWED_USERS) 또는 DM 페어링을 사용해 에이전트와 상호작용할 수 있는 사람을 제한하세요.

# Recommended: explicit allowlists per platform
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678

# Or use cross-platform allowlist
GATEWAY_ALLOWED_USERS=123456789,987654321

이 페이지에 추가하면 좋을 팁이 있나요? 이슈를 열거나 PR을 보내 주세요. 커뮤니티 기여를 환영합니다.