여러 사람이 한 레포를 함께 쓴다. 에이전트는 지금 누구의 지침으로 일하고 있을까?
답부터 적는다. 에이전트는 모른다. 공통 지침은 저절로 읽지만, 사람마다 나눠 둔 지침은 누가 골라 주지 않으면 읽지 않는다. 그래서 세 에이전트에 훅(hook, 이벤트마다 런타임이 부르는 스크립트)을 달았다. 훅은 세션마다 작업자를 묻게 하고, 답을 받기 전에는 도구를 막는다. 판정 스크립트는 하나다. 런타임마다 다른 것은 입력과 출력의 모양뿐인데, 사고는 전부 거기서 났다. 대상은 은행 개발 조직의 3인 팀이 함께 쓰는 레포다. 비공개 레포라 본문의 커밋 해시는 독자가 열어 볼 수 없다. 기록을 위해 남긴다. 수치는 2026-11-18 에 다시 셌다.
그림으로 줄이면 이렇다. 문은 셋이고 모양이 다르다. 자물쇠는 모두 같은 상자에 물려 있다. 들어가려는 에이전트는 먼저 누구의 일을 하는지 밝혀야 한다.
지침을 사람별로 나누면 ‘지금 누구냐’가 빈다
레포 루트에는 공통 지침 AGENTS.md 와 사람별 지침 AGENTS.<작업자>.md 세 개가 있다. 사람별 지침에는 작업 폴더·커밋 계정·담당 업무를 적는다. 세 에이전트(Claude Code, Codex, Antigravity)는 AGENTS.md 만 저절로 읽는다.
처음에는 공통 지침에 “세션을 시작하면 작업자가 누구인지 묻는다"고 적었다. 문서 규칙은 부탁이다. 지킬지는 에이전트가 정한다. 안내문도 같다. Antigravity(이하 agy)는 “개인 지침을 적용한다"는 안내만 받고 그 파일을 열지 않았다. 2026-11-04 실측이고 커밋 dc4cba9 에 남아 있다.
지금 작업자를 파일 하나로 표시하는 방법도 있다. 이 레포에는 AGENTS.current.md 라는 심볼릭 링크가 사람별 파일을 가리킨다. 그런데 이 링크가 git 에 추적된다. 2026-10-15 부터 2026-10-26 까지 커밋 7건이 이 링크를 만들거나 바꿨다. 커밋 저자 이름은 3종이었고, 가리키는 대상은 네 번 바뀌었다. pull 한 번에 내 체크아웃의 ‘현재 작업자’가 남으로 바뀔 수 있다.
그래서 작업자는 세션에 묶었다. 세션 ID 를 이름으로 쓰는 마커(표시 파일)에 작업자를 적는다. 마커 폴더는 git 에서 빼고, 7일 지난 마커는 지운다.
훅은 런타임마다 네 군데에 건다
훅은 세 런타임에 네 이벤트씩, 모두 12곳에 걸었다. 판정 스크립트는 <런타임> <이벤트> 두 인자를 받아 같은 판정을 한다.
| 하는 일 | Claude Code | Codex | agy |
|---|---|---|---|
| 세션 시작: 작업자를 물으라고 지시 | SessionStart | SessionStart | SessionStart |
| 입력마다: 아직 모르면 다시 지시 | UserPromptSubmit | UserPromptSubmit | PreInvocation |
| 도구 직전: 모르면 막는다 | PreToolUse | PreToolUse | PreToolUse |
| 도구 직후: 전환 명령이 성공하면 마커 기록 | PostToolUse (셸만) | PostToolUse | PostToolUse |
핵심은 도구 직전 판정이다. 작업자를 아직 모르면 질문 도구와 전환 명령 하나만 통과시킨다.
def on_pre_tool(ev):
user = read_marker(ev.session_id) # 세션마다 따로 둔 마커
if user:
return deny_if_other_owner(ev, user) # 정한 뒤에는 남의 지침 수정만 막는다
if ev.tool in QUESTION_TOOLS: # 사용자에게 묻는 도구
return allow(ev)
if ev.tool in SHELL_TOOLS and SWITCH.fullmatch(ev.command()):
return allow(ev) # 전환 명령 단독 실행만
return deny(ev, "작업자를 먼저 묻고 전환 명령을 실행한다")
전환 명령은 단독으로 실행할 때만 통과한다. 뒤에 && cat x 나 ; cat x 를 붙이면 막힌다(2026-11-18 복사본으로 확인). 전환 명령에 다른 명령을 얹어 게이트를 넘는 길을 막는 장치다.
런타임마다 입력과 출력의 모양이 다르다
세 런타임은 같은 일을 다른 말로 한다. 스크립트 앞단에서 입력을 한 모양으로 맞추고, 끝단에서 런타임의 말로 다시 내보낸다.
| 항목 | Claude Code · Codex | agy |
|---|---|---|
| 세션 ID | session_id | conversationId |
| 도구 이름·인자 | tool_name, tool_input | toolCall.name, toolCall.args |
| 컨텍스트 넣기 | hookSpecificOutput.additionalContext | injectSteps (시작은 systemMessage, 그 밖은 ephemeralMessage) |
| 거부 | permissionDecision: "deny" | {"decision": "deny"} |
| 통과 | 아무것도 출력하지 않는다 | {"decision": "allow"} |
훅 명령에는 절대 경로를 쓰지 않는다. PC 마다 레포 위치와 파이썬 경로가 다르다. Claude Code 는 $CLAUDE_PROJECT_DIR 로, Codex 와 agy 는 git rev-parse --show-toplevel 로 레포 루트를 찾는다. 파이썬은 작은 셸 실행기가 찾는다. 윈도우에서는 Git Bash 의 sh 가 PATH 에 있어야 한다.
agy 는 빈 JSON 을 거부로 읽었다
위 표의 마지막 줄이 가장 비쌌다. 처음에는 agy 의 통과도 {} 로 냈다. Claude Code 와 Codex 는 빈 출력을 통과로 읽으니 같은 뜻이라고 여겼다.
agy 1.5.0 은 PreToolUse 의 {} 를 거부로 읽었다. 사유가 빈 “tool call denied by pre-tool hook” 이 돌아왔다. 2026-11-04 샌드박스 실측에서는 작업자를 밝힌 뒤에도 통과 5회가 모두 거부됐다. 실행된 도구는 0회였다(dc4cba9). 고친 방법은 한 줄이다. PreToolUse 통과만 {"decision":"allow"} 로 내고, 나머지 이벤트는 {} 를 그대로 둔다.
그 전에 agy 훅은 19일 동안 꺼져 있었다. 2026-10-16 의 정리 커밋(e7ed1f8)이 agy 훅 설정 파일 이름을 .bak 으로 바꿨다. 그 커밋 메시지에는 이유가 없다. 고친 뒤 7분 만에 훅을 다시 켠 커밋(28153d4)이 이유를 짐작하게 한다. 작업자를 고른 뒤에도 agy 도구가 전부 막히던 문제가 이 수정으로 없어졌다고 적는다.
배운 것은 통과도 명시해야 한다는 점이다. 빈 출력의 뜻은 런타임이 정한다. 문서에 기본값이 없으면 직접 넣어 보고 확인한다. 이 해석이 agy 의 다른 버전에서도 같은지는 확인하지 못했다.
Codex 의 추가 컨텍스트는 호환 서버에서 대화 순서를 깼다
처음에는 전환 명령이 성공한 직후(PostToolUse)에 컨텍스트를 넣었다. “이제 이 사람의 지침을 따른다"는 내용이다. Claude Code 에서는 문제가 없었다.
Codex 에서는 오류가 났다. 코드 주석과 2026-10-18 의 작업 메모가 원인을 적어 두었다. Codex 는 PostToolUse 의 추가 컨텍스트를 developer 역할 메시지로 만들어 도구 결과 앞에 끼워 넣는다. OpenAI Chat Completions 형식을 따르는 호환 서버는 이 순서를 거부한다. assistant 의 tool_calls 바로 다음에는 tool 메시지가 와야 하기 때문이다. 그래서 PostToolUse 주입은 Claude Code 에만 남겼다(de07792). 오류 원문 로그는 레포에 없어서 이 설명은 기록으로만 확인했다.
Codex 와 agy 에는 다른 시점을 골랐다. 전환이 끝나면 ‘알릴 것’ 표시 파일을 남긴다. 다음 프롬프트 이벤트가 컨텍스트를 한 번 넣고 표시를 지운다(dc4cba9). 복사본에 넣어 보니 Codex 의 도구 직후 출력은 비어 있었다. 다음 프롬프트에서 컨텍스트가 한 번 나왔고, 그다음 프롬프트에서는 다시 비었다.
개인 지침은 본문째 싣고 16,000자에서 자른다
안내문만으로는 agy 가 파일을 열지 않았다. 그래서 작업자가 정해지면 넣는 컨텍스트에 사람별 파일의 본문을 그대로 붙인다. 16,000자를 넘으면 자르고, 잘린 자리에 “나머지는 파일을 직접 읽는다"는 줄을 단다.
2026-11-18 기준 사람별 파일 셋은 7,420자, 10,116자, 878자다. 모두 한도 안이다. 공통 AGENTS.md 는 20,065자이지만 런타임이 저절로 읽으므로 싣지 않는다. 한도를 16,000으로 정한 근거는 레포에 적혀 있지 않다.
해석은 이렇다. 한도를 넘으면 다시 부탁으로 돌아간다. 잘린 자리의 “직접 읽는다"는 줄은 agy 가 따르지 않았던 바로 그 종류의 안내다. 가장 긴 파일은 한도까지 5,884자 남았다. 그 파일이 16,000자를 넘는 날 이 판단은 틀린다. 사람별 지침은 짧게 두고, 긴 내용은 필요할 때 읽을 문서로 뺀다.
남의 지침 수정 차단은 경로 인자만 본다
작업자를 정한 뒤에는 다른 사람의 지침 파일 수정을 막는다. 첫 구현은 도구 인자 전체를 JSON 으로 펼쳐 AGENTS.<작업자>.md 모양을 찾았다. 그러자 메모 파일 본문에 다른 사람의 지침 파일 이름을 적기만 해도 그 메모 쓰기가 막혔다.
고친 판정은 파일 경로를 담는 인자만 본다. 런타임마다 이름이 달라 file_path, path, TargetFile, AbsolutePath 등 6개를 본다. Codex 의 패치 도구는 경로를 패치 머리줄(*** Update File: ...)에 적으므로 그 줄을 읽는다.
2026-11-18 에 두 판의 복사본에 같은 입력을 넣었다. 바꾸기 전 판은 dc4cba9 직전 것이고, 작업자는 A 로 정한 상태다.
| 입력 | 바꾸기 전 | 지금 |
|---|---|---|
AGENTS.<B>.md 에 쓰기 | 거부 | 거부 |
notes.md 에 쓰기, 본문에 AGENTS.<B>.md 이름 | 거부 | 통과 |
자기 파일 AGENTS.<A>.md 에 쓰기 | 통과 | 통과 |
Codex 패치로 AGENTS.<B>.md 수정 | 거부 | 거부 |
셸에서 echo x >> AGENTS.<B>.md | 통과 | 통과 |
마지막 줄이 이 장치의 한계다. 셸 명령은 처음부터 검사하지 않는다. 그러니 이 차단은 실수를 줄이는 안전띠이지 보안 경계가 아니다. 꼭 지켜야 하는 파일은 리뷰나 파일 권한 같은 다른 층에서 막는다.
Codex 는 PC 마다 신뢰 등록과 훅 승인이 있어야 돈다
Codex 는 프로젝트 훅을 바로 실행하지 않는다. PC 마다 이 레포를 신뢰 프로젝트로 등록하고, Codex 화면의 /hooks 에서 훅 4개를 승인해야 한다. 승인하기 전에는 훅이 돌지 않아 문서 규칙만 남는다.
그래서 확인 수준도 다르다. 2026-10-15 커밋 기록을 보면 Claude Code 와 agy 는 -p 실제 세션으로 확인했다. Codex 는 승인 전이라 훅이 돌지 않아 파이프 테스트만 했다.
새 PC 를 붙일 때 확인할 것은 셋이다.
- Codex 의 신뢰 등록과 훅 승인
sh와 파이썬 3.8 이상이 PATH 에 있는지- 에이전트에게 아무 도구나 시켰을 때 막히고 질문이 나오는지
이 판단이 틀리는 경우
- 혼자 쓰는 레포면 과하다. 세션마다 한 번 묻는 비용만 남는다.
- 셸로 고치는 길은 열려 있다. 악의를 막는 장치가 아니다.
- 런타임이 훅 형식을 바꾸면 다시 깨진다. agy 1.5.0 의
{}해석처럼 문서에 없는 동작은 버전마다 달라질 수 있다. - 사람별 지침이 16,000자를 넘으면 뒷부분은 다시 부탁이 된다.
정리
여러 사람이 레포를 함께 쓰면 에이전트는 작업자를 모른다. 문서로 부탁하지 말고, 세션마다 묻고 답 전에는 막는 훅으로 강제한다. 작업자는 git 이 추적하는 파일이 아니라 세션 마커에 둔다.
다음에 런타임을 하나 더 붙인다면 먼저 확인할 것이 하나다. 그 런타임은 훅의 빈 출력을 통과로 읽는가, 거부로 읽는가.