Hermes Agent 컨텍스트 파일 감사 및 슬림화 프롬프트: SOUL.md와 AGENTS.md 정비 기법

테크 엔지니어인 witcheer(@witcheer)가 Nous Research의 자율형 코딩 에이전트 Hermes Agent에서 세션마다 로드되는 핵심 설정 파일들(SOUL.md, USER.md, MEMORY.md, AGENTS.md)을 에이전트 스스로 감사하고 정비할 수 있도록 유도하는 실전 감사 프롬프트와 운영 원칙을 공유했습니다.

이미지 출처: witcheer (@witcheer) / X

AI 코딩 하네스를 장기간 운영하다 보면 컨텍스트 창 상단에 항상 주입되는 시스템 프롬프트와 메모리 파일에 과거의 임시 규칙, 폐기된 디렉토리 경로, 서로 충돌하는 지침이 누적되기 마련입니다. 이번에 공개된 프롬프트는 에이전트가 자신의 판단 기준이 되는 파일들을 로컬 머신의 실제 파일 시스템 및 프로젝트 코드와 한 줄씩 직접 대조하여, '자신이 기억하는 허구'를 스스로 검증하고 군더더기를 걷어내도록 강제합니다.

컨텍스트 부패(Context Rot)와 '자신의 허구 직면(Facing Its Own Fiction)'

Hermes Agent는 개발자가 작업을 시작할 때 시스템 프롬프트 빌더(prompt_builder.py)를 통해 네 가지 주요 마크다운 문서를 읽어 들여 에이전트의 페르소나와 작업 지침을 구성합니다.

• SOUL.md: 에이전트의 핵심 정체성, 어조, 기본 행동 원칙을 규정하는 파일
• USER.md: 사용자의 배경 지식, 개발 선호도, 소통 스타일을 기록하는 파일
• MEMORY.md: 과거 세션에서 학습한 장기 기억과 세션 간 누적 지식을 보관하는 파일
• AGENTS.md: 현재 작업 중인 프로젝트의 폴더 구조, 빌드 규칙, 테스트 제약 조건, 아키텍처 결정을 담은 프로젝트 지침 파일

문제는 세션이 수십 회 이상 이어지면서 발생합니다. 프로젝트 디렉토리가 변경되었음에도 AGENTS.md에 이전 경로가 남아 있거나, MEMORY.md에 이미 해결된 버그 대응책이 중복 기재되어 값비싼 컨텍스트 윈도우를 낭비하는 현상, 즉 '컨텍스트 부패(Context Rot)'가 발생합니다.

witcheer의 프롬프트는 에이전트에게 맹목적으로 작업을 시키는 대신, 커뮤니티 개발자(@BlesdAbroad)의 표현대로 "에이전트가 스스로 만들어낸 허구와 직접 대면(forcing it to confront its own fiction)"하게 만듭니다. 실제 머신 환경에 파일이 존재하는지, 지침이 두 번 이상 반복되지는 않았는지를 객관적으로 검증하도록 지시하는 것입니다.

Hermes Agent 컨텍스트 자체 감사 프롬프트 전문

프롬프트는 엄격한 XML 태그 구조를 취하고 있으며, 무단 파일 수정을 엄격히 금지하는 3대 원칙(Principles)과 7단계 실행 절차(Instructions)로 구성되어 있습니다.

<role>
You are my Hermes Agent. Audit the files you read at the start of every session, so what shapes you stays current and lean. Ask, do not assume.
</role>

<principles>
<principle name="Read only until my yes">
Read the files and change nothing: no memory entry, no file, no config. Every edit waits for my yes.
</principle>
<principle name="Every line earns its place">
Flag an entry that is stale, says something twice, contradicts another, or costs context without changing what you do.
</principle>
<principle name="Show before you change">
Show each file as it is and as you would leave it. If you cannot get my answer, end your turn and change nothing.
</principle>
</principles>

<instructions>
1. Read your SOUL.md, your memory files USER.md and MEMORY.md, and the AGENTS.md in this folder if there is one.
2. For each file, give its path and one line on what it is for.
3. Check each claim against this machine and the project files.
4. List every flagged entry: the file, the entry, the flag, and the reason in one sentence.
5. Where two entries contradict, name the one you would keep and ask me to confirm.
6. Show a before and after for each file you would change. Then stop and wait for my yes.
7. After my yes, apply only the changes I approve. Report what changed in each file.
</instructions>

<task>
Start with step one now.
</task>

프롬프트 핵심 안전 설계 3가지

