Jack.dev.blog

AI 에이전트에게 규칙을 읽히는 법

리뷰 봇이 막힌 PR 을 대신 리뷰하는 스킬과, AI 코딩 에이전트가 매 세션 읽는 규칙 문서를 예산 안에 두는 구조를 만들어 온 기록이에요.

AIClaude Code코드 리뷰

들어가며: 규칙 파일이 16바이트를 남기고 꽉 찼다

저는 Flutter 로 웰니스 앱을 만들고, 앱이 쓰는 서버(Django·FastAPI)도 함께 맡고 있어요. 코드 대부분은 Claude Code 같은 AI 코딩 에이전트와 함께 써요.

앞 글은 이렇게 끝났어요. 속도가 남긴 진짜 비용은 기준의 부재였고, 그래서 정한 기준을 에이전트가 작업할 때마다 읽는 규칙 파일에 한 줄로 넣었다. 이 글은 그 “한 줄”이 들어가는 파일 이야기예요.

그 파일에는 예산이 있어요. 에이전트가 세션을 시작할 때마다 통째로 읽는 문서 묶음은 합계 12,288 B(12 KiB)를 넘기지 않기로 정해 두었어요. 10월의 어느 날, 이 묶음이 12,272 B 가 됐어요. 남은 여유는 16바이트였어요. 한글 한 글자가 UTF-8 로 3바이트이니, 규칙 한 줄은커녕 다섯 글자 남짓이에요.

이 파일은 처음엔 2KB 도 안 됐어요. 열한 달 동안 이렇게 변했어요.

2025년 12월 2026년 11월
세션마다 읽히는 규칙 문서 파일 1개, 1,934 B 파일 3개, 10,788 B
번호 붙은 규칙 9줄 40줄
규칙 문서를 고친 사람 1명 저를 포함해 4명
설계 결정 기록(ADR) 0개 38개
직접 만든 에이전트·명령·스킬 0개 약 24개

규모가 커지자 세 가지 문제가 생겼어요.

  • 같은 규칙이 여러 곳에 복사되고, 복사본이 어긋났어요. 다른 AI 도구용 파일에는 몇 달 전 규칙이 남아 있었어요.
  • 매 세션 읽히는 문서가 계속 불어났어요. 규칙을 지우는 사람은 없고 더하는 사람만 있었어요.
  • 리뷰 봇이 막힌 PR 은 리뷰 없이 머지됐어요. 리뷰 봇의 시간당 한도에 걸린 PR 이 그대로 넘어갔어요.

이 글에서는 그 문제들을 풀려고 만든 장치 네 가지를 차례로 소개할게요.

  1. 규칙은 한 곳에만 — 복사본이 어긋나는 문제를 막아요.
  2. 「규칙 한 줄 + 상세는 다른 곳」 — 매 세션 읽히는 문서를 예산 안에 둬요.
  3. 하네스 감사 — 문서가 코드와 어긋난 곳을 정기적으로 찾아요.
  4. PR 리뷰 스킬 — 같은 규칙을 리뷰어 에이전트에게도 읽혀서, 리뷰 봇이 막힌 PR 을 대신 리뷰해요.

AI 에이전트용 규칙 파일(CLAUDE.md, AGENTS.md 등)을 쓰고 있는데 파일이 점점 길어지는 분, 팀원 여럿이 같은 규칙 파일을 고치는 분께 도움이 될 거예요.

배경: 에이전트는 무엇을, 언제 읽나

장치를 이야기하기 전에, Claude Code 가 문서를 읽는 시점부터 짚고 갈게요.

Claude Code 는 세션을 시작할 때 저장소 루트의 CLAUDE.md 를 읽어요. CLAUDE.md 안에 @rules.md 처럼 다른 파일을 적으면 그 파일도 함께 읽어요(import). 반면 하위 디렉토리의 CLAUDE.md 는 에이전트가 그 디렉토리의 파일을 다룰 때 불러와요. 세션 시작 비용에 들어가지 않아요. 그리고 docs/ 아래 문서는 누가 경로를 가리켜야 읽혀요.

이 글에서는 이걸 세 층으로 부를게요.

