이런 일이 일어나고 있다 → 어떻게 할 것인가
제목이 아니라 증상으로 찾습니다. "어떻게 할 것인가" 아래의 링크로 그 대응법을 적은 절로 이동합니다. 전체 기사 목차는 이 페이지 아래에 있습니다.
이 표는 Claude Code(Anthropic의 코딩 에이전트)를 전제로 합니다. hook, CLAUDE.md, subagent, auto memory는 그 기능의 이름입니다.
| 이런 일이 일어나고 있다 | 어떻게 할 것인가 |
|---|---|
| AI가 테스트를 실행할 때마다 수만 줄의 출력이 컨텍스트로 흘러들어온다 |
테스트 실행을 래퍼 스크립트 1개로 모으고, 전체 출력은 로그 파일에 남기고, AI에게는 실패 요약만 돌려줍니다. |
| AI가 지식 메모를 저장할수록, 이후 모든 세션이 읽어야 할 양이 늘어난다 |
메모리 쓰기 직전에 실행되는 PreToolUse hook으로 체크리스트를 읽게 합니다. 지시 파일(CLAUDE.md)에는 '쓰기 전에 읽는다'는 한 줄만 둡니다. |
| 테스트는 통과하지만, 그것이 실제로 무언가를 지키고 있는지는 알 수 없다 |
mutation testing(테스트를 일부러 망가뜨려 실패하는지 확인하는 기법) 방침을 문서 1장으로 만들어, 테스트 점검을 요청할 때 읽게 합니다. |
| 등록한 스킬을 AI가 쓸 때도 있고 안 쓸 때도 있다 |
명령은 일반 스크립트로 그대로 두고, 잘못된 호출 방식은 PreToolUse hook으로 막고, 읽어야 할 문서를 안내합니다. |
| 서브에이전트에 맡긴 작업은 끝날 때까지 무슨 일이 일어나는지 보이지 않는다 |
서브에이전트에 위임해도 되는 작업과 실행 전에 필요한 입력 파일을 YAML로 정의하고, hook으로 실행 전에 검사합니다. |
| 지시 파일에 규칙을 더할수록 이전에 넣은 규칙이 지켜지지 않는다 |
'~하지 않는다'는 규칙을 하나씩, 위반을 감지할 수 있는 자동 테스트(Minitest)로 바꿔 씁니다. |
| 병렬로 실행되는 세션이 공유하는 메모리가 흐트러진다. 방침을 읽혀도 효과가 없다 |
같은 방침 파일을 PostToolUse hook으로 옮겨, 저장 후 diff와 함께 제시합니다. 읽히는 내용은 그대로 두고 시점만 바꿉니다. |
| 같은 실패에 대한 대처를 적어 둬도 AI는 다음에 또 같은 실패를 한다 |
재시도 시의 방침을 몇 줄짜리 파일로 정리하고, 실패를 감지한 hook에서 자동으로 삽입합니다. |
| 인수인계 글과 완료 보고를 읽어도 불리한 내용이 빠져 있다 |
완료 보고 옆에 git diff --stat 등으로 기계적으로 얻은 수치를 매번 나란히 둡니다. |
| 기계가 센 숫자가 보고서에 도달하기 전에 다른 숫자로 바뀌어 있다 |
수치가 담긴 줄에 고정된 접두사를 붙이고, 그것이 그대로 복사되었는지 hook으로 검사합니다. |
| 작업 중인 AI에게 끼어들면 이후 동작이 흐트러진다 |
작업 중에 사람이 끼어드는 대신, 저장 직후 방침을 돌려주는 PostToolUse hook과 실패를 감지해 되돌리는 hook이 개입하게 합니다. 사람은 매듭까지 기다립니다. |
| 세션이 끝날 때 무엇을 읽고 무엇을 읽지 않아도 되는지 정해져 있지 않다 |
산출물도 작업 로그도 읽지 않고, 테스트나 린터의 종료 코드(exit code)에 의한 합격 여부만 봅니다. |
| 한번 거절한 제안이 다음 세션에서 다시 나온다 |
기각한 판단을 정해진 형식으로 문서 1개에 모읍니다. |
| 금지 사항 한 줄을 적었는데 확대 해석도 축소 해석도 된다 |
기각한 판단을 모아 둔 문서 1개(예: non_goals.md)에서, 금지 사항마다 '이유' 항목을 두어 결론과 함께 적습니다. |
| 금지 사항이 정확히 적혀 있는데도 지켜지지 않는다. 그때마다 문의가 온다 |
기각 문서의 금지 사항마다 '적용 범위' 항목을 두어, 판단이 애매한 경계 사례를 한 줄씩 나열합니다. |
| 같은 지시를 여러 서브에이전트에 나눠 주면 돌아오는 형식이 에이전트마다 다르다 |
서브에이전트에 맡겨도 되는 작업 목록에 실행 전 준비해야 할 입력 파일을 명시합니다. |
| 자동 테스트가 없는 금지 사항이 문서에만 적힌 채 쌓여 간다 |
기각 문서의 목록에 '기계 검증' 항목을 추가해, 대응하는 자동 테스트(Minitest)의 유무를 항목마다 명시합니다. |
| AI의 작업이 매번 '화면을 열어 확인해 주세요'로 끝난다 |
Playwright로 스모크 테스트를 1개 준비하고, 합격 여부는 화면의 겉모습이 아니라 DB에 남은 레코드로 판정합니다. |
| AI가 살짝 어긋난 말을 할 때마다 이쪽이 설명하며 고치고 있다 |
어긋남을 사람이 설명하며 고치는 대신, 지적을 hook의 stderr(exit 2)와 자동 테스트의 실패 메시지에 적어, AI에게 전달되는 경로를 그쪽으로 맞춥니다. |
| 거절한 판단의 목록이 계속 늘어나, 언젠가 아무도 읽지 않게 될 것 같다 |
기각 문서의 끝에 '채택하지 않은 안' 절을 두어, 기각한 제안은 거기에 기록합니다. |
| 지시 파일의 '반드시 실행하세요'가 줄지 않은 채 남아 있다 |
지시 파일이 '반드시 실행'이라고 적은 명령이 pre-commit hook에도 존재하는지 맞춰 보는 자동 테스트로 검증합니다. |
| 방법까지 적어서 건넸는데도 그대로 고쳐지지 않는다 |
절차를 지시하는 대신, 서브에이전트 실행 전에 반드시 있어야 할 입력 파일을 용도마다 정의합니다. |
| 버그를 전달할 때마다 이쪽이 재현 절차와 증상을 매번 적고 있다 |
버그 신고 폼을 두어, 사람이 입력하는 것은 증상 한 문장뿐으로 하고, URL·조작 이력·브라우저 정보는 JavaScript로 자동 수집합니다. |
| '먼저 계획을 내 주세요'라고 매번 입력하는 수고가 든다 |
새로운 구현은 필요 없습니다. 설계 문서를 1개 두면 AI가 기존 문서를 읽고 같은 형식을 따릅니다. |
| 지켜 주길 바라는 줄일수록 강하게 적었는데 효과가 있는지 알 수 없다 |
효과 측정은 그만두고, 지시 파일 안의 강조 표현이 포함된 줄 수를 세어 기준치를 넘으면 실패하는 자동 테스트(ratchet)를 둡니다. |
| 서브에이전트의 산출물이 이쪽이 예상한 것과 다른 형식으로 돌아온다 |
서브에이전트 용도마다 산출물의 수용 조건(파일명·형식·필수 항목)을 문서 1장으로 정의합니다. |
| 실수를 발견하면 '제대로 읽었나요'라고 추궁하고 싶어진다 |
추궁하는 대신, 의뢰의 두 번째 문장을 '~이 아닌가요?'라는 의문형 템플릿으로 고정합니다. |
| 돌아온 답에 '그게 아니라'라고 되돌려도 나아지지 않는다 |
지적하는 대신 대안 없는 금지 사항을 PostToolUse hook에서 저장 직후의 diff와 함께 제시합니다. |
| AI가 열지 않은 파일의 내용을 연 것처럼 이야기한다 |
참조한 문서와 코드 양쪽에 서로 대응하는 표시(marker)를 적게 하고, 그 표시가 실제로 있는지 자동 테스트로 검증합니다. |
| AI로부터 'A와 B 중 어느 쪽으로 할까요'라는 질문을 계속 받아 작업이 멈춘다 |
즉답을 그만두고, 선택지의 판정이 자동 테스트나 hook 쪽에서 결정되게 합니다. |
| AI에게 리뷰를 시키고 있지만 무엇을 보지 않았는지 알 수 없다 |
파일을 훑고 있으면서도 건수 하한(assert_operator ... :>=)이 없는 자동 테스트를, 외부에서 세는 자동 테스트로 검출합니다. |
| 촬영한 이미지가 쌓여 가지만 어느 것이 무엇을 확인한 한 장인지 알 수 없다 |
화면 확인 전에 '무엇을 검증하는가', '왜 더 저렴한 수단으로는 부족한가' 두 질문에 답하게 하고, 단위 테스트 → 결합 테스트 → E2E 순으로 저렴한 수단부터 시도하는 지침을 1장 둡니다. |
| 선언하는 공정을 두었는데 선언 없이 실행된 횟수를 셀 수 없다 |
촬영이나 E2E 전에 '무엇을 검증하는가'를 적는 선언 파일(예: tmp/visual_verification.md)을 두고, 그 존재를 PreToolUse hook의 실행 조건으로 삼아, 없으면 촬영이나 E2E가 시작되지 않게 합니다. |
| 코드를 바꾸지 않았는데 같은 테스트가 실행되어 그만큼 기다리게 된다 |
테스트 래퍼 스크립트에 --last 옵션을 추가해, 이전 로그를 다시 보여 주고 재실행을 불필요하게 합니다. |
| 아무것도 망가뜨리지 않았는데 낯선 에러가 잔뜩 나열된다 |
테스트 래퍼 스크립트에서 배타 락(mkdir의 원자성을 이용)을 걸어, 확보하지 못하면 실행하지 않게 합니다. |
| '테스트는 통과했습니다'라는 보고에 실행되지 않은 부분이 적혀 있지 않다 |
무거운 E2E에 영역명 태그를 붙여 기본값으로는 skip하고, 실행하지 않은 영역 목록을 매번 출력합니다. |
| 진행 방식을 지정한 지시가 지켜졌는지 나중에 구별할 수 없다 |
절차를 지키게 하고 싶을 때는 지시 문구를 강화하지 말고, 그 절차를 거친 흔적이 산출물로 남는 형태로 바꿉니다(예: 연 파일마다 한 줄씩 출력하게 함). |
| 만들어 둔 래퍼가 어느 순간부터 일반 명령으로 되돌아가 있다 |
래퍼를 쓰게 하고 싶을 때는 지시를 강화하지 말고, 일반 명령으로 돌아갈 필요가 남아 있지 않은지(래퍼의 기능이 부족하지 않은지) 확인합니다. |
| 같은 질문을 여러 번 던지면 답이 매번 다르다. 취합하면 무언가가 사라진다 |
여러 답을 하나로 취합하기 전에 지적 종류별 출현 횟수(몇 건 중 몇 건이 언급했는가)를 출력합니다. |
| '필요하면 ~해 주세요'라고 적은 줄이 실제로 발동했는지 알 수 없다 |
'필요하면 ~해 주세요' 같은 조건부 지시는 적지 말고, 그 공정을 거치지 않으면 다음으로 진행할 수 없는 hook으로 강제합니다. |
| '다시 한번 생각해 주세요'라고 돌려주면 답은 바뀌지만 납득했는지는 알 수 없다 |
'다시 한번 생각해 주세요'라고 되돌리지 말고, 어떤 전제가 잘못되었는지를 구체적으로 지적합니다. |
| '추측하지 마세요'라고 적었더니 AI가 아무것도 만들지 않고 돌아오게 되었다 |
금지만 전달하지 말고, '해당하지 않는 경우는 "해당 없음"이라고 출력해 주세요'처럼 대체 출력처를 함께 적습니다. |
| 잘 진행되고 있는 대화를 이어가면 확인하는 수고가 늘어난다 |
작업의 매듭에서 세션을 종료하고, 다음 작업은 새로운 세션에서 시작합니다. |
| 산출물은 전부 맞지만 거기에 남지 않는 낭비가 쌓여 간다 |
산출물이 갖춰진 시점에 작업 로그(transcript) 쪽을 스크립트로 한 번 집계합니다. |
| 다음 사람을 위해 남긴 지식 메모가 실제와 어긋나며 낡아 간다 |
지식은 문서에 남기지 말고, 자동 테스트의 실패 메시지나 hook의 중단 메시지에 심어 두어 필요한 순간에 출력되게 합니다. |
| 원인을 계속 파고들어, 답이 나온 뒤에도 계속 읽고 있다 |
작업 로그에서 '아무것도 바꾸지 않은 채 이어진 읽기의 연속'을 세어, 파고들기 전에 끝내는 조건을 한 줄로 적습니다. |
| 단가가 가장 저렴한 모델을, 용도를 재지 않고 기본값으로 쓰고 있다 |
같은 과제를 저렴한 모델과 비싼 모델 양쪽에 맡겨, 완료까지의 턴 수와 새로 읽힌 양·재사용한 양(cache read)·쓴 양을 따로 센 뒤 정합니다. |
| 잘 안 되면 구조가 아니라 모델을 올리러 간다 |
같은 과제를 상위 모델과 하위 모델 양쪽에 맡겨, 하위 모델만 실패한 부분을 검사로 만들어 둡니다. |
| 본체에서 끝낼 수 있는 조사를, 혹시 몰라 서브에이전트에 맡기고 있다 |
맡기기 전에 '그 전제를 부모 에이전트가 이미 가지고 있는가'를 봅니다. 가지고 있다면 부모 에이전트에서 계속하고, 가지고 있지 않은 대량 읽기만 sub-agent에 맡깁니다. |
| 일단 4개로 나눠 동시에 실행하고 있다 |
sub-agent 하나에 맡기는 것은 한 번의 응답으로 돌려줄 수 있는 크기까지로 합니다. 비용을 정하는 것은 개수가 아니라, 분할한 뒤의 하나가 부모 에이전트와 몇 번 왕복하는가입니다. |
| 작업 도중에 '여기도 봐 주세요'라고 외부에서 끼워 넣는다 |
작업의 매듭까지 기다린 뒤, 범위를 좁혀서 추가 요청을 넣습니다. AI 본인에게 부족한 점을 물을 때는 '충분하면 충분하다고 적어 주세요'를 반드시 덧붙입니다. 부족한 점을 억지로 만들어 내지 않아도 되는 도망갈 길(escape hatch)을 마련해 두기 위해서입니다. |
| 어떤 모델을 쓸지 비교해서 정하려 한다 |
모델을 비교하기 시작하기 전에, 그 비교가 hook이나 자동 테스트 몇 개 분량의 수고인지 셉니다. 적어 둘 수 있는 구조가 그보다 많다면 비교보다 먼저 그것을 둡니다. |
| '차이가 없었습니다'로 검증을 접으려 한다 |
'차이가 없었습니다'로 접기 전에 두 가지를 셉니다. 집계에서 제외한 결과(실패한 sub-agent 등)가 있다면 되돌려 다시 세고, 모든 조건에서 0인 항목이 절반 이상이면 과제의 표현을 바꿔 다시 측정합니다. |
전체 기사 목차
연재별로 서론부터 최종회까지의 순서입니다.
はじめに —— 3 つの連載を、1 冊に
バイブコーディングにおける読まない技術
- 読まない技術 序論 AIの出力を、もうほとんど読んでいない
- 読まない技術 第1回 テスト結果を読まない技術
- 読まない技術 第2回 メモリを読まない技術
- 読まない技術 第3回 単体テストを読まない技術
- 読まない技術 第4回 スキルを使わない技術
- 読まない技術 第5回 サブエージェントの出力だけは読め
- 読まない技術 第6回 ルールを読まない技術
- 読まない技術 第7回 共有メモリを整理しない技術
- 読まない技術 第8回 修正履歴を読まない技術
- 読まない技術 第9回 引き継ぎを読まない技術
- 読まない技術 第10回 AIに要約しろと言わない技術
- 読まない技術 第11回 口を挟まない技術
- 読まない技術 第12回 作業結果を読まない技術
- 読まない技術 最終回 AIの出力を、ほとんど読まなくなった
AIの意見を聞かない技術
言わない技術
- 言わない技術 序論 AI に指示することが、ほとんどなくなった
- 言わない技術 第1回 検証を指示しない技術
- 言わない技術 第2回 具体的な指示を出さない技術
- 言わない技術 第3回 不具合詳細を書かない技術
- 言わない技術 第4回 計画を書けと言わない技術
- 言わない技術 第5回 念を押さない技術
- 言わない技術 第6回 サブエージェントの出力だけは、細かく指示しろ
- 言わない技術 第7回 AI を問い詰めない技術
- 言わない技術 第8回 AI にダメ出ししない技術
- 言わない技術 第9回 AI に考えさせない技術
- 言わない技術 第10回 質問に答えない技術
- 言わない技術 第11回 AI にレビューをさせない技術
- 言わない技術 最終回 何もしない技術
付録
はじめに —— 前巻の続きを、もう 1 冊に
確かめない技術
動かさない技術
追わない技術
番外編
- 番外編 A-1 整理する技術 —— 記録が増えたときに、何が起きているか
- 番外編 A-2 指示を残す技術 —— 「調べるだけ」が通らなかった日
- 番外編 A-3 参照するタイミングを変える技術 —— 2,000 行の壁
- 番外編 A-4 導出を依頼者の言葉と分ける技術 —— 誰も言っていない条件が、memory に載った日
- 番外編 A-5 memory を要約しない技術 —— 整理から、要約を抜く
- 番外編 A-6 責務で線を引く技術 —— 仕組みが増えたときに、どれを消すか
- 番外編 A-7 読まれたかを確かめる技術 —— 確かめるのをやめて、読めていない形を止めた
- 番外編 A-8 面積で数える技術 —— 読ませた量で数えていたら、102 倍外していました
- 番外編 A-9 ルールを短くする技術 —— 読みに来るのは、止められた直後の人です
- 番外編 B-1 連載を本にする技術 —— 本単位のスイッチでは、足りなかった日
- 番外編 C-1 校正の方法に、先に本編を当てる技術 —— 方法を決める文が、本文と同じ地雷を踏んでいた日
- 番外編 C-2 仕組みと人を分ける技術 —— 検査を置いたその手で、検査の外側で 2 度転んだ日
- 番外編 C-3 要素ごとに観点を変える技術 —— 一様に当てた点検が、要素をまたいだところで数を落としていた
- 番外編 C-4 指示の揺れを、事故として残す技術 —— 事故を見て置いた仕組みは、まだ一度も鳴っていない
- 番外編 C-5 作業の流れを見る技術 —— 終わりにしたつもりの日に、まだ起きていたこと
- 番外編 C-6 作業を進める技術 —— 選ぶ場面が、1 つも残らなかった日
- 番外編 C-7 基準の出どころを見る技術 —— 2 分前に開いたページに、答えが書いてありました
- あとがき —— 本当の事実はどうでもいい話