1. 승인 전 무조건 읽기 전용 (Read only until my yes): 에이전트는 파일 내용을 스캔할 뿐 메모리 항목, 설정, 소스 코드를 임의로 수정할 수 없습니다. 모든 파일 변경은 인간 사용자의 명시적인 'yes' 응답을 받은 뒤에만 허용됩니다.
2. 모든 줄의 존재 가치 증명 (Every line earns its place): 오래되어 쓸모없어진(stale) 항목, 중복 서술된 항목, 다른 규칙과 상충되는 항목, 행동 변화 없이 토큰만 소모하는 비효율적인 문장을 빠짐없이 플래그(flag) 처리합니다.
3. 수정 전후 Diff 사전 제시 (Show before you change): 각 파일이 현재 어떤 상태이며 어떻게 고칠 것인지 Before & After를 명확히 제시해야 합니다. 사용자 피드백을 받을 수 없는 상태라면 즉시 턴을 종료하고 아무것도 건드리지 않습니다.

7단계 감사 및 정비 프로세스

• 1~2단계 (탐색 및 목적 정의): SOUL.md, USER.md, MEMORY.md, 프로젝트 루트의 AGENTS.md를 순서대로 읽고 각 파일의 경로와 역할을 한 줄로 요약합니다.
• 3~4단계 (실측 대조 및 플래그 지정): 문서에 적힌 모든 주장과 경로를 로컬 머신 및 프로젝트 파일과 대조합니다. 유효하지 않은 항목이 발견되면 파일명, 대상 구문, 플래그 종류, 지적 사유를 한 문장으로 정리해 보고합니다.
• 5단계 (충돌 해결 중재): 두 규칙이나 기억이 상충될 경우, 에이전트가 어떤 규칙을 남기는 것이 타당한지 추천안을 제시하고 사용자 컨펌을 구합니다.
• 6~7단계 (Diff 검토 및 선별 적용): 변경 제안 사항의 Before/After를 표시한 뒤 멈추고 대기합니다. 사용자가 승인한 항목에 한해서만 변경을 적용하고, 파일별 최종 반영 결과를 리포트합니다.

실무 적용 시 주의점과 커뮤니티 논의

프롬프트 공개 직후 Hermes Agent 실사용자들 사이에서 실전 배치 시 고려해야 할 중요한 엣지 케이스와 확장 아이디어가 활발히 논의되었습니다.

미생성 디렉토리 경로에 대한 오탐 위험

엔지니어 @mktpavlenko는 프로젝트 초기 단계의 AGENTS.md를 감사할 때 발생할 수 있는 주요 함정을 지적했습니다. AGENTS.md에는 향후 셋업이나 빌드 파이프라인에서 생성될 예정인 디렉토리 및 파일 경로가 사전 정의되어 있을 수 있는데, 에이전트가 이를 기계적으로 로컬 머신과 대조할 경우 아직 생성되지 않은 유효한 준비 지침을 삭제 후보로 올릴 위험이 있습니다.

그는 이어 프롬프트에 명시된 '수정 전 확인 단계(ask-before-edit)' 원칙 덕분에 에이전트가 독단으로 파일을 삭제하지 않고 사용자에게 의도된 향후 설정인지 확인할 기회가 보장된다고 분석했습니다.

누락된 규칙 vs 잘못된 규칙의 차이

John Rood(@johnroodepic)는 감사 프롬프트의 한계와 역할 범위를 명확히 짚었습니다.

"이 감사는 '잘못 적힌 줄(wrong lines)'을 찾아내지만, '존재해야 하는데 빠진 규칙(missing rules)'까지 찾아내지는 못합니다. 누락된 규칙은 대개 에이전트가 실제 작업 중 사고를 쳤을 때 비로소 드러납니다. 따라서 컨텍스트 파일의 진정한 개선 백로그는 과거에 발생한 장애와 사고(incidents) 기록입니다."

즉, 정기적인 파일 감사를 통해 레거시 규칙과 중복을 덜어내는 한편, 에이전트의 실수나 오작동이 발생했을 때 사후 분석을 거쳐 새로운 방어 규칙을 AGENTS.md에 추가하는 상호 보완적 운용이 필수적입니다.

세션 시작 루틴의 자동화 가능성

에이전트가 세션 시작 시 지침 읽기를 간헐적으로 건너뛰는 문제를 해결하기 위해 별도의 세션 시작 리추얼(Session start ritual) 플러그인을 제작해 사용 중이라는 피드백(@corylee4870)과 함께, 이 감사 워크플로우를 신규 프로젝트 온보딩 시 기본 실행 절차로 삼거나 Hermes Agent의 내장 자동 점검 기능(built-in automated check)으로 공식 통합하자는 제안(@linus5x, @yotamha1)에 대해 원작자 @witcheer는 향후 개발 방향으로 긍정적인 검토 의사를 밝혔습니다.

원문 출처

• witcheer (@witcheer) X 포스트