층 언제 읽히나 저희 저장소에서
상시 층 매 세션 시작 루트 CLAUDE.md + rules.md + docs/architecture.md
지연 층 그 디렉토리를 작업할 때 모듈별 CLAUDE.md(6개 모듈), docs/rules/*.md
기록 층 누군가 가리킬 때만 docs/adr/, 인수인계 문서

여기서 볼 건 상시 층만 비용이 매번 든다는 점이에요. 상시 층의 1바이트는 모든 세션, 모든 서브에이전트에 실려요. 지연 층은 그 모듈을 건드릴 때만, 기록 층은 필요할 때만 읽혀요. 아래 장치들은 결국 “이 지식을 어느 층에 둘까” 를 정하는 규칙이에요.

1. 복사본은 반드시 어긋난다: 규칙은 한 곳에만

왜 문제였나

처음 규칙 파일은 CLAUDE.md 하나였어요. 그런데 Codex 나 Gemini 같은 다른 도구는 CLAUDE.md 를 읽지 않아요. 그래서 같은 내용을 AGENTS.md, GEMINI.md 로 복사해 두었어요.

복사본은 금방 어긋났어요. 6월에 앱 저장소를 정리하면서 보니, AGENTS.md 는 1월 2일 이후 한 번도 고쳐지지 않은 2,223 B 였어요. 그사이 CLAUDE.md 는 4,567 B 로 두 배가 됐고요. AGENTS.md 를 읽는 도구는 반년 전 규칙으로 코드를 쓰고 있었던 거예요.

서버 저장소는 더 위험했어요. 8월에 서버 쪽 규칙 문서 21개를 감사했을 때, AGENTS.md·GEMINI.md 가 옛 CLAUDE.md 와 바이트 단위로 같은 복사본이었어요. 그사이 CLAUDE.md 에 들어간 최우선 안전 조항 4개가 복사본에는 통째로 없었어요. “main·develop 에 자동 머지 금지” 같은 조항이요. 다른 에이전트를 쓰면 머지 안전장치가 없는 규칙을 받는 상태였어요.

무엇을 만들었나

복사본을 정본을 가리키는 짧은 안내문으로 바꿨어요. 지금 앱 저장소의 AGENTS.md 는 이게 거의 전부예요.

# Project 규칙 (Codex 등 타 도구용 진입점)

규칙 정본은 도구 공통으로 아래 파일에 있다. 코드 생성 전 반드시 읽을 것
— 이 파일에 규칙을 복제하지 말 것(drift 방지):

- `CLAUDE.md` — tech stack, 기본 원칙
- `rules.md` — 코드 컨벤션·파일 배치·git 규칙 전체
- `docs/architecture.md` — 모듈 구조·데이터 흐름·심화 문서 인덱스

여기서 볼 건 “복제하지 말 것”을 파일 안에 적었다는 점이에요. 다음에 이 파일을 여는 사람이나 에이전트가 “규칙이 비어 있네” 하고 다시 채워 넣지 않게요. 서버 저장소에서는 안내문에 안전 조항 요약만 남겼어요. 다른 도구가 정본을 안 읽고 지나쳐도 최소한 머지 금지는 보이게요.

그리고 같은 원칙을 지식 전체로 넓혔어요. 새 지식은 정확히 한 곳에만 둔다. 어디에 둘지는 종류로 정해요.

지식의 종류 위치
설계 결정 docs/adr/
팀 컨벤션 rules.md
모듈 구조·데이터 흐름 docs/architecture.md
모듈별 함정·교훈 해당 모듈 CLAUDE.md (한 줄로 증류)
인수인계 docs/handoffs/

여기에 승급 조건을 하나 붙였어요. 상시 층이나 지연 층으로 올리는 건 같은 문제가 두 번 이상 재발했고, 팀 전체에 적용될 때만. 한 번 겪은 함정을 바로 규칙으로 만들면 규칙 파일이 사고 기록부가 되거든요.

개인 규칙도 같은 원칙으로 뺐다

같은 문제가 제 개인 설정에도 있었어요. “git stash 를 피한다”, “보고는 결론 먼저” 같은 제 작업 습관이 앱 저장소의 에이전트 메모리에 쌓여 있었어요. 서버 저장소에서 일할 때는 그 습관이 안 따라왔고요.

그래서 11월에 개인 규칙을 별도 저장소로 뺐어요. 매 세션 읽히는 개인 규칙 4개 파일(합계 5,125 B)과 개인 스킬 몇 개를 담고, 사용자 전역 설정(~/.claude/CLAUDE.md)에서 import 해요. 유지 규칙은 네 줄이에요.

  1. 두 번째 프로젝트에서 필요해질 때 옮긴다.
  2. 옮길 때 회사·프로젝트 흔적을 지우고, 무엇을 뺐는지 기록한다.
  3. 옮긴 항목은 원래 위치의 사본을 지워 한 곳에만 둔다.
  4. 매 세션 읽히는 규칙 파일은 짧게 유지한다.

이렇게 나누니 층이 하나 더 생겼어요. 팀 규칙은 저장소에, 제 습관은 개인 저장소에, 이 프로젝트의 사실(어떤 버그가 어디서 났는지)은 에이전트 메모리에 둬요.

2. 매 세션 읽히는 문서에는 예산이 있다: 「규칙 한 줄 + 상세는 다른 곳」

왜 문제였나

복사본을 정리하던 6월에, 하나뿐이던 CLAUDE.md(4,567 B)를 세 파일로 나눴어요. CLAUDE.md 는 647 B 로 줄이고, 컨벤션은 rules.md, 구조는 docs/architecture.md 로 보냈어요. 모듈마다 지연 층 CLAUDE.md 도 만들었어요.

이때 상시 층 예산을 12KB 로 정했어요. [확인 필요: 12KB 를 고른 근거] 그런데 예산을 정한 뒤에도 상시 층은 계속 자랐어요.

시점 상시 층 합계(wc -c) 무슨 일
2026-06 9,307 B 세 파일로 분리
2026-08 초 13,256 B 예산 초과
2026-08 12,259 B 첫 하네스 감사로 정비
2026-09 말 12,856 B 다시 예산 초과
2026-10 초 12,024 B 팀원이 규칙 정리
2026-10-21 12,272 B 여유 16바이트
2026-10-21 8,461 B 「한 줄 + 상세」 구조로 정리
2026-11-17 10,788 B 현재

여기서 볼 건 두 가지예요. 나눈 직후에도 합계는 줄지 않고 오히려 늘었어요. 나눈 건 구조였지 양이 아니었어요. 그리고 8월에 예산 안으로 돌아온 뒤에도 9월 말에 다시 넘었고, 10월에 또 끝까지 찼어요. 규칙을 더하는 커밋은 꾸준했고, 빼는 커밋은 넘친 뒤에야 나왔어요.

왜 이렇게 불어났을까요? 당시 rules.md 의 한 규칙은 이랬어요.

15. BlocProvider 는 Page 내부가 아닌 `{feature}_page_route.dart` 의 route builder 에서
    `create: (_) => XBloc(...)..add(InitEvent(...))` 로 주입한다. Page 는 `context.read<XBloc>()` 접근만.

규칙 하나가 무엇을 하라와 어떻게 하라를 함께 담고 있었어요. 다른 규칙에는 “왜 그런지”와 “예외는 무엇인지”까지 붙어 있었어요. 쓰는 사람에게는 친절한 문장이지만, 매 세션 모든 에이전트가 이 예시 코드까지 읽어요. 이 규칙과 상관없는 작업에서도요.

무엇을 만들었나

16바이트가 남은 그날, 팀원이 rules.md 를 다시 썼어요. [확인 필요: 정리를 시작한 계기가 예산이었는지] 원칙은 하나였어요. 상시 층에는 규칙 한 줄과 상세 경로만, 상세는 지연 층으로.

각 규칙은 한 줄 요약이다. 해당 작업을 하기 전에 섹션·줄 끝의 상세 문서를 읽는다.

## Code conventions — 상세 `docs/rules/code-conventions.md`

15. BlocProvider 는 `{feature}_page_route.dart` route builder 에서 주입, Page 는 `context.read` 만

같은 규칙이 “무엇을”만 남기고 한 줄이 됐어요. 예시와 이유는 docs/rules/code-conventions.md 로 갔고요. 섹션 제목에 상세 경로를 적어 두어서, 에이전트는 그 작업을 할 때만 상세를 열어요.

결과는 이랬어요. rules.md 가 8,006 B 에서 4,195 B 로 절반이 됐는데, 번호 붙은 규칙은 31줄에서 32줄로 오히려 하나 늘었어요. 정보를 버린 게 아니라 층을 옮긴 거예요.

헷갈리기 쉬운 것: 번호는 왜 고정하나요?

rules.md 에는 1, 2, 4, 5, 7… 처럼 빠진 번호가 있어요. 결번은 린트(analysis_options.yaml)로 옮긴 규칙이에요. 기계가 검사할 수 있는 규칙은 문서에 둘 이유가 없거든요. 번호를 다시 매기지 않는 건 계획서, 코드 주석, 리뷰 코멘트가 “§15” 처럼 번호로 규칙을 가리키기 때문이에요. 번호를 당기면 그 참조가 전부 엉뚱한 규칙을 가리켜요.

사례: 앞 글의 규칙은 세 층에 나눠 들어갔다

앞 글에서 정한 “BLoC 이벤트 겹침” 기준이 이 구조로 들어간 모습이에요. 하나의 결정이 층마다 다른 길이로 들어가요.

층 무엇을 담나 길이
상시 층 rules.md §42 하라·하지 마라 한 줄 + 상세 경로 1줄
지연 층 presenter/CLAUDE.md 어떤 이벤트에 어떤 transformer, emit.isDone 함정, 테스트 방법 1문단
기록 층 ADR 왜 이렇게 정했나, 버린 대안, 남긴 곳 문서 1개

상시 층의 한 줄은 이래요.

42. **BLoC 이벤트 겹침은 `bloc_concurrency` transformer 로 선언** — 플래그·세대 번호·`asyncExpand`
    손구현 금지, 기존은 수정 시 이관. 상세 `presenter/CLAUDE.md`·ADR 0034

여기서 볼 건 상시 층이 “이 규칙이 있다”는 사실과 상세 위치만 알린다는 점이에요. 화면(app) 코드만 고치는 세션은 presenter 의 함정을 읽지 않아요. BLoC 을 고치는 세션은 presenter 디렉토리 파일을 여는 순간 지연 층을 읽어요.

ADR: 주석 대신 결정을 남기는 곳

“왜 이렇게 했나”는 길어지기 쉬워요. 처음에는 이걸 코드 주석에 남겼어요. 그런데 주석이 길어지면 에이전트는 코드를 읽을 때마다 그 설명까지 읽고, 결정이 바뀌어도 주석은 그대로 남아요.

그래서 규칙을 이렇게 정했어요. 코드 주석은 코드만으로 드러나지 않는 WHY·제약만, 비자명한 설계 결정은 docs/adr/ 에. ADR 은 결정·이유·버린 대안을 각각 한 문단으로 써요. 남길지는 에이전트가 정하지 않고 사람에게 확인받고 써요. 6월에 첫 ADR 을 쓴 뒤 지금 38개가 쌓였어요.

장점과 한계

이 구조의 장점은 상시 층이 규칙 수에 비례해 자라지 않는다는 거예요. 규칙이 하나 늘 때 상시 층은 한 줄만 늘어요.

한계도 분명해요. 에이전트가 상세를 안 열면 한 줄만 보고 일해요. “상세 docs/rules/…” 라고 적어도, 그 문서를 열지는 에이전트가 판단해요. 그래서 한 줄 자체가 무엇을 하면 안 되는지는 담도록 써요. “§17 커스텀 백 처리 화면은 ShellRoute 하위 금지”처럼, 상세를 안 읽어도 금지사항은 지켜지게요.

그리고 비용이 사라지지 않고 옮겨 갈 뿐이에요. 이 글을 쓰면서 재 보니 지연 층의 화면 모듈 CLAUDE.md 가 10,606 B 였어요. 상시 층 예산과 거의 같은 크기예요. 화면 코드를 고치는 세션은 이걸 매번 읽어요.

3. 문서도 코드처럼 낡는다: 하네스 감사

왜 문제였나

예산을 정하는 것과 지키는 건 달랐어요. 규칙 문서는 테스트가 없어요. 틀린 내용이 들어가도 아무것도 실패하지 않아요. 에이전트가 그 틀린 내용대로 코드를 쓸 뿐이에요.

그래서 6월에 상시 층을 나눌 때, 문서 체계 전체를 점검하는 명령(/harness-audit)도 함께 만들었어요. 이 글에서 하네스는 에이전트가 읽는 문서·명령·스킬·훅 전체를 가리켜요.

무엇을 만들었나

감사 명령은 분석만 하고 아무것도 고치지 않아요. 정비안을 보고하면, 적용은 사람이 승인한 뒤 따로 해요. 점검하는 건 일곱 가지예요.

점검 무엇을 보나
런타임 로드 맵 @ import 를 따라가 상시 층 파일 크기를 실측, 예산 판정
import 정합성 가리키는 파일이 실재하는지, 순환이 없는지
orphan / missing 아무도 안 가리키는 문서, 가리키는데 없는 문서
drift 문서의 구조 설명이 실제 디렉토리와 맞는지, 복사본이 다시 생기지 않았는지
중복 개인 설정과 저장소 설정에 같은 이름의 명령·에이전트가 있는지
메모리 승급·가지치기 두 번 재발한 교훈은 규칙으로, 해결된 메모는 삭제 후보로
설정·MCP 설정 파일 JSON 유효성, 훅 등록, 연결 실패 서버

명령 안에 원칙도 하나 적어 두었어요. 해결된 항목과 낡은 규칙은 감사 때 지운다(append-only 금지). 더하기만 하는 문서는 결국 예산을 넘으니까요.

사례: 첫 감사에서 나온 것들

8월에 상시 층이 13,256 B 로 예산을 넘었을 때 첫 정비를 했어요. 감사가 찾은 문제는 이랬어요.

심각도 문제
높음 CLAUDE.md 의 Flutter·Dart 버전 표기가 실제 버전 고정 파일과 다름
높음 상시 층 어디에도 실행 명령이 없음 — 빌드·테스트 명령이 설정 파일에만 있음
중간 예산 초과. 한 규칙이 다른 규칙의 배치 표와 거의 완전히 중복
중간 한 규칙의 “배경: ADR” 참조가 무관한 ADR 을 가리킴
중간 규칙 번호가 문서 순서와 불일치, 밀린 번호를 가리키던 참조 4곳 미갱신

여기서 볼 건 에이전트가 이 문서를 믿고 일한다는 점이에요. 버전 표기가 틀리면 에이전트는 없는 API 를 쓰거나 있는 API 를 피해요. 실행 명령이 없으면 매번 설정 파일을 뒤져 명령을 추측해요. 엉뚱한 ADR 을 가리키면 배경을 찾으러 가서 다른 이야기를 읽고 와요.

이 정비에서 예산 표기도 고쳤어요. 원래는 “토큰 예산 12KB” 였어요. 그런데 12KB 가 12,000 인지 12,288 인지, 토큰인지 바이트인지 모호했어요. 그래서 ”wc -c 합계 12,288 B, 토큰 아닌 바이트” 로 못 박았어요. 토큰 수는 모델마다 세는 법이 달라 감사 때마다 재기 어렵지만, 바이트는 명령 하나로 누구나 같은 값을 얻어요.

무엇이 달라졌나

감사는 문서가 틀렸는데 아무것도 실패하지 않던 상태를, 표 한 장으로 드러나는 상태로 바꿨어요. 예산을 “토큰 12KB”에서 ”wc -c 12,288 B”로 바꾼 덕에, 이제는 누구든 명령 하나로 넘었는지 알 수 있어요.

다만 솔직히 말하면, 감사를 “월 1회” 돌리기로 했지만 감사 결과로 정비 PR 까지 간 건 8월 한 번이에요. [확인 필요: 8월 이후 감사를 실행한 횟수] 앞의 표에서 보듯 9월 말에 예산을 다시 넘었을 때도, 10월에 16바이트까지 찼을 때도 줄인 건 감사가 아니라 팀원의 정리 커밋이었어요. 감사는 돌려야 일하는 도구라서, 돌리는 사람이 바쁘면 멈춰요.

그다음 병목은 문서가 아니라 리뷰에서 나왔어요. 규칙을 아무리 다듬어도, 그 규칙대로 썼는지 확인할 사람이 없는 PR 이 생기고 있었거든요.

4. 같은 규칙을 리뷰어에게도 읽혔다: PR 리뷰 스킬

왜 문제였나

저희 저장소는 AI 리뷰 봇(CodeRabbit)을 써요. PR 을 올리면 요약과 인라인 지적을 달아 줘요. 앞 글에서 Claude 가 만든 회귀 세 건을 잡은 것도 이 봇이었어요.

문제는 시간당 리뷰 횟수 상한이었어요. 당시 쓰던 요금제에서는 “5 reviews per hour” 가 관측됐어요(2026년 9월 기준). 팀원 여럿이 PR 을 연달아 올리면 일부 PR 은 Review rate limited 로 남았어요. 그리고 리뷰 없이 머지됐어요. 서버 저장소에서는 최근 머지된 PR 15개 모두 리뷰 봇의 인라인 지적이 0건이었어요.

리뷰 봇 요금제를 올리는 방법도 있었어요. [확인 필요: 요금제 상향을 검토했는지, 안 한 이유] 저는 대신 봇이 막힌 PR 을 같은 형식으로 대신 리뷰하는 스킬(/pr-review)을 만들었어요. 목표는 봇을 끄는 게 아니었어요. 받는 사람이 봇 리뷰와 같은 방식으로 읽을 수 있으면 됐어요.

무엇을 만들었나

스킬은 다섯 단계로 돌아요.

  1. 수집: 스크립트가 PR diff 와 메타데이터를 모아요. 공유 체크아웃의 브랜치를 바꾸지 않고, PR 커밋만 받아 git show·git grep 으로 읽어요. 제외 경로는 봇 설정 파일(.coderabbit.yaml)을 그대로 따라요.
  2. 리뷰: 작은 PR(3파일·150줄 이하)은 리뷰어 에이전트 1개가 전부 봐요. 그보다 크면 정확성·안정성·아키텍처 관점별 리뷰어 3개를 병렬로 돌려요.
  3. 검증: 메인 세션이 지적마다 근거 위치의 코드를 직접 읽어, 본문이 말하는 동작이 실제 코드와 맞는지 확인해요. 맞지 않거나 확인할 수 없으면 버려요.
  4. 미리보기: 게시될 리뷰를 먼저 보여 줘요.
  5. 게시: 사람이 “올려”라고 답할 때만 PR 에 달아요.

이 글의 주제와 이어지는 건 2단계예요. 아키텍처 리뷰어의 기준은 PR head 의 rules.md + 상세 docs/rules/ + 변경된 모듈의 CLAUDE.md 예요. 코드를 쓰는 에이전트가 읽는 바로 그 문서를 리뷰어도 읽어요. 지적할 때는 ”rules.md §15 위반”처럼 규칙 번호를 인용해요. 번호를 고정한 이유가 여기서 하나 더 생겼어요.

리뷰어는 읽기 전용이어야 해요. 그래서 리뷰어 에이전트에 Bash 명령을 검사하는 훅을 달았어요. 허용 목록에 있는 명령만 통과시켜요.

# awk is absent on purpose: its program can run commands or write files through variables, which no pattern catches.
ALLOWED = {'cd', 'git', 'grep', 'rg', 'head', 'tail', 'wc', 'cat', 'sed', 'sort', 'uniq', 'nl', 'ls',
           'echo', 'printf'}
GIT_SUBCOMMANDS = {'show', 'grep', 'diff', 'log', 'cat-file', 'ls-tree', 'rev-parse', 'blame', 'merge-base'}

여기서 볼 건 금지 목록이 아니라 허용 목록이라는 점이에요. awk 는 일부러 뺐어요. 프로그램 안에서 명령을 실행하거나 파일을 쓸 수 있는데, 그걸 패턴으로 다 잡을 수 없어서요.

헛걸음: 정답을 알려 준 채로 시험을 봤다

만들고 나서 성능을 쟀어요. 방법은 리뷰 봇이 이미 리뷰한 과거 PR 을 다시 리뷰시켜, 봇의 지적과 비교하는 거예요.

첫 시험 대상은 봇이 Major 2건을 지적한 PR 이었어요. 결과는 애매했어요. 한 건은 찾았는데 Minor 로 매겼고, 다른 한 건은 놓쳤어요. 원인을 찾으려고 리뷰어가 읽는 문서를 다시 보다가 더 큰 문제를 발견했어요.

출력 형식 문서의 예시가 바로 그 PR 의 정답 지적 원문이었어요. 형식을 설명하려고 실제 지적을 하나 붙여 넣었는데, 그게 시험 문제의 답이었어요. 리뷰어가 찾은 한 건은 실력이 아니라 예시를 따라 쓴 것일 수 있었어요.

예시를 중립적인 내용으로 바꾸고 다시 돌리자 그 지적을 Major 로 찾았어요. 하지만 이 PR 은 더는 시험지로 쓸 수 없었어요. 관점별 점검 목록 몇 줄이 이 PR 의 지적에서 나왔거든요. 문서를 고치면서 시험지에 맞춰 버린 거예요.

그래서 세 번째는 블라인드로 했어요. 점검 목록과 상관없는 PR 을 고르고, 실행이 끝난 뒤 리뷰어의 기록을 감사해 정답을 엿본 흔적이 없는지 확인했어요.

리뷰 봇 /pr-review
Major 지적 3건 2건 적중, 1건 놓침
오탐 — 0건
적중한 지적의 심각도 Major 전부 Minor

여기서 볼 건 마지막 줄이에요. 찾기는 찾았는데 전부 한 단계 낮게 매겼어요. 첫 시험에서도 같은 일이 있었으니 재현된 거예요. 적중한 지적을 다시 보니 공통점이 있었어요. 강제 로그아웃이나 요청 경합처럼 드물게 지나가는 경로의 문제를 Minor 로 깎고 있었어요.

그래서 심각도 기준을 이렇게 바꿨어요.

심각도는 문제가 일어났을 때의 영향으로 정한다. 발생 빈도가 낮다는 이유로 낮추지 않는다 — 빈도는 본문에 적는다.

같은 시험에서 근거 줄번호 환각도 한 건 나왔어요. 34줄짜리 파일의 363~366줄을 근거로 댄 거예요. 그래서 메인 세션의 검증 단계에 근거 줄 범위를 실제 파일 길이와 대조하는 절차를 넣고, 심각도도 메인이 기준대로 다시 판정하게 했어요.

시험 방법에도 구멍이 하나 더 있었어요. 리뷰어는 git log 를 쓸 수 있어요. 그런데 이미 머지된 PR 을 시험하면, git log 에 그 PR 의 버그를 고친 후속 커밋이 보여요. 이번엔 쓰지 않았지만 막혀 있지도 않았어요. 과거 PR 로 리뷰 도구를 시험할 생각이라면 이 통로를 먼저 막는 게 좋아요.

리뷰 봇이 리뷰 스킬의 구멍을 찾았다

10월에 이 스킬을 서버 저장소 두 곳으로 옮겼어요. 스크립트는 그대로 두고, 관점별 점검 목록과 심각도 기준은 저장소마다 다시 썼어요. 서버에서 Critical 은 크래시가 아니라 데이터 오염, 중복 지급, 배포를 깨는 마이그레이션, 비밀값 노출이에요. 점검 목록도 시간대·단위 변환·N+1 쿼리·비동기 블로킹처럼 서버의 함정으로 바꿨어요.

서버 시험 결과는 이랬어요.

저장소 리뷰 봇 지적 재현 봇에 없던 지적
Django 4건 3건(같은 심각도) 비밀키가 에러 추적 도구 기록에 남는 경로 등
FastAPI 1건 0건 설정 버전 미갱신, 아무것도 검증하지 않는 테스트 등

FastAPI 에서 놓친 건 환경 변수 이름 변경이었어요. 배포 서버의 옛 값이 무시된다는 지적인데, 배포 환경 값은 저장소에서 확인할 수 없어요. 리뷰어가 “확인하지 못한 추측은 지적하지 않는다” 원칙대로 뺀 것으로 보여요. 오탐을 0으로 두려는 원칙의 대가예요. 두 저장소 모두 직접 대조한 지적 중 틀린 건 없었어요.

재미있는 일은 그다음이었어요. 이 서버 PR 들을 리뷰 봇이 리뷰하다가, 읽기 전용 훅을 우회하는 방법을 찾아냈어요.

  • git grep -O 는 결과 파일을 지정한 프로그램으로 열어요. -nOsh 처럼 짧은 옵션을 묶으면 검사를 빠져나갔어요.
  • sort --compress-program 은 임시 파일을 압축할 때 지정한 프로그램을 실행해요.

재현해 보니 둘 다 실제로 뚫렸어요. 고치면서 찾아보니 비슷한 구멍이 더 있었어요. sort --out= 처럼 긴 옵션을 줄여 써도 받아 주는 명령이 있었고, 2차 리뷰에서는 --${X}compress-program 처럼 셸 변수 확장으로 옵션 이름을 만드는 우회도 나왔어요. 그때마다 테스트를 먼저 쓰고 막았어요. 훅과 수집 스크립트의 테스트는 52개에서 86개가 됐어요.

리뷰 봇이 막힐 때 쓰려고 만든 도구의 보안 구멍을, 그 리뷰 봇이 찾았어요. 두 리뷰어가 서로를 대체하는 관계가 아니라는 걸 이때 알았어요. 봇은 패턴을 넓게 보고, 스킬은 저장소 규칙을 깊게 봐요.

비용: 리뷰어 하나가 10만 토큰으로 시작한다

남은 문제는 비용이었어요. 60개 파일, 6,379줄짜리 PR 을 3관점으로 돌리니 약 17분, 총 2,110만 토큰이 들었어요. 96.5% 가 캐시 읽기였어요.

transcript 를 열어 보니 원인이 보였어요. 리뷰어 에이전트는 아무것도 하기 전에 약 98K 토큰의 컨텍스트로 시작하고, 턴마다 그 컨텍스트를 다시 읽어요. 그러니 비용은 턴 수에 비례해요. 지난 실행 15건에서 관점 하나가 15~35턴을 썼어요. 파일을 한 턴에 하나씩 열고 있었거든요.

그래서 턴을 줄였어요.

  • 수집 스크립트가 리뷰어용 준비물을 미리 만들어요. 앞뒤 15줄 문맥을 붙인 diff 하나, 기준 규칙을 합친 파일 하나요.
  • 리뷰어는 첫 턴에 준비물을 병렬로 한 번만 읽고, 의심 지점 목록부터 만들어요.
  • 추가 확인은 여러 파일을 한 Bash 호출로 묶어요.

같은 PR 로 비교하니 3관점 합계가 84~86턴에서 23턴으로, 캐시 읽기가 약 1,500만에서 390만 토큰으로 줄었어요. 토큰 단가로 환산한 비용은 52~62% 줄었어요. PR 한 건으로 비교한 결과라 PR 크기에 따라 달라질 수 있어요.

여기서 다시 상시 층 예산으로 돌아와요. 턴을 줄이고 나니 남은 가장 큰 비용은 리뷰어마다 처음 읽는 약 10만 토큰이었어요. 리뷰어도 에이전트라서, 이 10만 토큰 안에 상시 층이 함께 실려요. 대부분은 도구 정의와 시스템 지시라 상시 층의 비중은 크지 않아요. [확인 필요: 약 98K 토큰 중 상시 층 비중] 그래도 상시 층의 1바이트는 리뷰어 3개에 각각 실려요. 상시 층을 줄이는 일은 문서 정리이면서 리뷰 비용이기도 했어요.

무엇이 달라졌나

스킬은 앱과 서버 두 곳, 세 저장소에 들어갔어요. 리뷰 봇이 한도에 걸린 PR 도 미리보기를 보고 리뷰를 달 수 있게 됐어요. [확인 필요: 배포 이후 /pr-review 로 게시한 리뷰 수와, 그중 머지 전에 고친 지적 수]

5. 이 글을 쓰다 찾은 어긋남들

이 글을 쓰려고 세 저장소를 다시 읽었어요. 그러다 제가 세운 원칙을 제가 어긴 곳들이 나왔어요.

리뷰 스킬 자체가 세 벌의 복사본이에요. 앱 저장소의 훅은 서버 두 곳보다 한 단계 뒤처져 있어요. 셸 변수 확장과 --textconv 를 막는 2차 수정이 앱 쪽에만 빠졌어요. 앱 PR 이 그 커밋을 올리기 전에 머지됐고, “사용에 큰 문제 없으면 그냥 두자”고 넘어갔던 거예요. 1장에서 말한 그대로예요. 복사본은 반드시 어긋나요. 스킬도 공용 위치 하나에 두고 저장소별 기준 문서만 따로 두는 구조로 옮겨야 해요.

리뷰어가 읽는 상세 문서 목록이 하드코딩돼 있어요. 10월 정리 때 리뷰어도 docs/rules/ 를 읽게 바꿨는데, 그때 있던 세 파일 이름을 목록으로 박았어요.

# rules.md keeps one line per rule; the detail a reviewer cites lives here.
RULE_DETAIL_PATHS = ['docs/rules/file-layout.md', 'docs/rules/code-conventions.md', 'docs/rules/work-closing.md']

그 뒤에 생긴 네이티브 채널 규칙과 접근성(Semantics) 규칙의 상세 문서는 이 목록에 없어요. 그래서 아키텍처 리뷰어는 그 두 규칙의 한 줄만 보고 리뷰해요. 「한 줄 + 상세」 구조의 한계가 리뷰어에게 그대로 옮겨 온 거예요.

번호 고정 원칙에도 구멍이 있어요. 지금 rules.md 에는 38번이 두 개 있어요. ADR 도 0002·0021·0024·0029 번호가 두 개씩이에요. 번호가 참조 키라면 중복은 깨진 참조와 같아요.

메모리 목차는 다시 불었어요. 에이전트 메모리의 목차 파일도 매 세션 통째로 읽혀요. 10월에 27KB 에서 16.9KB 로 줄이고 “목차에는 제목과 단서 몇 단어만”이라는 규칙도 남겼는데, 지금 23,166 B 예요. 상시 층에는 예산과 감사가 있지만, 메모리 목차에는 감사가 없어요.

네 가지 모두 원인이 같아요. 사람이 기억해서 지키는 규칙이었어요. 다음에 할 일은 이 규칙들을 감사 명령이나 테스트가 검사하게 바꾸는 거예요. 상세 문서 목록은 docs/rules/ 를 디렉토리째 읽게, 번호 중복은 감사 항목으로, 메모리 목차 크기는 상시 층처럼 예산으로요.

마치며: 규칙은 적는 것보다 읽히게 두는 게 어렵다

처음 규칙 파일을 만들 때는 잘 쓰면 된다고 생각했어요. 빠짐없이, 친절하게, 예시까지 붙여서요. 그렇게 쓴 파일이 16바이트를 남기고 꽉 찼어요.

열한 달 동안 바뀐 건 규칙의 내용보다 규칙이 놓인 자리였어요. 매 세션 읽혀야 하는 건 한 줄로, 그 작업을 할 때만 필요한 건 지연 층으로, 왜 그랬는지는 ADR 로 보냈어요. 복사본은 정본을 가리키는 안내문으로 바꿨고요. 그리고 같은 규칙을 코드를 쓰는 에이전트와 리뷰하는 에이전트가 함께 읽게 했어요.

에이전트에게 규칙을 읽히는 일은, 무엇을 매번 읽힐지 고르는 일입니다.

AI 에이전트용 규칙 파일을 쓰고 있다면 세 가지를 확인해 보세요.

  1. 세션마다 읽히는 문서의 크기를 지금 바이트로 말할 수 있나? 말할 수 없다면 그 문서는 이미 자라고 있어요. wc -c 한 줄이면 돼요.
  2. 같은 규칙이 두 곳 이상에 적혀 있지 않나? AGENTS.md, 다른 도구용 파일, 리뷰 봇 설정, 저장소마다 복사한 스킬까지 찾아보세요.
  3. 규칙대로 썼는지 확인하는 쪽도 같은 규칙을 읽나? 사람 리뷰어든 봇이든, 코드를 쓰는 쪽과 다른 기준으로 보고 있다면 둘 중 하나는 낡은 기준이에요.

돌아보면 규칙 파일이 1년 가까이 버텼던 건 규칙이 좋아서가 아니라, 그 파일이 넘칠 때마다 누군가 손으로 덜어 냈기 때문이었어요. 손으로 덜어 내는 일은 덜어 내는 사람이 바쁠 때 멈춰요. 그래서 다음 목표는 덜어 내야 할 때를 도구가 먼저 알려 주게 하는 거예요.

main 글 35개 Markdown UTF-8