---
title: "AI coding troubles, by symptom (what is happening → what to do)"
author: garplab
publisher: TypingTube
license: CC BY 4.0
license_url: https://creativecommons.org/licenses/by/4.0/
license_scope: The whole body of this document (excluding this frontmatter)
language: en
canonical: https://typing-tube.net/articles/en/lookup
---

# AI coding troubles, by symptom (what is happening → what to do)

A table you look up by symptom rather than by title. The "Details" link goes to the article section that describes the remedy with measurements.

This table assumes Claude Code (Anthropic's coding agent). hook, CLAUDE.md, subagent and auto memory are the names of its features.

| What is happening | What to do | Claude Code features | Details |
|---|---|---|---|
| Every time the AI runs the tests, tens of thousands of output lines flood the context | Route all test runs through a single wrapper script, write the full output to a log file, and return only a summary of the failures to the AI. | `context window` / `wrapper script` / `fixed-prefix count line ([observed])` | [The Art of Not Reading #1: The Art of Not Reading Test Output](https://typing-tube.net/articles/en/cd93e0c5cac832#cd93e0c5cac832-9fe639a8) |
| The more knowledge notes the AI saves, the more every future session has to read | Use a PreToolUse hook that runs right before a memory write to make the AI read a checklist first, and keep the instruction file (CLAUDE.md) down to a single line: "read before you write." | `MEMORY.md` / `loaded at session start` / `context rot` | [読まない技術 第2回：メモリを読まない技術](https://typing-tube.net/articles/384477896fec22#384477896fec22-4eea2df8) |
| The tests pass, but it's unclear whether they actually protect anything | Write a one-page policy on mutation testing (deliberately breaking the code to see whether the tests catch it), and have the AI read it whenever you ask it to review the tests. | `mutation testing` / `positive control` / `vacuous truth` | [読まない技術 第3回：単体テストを読まない技術](https://typing-tube.net/articles/e4ad91d2fd6c67#e4ad91d2fd6c67-4eea2df8) |
| The AI sometimes uses a registered skill and sometimes doesn't | Keep the command as an ordinary script, block incorrect invocations with a PreToolUse hook, and point the AI to the documentation it should read. | `PreToolUse hook (Bash matcher)` / `hook stderr + exit 2` / `mission` | [読まない技術 第4回：スキルを使わない技術](https://typing-tube.net/articles/8f9ae8791b448d#8f9ae8791b448d-4eea2df8) |
| Once work is handed to a sub-agent, you can't see what's happening until it finishes | Define, in YAML, which tasks may be delegated to a sub-agent and which input files must exist before launch, then check that with a hook before it starts. | `subagent (Agent tool)` / `subagent (no parent context)` / `contract (inputs / outputs / acceptance)` | [読まない技術 第5回：サブエージェントの出力だけは読め](https://typing-tube.net/articles/62f714d7c2b599#62f714d7c2b599-7e6cc5ce) |
| The more rules you add to the instruction file, the less the earlier rules get followed | Rewrite each "don't do X" rule, one at a time, as an automated test (Minitest) that can detect a violation. | `CLAUDE.md` / `Claude Code hooks (PreToolUse / PostToolUse / Stop / SubagentStop)` / `hook contract (proof of reading)` | [読まない技術 第6回：ルールを読まない技術](https://typing-tube.net/articles/569d598941c00f#569d598941c00f-4eea2df8) |
| Memory shared across parallel sessions gets messy, and having them read the policy doesn't help | Move the same policy file into a PostToolUse hook and show it alongside the diff right after the save. Keep the content unchanged — only change the timing. | `MEMORY.md` / `concurrent test runs` / `hooks / automated tests` | [読まない技術 第7回：共有メモリを整理しない技術](https://typing-tube.net/articles/83c46d1e6b2591#83c46d1e6b2591-4eea2df8) |
| Even after writing down how to handle a failure, the AI makes the same mistake again next time | Summarize the retry policy in a few lines in a file, and have a hook that detects the failure insert it automatically. | `auto memory (feedback_*)` | [読まない技術 第8回：修正履歴を読まない技術](https://typing-tube.net/articles/f7c9c30f567aee#f7c9c30f567aee-4eea2df8) |
| Even reading the handoff notes and completion report, the inconvenient parts are missing | Every time, place mechanically obtained numbers — from something like git diff --stat — right next to the completion report. | `handoff` / `test summary line (full log in a file)` | [読まない技術 第9回：引き継ぎを読まない技術](https://typing-tube.net/articles/a43b57a94d2216#a43b57a94d2216-4eea2df8) |
| Numbers the machine counted turn into different numbers by the time they reach the report | Attach a fixed prefix to the line with the number, and have a hook check that it was copied verbatim. | `machine-counted numbers ([observed] / git diff --stat)` / `test summary line (full log in a file)` / `self-report (bias toward completion)` | [読まない技術 第10回：AIに要約しろと言わない技術](https://typing-tube.net/articles/yomanai-10-no-summary#yomanai-10-no-summary-4eea2df8) |
| Interrupting the AI mid-task throws off everything it does afterward | Instead of a person interrupting mid-task, let a PostToolUse hook that returns the policy right after a save, and a hook that detects failure and sends the work back, do the intervening. The person waits for a natural break. | `user message during a task` / `recency` / `context window` | [読まない技術 第11回：口を挟まない技術](https://typing-tube.net/articles/6c6d2e4f80a649#6c6d2e4f80a649-e4cb60ea) |
| At the end of a session, it's undecided what needs reading and what doesn't | Don't read the deliverable or the work log — judge pass or fail solely by the exit code of the tests or linter. | `self-report (bias toward completion)` / `machine-counted numbers ([observed] / git diff --stat)` / `exit code (pass / fail)` | [読まない技術 第12回：作業結果を読まない技術](https://typing-tube.net/articles/1769779c2f1b4b#1769779c2f1b4b-4eea2df8) |
| A proposal you already rejected comes back again in the next session | Consolidate every rejected decision into a single document, using a fixed format. |  | [AIの意見を聞かない技術 第1回：提案を検討しない技術](https://typing-tube.net/articles/kikanai-01-no-review#kikanai-01-no-review-9e2b31e8) |
| Even with a one-line prohibition written down, it gets both over- and under-interpreted | In the single document that collects rejected decisions (for example non_goals.md), add a "reason" heading to each prohibition, next to the conclusion. |  | [AIの意見を聞かない技術 第2回：禁止を書かない技術](https://typing-tube.net/articles/kikanai-02-reason#kikanai-02-reason-2973ce11) |
| The prohibition is written correctly but not followed, and each time someone asks about it | In the rejected-decisions document, add a "scope" heading to each prohibition and list, one line at a time, the borderline cases that cause confusion. | `gap between goal pressure and spec` / `rule-to-test mapping` | [AIの意見を聞かない技術 第3回：禁止ルールを作らない技術](https://typing-tube.net/articles/kikanai-03-scope#kikanai-03-scope-1db3e01a) |
| Give the same instructions to several sub-agents and each one comes back in a different shape | In the list of tasks that may be delegated to a sub-agent, explicitly state the input files that must be prepared before launch. | `subagent mission catalog + launch hook` / `contract (inputs / outputs / acceptance)` / `required input files` | [AIの意見を聞かない技術 第4回：サブエージェントの入力だけは、確かめろ](https://typing-tube.net/articles/kikanai-04-subagent-input#kikanai-04-subagent-input-0b96e6a8) |
| Prohibitions with no automated test pile up, staying nothing more than text on a page | In the rejected-decisions document, add a "machine-checked" heading to the list and mark, item by item, whether a corresponding automated test (Minitest) exists. | `probabilistic compliance (p^n)` | [AIの意見を聞かない技術 第5回：自動テストを書かない技術](https://typing-tube.net/articles/kikanai-05-machine-check#kikanai-05-machine-check-0f82d02b) |
| Every piece of AI work ends with "please open the screen and check it" | Prepare a single Playwright smoke test, and judge pass or fail by the record left in the database rather than by how the screen looks. | `automatic error report from users` | [AIの意見を聞かない技術 第6回：AIの確認依頼を断る技術](https://typing-tube.net/articles/kikanai-06-production#kikanai-06-production-6c41de4e) |
| Every time the AI says something slightly off, you're the one explaining and fixing it | Instead of a person explaining and correcting each slip, write the correction into a hook's stderr (exit 2) and into automated-test failure messages, so that is the route by which it reaches the AI. | `SendMessage (retry)` | [AIの意見を聞かない技術 第7回：AIの話を聞かない技術](https://typing-tube.net/articles/kikanai-07-no-listening#kikanai-07-no-listening-f900b392) |
| The list of rejected decisions keeps growing and looks headed for the point where nobody reads it | Add a "not adopted" section at the end of the rejected-decisions document, and record rejected proposals there. | `MEMORY.md` / `context rot` | [AIの意見を聞かない技術 第8回：ルールを整理しない技術](https://typing-tube.net/articles/kikanai-08-no-inventory#kikanai-08-no-inventory-d72023ae) |
| The instruction file's "always run this" lines never seem to shrink | Use an automated test to cross-check whether every command the instruction file marks "always run" also exists in a pre-commit hook. | `CLAUDE.md` / `Minitest` / `hooks / automated tests` | [言わない技術 第1回：検証を指示しない技術](https://typing-tube.net/articles/iwanai-01-no-verification#iwanai-01-no-verification-f9f3539e) |
| Even after writing out exactly how to do it, the fix doesn't come back that way | Instead of dictating the procedure, define, per use case, the input files that must exist before a sub-agent can be launched. | `per-mission guide document` / `presupposition` / `launch without a contract` | [言わない技術 第2回：具体的な指示を出さない技術](https://typing-tube.net/articles/iwanai-02-no-procedure#iwanai-02-no-procedure-e45dd403) |
| Reporting a bug means writing out the steps and symptoms yourself, every single time | Set up a bug report form where the person only types one sentence describing the symptom, and let JavaScript automatically collect the URL, action history, and browser information. | `bug report form (JS collects URL / actions / browser)` | [言わない技術 第3回：不具合詳細を書かない技術](https://typing-tube.net/articles/iwanai-03-no-bug-details#iwanai-03-no-bug-details-e45dd403) |
| Typing "give me a plan first" every time is its own recurring chore | No new implementation is needed. Put a single design document in place, and the AI will read the existing documents and follow the same format. |  | [言わない技術 第4回：計画を書けと言わない技術](https://typing-tube.net/articles/iwanai-04-no-plan-request#iwanai-04-no-plan-request-be44c158) |
| The lines you most want followed are written the most emphatically, yet you can't tell whether that helps | Stop trying to measure the effect — instead count the lines in the instruction file that use emphasis, and add an automated test (a ratchet) that fails once that count exceeds a threshold. | `emphasis count in CLAUDE.md` / `sycophancy` / `Dir.glob scan` | [言わない技術 第5回：念を押さない技術](https://typing-tube.net/articles/iwanai-05-no-emphasis#iwanai-05-no-emphasis-abb803f1) |
| A sub-agent's deliverable comes back in a different shape than you expected | For each sub-agent use case, define the acceptance criteria for its deliverable — file name, format, required fields — in a single document. | `subagent (Agent tool)` / `contract (inputs / outputs / acceptance)` / `self-report (bias toward completion)` | [言わない技術 第6回：サブエージェントの出力だけは、細かく指示しろ](https://typing-tube.net/articles/iwanai-06-subagent-output#iwanai-06-subagent-output-633e9bd9) |
| Finding a mistake makes you want to demand, "did you actually read this?" | Instead of demanding an answer, fix the second sentence of every request to the question template "isn't it the case that ...?". | `sycophancy` | [言わない技術 第7回：AI を問い詰めない技術](https://typing-tube.net/articles/iwanai-07-no-interrogation#iwanai-07-no-interrogation-293fc181) |
| Replying "that's not it" to the answer you got back doesn't make it any better | Instead of pointing it out yourself, present prohibitions that come with no alternative through a PostToolUse hook, shown alongside the diff right after the save. | `SendMessage (retry)` / `guarded_by + marker` / `over-triggering` | [言わない技術 第8回：AI にダメ出ししない技術](https://typing-tube.net/articles/iwanai-08-no-criticism#iwanai-08-no-criticism-e4cb60ea) |
| The AI talks about a file's contents as though it had opened it, when it hasn't | Have the AI write matching markers in both the referenced document and the code, and verify with an automated test that the markers actually exist. | `hallucination` / `escape hatch (SKIP_*= / --no-verify)` / `marker` | [言わない技術 第9回：AI に考えさせない技術](https://typing-tube.net/articles/iwanai-09-no-guessing#iwanai-09-no-guessing-61ef1df2) |
| The AI keeps asking "A or B?" and work grinds to a halt while you decide | Stop answering on the spot — arrange for the choice to be decided by an automated test or a hook instead. |  | [言わない技術 第10回：質問に答えない技術](https://typing-tube.net/articles/iwanai-10-no-answering#iwanai-10-no-answering-0efdc39b) |
| The AI is doing the review, but it's unclear what it isn't looking at | Use an outside automated test that counts things to catch any automated test that scans files but has no lower-bound assertion on the count (e.g. assert_operator ... :>=). | `Minitest` / `vacuous truth` / `Dir.glob scan` | [言わない技術 第11回：AI にレビューをさせない技術](https://typing-tube.net/articles/iwanai-11-no-review#iwanai-11-no-review-659e23ad) |
| Screenshots keep piling up, but it's unclear which one verified what | Before checking the screen, require answers to two questions — "what is being verified" and "why a cheaper method won't do" — and keep a one-page guideline for trying the cheapest option first, in the order unit test, integration test, then E2E. | `Playwright screenshot` / `verification ladder (unit → integration → E2E)` / `verification declaration file + PreToolUse hook` | [確かめない技術 第1回：スクリーンショットを撮らない技術](https://typing-tube.net/articles/tashikamenai-01-no-screenshots#tashikamenai-01-no-screenshots-d3d345e4) |
| A step that requires writing something down is in place, but you can't count how many runs skipped it | Before a screenshot or an E2E run, have a declaration file written that states what is being verified (for example tmp/visual_verification.md), make its existence a precondition of a PreToolUse hook, and let the screenshot or E2E refuse to start without it. | `verification declaration file + PreToolUse hook` / `Claude Code hooks (PreToolUse / PostToolUse / Stop / SubagentStop)` / `PreToolUse hook (Bash matcher)` | [確かめない技術 第2回：宣言を信じない技術](https://typing-tube.net/articles/tashikamenai-02-declaration-guard#tashikamenai-02-declaration-guard-4eea2df8) |
| The same test runs again even though the code hasn't changed, and you wait for it anyway | Add a --last option to the test wrapper script that replays the previous log, so a rerun isn't needed. | `--last (replay the previous result)` / `mtime check` / `expensive entry point (screenshot / E2E / production)` | [確かめない技術 第3回：テストを再実行しない技術](https://typing-tube.net/articles/tashikamenai-03-no-rerun#tashikamenai-03-no-rerun-ffaed55c) |
| Nothing was broken, yet a wall of unfamiliar errors shows up | Have the test wrapper script take an exclusive lock (using the atomicity of mkdir), and refuse to run if it can't acquire one. | `flaky failure` / `mkdir lock` / `concurrent test runs` | [確かめない技術 第4回：偽の失敗を読まない技術](https://typing-tube.net/articles/tashikamenai-04-false-failures#tashikamenai-04-false-failures-a29d752a) |
| A report saying "the tests pass" doesn't mention the parts that never ran | Tag heavy E2E tests by area name and skip them by default, and print the list of areas that didn't run every time. | `E2E area (E2E=<area>)` / `skipped-area count line` / `pass / fail by DB record` | [確かめない技術 第5回：全部走らせない技術](https://typing-tube.net/articles/tashikamenai-05-selective-e2e#tashikamenai-05-selective-e2e-bb037847) |
| There's no way to tell afterward whether an instruction specifying how to proceed was actually followed | When you want a procedure followed, don't strengthen the wording of the instruction — instead change it so that following the procedure leaves a trace in the deliverable (for example, having it print one line for every file it opens). | `sycophancy` / `file existence check` / `tool_use count` | [動かさない技術 第1回：手順を守らせない技術](https://typing-tube.net/articles/ugokasanai-01-no-procedure-enforcement#ugokasanai-01-no-procedure-enforcement-129e096a) |
| A wrapper you put in place gets abandoned partway through, back to the raw command | When you want the wrapper used, don't strengthen the instruction — check instead whether there's still a reason to fall back to the raw command, meaning the wrapper is missing some capability. | `wrapper script` / `the raw command the model defaults to` / `workaround after exit 2` | [動かさない技術 第2回：ラッパーを使わせない技術](https://typing-tube.net/articles/ugokasanai-02-no-wrapper-enforcement#ugokasanai-02-no-wrapper-enforcement-129e096a) |
| Asking the same question repeatedly gets a different answer each time, and summarizing loses something | Before merging multiple answers into one, print how often each type of finding appeared — how many out of how many raised it. | `one subagent run` / `answer key` | [動かさない技術 第3回：集めない技術](https://typing-tube.net/articles/ugokasanai-03-no-aggregation#ugokasanai-03-no-aggregation-f7af24f4) |
| There's no way to tell whether a line that says "do X if needed" ever actually fired | Don't write conditional instructions like "do X if needed" — instead enforce the step with a hook that blocks progress until it's done. | `rule-to-test mapping` / `Claude Code hooks (PreToolUse / PostToolUse / Stop / SubagentStop)` / `file existence check` | [動かさない技術 第4回：役に立たない技術](https://typing-tube.net/articles/ugokasanai-04-no-conditional-instruction#ugokasanai-04-no-conditional-instruction-e45dd403) |
| Saying "think about it again" changes the answer, but it's unclear whether the AI is actually convinced | Instead of sending it back with "think about it again," point out specifically which premise is wrong. | `sycophancy` / `SendMessage (retry)` / `guarded_by + marker` | [動かさない技術 第5回：選び直させない技術](https://typing-tube.net/articles/ugokasanai-05-no-reselection#ugokasanai-05-no-reselection-88f30148) |
| Writing "don't guess" made the AI start coming back having built nothing at all | Don't hand over only a prohibition — pair it with a fallback output, such as "if nothing applies, output 'not applicable'". | `escape hatch (SKIP_*= / --no-verify)` / `hooks + automated tests + ratchet` / `hallucination` | [動かさない技術 第6回：逃げ道を塞がない技術](https://typing-tube.net/articles/ugokasanai-06-no-blocking-exits#ugokasanai-06-no-blocking-exits-420ce5bc) |
| The longer a conversation that's going well continues, the more effort it takes to verify | End the session at each task boundary, and start the next task in a new session. | `context window` / `input / output / cache read tokens` / `sycophancy` | [動かさない技術 第7回：セッションを続けない技術](https://typing-tube.net/articles/ugokasanai-07-no-long-sessions#ugokasanai-07-no-long-sessions-a59368ec) |
| Every deliverable is correct, yet waste that never shows up in them keeps building up | Once the deliverables are complete, run a script to tally the work log (transcript) itself, once. | `file existence check` / `machine-counted numbers ([observed] / git diff --stat)` / `Dir.glob scan` | [動かさない技術 第8回：成果物で判断しない技術](https://typing-tube.net/articles/ugokasanai-08-no-artifact-judgment#ugokasanai-08-no-artifact-judgment-588e1e37) |
| Notes left behind for the next person drift out of sync with reality and go stale | Don't leave the knowledge in a document — embed it in an automated test's failure message or a hook's stop message, so it surfaces exactly when it's needed. | `handoff` / `MEMORY.md` / `mtime check` | [動かさない技術 第9回：知見を残さない技術](https://typing-tube.net/articles/ugokasanai-09-no-knowledge-notes#ugokasanai-09-no-knowledge-notes-cb7946f3) |
| Digging into the cause continues, and the reading keeps going even after the answer is found | Count, from the work log, runs of reads that never changed anything, and write a one-line stopping condition before you start digging. | `machine-counted numbers ([observed] / git diff --stat)` / `input / output / cache read tokens` / `Dir.glob scan` | [追わない技術 第1回：深追いしない技術](https://typing-tube.net/articles/owanai-01-no-deep-dive#owanai-01-no-deep-dive-36119a54) |
| The lowest-priced model is made the default without measuring whether it actually fits the use case | Give the same task to both the cheaper and the more expensive model, then decide only after separately counting the turns to completion and the amount newly read, reused (cache read), and written. | `rule-to-test mapping` / `Minitest` / `machine-counted numbers ([observed] / git diff --stat)` | [追わない技術 第2回：一番安いモデルを使わない技術](https://typing-tube.net/articles/owanai-02-no-cheapest-model#owanai-02-no-cheapest-model-15eb5702) |
| When something isn't working, the fix reached for is a bigger model rather than a better mechanism | Give the same task to both the more expensive and the cheaper model, and turn the spots where only the cheaper one fails into a permanent check. | `rule-to-test mapping` / `Minitest` / `machine-counted numbers ([observed] / git diff --stat)` | [追わない技術 第3回：最新モデルを使わない技術](https://typing-tube.net/articles/owanai-03-no-latest-model#owanai-03-no-latest-model-eec0ed05) |
| Research that the main session could finish on its own gets handed to a sub-agent just in case | Before delegating, check whether the parent agent already has that context. If it does, keep going in the parent agent; hand a subagent only the bulk of the reading it doesn't already have. | `subagent (Agent tool)` / `context window` / `input / output / cache read tokens` | [追わない技術 第4回：サブエージェントを使わない技術](https://typing-tube.net/articles/owanai-04-no-subagent#owanai-04-no-subagent-efc681e6) |
| The default move is to split the work into four and run them all at once, just because | Give each subagent only as much as it can return in a single response. What sets the cost isn't how many subagents there are, but how many round trips each split-off subagent makes with the parent agent. | `subagent (Agent tool)` / `input / output / cache read tokens` / `machine-counted numbers ([observed] / git diff --stat)` | [追わない技術 第5回：エージェントチームを使わない技術](https://typing-tube.net/articles/owanai-05-no-agent-team#owanai-05-no-agent-team-037074af) |
| "Take a look at this too" gets injected from outside partway through the work | Wait for a natural break in the work, then bring in the extra request with a narrowed scope. When asking the AI itself about gaps, always add: "if it's sufficient, say so explicitly." That gives it an escape hatch, so it doesn't have to invent a gap. | `subagent (Agent tool)` / `instruction priority (position / recency / system vs user)` / `over-triggering` | [追わない技術 第6回：途中でレビューさせない技術](https://typing-tube.net/articles/owanai-06-no-midway-review#owanai-06-no-midway-review-542ab968) |
| Which model to use is being decided by comparing them head to head | Before starting to compare models, count how many hooks or automated tests the comparison would cost in effort. If you can write down more mechanisms than that, put those in place before comparing. | `input / output / cache read tokens` / `rule-to-test mapping` | [追わない技術 第7回：モデルを選ばない技術](https://typing-tube.net/articles/owanai-07-no-model-choice#owanai-07-no-model-choice-41136ab2) |
| "There was no difference" is used as the reason to wrap up the verification | Before wrapping up with "there was no difference", count two things: if any results were excluded from the tally (such as failed subagents), put them back and recount; if more than half the items score zero under every condition, rephrase the task and measure again. | `machine-counted numbers ([observed] / git diff --stat)` / `vacuous truth` | [追わない技術 第8回：諦めさせない技術](https://typing-tube.net/articles/owanai-08-no-giving-up#owanai-08-no-giving-up-82156f07) |

---

Source: "AI coding troubles, by symptom (what is happening → what to do)" by garplab (TypingTube) https://typing-tube.net/articles/en/lookup / CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)
You may copy, republish, translate and use this table commercially as long as you credit the source. The latest version and the full articles are at the URL above.