.hermes.md와 AGENTS.md로 프로젝트 규칙 전달하기

Project rule은 project와 함께 이동해야 합니다. Hermes는 전용 .hermes.md 계열이나 portable AGENTS.md 계열 중 하나를 불러올 수 있습니다. 어떤 type이 선택되고 directory scope가 어디까지인지에 따라 agent가 받는 지침이 달라집니다.

.hermes.md는 가장 높은 우선순위의 Hermes 전용 project context type입니다.
AGENTS.md는 여러 coding agent에서 함께 쓸 수 있습니다.
시작할 때 project-context type 하나만 선택됩니다.
계층형 file은 넓은 repository rule부터 더 구체적인 subdirectory rule 순서로 적용됩니다.

1. File 계열 선택

Hermes에만 필요한 규칙이거나 parent에서 Git root까지 찾는 동작이 필요하면 .hermes.md를 씁니다. Hermes와 다른 coding agent에서 같은 지침을 공유하려면 AGENTS.md가 맞습니다.

작은 project file에는 일반적인 격려 대신 구체적인 build command, boundary, convention을 적습니다.

# Project rules

## Build
- Run `python3 -m unittest discover -s tests -v` before finishing.

## Boundaries
- Do not edit generated files by hand.
- Keep credentials outside the repository.

사용자 identity나 project를 가로지르는 preference는 project file에 두지 않습니다. 이런 정보에는 별도의 저장 위치가 있습니다.

2. Type 우선순위 이해

Hermes는 project-context type 하나를 선택합니다. 현재 우선순위는 .hermes.md 또는 HERMES.md에서 시작하고 AGENTS 계열, 호환 alternative가 뒤따릅니다. 높은 우선순위 type이 있으면 낮은 type은 시작 project context로 불러오지 않습니다.

기존 AGENTS.md 옆에 .hermes.md를 추가하는 작업은 merge가 아닙니다. Hermes 전용 계열이 이깁니다. 누적될 것처럼 보이지만 실제로는 그렇지 않은 두 file을 따로 관리하지 말고 shared rule은 한곳에 둡니다.

3. 계층형 scope 설계

AGENTS 계열 안에서는 Git root부터 intermediate directory를 거쳐 working directory까지 chain을 합칠 수 있습니다. 더 깊은 file이 나중에 놓이므로 특정 package에서 repository 공통 지침을 세분화할 수 있습니다. AGENTS.override.md는 개인용 per-directory override이며 보통 Git에서 제외합니다.

실용적인 분리는 다음처럼 생겼습니다.

AGENTS.md
packages/
  api/
    AGENTS.md

Root file에는 repository 전체 test와 security rule을 둡니다. Package file에는 API 전용 command나 exception만 적는 편이 좋습니다. Root file 전체를 반복하면 내용이 어긋나기 쉽습니다.

4. Context가 불리는 시점 확인

Startup context는 session이 시작될 때 조립됩니다. Context file을 바꿨다면 새 session을 시작해야 startup prompt에 반영됩니다. Tool이 subdirectory로 이동할 때 더 깊은 AGENTS 계열 file이 추가로 발견될 수도 있으므로, package 작업에 들어간 시점에 해당 rule이 관련성을 갖습니다.

--ignore-rules는 진단 boundary로만 사용합니다. 이 flag는 다른 rule과 customization input도 건너뜁니다. 따라서 이 상태에서 성공하면 injected context가 문제일 가능성은 보여 주지만 어느 file이 원인인지는 증명하지 않습니다.

hermes --ignore-rules

5. Model 호출 없이 우선순위 확인

독립 fixture는 두 case를 재현합니다. 첫 case에는 두 file 계열이 모두 있고 .hermes.md가 선택됩니다. 두 번째에는 root와 package의 AGENTS example이 있으며 root-to-leaf 순서를 출력합니다.

python3 examples/chapter-04-project-context/context_probe.py --root examples/chapter-04-project-context/fixtures/priority --cwd examples/chapter-04-project-context/fixtures/priority/service
python3 examples/chapter-04-project-context/context_probe.py --root examples/chapter-04-project-context/fixtures/agents-chain --cwd examples/chapter-04-project-context/fixtures/agents-chain/packages/api

{"context_type":"hermes","files":[".hermes.md"]}
{"context_type":"agents","files":["AGENTS.md","packages/api/AGENTS.md"]}

커밋된 sample은 이 repository에서 작업하는 agent에게 tutorial text를 주입하지 않도록 AGENTS.example.md라는 이름을 씁니다. 실제 project에서는 AGENTS.md로 만듭니다.

6. 작고 testable한 rule 유지

좋은 context는 정확한 command와 boundary를 말합니다. 한 test suite를 실행하고, 한 generated directory를 건드리지 않으며, 한 package manager를 쓰도록 적는 식입니다. 막연한 조언은 context를 차지하지만 결정을 돕지 못합니다. 아주 긴 file은 잘릴 수 있고 stale rule은 잘못된 action을 자신 있게 지시하므로 rule이 없는 것보다 나쁩니다.

Repository root에서 짧은 portable file로 시작합니다. Subtree에 정말 다른 지침이 필요할 때만 nested file을 추가합니다. 동작이 의도적으로 Hermes 전용이라면 .hermes.md를 선택합니다.

[Hermes Agent 실전 04] .hermes.md와 AGENTS.md로 프로젝트 규칙 전달하기