正在發生這種狀況 → 該怎麼做
不是依標題查找,而是依症狀查找。點選「該怎麼做」下方的連結,就能跳到寫著具體做法的那一節。全部文章的目錄在這個頁面的下方。
本表以 Claude Code(Anthropic 的程式設計代理)為前提。hook、CLAUDE.md、subagent、auto memory 都是它的功能名稱。
| 正在發生這種狀況 | 該怎麼做 |
|---|---|
| AI 每次執行測試,都會有數萬行輸出湧入上下文 |
把測試執行整合成一個包裝腳本(wrapper script),全部輸出寫入日誌檔案,只把失敗的摘要回傳給 AI。 |
| AI 儲存的知識筆記越多,之後每個工作階段要讀的量就越大 |
在寫入 memory 前觸發的 PreToolUse hook 裡讓它先讀一份檢查清單,指示檔案(CLAUDE.md)裡只留「寫之前先讀」這一行。 |
| 測試都通過了,但不知道它們是不是真的有在保護什麼 |
把 mutation testing(故意讓程式碼壞掉,看測試會不會抓到的手法)的方針寫成一份文件,請它檢查測試時就讓它讀這份文件。 |
| 註冊好的 skill,AI 有時候會用、有時候不會用 |
指令仍維持一般腳本的形式,用 PreToolUse hook 擋下錯誤的呼叫方式,並引導它去讀該讀的文件。 |
| 交給 sub-agent 的工作,在完成之前看不到裡面發生了什麼 |
用 YAML 定義可以委派給 sub-agent 的任務、以及啟動前必須準備好的輸入檔案,再用 hook 在啟動前檢查。 |
| 指示檔案裡規則加得越多,先前加的規則就越沒被遵守 |
把每一條「不要做某事」的規則,逐條改寫成能偵測違規的自動化測試(Minitest)。 |
| 並行執行的多個工作階段共用的 memory 變得雜亂,就算讓它讀方針也沒用 |
把同一份方針檔案移到 PostToolUse hook 裡,跟儲存後的 diff 一起顯示出來。讀的內容不變,只改變出現的時機。 |
| 就算寫好同一種失敗的處理方式,AI 下次還是會犯同樣的錯 |
把重試時的方針整理成幾行的檔案,由偵測到失敗的 hook 自動插入。 |
| 讀了交接說明和完成報告,對自己不利的部分還是被漏掉了 |
在完成報告旁邊,每次都附上用 git diff --stat 之類指令機械取得的數字。 |
| 機器算出來的數字,傳到報告時已經變成另一個數字 |
在數字那一行加上固定的前綴,再用 hook 檢查是不是逐字複製過來的。 |
| 在 AI 工作中插話,之後的動作就會亂掉 |
不要在工作中途由人插話,而是讓儲存後立即回傳方針的 PostToolUse hook,以及偵測到失敗就打回的 hook 來介入。人等到一個段落結束再說。 |
| 工作階段結束時,該讀什麼、不用讀什麼並沒有定下來 |
成果物和作業紀錄都不讀,只看測試或 linter 的 exit code 來判斷成功或失敗。 |
| 已經回絕過的提案,在下一個工作階段又被提出來 |
把回絕過的判斷,用固定的格式整理進同一份文件裡。 |
| 明明寫了一行禁止事項,卻還是被過度解讀或過度限縮解讀 |
在彙整回絕判斷的那一份文件(例如 non_goals.md)裡,為每一條禁止事項設一個「理由」的標題,跟結論並列寫出來。 |
| 禁止事項明明寫得沒錯卻沒被遵守,每次都要被問一次 |
在回絕文件裡為每一條禁止事項設一個「適用範圍」的標題,把容易判斷不清的邊界情況一條一條列出來。 |
| 把同一份指示分給多個 sub-agent,回來的格式卻各不相同 |
在可以交給 sub-agent 的任務清單裡,明確寫出啟動前該準備好的輸入檔案。 |
| 沒有自動化測試的禁止事項,只是寫在那裡不斷堆積 |
在回絕文件的清單裡加一個「機器驗證」的標題,逐項標明有沒有對應的自動化測試(Minitest)。 |
| AI 的工作每次都以「請打開畫面確認一下」收尾 |
用 Playwright 準備一個 smoke test,用資料庫裡留下的紀錄判斷成功或失敗,而不是看畫面外觀。 |
| AI 每次講得有點偏,都要自己解釋再糾正 |
不要由人來解釋並糾正偏差,而是把指正寫進 hook 的 stderr(exit 2)和自動化測試的失敗訊息裡,讓它透過這條路徑送達 AI。 |
| 回絕過的判斷清單不斷變長,眼看就要沒人再讀了 |
在回絕文件的最後加一個「未採用方案」的段落,把回絕的提案記錄在那裡。 |
| 指示檔案裡「請務必執行」的項目一直堆在那裡,沒有變少 |
用一個自動化測試去比對:指示檔案裡寫著「務必執行」的指令,是不是也存在於 pre-commit hook 裡。 |
| 連做法都寫清楚交出去了,結果改回來的還是不一樣 |
不去指示步驟,而是按用途定義 sub-agent 啟動前必須存在的輸入檔案。 |
| 每次回報 bug,都要自己把重現步驟和症狀重新寫一遍 |
設置一個 bug 回報表單,人只需要輸入一句症狀描述,URL、操作紀錄、瀏覽器資訊由 JavaScript 自動收集。 |
| 每次都要花力氣打一句「先給我計畫」 |
不需要新的實作。放一份設計文件,AI 就會去讀現有的文件並沿用同樣的格式。 |
| 越希望被遵守的內容寫得越強調,卻不知道有沒有效果 |
不去測量效果,改成計算指示檔案裡帶強調用語的行數,超過基準值就判定失敗的自動化測試(ratchet)。 |
| sub-agent 交回來的成果,格式跟原本預想的不一樣 |
按 sub-agent 的每種用途,把成果物的驗收條件(檔名、格式、必填項目)定義在一份文件裡。 |
| 發現錯誤時,忍不住想追問「你真的有讀過嗎」 |
不去追問,而是把每次請求的第二句話固定成「……不是嗎?」這樣的疑問句模板。 |
| 對回來的答案回一句「不是這個意思」,情況也不會變好 |
不去指出問題,而是把沒有替代方案的禁止事項,透過 PostToolUse hook 跟儲存後的 diff 一起呈現出來。 |
| AI 會像打開過某個檔案一樣,講述它其實沒打開過的內容 |
讓 AI 在被參照的文件和程式碼兩邊都寫上互相對應的標記(marker),再用自動化測試驗證標記是否真的存在。 |
| AI 不斷問「要選 A 還是 B」,手上的工作就停下來了 |
不再當場回答,改成讓選項的判定交給自動化測試或 hook 那一邊來決定。 |
| 讓 AI 做 review,但不知道它到底沒看到什麼 |
用一個從外部計數的自動化測試,抓出那些會走訪檔案卻沒有設下限(assert_operator ... :>=)的自動化測試。 |
| 截圖越存越多,卻分不清哪一張驗證了什麼 |
在確認畫面之前,先回答「要驗證什麼」「為什麼比較便宜的做法不夠用」這兩個問題,並放一份依單元測試 → 整合測試 → E2E 的順序、從便宜的做法先試起的方針文件。 |
| 設了要求先寫聲明的步驟,卻數不出有多少次執行是沒寫聲明就直接跑的 |
在截圖或 E2E 之前先寫一個聲明檔案(例如 tmp/visual_verification.md),說明「要驗證什麼」,把它是否存在當成 PreToolUse hook 的執行條件,沒有聲明檔案就不啟動截圖或 E2E。 |
| 程式碼明明沒有改動,同一批測試卻又跑了一次,白白多等 |
在測試的包裝腳本加上 --last 選項,重新顯示上一次的日誌,省去再跑一次的必要。 |
| 什麼都沒弄壞,卻冒出一大串沒看過的錯誤 |
在測試的包裝腳本裡取得互斥鎖(利用 mkdir 的原子性),拿不到鎖就不執行。 |
| 「測試都通過了」的報告裡,沒寫出哪些部分根本沒跑 |
給耗時的 E2E 貼上區域名稱的標籤,預設 skip,並每次都輸出沒有執行的區域清單。 |
| 指定了進行方式的指示,事後沒辦法判斷有沒有被遵守 |
想讓它遵守步驟時,不要加強指示的措辭,而是改成讓走過該步驟的痕跡留在成果物裡(例如每打開一個檔案就輸出一行)。 |
| 設好的 wrapper,用到一半又被換回原始指令 |
想讓它使用 wrapper 時不要加強指示,而是確認是不是還殘留著非用原始指令不可的理由(也就是 wrapper 的功能是不是有所欠缺)。 |
| 同一個問題問好幾次,每次答案都不一樣,一彙整又漏掉了什麼 |
在把多個回答彙整成一個之前,先依指摘的種類輸出出現次數(幾件裡有幾件提到)。 |
| 寫了「如有需要請執行……」這樣的條件式指示,卻不知道有沒有觸發 |
不寫「如有需要請執行……」這種條件式指示,改用不經過這道工序就無法往下走的 hook 來強制執行。 |
| 回一句「再想一次」答案就會變,卻不知道它是不是真的想通了 |
不用「請再想一次」打回去,而是具體指出是哪一個前提錯了。 |
| 寫了「不要用猜的」之後,AI 變成什麼都不產出就交回來了 |
不只給禁止事項,還要一併寫出替代的輸出方式,例如「不適用時請輸出『無』」。 |
| 順利的對話一直延續下去,需要確認的工作量卻越積越多 |
在任務的分界點結束工作階段,下一個任務用新的工作階段開始。 |
| 成果物全部都正確,但不會留在成果物裡的浪費卻在不斷累積 |
在成果物齊全的那一刻,用腳本對作業紀錄(transcript)那一邊做一次統計。 |
| 為後人留下的知識筆記,會跟實際狀況脫節、變得過時 |
不把知識寫進文件裡留存,而是嵌入自動化測試的失敗訊息或 hook 的中止訊息裡,讓它在需要的那一刻才輸出。 |
| 一直挖下去找原因,答案出來之後還在繼續讀 |
從作業紀錄裡統計「什麼都沒改就連續進行的讀取」,並在開始深挖之前用一行寫清楚結束的條件。 |
| 沒有評估用途,就把單價最便宜的模型當成預設選項 |
把同一個課題分別交給便宜的模型和貴的模型,分別數清楚完成所需的來回次數,以及新讀取量、重複使用量(cache read)、寫入量之後再決定。 |
| 一旦不順利,想到的不是改善機制,而是換更高階的模型 |
把同一個課題同時交給比較貴和比較便宜的模型,把只有便宜那邊沒過的地方做成檢查項留下來。 |
| 本體自己就能查完的東西,卻為了保險起見交給 sub-agent |
交出去之前先看「父 agent 是不是已經有了這個前提」。已經有的話就在父 agent 繼續處理,只把父 agent 還沒有、需要大量讀取的部分交給 sub-agent。 |
| 不假思索就分成 4 份,同時跑起來 |
交給一個 sub-agent 的量,控制在一次回覆就能回傳的大小以內。決定成本的不是數量,而是分割後的每一個要和父 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 分前に開いたページに、答えが書いてありました
- あとがき —— 本当の事実はどうでもいい話