무엇인가
에이전트 런타임 다섯 개가 지침 파일 하나를 읽는다.
Claude Code·Codex·gjc·senpi·aside의 지침 경로 다섯 곳이
전부 같은 파일을 가리키는 심링크라서
어느 경로로 고쳐도 다섯 런타임에 한꺼번에 반영된다.
지침에 다 담기에는 긴 규칙은 그 동작 직전에 읽을 문서로 따로 두고
지침에는 "호출 직전 무조건 참고" 한 줄만 남겼다.
이 구조는 비공개 vault 리포의 agent-set 폴더에 있다.
다섯 런타임의 지침·훅·스킬·라우팅을 한곳에서 관리하는 설정 정본이고
설명 문서와 함께 런타임이 실제로 불러 쓰는 실행 파일이 들어 있다.
왜 만들었나
7월 하순 나는 gjc 세션에서 지침을 심링크로 걸라고 지시했다.
"이걸 심링크해서 매 세션, 재부팅해도 안사라지게 자동로딩되도록."
같은 날 저녁에는 Codex 쪽도 같은 방식으로 걸자고 했다.
10월 6일에는 이 구조를 만든 목적을 이렇게 되물었다.
"이제 claude.md를 모든 에이전트가 공통으로 쓸수있게끔 만든거야. 맞는가?"
그런데 다섯 경로가 가리키는 실물은 git 밖에 있었다.
vault 리포를 만든 다음 날 지침 실물을 리포 안으로 옮겼고
그 커밋 본문은 다섯 경로가 가리키던 정본이
버전관리도 백업도 없이 운영되고 있었다고 적는다.
이튿날 새벽에는 에이전트마다 설정을 정리한 허브 문서를 만들라고 지시했다.
"설정값 토폴로지와 뭐가수정되면 고쳐야하는지를 적어놔."
그 커밋 본문은 그때까지 "설정을 바꾸려는데 어디부터 봐야 하나"라는 질문에
답해 주는 진입점이 없었다고 적는다.
허브 문서는 이 문서를 읽어야 하는 상황을 여섯 가지로 든다.
모델·effort·라우팅 변경, MCP 서버 추가·수정·제거, 공통 지침 수정,
토큰 로테이션, 런타임 업데이트 뒤 점검, 새 머신 복원이다.
지침에는 에이전트 설정을 건드리기 전에 이 문서부터 읽으라는 줄이 들어갔다.
어떻게 동작하나
한 파일, 다섯 경로
다섯 경로는 중간 경유 없이 모두 vault 파일을 직접 가리킨다.
Claude Code의 지침 자리는 /init과 fablize 설치 스크립트가 쓰는 곳이라
가장 덮어쓰이기 쉽고 2단 구조에서는 그 한 곳이 단일 실패점이 된다.
fablize는 검증 절차를 얹어 주던 플러그인이다.
평면 구조에서는 이탈이 한 경로에 그치므로 규칙 불일치로 바로 드러난다.
하드링크는 git checkout과 stash가 경고 없이 링크를 끊고
두 파일이 다른 내용으로 갈라지는 현상을 실측한 뒤 배제했다.
지금 다섯 경로는 stat -L로 확인한 inode 번호가 같고,
그 파일은 14,223B, 106줄이다.
허브 문서와 점검 스크립트
허브 문서는 설정을 잇는 방식이 취향이 아니라 런타임이 허용하는 것으로 정해진다며
심링크, 실경로 직접 지정, 복사 동기를
이 순서로 시도하라고 적고,
스킬 디렉터리용 재적용 스크립트가 넷째 방식으로 나중에 더해졌다.
런타임마다 걸리는 데가 달랐다.
gjc는 --mcp-config에 심링크가 있으면 에러 없이 툴이 0개가 된다고 커밋 본문이 적는다.
같은 본문은 gjc의 config.yml을 심링크로 걸면 첫 설정 변경의 rename 원자 교체에 끊기는데,
읽기는 통과해 한동안 정상으로 보이므로 더 위험하다고 적는다.
senpi는 허브 문서의 설명에 따르면 로더는 심링크를 정상으로 읽지만
설정을 쓰는 writer는 심링크를 만나면 예외를 던진다.
aside는 설정 파일 심링크 자체는 문제가 없었으나,
링크 대상에 실토큰이 있어야 해서 vault에 둘 수 없었다.
커밋 본문은 이를 앱을 4번 재시작하며 갈랐다고 적는다.
복사 동기를 쓰면 사람이 손으로 동기화해야 하는 일이 생긴다.
그래서 점검 스크립트 하나가 심링크 10경로, 복사 동기 2개,
vault 시크릿 유출을 한 번에 검사하고 인자 하나로 런타임 설정을 vault로 복사한다.
그 커밋 본문은 확인 명령만 문서에 두는 방식을
"실제로는 지켜지지 않을 구조였다"고 적는다.
같은 새벽 나는 aside 예외를 지침에 한 줄 넣어야 하나 물으며
"지침은 최대한 간결하게."라고 덧붙였다.
결론은 넣지 않는 쪽이었다.
그 커밋이 남긴 이유는 세 가지다. 허브 문서를 읽으라는 지침 한 줄이 이미 덮고,
런타임별 예외를 지침으로 옮기면 허브 문서의 열화 사본이 되며,
저절로 생기는 어긋남은 문구로 못 잡는다.
같은 다섯 런타임에 훅을 붙인 과정은
훅 하나를 다섯 런타임에 붙이는 데 네 가지 방식이 들었다에 따로 적었다.
동작 게이트
9월 초 aside를 지침에 어떻게 넣을지 정하다가 나는 이 정도만 박자고 했다.
"aside 호출직전에 무조건 이문서를 참고할것"
7분 뒤에는 이를 일반 규칙으로 넓혔다.
어떤 동작을 할 때 필수로 읽어야 하는 레퍼런스가 생기면
해당 폴더에 저장하고 그 동작 때 읽게 하라는 것이다.
2분 뒤 커밋이 aside 플레이북을 저장해 지침의 브라우저 절에 배선했고,
지침의 SSoT 절에 이 규칙을 굵은 한 줄로 적었다.
2026-10-19 확인 기준 그 규칙 문장에는
"저장과 배선은 세트다 - 한쪽만 하면 미완"이라는 말이 들어 있다.
그 뒤 같은 규칙이 네 번 더 적용됐다.
| 호 | 걸리는 동작 | 읽는 문서 | 도입 |
|---|---|---|---|
| 1 | aside 호출 | aside 플레이북 | 2026-09-01 |
| 2 | GitHub 이슈 발행·본문 수정·댓글 | 이슈 규약 | 2026-09-30 |
| 3 | 외부 레퍼런스 탐색·추천·카드 추가 | 레퍼런스 카드 안내 | 2026-10-01 |
| 4 | 시장조사 시작 | 시장조사 플레이북 | 2026-10-01 |
| 5 | 시크릿 생성·조회·이동·교체 | 시크릿 규칙 | 2026-10-16 |
규약 본문을 지침에 상시로 싣는 안은 2호를 도입할 때 기각됐다.
기각 근거로 적힌 것은 이 한 줄이다.
"컨텍스트 파일은 성공률 개선 없이 비용만 늘린다(arXiv 2602.11988)"
4호는 3호가 카드를 만지는 순간에만 걸려
조사를 시작하는 순간을 잡지 못한다는 이유로 생겼다.
2026-10-19 확인 기준 내 역할은 카탈로그에 규칙과 결정이라고 적혀 있다.
agent-set 경로의 비머지 커밋 268건은 작성자 이름이 전부 내 계정이고,
그중 124건에 모델 공동 작성 줄이 있다.
줄이 없는 144건을 누가 썼는지는 확인하지 않았다.
221건이 Constraint·Rejected·Not-tested 줄로 결정 근거를 남겼다.
써 보니
1호와 2호 게이트 문서는 대체로 열렸다.
Claude Code 메인 세션 기록(서브에이전트 제외)에서
규약 도입 뒤 처음 이슈 명령을 낸 세션을 세면,
60개 중 53개가 그 명령 전에 이슈 규약을 열었다.
같은 방식으로 aside를 세면 첫 호출 전에 플레이북을 연 세션이 42개 중 40개다.
heredoc 본문을 뺀 명령에서 호출이 명령 머리나 구분자 뒤, 줄 머리에 오는 것만 세고
aside는 MCP 호출도 센 기준의 값이다.
이 리포의 커밋 메시지와 이슈에서 찾은 준수율 측정 기록은 2호 것 하나다.
이슈 댓글에 남은 파일럿 결과를 보면, 도입 뒤 새 이슈 34건에서
제목 유형·완료 기준·제약·범위 밖 4개 지표가 모두 100%였고
도입 전 기준선은 0/47/7/2%였다.
같은 댓글에는 편향도 적혀 있었다.
34건 중 30건이 Hindsight-Crew 이슈였고 도입 뒤 2일치라 초기 효과일 수 있다.
실패와 고친 것
첫 실패는 같은 날 뒤집힌 판정이다.
7월 28일 자정 무렵 두 커밋이 senpi 설정 파일의 위치를 단정했는데,
세 시간이 안 돼 나온 커밋이 현행 런타임에서는 반대라고 적었다.
그 커밋 본문은 오진의 원인을 이렇게 든다.
근거로 삼은 파일이 체크아웃 소스였는데
senpi 업데이트는 플러그인 번들만 바꿔서 소스가 갱신되지 않았다.
같은 본문은 그 사이 재시작에서 reviewer not found 에러와 전 카테고리 빌트인 폴백이 난 것이
이 오진의 결과였다고 적는다.
10월 6일에는 지침이 두 번 실리고 있다는 에이전트 보고가 나왔다.
Claude Code 변경 기록에서
2.1.277은 CLAUDE.md가 없는 프로젝트에서 AGENTS.md를 대신 읽는 기능을 더했다.
다섯 경로 중 하나가 홈 디렉터리의 AGENTS.md인데, 홈에는 CLAUDE.md가 없다.
에이전트는 세션 299개를 버전별로 세어 2.1.282 이후는 전부 두 번 실렸다고 보고했다.
또 중첩 claude -p로 8가지 경우를 돌려,
AGENTS.md만 읽게 바꾸면 자체 CLAUDE.md가 있는 리포와 홈 바깥 작업 폴더에서
공용 지침이 실리지 않는다고 보고했다.
나는 이렇게 되물었다.
"그럼 클로드코드가 agent.md를 참조하는 옵션만 끄자는건가?"
"ㄱ" 한 글자로 승인하자 에이전트는
claudeMdExcludes로 홈의 AGENTS.md 한 파일만 제외해 적용했다고 보고했다.
웹 읽기 규칙은 바꾼 지 45분 만에 다시 고쳤다.
요약 도구의 결과에 조직 계정의 지침이 섞여 들어오는 것을 확인했다며
기본 레인을 curl 원문으로 바꿨다.
다시 고친 커밋의 본문은
curl -sL이 403·429·봇 확인 페이지에도 exit 0을 돌려줘
막히는 즉시 갈아타는 1스트라이크 승격이 작동하지 않고
차단 페이지가 원문으로 인용될 수 있었다고 적고,
이를 code-review 지적이라고 밝힌다.
같은 커밋은 -sL에서 403이 exit 0, -fsSL에서 exit 56인 것을 실측으로 적는다.
fablize를 지우면서 공용 원칙을 알리는 문장까지 같이 지웠다.
10월 6일 새 모델 가이드에 맞춰 시스템을 줄였다는 남의 글을 보고 점검한 끝에
"페이블라이즈는 이제 지우자."라고 정했고,
1분쯤 뒤 커밋이 지침에서 해당 블록을 제거했다.
4분 뒤 나는 제거 결과를 Opus 5.5와 gpt-6.1-sol에게 교차 검토시켰다.
되돌린 커밋의 본문은 리뷰가 두 가지를 찾았다고 적는다.
Codex 예외 줄이 말이 안 되는 문장이 되었고
결과부터 보고·파괴적 작업 전 확인·근거 있는 완료라는 원칙을
같은 기본값이 없는 런타임에 알리는 공용 문장이 없어졌다.
제거 28분 뒤 커밋이 원칙 셋을 한 줄로 되돌렸고 검증 절차 전체를 복원하는 안은 기각했다.
나머지는 한 줄씩 정리해 둔다.
| 시점 | 무엇이 어긋났나 | 처리 |
|---|---|---|
| 2호 도입 | 이슈 규약이 문서 지도에 등재되지 않았다 | 이틀 뒤 다른 작업 커밋에 함께 등재 |
| 5호 도입 | 시크릿 규칙 문서가 카드 형식이 아니라 레퍼런스 카드 검증이 실패로 바뀌었다 | 2026-10-19 확인 기준 아직 실패 |
지금 상태
2026-10-19 확인 기준 agent-set은 운영 중이고, 쓰는 사람은 나 하나다.
리포는 비공개이고 다섯 심링크 경로도 전부 내 맥 홈 디렉터리 아래에 있다.
10월 19일 새벽 점검 스크립트는 종료 코드 1로 끝났다.
지침 심링크 5경로와 시크릿 유출 검사를 포함한 OK가 29줄이었고,
DRIFT 3건은 aside 설정 복사 동기, senpi 로컬 패치 미적용, SDK 슬롯 드리프트다.
2026-10-19 확인 기준으로 정리되지 않은 것이 있다.
5호가 깨뜨린 카드 검증은 아직 실패한다.
허브 문서 첫머리의 기준일은 7월 27일에 멈춘 채 본문만 10월까지 자랐다.
파일럿 결과를 적은 이슈 댓글은 재검토 트리거로
11월 2일 전후 같은 명령으로 재측정해
한 지표라도 90% 미만이면 경고 전용 훅 티켓을 발행한다고 적는다.
2026-10-19 확인 기준으로 허브 문서는 정본 밖에 있는 일곱 항목을
"의도적으로 뺀 게 아니라 아직 안 한 것"으로 적는다.
그중 하나가 Claude Code 설정 파일이다.
지침이 두 번 실린다는 보고에 따라 넣은 claudeMdExcludes 한 줄이 바로 그 파일에 있다.