
Claude Code에 전달하는 25개의 규칙 전체 공개 ── 실패할 때마다 추가해 온 5개월의 기록
요약
Claude Code 사용 시 에이전트의 성능을 극대화하기 위해 5개월간 축적한 25개의 규칙(Rules) 카탈로그를 공개합니다. 이론이 아닌 실제 실패 사례를 바탕으로 작성된 4,123행의 규칙을 통해 에이전트 제어 노하우를 공유합니다.
핵심 포인트
- 실패 경험을 바탕으로 작성된 25개의 실전 규칙 공개
- 에이전트의 능력이 아닌 사용자의 전달 방식 개선에 초점
- 스킬(Skill)과 규칙(Rules)의 차이 및 활용법 제시
- 검증, 정밀도, 워크플로우 등 7개 그룹의 규칙 체계
~/.claude/rules/
에는 25개의 규칙이 있습니다. 총 4,123행. 가장 오래된 기록은 2026-03-07이며, 가장 최신은 2026-08-04였습니다. 5개월 분량입니다.
이 기사는 "에이전트(Agent)에게 무엇을 써서 전달해야 할지 모르겠다"는 분들을 위해, 실물을 전부 보여드리기 위해 작성했습니다. 이론적인 이야기가 아닙니다. 전부, 실패한 뒤에 작성한 것들입니다.
TL;DR
- 규칙은
25개 / 4,123행. 기간은 2026-03-07부터 2026-08-04까지의 5개월입니다 - 단 하나도 빠짐없이, 실패로부터 태어났습니다. 먼저 체계를 설계해서 작성한 것은 단 하나도 없습니다 - 규칙 안에 적혀 있는 날짜는
317회 등장합니다. 실패한 날과, 그것을 추가로 작성한 날의 기록입니다 - 월별 날짜 출현 수는
3월 7 → 4월 33 → 5월 59 → 6월 65 → 7월 133. 가속화되고 있습니다 - 가장 밀도가 높은 하루는
2026-07-30의 28곳. 에이전트(Agent) 9대를 나란히 세워 15시간 동안 실행시킨 다음 날에 해당합니다 2일 전(8/4)은 4,023행이었습니다. 이틀 만에 100행이 늘어났습니다- 이 기사에서는 25개 규칙 전체 카탈로그와,
효과가 없었던 것·삭제한 것·보류 중인 것까지 공개합니다
규칙(Rules)이란 에이전트(Agent)가 읽는 파일입니다. 편집 중인 파일이나 대화 내용에 따라 자동으로 읽혀져, "이럴 때는 이렇게 해라"를 전달합니다. 스킬(Skill)이 "호출하는 절차서"라면, 규칙(Rules)은 "호출하지 않아도 적용되는 제약"에 해당합니다.
처음에는 0개였다
가장 오래된 기록은 record.md
의 2026-03-07이며, 내용은 "암묵지(Tacit Knowledge)를 밖으로 꺼내기"였습니다. 대화 도중에 과거의 판단이나 생각을 말하기 시작하면, 그것을 기록하라는 짧은 규칙입니다.
다만, 실패로서 선명한 것은 그다음 3개의 규칙입니다.
strategy.md
의 2026-03-15. 새로운 메커니즘을 제안했더니, "그거, 이미 기존 기능으로 할 수 있는 거잖아요"라는 지적을 받았습니다. 즉, 수중에 있는 도구를 다 쓰지 않고 새로운 도구를 만들려고 했던 것입니다. 이 한마디가 그대로 "기존 툴을 다 쓰기"라는 규칙의 첫 번째 줄이 되었습니다.
pr-workflow.md
의 2026-03-16. PR을 9개, 수동으로 만들었습니다. 설명이 얕다는 지적을 받았습니다. 전용 스킬(Skill)을 경유하면 차이점(Diff)으로부터 일본어 설명이 생성되는데, 그것을 사용하지 않았던 것입니다.
linear.md
의 2026-03-23. 알림이 짧은 시간에 대량으로 날아오는 상황에서, 한 건씩 성실하게 요약해서 보고하고 있었습니다. 돌아온 답변은 "뭔가 생중계만 하고 있는 것 같네"였습니다.
3개 모두 구조가 같습니다. 에이전트(Agent)의 능력이 부족했던 것이 아니라, 이쪽의 전달 방식이 부족했던 것입니다. 그래서 규칙(Rules)에 적었습니다. 적은 순간부터 다음 세션에서는 같은 일이 일어나지 않게 됩니다. 그것을 깨닫고 나서, 실패할 때마다 추가로 적게 되었습니다.
전체 25개 카탈로그
기능별로 7개의 그룹으로 나눕니다. "행수"는 2026-08-06 시점의 실측치이며, "계기가 된 실패"는 규칙 본문의 "경위", "기점" 섹션에 적혀 있는 내용입니다.
또한, 여기에 적은 날짜는 파일의 생성일이 아니라, 해당 규칙 안에 기록되어 있는 가장 오래된 실패의 날짜를 가리킵니다. 도중에 분할·통합한 파일이 있으므로 양자는 일치하지 않습니다. 예를 들어 동작 검증과 정보의 정밀도는 원래 1개였던 것을 2026-06-29에 2개로 나누었습니다.
A. 검증과 정밀도 ── 사실이 망가지는 것을 방지 (5개)
| 규칙 | 행 수 | 방지하고 있는 것 | 계기가 된 실패 |
|---|---|---|---|
verify.md | |||
| 372 | 동작 여부를 명령(Command) 출력으로 확인한다 | 스킬 개수를 「92"라고 쓰는 도중에, 실제로는 100개였다는 사실이 발각됨(2026-03-28) | |
accuracy.md | |||
| 298 | 정보의 출처와 강도를 떨어뜨리지 않는다 | 전사(Transcription)된 발언자를 확신을 가진 채 잘못 귀속시킴(2026-04-03) | |
completion.md | |||
| 121 | 테스트와 수락 기준(Acceptance Criteria) 검증을 건너뛰고 「완료"라고 말하지 않는다 | 실제로 그렇게 보고하는 동작을 관찰함(2026-06-28) | |
subagent-verification.md | |||
| 179 | 하위 에이전트(Sub-agent)의 주장을 근거 확인 없이 상위로 전달하지 않는다 | 구현 결과물은 변이 주입(Mutation Injection)까지 다시 수행하면서, 조사 보고는 그대로 흘려보내 잘못된 정보를 전달함(2026-07-30) | |
review-coverage.md | |||
| 57 | 리뷰의 「발견"과 「선별"을 분리한다 | 「중요한 것만 보고하라"고 쓰면, 새로운 모델은 이를 충실히 따라 진짜 버그를 묵묵히 누락시킨다 |
이 5개 중 verify.md가 가장 두껍습니다. 내용은 13개의 절로 나뉘어 있으며, 후반부로 갈수록 기괴해집니다. 「테스트가 버그 상태를 고정해버리는 함정」, 「검사 자체가 부패함」, 「검증 수단이 대상을 파괴함」, 「빈 출력을 「없음"으로 읽음」 ── 모두 테스트는 통과(Green) 상태인데 무언가가 망가져 있는 이야기들입니다.
review-coverage.md는 반대로, 작성 방식이 에이전트의 성능을 떨어뜨렸던 사례입니다. 발견 단계에서 「보수적으로"라고 지시하면, 조사하는 깊이는 동일함에도 보고 단계에서 누락됩니다. 그래서 발견과 선별을 별도의 경로(Path)로 분리했습니다.
B. 위임과 병렬 ── 다른 에이전트에게 맡기기 (3개)
| 규칙 | 행 수 | 방지하고 있는 것 | 계기가 된 실패 |
|---|---|---|---|
delegation-prompt.md | |||
| 244 | 요청 방식. 완료 조건을 기계가 측정할 수 있는 형태로 만든다 | 3건을 묶어서 던졌더니 85분 동안 결과물 제로. 1건으로 좁히고 grep 결과를 조건으로 걸었더니 6분 만에 끝남(2026-07-29) | |
spawn-preflight.md | |||
| 185 | 새로운 병렬 세션(Parallel Session)을 만들기 전에 기존의 것을 모두 찾는다 | 상태 파일(State file)의 위치가 2곳이라, 한쪽만 보고 「없음"이라고 판단하여 중복 생성함(2026-04-24) | |
strategy.md | |||
| 126 | 무엇을 직접 만들고 무엇을 만들지 않을 것인가. 모델 세대 교체 시의 재고 조사 | 직접 만들던 자동화 기능의 절반 이상이, 공식 기능 발표로 인해 하룻밤 사이에 진부해짐(2026-03-27) |
delegation-prompt.md는 7월 말에 한꺼번에 두꺼워졌습니다. 9개를 병렬로 돌려 15시간 동안 44개의 PR을 냈던 날, 멈춰버린 요청이 3건 발생했습니다. 멈춘 원인은 모두 범위의 넓이가 아니라, 만들 대상의 형태가 결정되지 않았기 때문이었습니다. 「디자인을 개선해줘"라고 던지면 멈추고, 「grep 'style={{' 결과가 0건"이라고 던지면 움직입니다.
spawn-preflight.md는 성격이 조금 달라서, 「찾는 방법"에 관한 규칙입니다. 티켓 번호로만 검색하면 파일명이 기능명 기반일 경우 걸리지 않습니다. 그래서 최소 3가지 축(번호·영어명·일본어명)으로 횡단 검색하는 절차가 적혀 있습니다.
C. 인간의 판단을 보호하기 (5개)
| 규칙 | 행수 | 방지하고 있는 것 | 계기가 된 실패 |
|---|---|---|---|
approval.md | |||
| 118 | 목록을 나열하고 "괜찮아 보이면 승인해 주세요"라고 말하게 하지 않기 | 수용 기준(Acceptance Criteria)이 184건 정의되어 있었음에도, 중대한 버그 2건이 모두 통과됨 | |
quota.md | |||
| 111 | 가벼운 판단으로 매번 멈추지 않기. 확인의 경계를 결정하기 | 동일한 세션에서 세세한 선택지를 계속 제시하여, "무엇을 판단해야 하는 거지?"라는 혼란을 유발함 | |
readability.md | |||
| 70 | 결론을 맨 앞에. 화살표 연쇄와 자체 제작 약어 금지 | 자체 제작한 라벨 "태스크 A / B / C"를 정의한 지 몇 시간 후 설명 없이 재사용함 (2026-07-13) | |
elicitation.md | |||
| 54 | 모르는 것을 구현 단계에서 큰 비용을 치르기 전에 저렴하게 찾아내기 | 미경험 영역에서 구현을 마친 뒤에야 문제를 인지하는 상황이 반복됨 | |
crystallization-ritual.md | |||
| 38 | 결론을 작성하기 전에, 반증(Counter-evidence)만 찾는 역할을 1회 배치하기 | 벽치기(Wall-hitting, 아이디어 브레인스토밍)를 방치하면 맞장구치기로 퇴화함. AI의 기본 설정은 아부하는 것이었음 |
approval.md의 핵심은 "양 그 자체가 아니라, 양이 보이지 않는 것에 편향(Bias)이 생긴다"는 관찰입니다. 184건은 통과되었지만, 77건을 제시했을 때는 "리뷰할 수 없다"며 올바르게 제동이 걸렸습니다. 그래서 승인은 3개 층으로 나누어 제시합니다 ── 인간이 봐야 할 몇 건, 기계로 담보된 층, 담보되지 않았다고 솔직하게 말하는 층.
crystallization-ritual.md는 25개 중 3번째로 짧지만, 가장 효과적인 규칙일지도 모릅니다. 결론을 작성하는 말미에 "이 결론은 ◯◯라는 데이터가 나오면 틀린다. 확인일 = YYYY-MM-DD"를 반드시 한 줄 적습니다. 이 글의 끝부분에도 동일한 내용을 두었습니다.
D. 외부로 내보내기 전에 멈추기 (5개)
| 규칙 | 행수 | 방지하고 있는 것 | 계기가 된 실패 |
|---|---|---|---|
deploy-declaration.md | |||
| 89 | 공유 환경 반영 및 외부 게시 직전에 한 줄 선언하기 | 승인되었으나 아무 말 없이 공유 환경을 덮어씌워, "실행되는 순간이 보이지 않는" 당혹감을 유발함 (2026-06-12) | |
artifact-freshness.md | |||
| 104 | 진행 상황 보드의 숫자와 문장의 신선도를 분리하여 표시하기 | 전날 만든 보드가 아침에는 낡아 있었고, 숫자보다 문장의 해악이 더 컸음 (2026-07-30) | |
draft.md | |||
| 40 | 그대로 붙여넣을 수 있는 형태로 초안을 내기 | 인용 기호로 감싸서 내보내는 바람, 붙여넣기 전에 손으로 전부 떼어내는 작업이 발생함 (2026-07-06) | |
schedule-proposal.md | |||
| 32 | 일정 후보에 종료 시각과 버퍼(Buffer)를 반드시 포함하기 | 시작 시각만 적어서 내보냈다가, "일정이 겹치지 않겠습니까?"라는 답변을 받음 (2026-07-16) | |
slack-formatting.md | |||
| 28 | 멘션(Mention) 직후에 줄바꿈하기 | ── |
slack-formatting.md는 25개 중 유일하게 본문에 날짜를 하나도 포함하지 않는 규칙입니다. 28행이며, 내용은 거의 "멘션 뒤에는 줄바꿈"이라는 한 가지뿐입니다. 너무 작아서 통합하고 싶어지지만, 남겨두었습니다. 작은 상태로 남아 있는 규칙일수록, 위반해도 아무도 곤란해하지 않지만 매번 미세하게 읽기 불편하다는 종류의 문제를 다루고 있습니다.
artifact-freshness.md에는 가장 최신의 설계 사상이 담겨 있습니다. 보드의 내용은 "숫자"와 "판단의 문장"에 따라 부패하는 속도가 다른데, "최종 업데이트 10:35"라고 적으면 그 둘 모두를 보장하는 것처럼 보입니다. 그래서 숫자는 기계가 업데이트하고, 문장의 신선도를 나타내는 표시는 인간만이 수정한다는 형태로 만들었습니다.
E. 사양과 코드의 운용 (3개)
| 규칙 | 행수 | 방지하고 있는 것 | 계기가 된 실패 |
|---|---|---|---|
spec.md | 258 | 설계 문서(Design Document)를 유일한 정본으로 삼는다. 구현 절차서를 별도로 만들지 않는다 | 절차서가 설계서의 열화된 복사본이 되어, 사양 변경 시마다 양쪽을 모두 수정해야 하는 상황이 발생함 |
pr-workflow.md | 221 | PR(Pull Request) 작성 방법과 리뷰 답변. 리포지토리별 예외 사항 포함 | rename을 포함한 여러 커밋을 squash로 통합했더니, rename이 누락되어 파일이 이동하지 않음 (2026-05-06) |
linear.md | 115 | 티켓 ID만 나열하지 않는다. 진행 상황은 설명란에 추가한다 | 방대한 양의 알림을 하나씩 요약하다 보니 '실황 중계만 하는 상태'가 됨 (2026-03-23) |
spec.md에는 폐지 기록이 2개 포함되어 있습니다. 구현 절차서를 별도 파일로 만드는 것을 그만두었으며, 수락 기준(Acceptance Criteria)을 별도의 JSON 파일로 분리하는 것도 그만두었습니다. 둘 다 "정본이 두 개로 나뉜다"는 동일한 이유로 삭제했습니다.
linear.md의 "ID만 나열하지 않는다"는 사소해 보이지만 효과적입니다. "XX-4274 상황 확인"이 아니라 "테스트 결과 공개 기능(XX-4274)의 상황 확인"이라고 작성합니다. 번호는 기억과 연결되지 않습니다.
F. 기억 (2개)
| 규칙 | 행수 | 방지하고 있는 것 | 계기가 된 실패 |
|---|---|---|---|
record.md | 70 | 무엇을 기억할 것인가. 기본값은 억제, 명시된 요청만 기록한다 | ── (25개 중 가장 오래됨, 2026-03-07) |
recall.md | 61 | 무엇을 떠올릴 것인가. 행동을 촉구하는 턴에서는 반드시 본문을 연다 | 한 줄의 설명문만으로 원문 인용을 제시하여, 본문과 다른 문구를 출력할 뻔함 |
이 두 개는 쌍을 이룹니다. record.md는 "결론뿐만 아니라, 왜 그렇게 판단했는지에 대한 구조를 써라"라고 요구합니다. "X를 채택했다"가 아니라 "(1) 전제 Y가 있다 (2) 트레이드오프(Trade-off) Z를 수용했다 (3) 대안 W보다 N이라는 점에서 우수하다"라고 작성합니다.
recall.md 쪽은 반대로 "매번 본문을 읽지 마라"라고 말합니다. 상대가 관찰 내용을 말했을 뿐인 턴에서는 인덱스(Index)만으로 응답해도 됩니다. 행동을 취하려는 턴에서만 본문을 열어 확인합니다. 판단의 축은 하나, "지금 나의 응답을 바탕으로 행동이 일어나는가"입니다.
G. 고유 도메인의 함정 (2개)
| 규칙 | 행수 | 방지하고 있는 것 | 계기가 된 실패 |
|---|---|---|---|
traps.md | 946 | 도구를 사용할 때 빠지는 함정과 회피책의 집적 | 병렬로 던진 Bash 중 하나가 실패하여 나머지 전부가 취소됨 (2026-04-21) |
line-messaging-liff.md | 161 | 메시징 기반의 3가지 채널을 혼동하지 않는다 | 하나의 프로젝트에서 이틀 동안 8개의 버그를 겪음 (2026-07-13~14) |
traps.md가 946행으로, **25개 합계 4,123행의 약 23%**를 차지합니다. 번호는 36번까지 있지만, 중간의 12개는 내용이 스킬이나 프로젝트 고유 규칙으로 옮겨져 참조용 1행만 남아 있습니다.
내용은 정말 처절합니다. zsh의 예약 변수, 변수 바로 뒤에 대괄호가 이어지면 배열 인덱스로 오해받는 문제, cd가 복합 명령의 후반부까지 계속 적용되는 문제, git add -A가 추적되지 않은 파일(untracked files)까지 포함하는 문제, git mv가 스테이징되지 않은 편집 사항을 잡지 못하는 문제, 외부 CDN의 버전 고정 URL이 실제로는 변경되는 문제, .env에 계속 추가만 하다 보면 동일한 키가 3줄 생겨서 잘못된 값을 읽게 되는 문제, worktree를 삭제하면 제외 설정했던 파일도 함께 삭제되는 문제 등입니다.
line-messaging-liff.md는 25개 중 유일하게 하나의 서비스 통합에 묶인 규칙입니다. 범용성은 없지만, 다음에 같은 기반을 다룰 때 이틀 치의 시간을 돌려받을 수 있습니다.
내용 공개 ── 발췌 6개
카탈로그만으로는 "그래서 실제로 어떻게 적혀 있는가"를 알 수 없으므로, 짧고 강력한 효과를 내는 것 6개를 보여드립니다.
verify.md §11)
- 검사가 통과하는 이유는 1개인가, 2개 이상인가 (배포 디렉토리 외부로 나갈 수 없다는 것을 이렇게 확인하고 있었습니다.
curl '.../../package.json' 이 404인 것
통과되었습니다. 그런데 그 후, 같은 디렉토리에 package.json을 새로 두었습니다. 그러자 ..은 정규화(Normalization)로 인해 무효화되어 배포 디렉토리의 직하를 가리키게 되었고, 그곳에 실제로 존재하게 되어 200이 반환되었습니다.
404였던 이유는 "방어가 작동했기 때문"이 아니라 "그곳에 파일이 없었기 때문"이었습니다. 판별 질문은 하나가 됩니다.
"이 검사가 통과하는 이유는 1개인가, 2개 이상인가"
이유가 2개 이상인 검사는, 언젠가 더 약한 쪽의 이유만으로 통과하게 됩니다.
그래서 검사 대상을 /../../../etc/passwd와 같이 "배포 대상으로서 존재할 수 없는 것"으로 교체했습니다.
delegation-prompt.md
§5)
- 완료 조건을 기계로 측정할 수 있는 형태로 만들기 (| 나쁜 완료 조건 | 좋은 완료 조건 |
|---|---|
| 디자인을 개선한다 |grep 'style={{'가 0건 |
| 보안을 강화한다 |curl --path-as-is '.../../etc/passwd'가 404 |
| 테스트를 충실히 한다 | 변이 주입 (Mutation Injection)으로 N곳을 망가뜨렸을 때, 각각의 테스트가 실패하는 것 |
| 동작하게 만든다 | 설정을 작성하지 않고 브라우저로 열었을 때, 이벤트가 202로 도달하는 것 |
마지막 행이 요점입니다. "테스트가 통과하는 것"을 완료 조건으로 삼으면, 테스트 코드를 수정해서 통과시켜 버릴 수 있으므로 고쳐졌다는 증거가 되지 않습니다. 결과물 외부에서 관측할 수 있는 사실을 조건으로 둡니다.
이 규칙에는 뒷이야기가 있어서, 작성 당일에 스스로 2번 어겼던 기록까지 적혀 있습니다. "이번에는 지켰다"라고 생각할 때일수록 숫자를 세라는 내용입니다.
cd를 사용하지 않기 (traps.md §33)
- 여러 리포지토리를 가로지를 때
# 위험: 후반부가 다른 리포지토리에서 실행됨
cd ~/repo-a && gh pr merge 77 && ... && git rm CLAUDE.md && cat > CLAUDE.md <<'EOF' ...
하루에 3번 저질렀습니다. 2번은 오판정으로 끝났지만, 3번째에는 자료 측에서 실행하려던 "CLAUDE.md를 안내문으로 교체하기"가 구현 측에서 실행되어, 올바른 파일을 삭제하고 다른 내용으로 덮어쓴 뒤, 그대로 직접 커밋해 버렸습니다. push 하기 전에 알아채서 되돌렸지만, 만약 push 했다면 되돌릴 수 없었을 것입니다.
처방은 한 줄입니다. 여러 리포지토리를 가로지르는 작업에서는 cd를 사용하지 않는 것입니다.
git -C <path>와 절대 경로를 사용합니다. cd를 사용한다면 1회 호출당 1개의 리포지토리로 제한합니다.
verify.md §13)
- 빈 출력을 사실의 주장으로 읽지 않기 (1 세션에서 4번 저질렀습니다.)
- 1MB 초과 파일을 찾는 명령어가 빈 결과로 나옴 → "하나도 없다"라고 읽었습니다. 실제로는 에러로 인해 중간에 종료되었습니다 (2.6MB의 이미지가 있었습니다).
- 변이 주입을 했더니 "테스트가 없다"라고 나옴 → "그 검사는 존재하지 않는다"라고 읽었습니다. 실제로는 제가 적용한 방식이 파일을 구문 에러 (Syntax Error) 상태로 만들었습니다.
- 미로그인 상태의
curl이 307을 반환함 → "그 경로는 없다"라고 읽었습니다. 존재하지 않는 경로도 307이었습니다. grep결과가 빈 값임 → "그 요소는 없다"라고 읽었습니다.grep은 행 단위로 작동하므로, 줄바꿈이 포함된 구조에는 매치되지 않습니다.
처방 중 하나는 변이 주입의 절차입니다. 초록색을 본다 → 변이를 가한다 → 빨간색을 본다 → 되돌린다 → 초록색을 본다의 5단계입니다. 빨간색 상태에서 변이를 가하면, 변이가 먹힌 것인지 원래 빨간색이었는지 구분할 수 없습니다.
approval.md §0)
- 착수 전에 예상치를 받기 (분류·분석·조사·리뷰처럼, 출력이 인간의 판단 재료가 되는 작업을 요청받았을 때, 착수 전에 "예상을 1~3줄" 받기 전까지는 착수하지 않는다는 게이트입니다.)
"이 802건을 분류하기 전에, '자신은 이렇게 나뉠 것이다'라는 내용을 1~3줄 주세요. 나중에 출력물과 대조하겠습니다."
왜 반드시 착수 전이어야 하는가. 결과물이 나온 뒤에 예상을 요구하면, 인지 부하 (Cognitive Load)가 정점일 때 가장 비용이 높은 행위를 요구하게 되어 반드시 실패합니다. 실제로 그렇게 실패했던 기록이 같은 절에 적혀 있습니다.
그리고 예측과 출력이 일치했을 때는 「확인했다」가 아니라 위험 신호로 취급합니다. 자신과 같은 의견을 가진 AI를 선택적으로 수용하고 있는 것일지도 모르기 때문입니다. 일치한 항목이야말로 무작위로 섞어서 테스트합니다.
artifact-freshness.md
)
- 기계가 건드리지 못하게 할 한 줄을 정한다(진척 보드에는 두 개의 표시를 넣어 두었습니다. 숫자를 교체할 범위를 둘러싸는 표시와, 본문이 어느 시점의 코드에 대응하는지를 나타내는
data-prose-sha입니다.
**
data-prose-sha를 쓰는 것은 사람뿐입니다. **본문을 수정한 세션이, 그 당시에 보고 있던 상태로 다시 씁니다. 기계는 절대로 건드리지 않습니다. 건드리는 순간 「본문을 읽지 않았는데 최신이라고 말하는」 장치가 되어버립니다.
이 설계의 장점은 방치해도 거짓이 되지 않는다는 점입니다. 사람이 본문을 수정하지 않으면, 보드는 스스로 「본문은 N개만큼 뒤처져 있다」고 계속 말할 것입니다.
추가되는 속도
규칙 안에 등장하는 날짜를 월별로 세어보면 다음과 같습니다.
| 월 | 날짜 출현 수 |
|---|---|
| 2026-03 | 7 |
| ... |
7월만 돌출되어 있습니다. 일별로 나누면 7/30이 28곳, 7/29가 15곳으로, 이 이틀만 합쳐도 43곳이 됩니다.
무슨 일이 있었냐면, 에이전트를 9체 나란히 세워 15시간 동안 실행했습니다. PR은 44개가 나왔습니다. 거기서 발생한 일들이 delegation-prompt.md에 21곳, verify.md에 18곳, traps.md에 31곳 분량으로 추가되었습니다.
여기서 관찰할 수 있는 점이 두 가지 있습니다.
첫째. 규칙이 늘어나서 실패가 줄어든 것이 아니라, 병렬로 실행하는 양이 늘어나서 실패가 늘어난 것입니다. 가속되고 있는 것은 학습 곡선이 아니라, 다루고 있는 양입니다.
둘째. 실패의 종류가 바뀌고 있습니다. 3월에서 4월 사이의 실패는 자신의 습관이었습니다 ── 숫자를 잘못 세거나, PR 설명을 직접 쓰거나, 알림을 하나씩 중계하는 것 등입니다. 7월의 실패는 구조적인 측면에 있습니다 ── 위임한 대상이 멈춰 있다는 것을 2시간 18분 동안 알아차리지 못하거나, 보고가 하나씩 늦게 도착하거나, 검사가 아무것도 측정하지 못하는 것 등입니다.
혼자서 작성하던 시절의 실패와, 9체에게 맡기고 있는 시절의 실패는 별개의 것이었습니다.
효과가 없었던 것 · 삭제한 것 · 보류한 것
성공 사례만 나열하면 세상에 흔한 설정집과 다를 바 없습니다. 그래서 제외한 측면도 공개합니다.
재고 조사를 했지만, 단 하나도 지울 수 없었다
strategy.md에는 「모델 세대교체 시의 재고 조사」라는 절차가 적혀 있습니다. 새로운 모델이 나오면 너무 세세한 절차 지시를 덜어내고, 「CRITICAL: You MUST」와 같은 강조를 약화시키며, 강제적인 발판을 제거합니다. 공식 가이드가 명시적으로 그렇게 권장하고 있기 때문입니다.
2026-08-04에 그것을 실행했습니다. 25개 항목 모두에 「최종 검증 / 검증 단계 / 만약을 위해 / 재확인 / 재검증」으로 검색을 걸었습니다.
검색 결과는 2건이었고, 둘 다 오탐지였습니다. 삭제는 0건.
이유는 명확합니다. 실패에서 태어난 규칙은 처음부터 「기계로 측정하는 형태」로 작성되었기 때문입니다. 「만약을 위해 다시 한번 확인하라」가 아니라 「wc -l로 다시 센다」, 「변이 주입을 통해 떨어지는지 확인한다」라고 적혀 있습니다. 판정의 한 줄은 다음과 같이 바뀌었습니다.
「그 검증은 커맨드의 출력이 근거가 되는가?」
근거가 되지 않는 검증 지시는 쓰지 않습니다. 역설적으로 말하면, 삭제할 수 있는 지시를 쓰고 있었다면 그것은 처음부터 효과가 없었던 것입니다.
같은 날 아침에 정한 기본값을 밤에 반전시켰다
delegation-prompt.md의 §0은 「위임 여부를 먼저 결정한다」는 절로, 2026-08-04 아침에 「기본값은 위임하지 않는다」라고 적었습니다. 공식 가이드가 「새로운 모델은 너무 많이 위임하므로 억제하라」고 했기 때문입니다.
그날 밤에 이를 반전시켜 「기본값은 위임한다」로 다시 썼습니다. 이유는 현장에 있었습니다. CI가 6~8분 걸리는 환경에서는, 부모(Parent)가 구현에 빠져 있는 비용이 더 크기 때문입니다. 부모가 빠지면 그동안 다른 모든 것이 멈춥니다.
해당 절의 말미에는 이렇게 적혀 있습니다. 「기본값을 반전시킨 것은 기동 판정을 완화한 것이지, 뒷정리를 완화한 것이 아니다.」 완료 조건을 기계로 측정하고, 실물을 확인하고, 정기적으로 모니터링하고, 끝나면 닫는 것 ── 이 4가지는 그대로 유지했습니다.
의무화했던 것을 2개월 후에 폐지했다
traps.md
§17에 폐지 기록이 남아 있습니다. 특정 명령어가 권한 설정으로 인해 차단되었을 때, 다른 경로로 우회하는 것을 2026-05-12에 의무화했습니다. 실제로 2건의 실적이 있었습니다.
2026-06-18에 이를 폐지했습니다. 이유는 우회로가 존재한다는 사실 자체가 설정한 금지를 '형식적인 금지'로 만들었기 때문입니다. 정말로 막고 싶었다면, 그 전 단계인 플랫폼 측에서 막았어야 했습니다. 이중 관리로 인한 인지 부하(Cognitive Load)도 발생했습니다.
해당 절에는 폐지하게 된 경위만 남아 있고, 절차는 삭제되었습니다.
"이것은 파악되지 않음"이라고 적혀 있는 것
traps.md
§9는 장시간 대기 처리(Waiting process)를 어떻게 작성할지에 대한 절입니다. 백그라운드 실행(Background execution)으로 작성한 스크립트가 조기에 종료되는 현상을 여러 차례 관찰했지만, 재현 조건과 원인을 특정하지 못했습니다.
그래서 해당 절에는 다음과 같이 적혀 있습니다. "관찰 사실에 기반한 잠정적인 지침이며, 재현 조건과 원인이 밝혀지면 업데이트한다". 파악되지 않은 것을 파악되지 않았다고 명시한 채, 실용적으로 작동하는 수단을 기본값으로 설정해 두었습니다.
§20은 훨씬 더 약한 단계로, "N=1의 관찰, 2회 이상 관찰하면 정식화할 후보"라고 명시되어 있습니다. **승격 대기 중인 선반(Shelf)**이 마련되어 있는 셈입니다.
작성했지만 발화(Trigger)하지 않은 것
가장 뼈아픈 부분입니다.
approval.md
의 §0은 애초에 "형태(Pattern)는 이미 존재하는데 발화하지 않는다"라는 실측 결과로부터 탄생했습니다. "보기 전에 예측을 세운다"는 내용은 다른 곳에 적어 운용하고 있었지만, 실제로 검색해 보니 예측을 적어둔 메모는 0건이었습니다. 그래서 '인간이 유념해야 할 규율'에서 '에이전트 측에서 차단하는 구조'로 옮겼습니다.
verify.md
§13에도 동일한 형태가 나타납니다. 빈 출력을 사실로 읽지 말라는 절을 작성한 다음 날 바로 똑같은 실수를 저질렀습니다. 해당 절에는 그대로 "형태의 재고는 있지만 발화하지 않음"이라고 적혀 있습니다.
쓴다고 해서 반드시 효과가 있는 것은 아닙니다. 규칙에 적음으로써 확실히 변하는 것은 에이전트가 그것을 읽느냐의 여부이지, 인간이 그것을 기억해 내느냐의 여부가 아닙니다.
규칙을 규칙으로 측정하면, 기록이 측정을 오염시킨다
이것은 웃픈 이야기(Laughable story)에 가깝습니다. 재고 조사를 위해 25개를 검색하여 "히트 2건"이라는 결과를 얻었습니다. 그리고 그 결과를 동일한 25개 항목 안에 적었습니다.
다시 한번 동일한 검색을 수행하자 9건이 반환되었습니다. 늘어난 7건은 감사(Audit) 결과를 기술한 문장 그 자체였습니다.
| 상태 | 히트 |
|---|---|
| 커밋된 상태 | 1 |
| ... |
대처법은 한 줄입니다. 측정은 작업 트리(Working tree)가 아니라 커밋된 상태를 대상으로 수행합니다. 그리고 측정한 수치를 남길 때는 언제, 어떤 상태를 측정했는지를 병기합니다.
새로 만드는 사람을 위한 순서
25개를 한꺼번에 만들 필요는 없습니다. 아니, 만들 수도 없습니다. 전부 실패한 후에 작성한 것들이기에, 실패하지 않은 규칙은 쓸 방법이 없기 때문입니다.
자신의 이력을 실제 순서대로 나열하면 다음과 같습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기