소스코드 앞에 놓인 안전장치: Hermes 기본 AGENTS.md의 하네스 구조 읽기
2026.05.19
소스코드 앞에 놓인 안전장치: Hermes 기본 AGENTS.md의 하네스 구조 읽기
한 줄 요약
Hermes Agent 저장소의 기본 AGENTS.md는 단순한 개발 안내 문서라기보다, AI 코딩 에이전트가 저장소를 추측으로 다루지 않도록 잡아주는 지도·계약·검증·경고 레이어의 하네스에 가까웠습니다.
이런 분들께 도움이 됩니다
AI 코딩 에이전트를 실제 저장소에 붙여 쓰는 분
AGENTS.md, CLAUDE.md, CONTRIBUTING.md를 어떻게 써야 할지 고민하는 분
에이전트가 프로젝트 구조를 오해하거나 같은 실수를 반복해서 답답했던 분
저장소의 작업 규칙, 테스트 기준, 금지 사항을 문서로 고정하고 싶은 분
“좋은 프롬프트”를 넘어서 “좋은 작업 환경”을 만들고 싶은 분
---
시작점: AI 에이전트에게는 코드보다 먼저 현장 지도가 필요했습니다
AI 코딩 에이전트에게 작업을 맡기다 보면, 모델 성능만으로는 해결되지 않는 문제가 있습니다.
모델이 코드를 읽고 수정할 수는 있지만, 저장소마다 다른 운영 규칙까지 자동으로 아는 것은 아닙니다.
예를 들어 이런 일이 생깁니다.
핵심 진입점이 아닌 주변 파일부터 고칩니다.
이미 정해진 테스트 방식이 있는데 임의로 다른 명령을 실행합니다.
설정 파일과 secret 파일의 경계를 흐리게 다룹니다.
profile이나 workspace처럼 격리되어야 하는 경로를 하드코딩합니다.
과거에 이미 겪은 실패를 다시 반복합니다.
“일반적인 Python 프로젝트”라고 가정하고 저장소 고유의 구조를 놓칩니다.
그래서 이번에는 Hermes Agent 저장소 루트의 기본 AGENTS.md를 하나의 하네스 문서로 보고 분석했습니다.
여기서 말하는 하네스는 거창한 별도 시스템이 아니라, 에이전트가 작업할 때 다음을 고정해주는 구조입니다.
어디부터 읽어야 하는지
어떤 파일이 실제 진입점인지
새 기능을 어디에 연결해야 하는지
무엇을 절대 하면 안 되는지
테스트는 어떤 방식으로 검증해야 하는지
이전에 어떤 함정이 있었는지
즉, 모델에게 “이 저장소에서는 이렇게 움직여야 합니다”라고 알려주는 작업 환경입니다.
---
확인한 자료
분석 대상은 Hermes Agent 저장소 루트에 있는 기본 AGENTS.md였습니다.
파일 규모는 다음과 같았습니다.
```bash
wc -l -c AGENTS.md
# 1102 51529 AGENTS.md
```
정리하면 약 1,100줄, 약 5만 자 규모의 문서입니다.
크기만 보면 긴 편이지만, 내용을 따라가 보니 단순히 정보를 많이 넣은 문서라기보다 에이전트가 작업할 때 필요한 판단 기준을 여러 레이어로 나눠 둔 구조에 가까웠습니다.
---
전체 구조를 하네스 관점으로 보면
이 문서는 크게 여섯 개 레이어로 읽을 수 있었습니다.
프로젝트 지도 레이어
의존 관계 레이어
실행 루프 레이어
인터페이스 계약 레이어
안전 정책 레이어
검증과 실패 기록 레이어
각 레이어는 따로 떨어진 설명이 아니라, 에이전트가 실제로 코드를 수정할 때 순서대로 작동하는 장치처럼 보였습니다.
```text
프로젝트 지도
→ 의존 관계 파악
→ 실행 루프 이해
→ 명령/도구/확장 지점 확인
→ 안전 정책 적용
→ 테스트와 Known Pitfalls로 검증
```
이 흐름이 있기 때문에 AGENTS.md가 단순 README보다 더 실전적인 역할을 합니다.
---
1. 프로젝트 지도 레이어: 어디가 핵심인지 먼저 알려줍니다
문서 앞부분은 프로젝트 구조를 설명합니다.
좋았던 점은 폴더를 전부 나열하려고 하지 않는다는 점이었습니다.
대신 실제로 자주 건드리게 되는 load-bearing 파일을 먼저 보여줍니다.
예를 들어 다음 파일들이 핵심 진입점으로 소개됩니다.
run_agent.py: AIAgent class와 core conversation loop
model_tools.py: tool discovery와 function call 처리
toolsets.py: toolset 정의
cli.py: interactive CLI 오케스트레이션
hermes_state.py: SQLite 기반 session store
gateway/: Telegram, Discord, Slack 등 플랫폼 adapter
tools/: tool implementation
cron/: scheduler
tests/: pytest suite
여기서 중요한 문장이 하나 있습니다.
> File counts shift constantly — don't treat the tree below as exhaustive. The canonical source is the filesystem.
이 문장은 에이전트에게 꽤 중요한 신호입니다.
문서는 지도를 제공하지만, 실제 최신 상태는 파일시스템에서 확인하라는 뜻입니다.
AI는 문서에 적힌 구조를 너무 강하게 믿는 경향이 있습니다. 그런데 이 문장은 “문서는 방향을 주고, 최종 확인은 실제 파일에서 하라”는 기준을 먼저 세워줍니다.
이런 식의 문구는 오래된 문서 때문에 잘못된 판단을 하는 일을 줄여줍니다.
---
2. 의존 관계 레이어: 어떤 수정이 어디까지 번지는지 보여줍니다
그다음 인상적이었던 부분은 File Dependency Chain입니다.
문서에는 대략 이런 흐름이 들어 있습니다.
```text
tools/registry.py
↑
tools/*.py
↑
model_tools.py
↑
run_agent.py, cli.py, batch_runner.py, environments/
```
이 구조는 단순한 폴더 설명보다 훨씬 유용합니다.
AI 에이전트가 코드를 고칠 때 자주 하는 실수는 “지금 보고 있는 파일 하나만 고치면 된다”고 생각하는 것입니다.
하지만 실제로는 등록 지점, discovery 지점, 실행 지점이 따로 있을 수 있습니다.
이 의존 관계는 에이전트에게 다음 질문을 하게 만듭니다.
이 파일을 고치면 어디에서 import되는가?
등록만 하면 끝나는가, discovery 흐름도 확인해야 하는가?
CLI에서는 보이지만 gateway에서는 안 보이는 구조는 아닌가?
테스트는 단위 테스트만 보면 되는가, 실제 호출 경로도 확인해야 하는가?
즉, 코드 조각을 수정하는 것이 아니라 실행 경로를 따라가도록 만드는 장치입니다.
---
3. 실행 루프 레이어: AI 에이전트의 실제 심장을 보여줍니다
AIAgent Class 섹션은 에이전트가 실제로 어떻게 동작하는지 알려줍니다.
여기서 단순히 “이 클래스가 중요하다”라고 말하지 않고, AIAgent.__init__이 실제로는 많은 파라미터를 받는다는 점을 먼저 밝힙니다.
문서에서는 보통 만지게 되는 최소 subset만 보여주고, 전체 시그니처는 run_agent.py에서 확인하라고 안내합니다.
이것도 좋은 균형입니다.
문서에 모든 것을 복사하지 않습니다.
하지만 에이전트가 시작점을 잃지 않게 최소 구조는 보여줍니다.
전체 진실은 소스 파일에서 확인하게 합니다.
Agent Loop 설명도 중요합니다.
핵심 흐름은 다음과 같습니다.
```text
사용자 메시지 수신
→ system prompt와 conversation history 구성
→ LLM 호출
→ tool call이 있으면 handle_function_call로 실행
→ tool result를 messages에 추가
→ 다시 LLM 호출
→ 최종 text response가 나오면 종료
```
이 구조를 알고 있으면 에이전트가 수정할 때 관점이 달라집니다.
예를 들어 tool 관련 문제가 생겼을 때 단순히 tool 파일만 볼 것이 아니라, 다음을 함께 봐야 합니다.
tool schema가 제대로 노출되는가?
handle_function_call에서 dispatch되는가?
tool result message 형식이 맞는가?
iteration budget과 interrupt 처리에 영향을 주는가?
conversation history에 어떤 role로 들어가는가?
이 문서는 에이전트가 “기능 하나 추가”가 아니라 “대화 루프 안에서 기능이 어떻게 흘러가는지”를 보게 만듭니다.
---
4. 인터페이스 계약 레이어: CLI, TUI, Gateway가 따로 놀지 않게 합니다
Hermes는 terminal CLI만 있는 도구가 아니라, TUI와 gateway까지 함께 움직이는 구조입니다.
그래서 AGENTS.md는 CLI, slash command, TUI, gateway의 연결 방식을 꽤 자세히 설명합니다.
특히 slash command registry 구조가 좋았습니다.
모든 slash command는 hermes_cli/commands.py의 COMMAND_REGISTRY에서 정의되고, downstream consumer들이 이 registry에서 파생됩니다.
이 구조는 에이전트에게 중요한 원칙을 줍니다.
> 명령어를 하나 추가할 때, CLI에만 보이게 만들지 말고 중앙 registry 기준으로 연결하라.
문서에서 설명하는 downstream consumer는 대략 다음과 같습니다.
CLI command resolution
Gateway known commands
Gateway help
Telegram menu
Slack mapping
CLI help
이런 설명이 없으면 AI는 흔히 한 화면에서 보이는 부분만 고칩니다.
예를 들어 CLI에서는 작동하지만 gateway help에는 나오지 않거나, Telegram menu에는 빠지는 식입니다.
중앙 registry를 기준으로 설명하면, 에이전트가 “사용자 인터페이스마다 따로 고치기”보다 “공통 원천을 고치기”로 접근하게 됩니다.
이것은 좋은 하네스의 특징입니다.
중복 구현을 줄이고, 수정 위치를 한 곳으로 모읍니다.
---
5. 확장 지점 레이어: 새 기능을 어떻게 붙일지 계약으로 정합니다
문서에는 새 tool 추가, slash command 추가, plugin 구조 같은 확장 지점이 정리되어 있습니다.
이 부분의 핵심은 “기능을 어디에 만들면 되는지”가 아니라, “만든 기능이 시스템에 어떻게 등록되고 발견되는지”입니다.
예를 들어 tool 추가 흐름은 다음 기준을 갖습니다.
tools/your_tool.py를 만든다.
tools.registry의 registry.register()를 호출한다.
schema, handler, requirement check를 함께 등록한다.
필요하면 toolset 정의에도 연결한다.
handler는 JSON string을 반환해야 한다.
이런 계약은 AI에게 매우 중요합니다.
AI는 종종 구현 파일 하나를 만들고 끝났다고 판단합니다.
하지만 실제 시스템에서는 “파일이 있다”와 “런타임이 발견한다”가 다릅니다.
좋은 AGENTS.md는 이 차이를 문서로 고정합니다.
```text
파일 생성
→ registry 등록
→ toolset 연결
→ requirement check
→ 실제 agent loop에서 호출 가능
→ 테스트
```
이 흐름이 있어야 기능이 문서상 존재하는 것이 아니라 실제로 작동합니다.
---
6. 안전 정책 레이어: 프롬프트 캐시와 프로필 경계를 깨지 않게 합니다
문서 후반부에는 Important Policies가 나옵니다.
여기서 가장 눈에 띄는 부분은 prompt caching입니다.
문서에서는 대화 중에 past context, toolset, memory, system prompt를 마음대로 바꾸지 말라고 합니다.
이유도 명확합니다.
캐시가 깨지면 비용이 커집니다.
대화 중간 상태가 예상과 달라질 수 있습니다.
변경은 보통 다음 session에서 적용되도록 해야 합니다.
즉시 적용이 필요하면 명시적인 --now 같은 opt-in이 필요합니다.
이 기준은 꽤 중요합니다.
AI 에이전트는 “지금 바로 반영”을 선호할 수 있습니다. 하지만 런타임 관점에서는 지금 반영하는 것이 캐시나 상태 일관성을 깨뜨릴 수 있습니다.
문서가 이 경계를 명시하면, 에이전트는 “즉시 고치기”보다 “언제 적용되어야 안전한가”를 생각하게 됩니다.
Profile 관련 규칙도 좋았습니다.
Hermes는 여러 profile을 지원하고, 각 profile은 config, auth, memory, session, gateway 상태를 따로 가질 수 있습니다.
그래서 문서에서는 ~/.hermes를 하드코딩하지 말고 get_hermes_home()을 쓰라고 강조합니다.
좋은 예시는 다음과 같습니다.
```python
from hermes_constants import get_hermes_home
config_path = get_hermes_home() / "config.yaml"
```
나쁜 예시는 다음과 같습니다.
```python
config_path = Path.home() / ".hermes" / "config.yaml"
```
이 차이는 작아 보이지만, 멀티 인스턴스 환경에서는 치명적일 수 있습니다.
기본 profile에서는 잘 돌아가도, 다른 profile에서는 잘못된 config나 token을 읽을 수 있기 때문입니다.
이런 규칙은 단순 스타일이 아니라 런타임 안전장치입니다.
---
7. 검증 레이어: 테스트 명령까지 하네스에 포함합니다
문서의 Testing 섹션도 꽤 강하게 쓰여 있습니다.
핵심은 pytest를 직접 호출하지 말고 scripts/run_tests.sh를 사용하라는 것입니다.
이유가 구체적입니다.
wrapper script는 다음 차이를 줄여줍니다.
개발자 로컬 환경의 API key 자동 감지
실제 HOME과 ~/.hermes/ 오염
로컬 timezone 차이
locale 차이
xdist worker 수 차이
즉, “내 컴퓨터에서는 통과했는데 CI에서는 깨짐”을 줄이는 장치입니다.
AI 에이전트에게 테스트를 맡길 때 가장 위험한 패턴 중 하나는, 로컬에서 편한 명령만 실행하고 통과했다고 말하는 것입니다.
이 문서는 완료 기준을 더 엄격하게 만듭니다.
```text
그냥 테스트 실행
→ CI와 비슷한 환경에서 테스트 실행
→ secret과 HOME을 격리한 상태로 확인
→ routine source update에 깨지는 snapshot 테스트는 피하기
```
특히 change-detector test를 쓰지 말라는 부분도 좋았습니다.
문서에서는 모델 목록, config version number, provider model count처럼 바뀌는 데이터의 현재 값을 그대로 고정하는 테스트를 피하라고 합니다.
대신 관계나 invariant를 테스트하라고 합니다.
예를 들면 이런 차이입니다.
```python
# 좋지 않은 방향: 현재 목록을 그대로 얼립니다.
assert len(models) == 8
# 더 나은 방향: 유지되어야 하는 관계를 확인합니다.
for model in models:
assert model.lower() in DEFAULT_CONTEXT_LENGTHS_LOWER
```
이 부분은 AI가 테스트를 만들 때 특히 중요합니다.
AI는 현재 상태를 스냅샷으로 고정하는 테스트를 쉽게 만듭니다. 하지만 좋은 테스트는 현재 상태 자체가 아니라, 깨지면 안 되는 계약을 확인해야 합니다.
---
8. 실패 기록 레이어: Known Pitfalls가 팀의 기억 역할을 합니다
문서에서 가장 실전적이라고 느낀 부분은 Known Pitfalls였습니다.
여기에는 이미 겪었거나 다시 겪기 쉬운 함정이 구체적으로 적혀 있습니다.
예를 들면 다음과 같습니다.
~/.hermes 경로를 하드코딩하지 말 것
새 interactive menu에는 특정 legacy menu 방식을 추가하지 말 것
display code에서 특정 ANSI erase sequence를 쓰지 말 것
gateway에는 message guard가 두 개 있으므로 control command는 둘 다 고려할 것
stale branch를 squash merge하면 최근 수정이 조용히 되돌아갈 수 있음
E2E validation 없이 dead code를 live path에 연결하지 말 것
테스트가 실제 ~/.hermes/에 쓰면 안 됨
이런 내용은 일반적인 개발 문서에는 잘 들어가지 않습니다.
하지만 AI 에이전트에게는 이런 기록이 매우 중요합니다.
사람은 팀 회의, PR 리뷰, 과거 장애 경험을 기억할 수 있습니다. 반면 에이전트는 매번 저장소를 새로 읽는 쪽에 가깝습니다.
그래서 Known Pitfalls는 저장소의 장기 기억처럼 작동합니다.
“여기서 이런 식으로 망한 적이 있으니, 같은 길로 가지 마세요.”
이 한 줄을 문서로 남겨두는 것만으로도, 다음 에이전트 작업의 위험이 줄어듭니다.
---
이 문서가 실제로 잡아주는 작업 방식
이 글에서 말할 수 있는 것은 “새로 도입해서 달라진 변화”가 아닙니다.
이 AGENTS.md는 새로 추가한 개선안이 아니라, 저장소에 기본으로 놓여 있는 작업 전제에 가깝습니다. 그래서 이 문서를 평가할 때는 “없던 것이 생겨서 무엇이 달라졌는가”보다, “이미 존재하는 기본 문서가 에이전트의 행동을 어떤 궤도로 고정하는가”를 보는 편이 더 정확합니다.
분석하면서 보인 핵심은 다음과 같습니다.
수정하기 전에 먼저 프로젝트의 load-bearing 파일을 확인하게 합니다.
변경이 흘러가는 의존 관계를 보게 합니다.
agent loop와 tool dispatch 경로를 함께 고려하게 합니다.
명령어와 UI surface를 중앙 registry 기준으로 보게 합니다.
config, secret, profile, cache 정책을 지키게 합니다.
테스트를 CI와 가까운 방식으로 실행하게 합니다.
Known Pitfalls를 먼저 확인하고 같은 실수를 피하게 합니다.
좋은 하네스는 새 기능처럼 눈에 띄기보다, 작업자가 처음부터 덜 위험한 경로로 움직이게 만듭니다.
이 경우 핵심은 “문서가 생겨서 좋아졌다”가 아니라, “이미 존재하는 기본 문서가 에이전트에게 어떤 안전한 작업 궤도를 제공하는가”입니다.
결국 질문은 “AI가 코드를 읽을 수 있는가”가 아니라, “AI가 이 저장소의 작업 방식으로 움직이도록 충분히 안내받고 있는가”에 가깝습니다.
---
좋았던 점
1. 문서가 최신성의 한계를 인정합니다
프로젝트 트리를 보여주면서도, 실제 canonical source는 파일시스템이라고 말합니다.
이 태도가 좋았습니다.
문서가 모든 것을 대체하려고 하지 않고, 에이전트가 확인해야 할 방향을 제시합니다.
2. 코드 구조가 아니라 작업 흐름을 설명합니다
단순히 “이 파일은 이런 역할”에서 끝나지 않습니다.
의존 관계, registry, dispatch, test wrapper, gateway guard처럼 실제 작업에서 문제가 되는 연결부를 설명합니다.
3. 금지 사항에 대안이 붙어 있습니다
“하지 마세요”만 있으면 AI는 다음 선택지를 잃습니다.
이 문서는 보통 대안을 함께 줍니다.
~/.hermes를 하드코딩하지 말고 get_hermes_home()을 쓰기
직접 pytest를 부르지 말고 scripts/run_tests.sh를 쓰기
snapshot test 대신 invariant test를 쓰기
system prompt mutation은 즉시 반영보다 deferred invalidation을 기본으로 하기
이런 식의 금지와 대안 조합은 에이전트에게 실제 행동 지침이 됩니다.
4. 실패를 숨기지 않고 문서화합니다
Known Pitfalls는 이 문서의 핵심 가치 중 하나입니다.
성공 경로만 쓰는 문서는 보기에는 깔끔하지만, 에이전트의 실수를 막기에는 부족합니다.
오히려 자주 터졌던 문제, 헷갈리기 쉬운 edge case, 잘못된 merge 습관 같은 것이 더 실용적입니다.
5. 테스트를 “실행”이 아니라 “환경 재현”으로 봅니다
테스트 명령 하나를 알려주는 수준이 아니라, 왜 wrapper가 필요한지 설명합니다.
API key, HOME, timezone, locale, worker count 같은 환경 차이를 언급하는 점이 좋았습니다.
이것은 테스트를 단순한 확인 절차가 아니라 재현성 관리로 보는 관점입니다.
---
아쉬운 점도 있었습니다
중립적으로 보면, 이 문서가 완벽하기만 한 것은 아닙니다.
1. 처음 읽는 사람에게는 꽤 깁니다
약 1,100줄 규모라서 한 번에 읽기에는 부담이 있습니다.
에이전트에게는 필요한 정보가 많지만, 사람 기여자에게는 빠른 요약이나 “처음 읽을 때는 이 순서로 보세요” 같은 안내가 더 있으면 좋을 수 있습니다.
2. 명시적인 하네스 다이어그램은 없습니다
문서 안에 여러 레이어가 잘 들어 있지만, 그것을 하나의 하네스 구조로 요약한 그림이나 섹션은 따로 보이지 않았습니다.
예를 들어 다음과 같은 요약이 있으면 더 빠르게 이해할 수 있을 것 같습니다.
```text
Orientation → Wiring → Extension Contract → Runtime Policy → Verification → Pitfalls
```
현재 문서는 내용을 따라가며 구조를 발견해야 합니다.
3. 유지보수 비용이 있습니다
이 정도로 상세한 문서는 최신성을 유지하는 것이 중요합니다.
CLI flag, gateway behavior, test wrapper, profile rule, plugin 구조가 바뀌면 문서도 같이 바뀌어야 합니다.
좋은 하네스일수록, 오래 방치되면 오히려 잘못된 신호를 줄 수 있습니다.
4. 중요한 규칙이 길이에 묻힐 수 있습니다
프로필 경로, prompt caching, test wrapper, Known Pitfalls 같은 규칙은 매우 중요합니다.
문서가 길어질수록 이런 핵심 규칙이 눈에 덜 띌 수 있습니다.
따라서 “절대 어기면 안 되는 10가지” 같은 짧은 상단 요약이 있으면 더 좋을 수 있습니다.
---
다른 프로젝트에 가져갈 수 있는 구조
이번 분석에서 가장 실용적으로 가져갈 수 있는 점은, AGENTS.md를 단순 안내 문서가 아니라 하네스로 설계하는 방식입니다.
다른 프로젝트에 적용한다면 이런 구조가 좋겠습니다.
```text
1. 이 저장소에서 가장 먼저 봐야 할 파일
2. 기능이 실제로 등록되고 실행되는 경로
3. 새 기능을 추가할 때 반드시 거치는 contract
4. config와 secret의 경계
5. profile/workspace/runtime 격리 규칙
6. 테스트 명령과 CI parity 기준
7. 자주 반복된 실패와 금지 사항
8. 금지 사항마다 대안 명령 또는 대안 패턴
9. 완료 기준 체크리스트
```
이 구조가 있으면 AI 에이전트가 저장소를 훨씬 덜 추측합니다.
중요한 것은 문서를 길게 쓰는 것이 아닙니다.
에이전트가 실수하기 쉬운 부분을 정확히 막아주는 것입니다.
---
바로 써볼 수 있는 점검 질문
다른 저장소의 AGENTS.md를 점검할 때는 아래 질문을 사용할 수 있습니다.
```text
이 저장소의 AGENTS.md를 하네스 관점에서 점검해주세요.
단순 요약이 아니라, AI 코딩 에이전트가 실제 작업할 때
추측을 줄이고 안전하게 수정할 수 있는지 기준으로 봐주세요.
확인할 항목:
1. 핵심 진입점과 load-bearing 파일이 명확한가?
2. 파일 의존 관계나 실행 경로가 설명되어 있는가?
3. 새 기능을 추가할 때 registry, router, config, test까지 이어지는 contract가 있는가?
4. CLI, UI, gateway처럼 여러 interface가 같은 source of truth를 공유하는가?
5. config와 secret의 경계가 명확한가?
6. profile, workspace, runtime 격리 규칙이 있는가?
7. 테스트 실행 방식이 CI와 최대한 가깝게 고정되어 있는가?
8. 자주 반복된 실패가 Known Pitfalls로 남아 있는가?
9. 금지 사항마다 대안이 같이 제시되어 있는가?
10. 문서가 오래되었을 때 실제 파일을 확인하라는 기준이 있는가?
부족한 부분은 개선안으로 정리해주세요.
```
---
결과와 배운 점
Hermes 기본 AGENTS.md를 하네스 관점으로 읽어보니, 좋은 작업 문서는 단순히 친절한 설명이 아니라 에이전트의 행동 반경을 안전하게 잡아주는 구조라는 생각이 들었습니다.
이 문서가 잘하는 일은 크게 세 가지였습니다.
첫째, 에이전트가 저장소를 추측하지 않게 합니다.
프로젝트 구조, 의존 관계, 실행 루프, registry, gateway, test wrapper가 모두 구체적으로 적혀 있습니다.
둘째, 에이전트가 너무 쉽게 바꾸면 안 되는 것들을 알려줍니다.
prompt caching, profile path, config/secret 경계, runtime state 같은 부분은 일반 코드 수정보다 조심해야 합니다.
셋째, 과거의 실패를 다음 작업의 guardrail로 바꿉니다.
Known Pitfalls는 문서 속 작은 섹션처럼 보이지만, 실제로는 에이전트가 같은 실수를 반복하지 않게 하는 중요한 장치입니다.
결국 좋은 AGENTS.md는 “AI에게 뭘 시킬지”보다 “AI가 어떤 환경에서 어떻게 일해야 하는지”를 정리하는 문서에 가깝습니다.
모델 성능이 좋아질수록 이런 문서의 중요성은 줄어드는 것이 아니라 오히려 커질 수 있습니다.
더 강한 모델일수록 더 많은 것을 바꿀 수 있기 때문에, 어디까지 바꿔도 되고 어디서 멈춰야 하는지를 알려주는 하네스가 필요하기 때문입니다.
---
짧은 마무리
Hermes 기본 AGENTS.md는 약 5만 자짜리 개발 안내 문서처럼 보이지만, 실제로는 AI 코딩 에이전트를 위한 작업 하네스에 가까웠습니다.
좋은 하네스는 에이전트에게 자유를 빼앗는 것이 아니라, 안전하게 움직일 수 있는 레일을 깔아줍니다.
코드를 잘 쓰는 AI보다 더 중요한 것은, 프로젝트의 방식대로 일하는 AI입니다.
그리고 그 차이를 만드는 첫 번째 문서가 AGENTS.md가 될 수 있습니다.




좋은 글 감사합니다.