역인덱스

이런 일이 일어나고 있다 → 어떻게 할 것인가

제목이 아니라 증상으로 찾습니다. "어떻게 할 것인가" 아래의 링크로 그 대응법을 적은 절로 이동합니다. 연재 기사 목록은 이 페이지 아래에 있습니다(역인덱스의 바깥입니다).

이 표는 Claude Code(Anthropic의 코딩 에이전트)를 전제로 합니다. hook, CLAUDE.md, subagent, auto memory는 그 기능의 이름입니다.

문제가 생겼을 때 사람이 입력하는 한 문장

「todo를 모두 지워 주세요. https://typing-tube.net/articles/ko/lookup.md을 확인하고, 이 세션을 되짚어 문제가 없는지 점검해 주세요.」

여기서 나오는 것은 문제 목록까지입니다. 어떻게 고칠지는 각자의 프로젝트에 맞춰 정하세요.

markdown으로 열기 권장하는 방법은 자신의 프로젝트에 맞게 다시 만드는 것입니다. 다시 만든 표는 출처 표시 없이 자유롭게 쓸 수 있습니다. 그대로 쓰는 행은 한 줄이라도 CC BY 4.0의 대상이며, 출처 표시가 조건입니다. 뒤를 잇는 담당자가 출처를 따라갈 수 있습니다. AI에 건넬 때는 표를 붙여넣지 말고, 위의 한 문장으로 URL을 건넵니다.

스폰서

