에이전트가 읽는 지침과 스킬 문서의 숫자가 실제와 어긋나면, 어떻게 찾고 어떻게 막을까?
답부터 적는다. 숫자를 문서에 베껴 적는 순간 어긋날 준비가 끝난다. 사람도 에이전트도 고칠 때는 눈앞의 한 곳만 고치기 때문이다. 막는 길은 둘이다. 숫자를 적지 않고 원본 파일을 가리키거나, 적었다면 원본에서 센 값과 대조하는 검사를 CI 에 건다. 검사기를 만들어 두기만 하면 막지 못한다. 아래 숫자는 2026-11-18 에 직접 셌다.
그림으로 줄이면 이렇다. 계산대 로봇 앞의 장부 세 권은 합계가 모두 다르다. 옆의 검수 로봇은 장부를 믿지 않고 선반의 물건을 직접 센다.
근거는 은행 개발 조직의 3인 팀이 2026-10-14 부터 쓴 업무 저장소다. 세 사람이 Claude Code·Codex·Antigravity 세 에이전트로 같은 저장소를 고친다. 저장소가 비공개라 본문의 커밋 해시는 독자가 열어 볼 수 없다. 찾아갈 표시로만 남긴다.
도구 개수가 네 곳에 세 가지로 적혀 있었다
이 저장소에는 폐쇄망 PC 에 미리 깔아 둔 에이전트용 도구 목록이 있다. 관제 화면은 카탈로그 JSON 을 읽어 도구 상태를 보여 준다. 같은 개수가 문서 세 곳에도 적혀 있다.
| 위치 | 적힌 개수 |
|---|---|
| 카탈로그 JSON 의 항목 수 | 22 |
AGENTS.md 도구 표의 제목과 행 수 | 20 |
AGENTS.md 의 다른 항(데이터 위치 설명) | 18 |
도구 스킬의 SKILL.md | 18 |
도구 스킬 문서는 카탈로그를 “18종 SSOT"라고 부른다. SSOT(단일 진실 원천)를 가리키면서 그 원본의 개수를 옆에 베껴 적었다. 원본이 22개로 늘어도 이 문장은 18에 머문다.
이력을 거슬러 올라가면 어긋난 과정이 보인다. 2026-10-18 커밋 58ecfad 에서는 네 곳이 모두 18이었다. 같은 날 다음 커밋 bd0282e 가 도구 하나를 더하면서 JSON 과 표만 19로 고쳤다. 나머지 두 곳은 그대로 남았다. 그 뒤 JSON 은 20, 21, 22 로 늘었고 표는 20에서 멈췄다.
어긋남은 한꺼번에 생기지 않았다. 고칠 때마다 한두 곳이 빠졌고, 빠진 곳이 쌓였다. 같은 파일 안에서도 런타임 하나의 버전이 환경 설명 줄과 도구 표에서 달랐다.
해석은 이렇다. 네 곳 가운데 맞는 값은 프로그램이 읽는 JSON 하나다. 사람과 에이전트만 읽는 글은 틀려도 아무것도 멈추지 않아서 먼저 낡았다.
엑셀 열 수는 같은 판 안에서도 달랐다
두 번째 사례는 기능정의서 엑셀이다. 열 구성은 스킬 문서와 AGENTS.md 가 함께 정한다. 실제 산출물과 나란히 놓으면 이렇다.
| 출처 | 열 수 | 데이터 행 수 |
|---|---|---|
| 기능정의서 스킬 문서 | 20 | 필터 범위로 보면 100 |
AGENTS.md 의 규칙 | 19 | 적지 않음 |
| 산출물 v0.1 엑셀 | 20 | 99 |
| 산출물 v0.1 CSV | 19 | 99 |
| 산출물 v0.2 엑셀과 CSV | 14 | 99 |
같은 v0.1 인데 엑셀은 20열, CSV 는 19열이다. 스킬에 열 하나를 더한 뒤 엑셀만 다시 만든 듯하다. 최신 판인 v0.2 는 열 구성 자체가 바뀌었는데 두 문서 어디에도 반영되지 않았다.
에이전트에게는 이 차이가 곧 다른 결과물이다. 지시대로라면 AGENTS.md 를 따른 에이전트는 19열을, 스킬을 따른 에이전트는 20열을 만든다. 최신 판의 14열은 어느 쪽도 만들지 않는다.
규칙과 반대로 짠 스크립트가 같은 저장소에 있었다
AGENTS.md 에는 “PC 마다 경로가 다르므로 훅 명령에 절대경로를 쓰지 않는다"는 규칙이 있다. 훅 실행기는 저장소 루트를 자기 위치에서 찾는다. 규칙의 이유도 맞고 지키는 코드도 있다.
그런데 공용 스킬 폴더의 Python 스크립트 10개는 한 PC 의 홈 경로를 박아 두었다. 설명 주석까지 25줄이다. 한 스킬 문서는 산출물을 특정 PC 의 바탕화면 경로로 복사하라고 정해 두기까지 했다. 다른 PC 에서 돌리면 이 스크립트들은 시작하자마자 경로를 찾지 못한다.
해석은 이렇다. 규칙은 훅에서 겪은 문제로 생겼고, 그 범위를 넘어 일반화되지 않았다. 에이전트는 새 스크립트를 쓸 때 규칙 문장보다 옆의 기존 스크립트를 더 따라 하는 듯하다. 이 말은 잰 값이 아니라 관찰이다.
지침 파일은 4주에 37번 바뀌었다
AGENTS.md 는 저장소 첫날인 2026-10-14 에 생겼다. 그 뒤 4주(10-14~11-10) 동안 머지를 빼고 37번 고쳐졌다. 더한 줄이 660, 지운 줄이 369 이고 지금 291줄이다. 같은 기간 저장소 전체 커밋이 420개이니 약 9% 가 지침을 건드렸다.
이만큼 자주 바뀌면 손으로 맞추기 어렵다. 한 번 고칠 때 같은 사실이 적힌 곳을 모두 떠올려야 한다. 세 사람과 세 에이전트가 번갈아 고치면 전체를 기억하는 쪽이 없다.
AGENTS.md 끝에는 학습 이력 표가 있다. 날짜, 실수, 원인, 수정을 한 줄씩 적어 규칙이 생긴 이유를 남긴다. 지금 네 줄이고 마지막 줄은 10-20 이다. 그 뒤 지침이 8번 더 바뀌었지만 표는 늘지 않았다. 이 글의 어긋남도 표에 없다.
숫자는 적지 말고 가리키거나, 적었다면 센다
막는 장치를 이 저장소와 내 공개 저장소(agents-scaffold)에서 모았다. 아래 표는 장치마다 막는 것과 도는 자리를 나란히 놓았다.
| 장치 | 무엇을 막나 | 언제 도나 |
|---|---|---|
| 원본 가리키기 | 숫자를 적지 않으니 낡을 숫자가 없다 | 쓸 때 |
문서 수치 검사 check-doc-numbers.py | README 의 스킬 수·스택 수·CLI 버전이 저장소에서 센 값과 다르면 실패 | CI |
AGENTS.yaml 검증기 | 없는 경로, 따옴표 없는 날짜·버전, 오타 난 최상위 키 | CI |
스킬 흐름 지도 flow.yaml 과 flow_map.py --check | 지도에 없는 SKILL.md 절·옵션·환경변수·파일 | CI 의 스킬 테스트 |
링크 검사 agents-link.sh --check | 세 에이전트 폴더의 스킬 링크 누락·불일치 | 사람이 돌릴 때만 |
| 학습 이력 표 | 규칙이 생긴 이유를 남긴다. 검사는 하지 않는다 | 사람이 적을 때만 |
문서 수치 검사는 첫 줄의 원칙이 핵심이다. “사실은 레포에서 뽑는다. 문서에 적힌 값을 기준으로 삼지 않는다.” 스킬 수는 SKILL.md 파일을 세고, 버전은 매니페스트에서 읽는다. 그다음 README 의 정해진 문구 옆 숫자와 맞춘다.
흐름 지도는 한 걸음 더 나간다. 스킬의 모든 절과 옵션이 어느 작업 단계에 연결돼야 통과한다. 지금 지도에는 단계 47개와 도구 7개가 있고 검사 결과는 0건이다. 스크립트에 옵션을 더하고 지도를 고치지 않으면 테스트가 깨진다.
같은 방식을 이 저장소에 붙이면 열 줄 남짓이다.
import json, re
want = len(json.load(open("catalog.json", encoding="utf-8"))["tools"])
pat = re.compile(r"(?:툴|도구)[^\d\n]{0,12}(\d+)\s*종|(\d+)\s*개\s*(?:툴|도구)")
for doc in ["AGENTS.md", "skills/tools/SKILL.md"]:
for no, line in enumerate(open(doc, encoding="utf-8"), 1):
for m in pat.finditer(line):
if int(m.group(1) or m.group(2)) != want:
print(f"{doc}:{no}: {m.group(0)!r} — 카탈로그는 {want}개")
경로만 바꿔 이 저장소에 돌리니 두 파일에서 네 줄이 걸렸다. 위 표의 20, 18, 18 이 모두 잡혔다.
검사기는 CI 에 걸려야 검사기다
이 저장소에도 검사기가 있다. 스킬 원본을 세 에이전트 폴더에 링크로 거는 스크립트에 --check 가 있다. AGENTS.md 는 스킬을 더하면 이것을 돌려 종료 코드 0 을 확인하라고 적어 두었다.
오늘 돌려 보니 문제 19건이 나왔다. 2026-10-21 오후 세 커밋으로 들어온 스킬 10개가 원인이다. Claude Code 폴더에는 하나도, Codex·Antigravity 공용 폴더에는 하나만 링크됐다. 링크가 없는 에이전트는 그 스킬을 자동으로 찾지 못한다. 규칙도 검사기도 있었지만 저장소에 CI 설정이 없어 커밋할 때 검사가 돌지 않는다.
같은 날 개인 폴더에는 이 스킬들의 사본도 생겼다. 윈도우 탐색기에서 보이게 하려고 링크를 실제 폴더로 바꿨다는 커밋이다. 지금 개인 폴더의 스킬 사본 12개 가운데 1개는 원본과 내용이 다르다. 사본을 만들면 어긋날 곳이 하나 더 생긴다.
내 공개 저장소의 문서 수치 검사기도 처음에는 CI 없이 들어왔다. 2026-11-10 커밋 메시지에 “CI 배선은 포함하지 않는다"고 적혀 있다. 4분 뒤 다음 커밋이 CI 에 걸었다. 검사기를 만드는 일과 거는 일은 따로 챙겨야 하는 두 단계다.
이 판단이 틀리는 경우
- 문구 검사는 문구를 바꾸면 빠져나간다. “도구 20종"을 “도구 스무 가지"로 쓰면 잡지 못한다. 문서 수치 검사기의 주석도 이 한계를 적어 두었다.
- 날짜가 붙은 숫자는 낡아도 틀린 것이 아니다. 이 저장소의 추천 목록에는 “2026-10-18 · 구비 16종"이라는 기준이 있다. 그날의 기록이라 검사에서 빼야 한다.
- 계획 수치와 목표값은 셀 원본이 없다. 이런 숫자는 한 파일에만 두고 다른 문서가 그 파일을 가리키게 할 수밖에 없다.
- 지침을 한 사람이 가끔 고치는 저장소라면 검사기를 만드는 값이 더 클 수 있다. 4주에 37번 고치는 저장소에서는 값을 한다.
정리
코드가 읽는 값은 틀리면 바로 드러나지만, 지침과 스킬 문서는 틀려도 아무것도 멈추지 않는다. 그래서 문서가 먼저 낡는다. 숫자는 적지 않고 원본을 가리킨다. 꼭 적어야 하면 원본에서 세어 맞추는 검사를 CI 에 건다.
지금 확인할 것은 하나다. grep -nE '[0-9]+ ?(종|개)' AGENTS.md 로 지침의 숫자를 뽑고, 숫자마다 어디서 세는지 답할 수 있는지 본다.