이런 일이 일어나고 있다	대응 방안
No.1 AI가 테스트를 실행할 때마다 수만 줄의 출력이 컨텍스트로 흘러들어온다	대응 예:테스트 실행을 래퍼로 모으고, AI에게는 실패 요약만 돌려줍니다. 読まない技術第1回：テスト結果を読まない技術
No.2 AI가 지식 메모를 저장할수록, 이후 모든 세션이 읽어야 할 양이 늘어난다	대응 예:쓰기 전에 체크리스트를 읽히고, 매번 읽는 파일에는 1줄만 둡니다. 読まない技術第2回：メモリを読まない技術
No.3 테스트는 통과하지만, 그것이 실제로 무언가를 지키고 있는지는 알 수 없다	대응 예:AI에게 mutation testing을 지시합니다. 読まない技術第3回：単体テストを読まない技術
No.4 등록한 스킬을 AI가 쓸 때도 있고 안 쓸 때도 있다	대응 예:잘못된 호출을 입구에서 막고, 읽어야 할 문서를 안내합니다. 読まない技術第4回：スキルを使わない技術
No.5 서브에이전트에 맡긴 작업은 끝날 때까지 무슨 일이 일어나는지 보이지 않는다	대응 예:위임해도 되는 일을 목록화하고, 실행 전에 hook으로 확인합니다. 読まない技術第5回：サブエージェントの出力だけは読め
No.6 지시 파일에 규칙을 더할수록 이전에 넣은 규칙이 지켜지지 않는다	대응 예:'~하지 않는다'를 하나씩, 위반을 감지하는 자동 테스트로 바꿔 씁니다. 読まない技術第6回：ルールを読まない技術
No.7 병렬로 실행되는 세션이 공유하는 메모리가 흐트러진다. 방침을 읽혀도 효과가 없다	대응 예:읽히는 내용은 그대로 두고, 저장 직후에 보여주는 시점만 바꿉니다. 読まない技術第7回：共有メモリを整理しない技術
No.8 같은 실패에 대한 대처를 적어 둬도 AI는 다음에 또 같은 실패를 한다	대응 예:실패를 감지한 시점에 재시도 방침을 자동으로 끼워 넣습니다. 読まない技術第8回：修正履歴を読まない技術
No.9 인수인계 글과 완료 보고를 읽어도 불리한 내용이 빠져 있다	대응 예:완료 보고 옆에 기계가 센 수치를 매번 나란히 둡니다. 読まない技術第9回：引き継ぎを読まない技術
No.10 기계가 센 숫자가 보고서에 도달하기 전에 다른 숫자로 바뀌어 있다	대응 예:수치가 담긴 줄에 정해진 머리말을 붙이고, 한 글자도 틀리지 않게 복사됐는지 hook으로 확인합니다. 読まない技術第10回：AIに要約しろと言わない技術
No.11 작업 중인 AI에게 끼어들면 이후 동작이 흐트러진다	대응 예:작업 중에는 끼어들지 않고 매듭까지 기다립니다. 개입은 구조에 맡깁니다. 読まない技術第11回：口を挟まない技術
No.12 세션이 끝날 때 무엇을 읽고 무엇을 읽지 않아도 되는지 정해져 있지 않다	대응 예:산출물도 작업 로그도 읽지 않고, exit code로만 합격 여부를 봅니다. 読まない技術第12回：作業結果を読まない技術
No.13 한번 거절한 제안이 다음 세션에서 다시 나온다	대응 예:기각한 판단을 문서 1개에 모읍니다. AIの意見を聞かない技術第1回：提案を検討しない技術
No.14 금지 사항 한 줄을 적었는데 확대 해석도 축소 해석도 된다	대응 예:금지 사항마다 '이유'를 결론과 나란히 적습니다. AIの意見を聞かない技術第2回：禁止を書かない技術
No.15 금지 사항이 정확히 적혀 있는데도 지켜지지 않는다. 그때마다 문의가 온다	대응 예:금지 사항마다 '적용 범위'를 적고, 애매한 경계를 한 줄씩 듭니다. AIの意見を聞かない技術第3回：禁止ルールを作らない技術
No.16 같은 지시를 여러 서브에이전트에 나눠 주면 돌아오는 형식이 에이전트마다 다르다	대응 예:맡겨도 되는 일 목록에 실행 전 필요한 입력을 명시합니다. AIの意見を聞かない技術第4回：サブエージェントの入力だけは、確かめろ
No.17 자동 테스트가 없는 금지 사항이 문서에만 적힌 채 쌓여 간다	대응 예:금지 사항마다 대응하는 자동 테스트 유무를 명시합니다. AIの意見を聞かない技術第5回：自動テストを書かない技術
No.18 AI의 작업이 매번 '화면을 열어 확인해 주세요'로 끝난다	대응 예:합격 여부는 화면 겉모습이 아니라 남은 데이터로 판정합니다. AIの意見を聞かない技術第6回：AIの確認依頼を断る技術
No.19 AI가 살짝 어긋난 말을 할 때마다 이쪽이 설명하며 고치고 있다	대응 예:사람이 설명해 고치지 않고, hook과 자동 테스트의 실패 메시지로 돌려줍니다. AIの意見を聞かない技術第7回：AIの話を聞かない技術
No.20 거절한 판단의 목록이 계속 늘어나, 언젠가 아무도 읽지 않게 될 것 같다	대응 예:거절한 제안은 끝의 '채택하지 않은 안'으로 보냅니다. AIの意見を聞かない技術第8回：ルールを整理しない技術
No.21 지시 파일의 '반드시 실행하세요'가 줄지 않은 채 남아 있다	대응 예:지시 파일이 '반드시 실행'이라 적은 명령이 구조 쪽에도 있는지 맞춰 봅니다. 言わない技術第1回：検証を指示しない技術
No.22 방법까지 적어서 건넸는데도 그대로 고쳐지지 않는다	대응 예:절차를 지시하지 않고, 시작 전에 필요한 입력만 정합니다. 言わない技術第2回：具体的な指示を出さない技術
No.23 버그를 전달할 때마다 이쪽이 재현 절차와 증상을 매번 적고 있다	대응 예:사람이 적는 것은 증상 한 문장뿐, 나머지는 자동으로 모읍니다. 言わない技術第3回：不具合詳細を書かない技術
No.24 '먼저 계획을 내 주세요'라고 매번 입력하는 수고가 든다	대응 예:설계 문서를 1개 두면 AI가 그 형식을 따릅니다. 言わない技術第4回：計画を書けと言わない技術
No.25 지켜 주길 바라는 줄일수록 강하게 적었는데 효과가 있는지 알 수 없다	대응 예:효과 측정은 그만두고, 강조를 포함한 줄 수를 세어 상한을 정합니다. 言わない技術第5回：念を押さない技術
No.26 서브에이전트의 산출물이 이쪽이 예상한 것과 다른 형식으로 돌아온다	대응 예:산출물의 수용 조건을 넘기기 전에 정해 둡니다. 言わない技術第6回：サブエージェントの出力だけは、細かく指示しろ
No.27 실수를 발견하면 '제대로 읽었나요'라고 추궁하고 싶어진다	대응 예:추궁하지 않고, '~이 아닌가요?'라는 의문형으로 묻습니다. 言わない技術第7回：AI を問い詰めない技術
No.28 돌아온 답에 '그게 아니라'라고 되돌려도 나아지지 않는다	대응 예:사람이 지적하지 않고, 저장 직후 diff와 함께 금지 사항을 냅니다. 言わない技術第8回：AI にダメ出ししない技術
No.29 AI가 열지 않은 파일의 내용을 연 것처럼 이야기한다	대응 예:참조처와 구현 양쪽에 동일한 식별자를 적게 하고, 그 식별자가 실제로 존재하는지 자동 테스트로 확인합니다. 言わない技術第9回：AI に考えさせない技術
No.30 AI로부터 'A와 B 중 어느 쪽으로 할까요'라는 질문을 계속 받아 작업이 멈춘다	대응 예:즉답하지 않고, 선택 기준이 구조 쪽에서 정해지게 합니다. 言わない技術第10回：質問に答えない技術
No.31 AI에게 리뷰를 시키고 있지만 무엇을 보지 않았는지 알 수 없다	대응 예:훑고 있으면서 건수 하한이 없는 자동 테스트를, 밖에서 세어 찾아냅니다. 言わない技術第11回：AI にレビューをさせない技術
No.32 촬영한 이미지가 쌓여 가지만 어느 것이 무엇을 확인한 한 장인지 알 수 없다	대응 예:찍기 전에 '무엇을 확인하나'를 적게 하고, 저렴한 수단부터 시도합니다. 確かめない技術第1回：スクリーンショットを撮らない技術
No.33 선언하는 공정을 두었는데 선언 없이 실행된 횟수를 셀 수 없다	대응 예:촬영이나 E2E 전에 '무엇을 확인하나'를 적게 하고, 안 적으면 실행하지 않습니다. 確かめない技術第2回：宣言を信じない技術
No.34 코드를 바꾸지 않았는데 같은 테스트가 실행되어 그만큼 기다리게 된다	대응 예:이전 로그를 다시 볼 수 있게 해, 같은 실행을 반복하지 않습니다. 確かめない技術第3回：テストを再実行しない技術
No.35 아무것도 망가뜨리지 않았는데 낯선 에러가 잔뜩 나열된다	대응 예:테스트 실행에 배타 lock을 걸어, 얻지 못하면 실행하지 않습니다. 確かめない技術第4回：偽の失敗を読まない技術
No.36 '테스트는 통과했습니다'라는 보고에 실행되지 않은 부분이 적혀 있지 않다	대응 예:무거운 테스트는 기본으로 건너뛰고, 건너뛴 영역 목록을 매번 냅니다. 確かめない技術第5回：全部走らせない技術
No.37 진행 방식을 지정한 지시가 지켜졌는지 나중에 구별할 수 없다	대응 예:지시를 강화하지 않고, 절차를 거친 흔적이 산출물에 남게 합니다. 動かさない技術第1回：手順を守らせない技術
No.38 만들어 둔 래퍼가 어느 순간부터 일반 명령으로 되돌아가 있다	대응 예:지시를 강화하지 않고, 기본 명령으로 돌아갈 이유가 남았는지 봅니다. 動かさない技術第2回：ラッパーを使わせない技術
No.39 같은 질문을 여러 번 던지면 답이 매번 다르다. 취합하면 무언가가 사라진다	대응 예:취합 전에 지적 종류마다 몇 건 중 몇 건이 들었는지 냅니다. 動かさない技術第3回：集めない技術
No.40 '필요하면 ~해 주세요'라고 적은 줄이 실제로 발동했는지 알 수 없다	대응 예:'필요하면'이라 적지 않고, 그 공정을 거쳐야 다음으로 넘어가게 합니다. 動かさない技術第4回：役に立たない技術
No.41 '다시 한번 생각해 주세요'라고 돌려주면 답은 바뀌지만 납득했는지는 알 수 없다	대응 예:돌려보내지 않고, 어떤 전제가 틀렸는지 구체적으로 지적합니다. 動かさない技術第5回：選び直させない技術
No.42 '추측하지 마세요'라고 적었더니 AI가 아무것도 만들지 않고 돌아오게 되었다	대응 예:금지만 전달하지 않고, '해당 없음'이라 적을 도망길을 함께 둡니다. 動かさない技術第6回：逃げ道を塞がない技術
No.43 잘 진행되고 있는 대화를 이어가면 확인하는 수고가 늘어난다	대응 예:매듭에서 세션을 끝내고, 다음은 새 세션에서 시작합니다. 動かさない技術第7回：セッションを続けない技術
No.44 산출물은 전부 맞지만 거기에 남지 않는 낭비가 쌓여 간다	대응 예:산출물이 갖춰진 시점에 작업 로그 쪽을 한 번 집계합니다. 動かさない技術第8回：成果物で判断しない技術
No.45 다음 사람을 위해 남긴 지식 메모가 실제와 어긋나며 낡아 간다	대응 예:지식은 문서에 남기지 않고, 멈췄을 때의 메시지에 심어 둡니다. 動かさない技術第9回：知見を残さない技術
No.46 원인을 계속 파고들어, 답이 나온 뒤에도 계속 읽고 있다	대응 예:아무것도 안 바꾼 채 이어진 읽기를 세어, 파고들기 전에 끝낼 조건을 적습니다. 追わない技術第1回：深追いしない技術
No.47 단가가 가장 저렴한 모델을, 용도를 재지 않고 기본값으로 쓰고 있다	대응 예:같은 과제를 저렴한 쪽과 비싼 쪽 양쪽에 맡겨, 턴 수와 양을 세어 정합니다. 追わない技術第2回：一番安いモデルを使わない技術
No.48 잘 안 되면 구조가 아니라 모델을 올리러 간다	대응 예:같은 과제를 양쪽 모델에 맡겨, 저렴한 쪽만 실패한 부분을 자동 테스트로 만듭니다. 追わない技術第3回：最新モデルを使わない技術
No.49 본체에서 끝낼 수 있는 조사를, 혹시 몰라 서브에이전트에 맡기고 있다	대응 예:부모가 이미 가진 전제면 맡기지 않고, 없는 읽기만 맡깁니다. 追わない技術第4回：サブエージェントを使わない技術
No.50 일단 4개로 나눠 동시에 실행하고 있다	대응 예:서브에이전트에 맡기는 건 응답 1번 분량까지. 비용은 개수가 아니라 왕복 횟수로 정합니다. 追わない技術第5回：エージェントチームを使わない技術
No.53 작업 도중에 '여기도 봐 주세요'라고 외부에서 끼워 넣는다	대응 예:매듭까지 기다리고 범위를 좁혀 부탁합니다. '충분하면 충분하다고 적어 주세요'를 덧붙입니다. 追わない技術第6回：途中でレビューさせない技術
No.52 어떤 모델을 쓸지 비교해서 정하려 한다	대응 예:비교를 시작하기 전에, 그 비교가 구조 몇 개 분량의 수고인지 셉니다. 追わない技術第7回：モデルを選ばない技術
No.51 '차이가 없었습니다'로 검증을 접으려 한다	대응 예:접기 전에 집계에서 뺀 결과와, 전 조건에서 0인 항목을 다시 셉니다. 追わない技術第8回：諦めさせない技術
No.54 어느 날부터 AI의 작업 방식이 달라졌다. 지시도 설정도 바꾸지 않았는데	대응 예:제품 쪽 지시와 충돌하는 건 적지 않고, 그 지시가 정하지 않은 것만 보탭니다. 진행 방식을 바꿀 땐 설정을 전환합니다. 番外編 A-7 読まれたかを確かめる技術 —— 確かめるのをやめて、読めていない形を止めた

연재 기사 목록

여기서부터는 역인덱스가 아니라 연재 기사로 가는 링크입니다. 연재별로 서론부터 최종회까지의 순서입니다.

이런 일이 일어나고 있다 → 어떻게 할 것인가

연재 기사 목록

はじめに —— 3 つの連載を、1 冊に

バイブコーディングにおける読まない技術

AIの意見を聞かない技術

言わない技術

付録

はじめに —— 前巻の続きを、もう 1 冊に

確かめない技術

動かさない技術

追わない技術

番外編