ローカル coding agent が失敗したら、最初にモデル、量子化、コンテキスト長、ツール環境をまとめて変えないでください。同じ壊れた修正でも、原因は三つに分かれます。モデルや runtime の精度が足りない、必要な証拠がコンテキストに入っていない、または Harness が編集、コマンド、テスト、フィードバックを正しく回せていない、という三層です。
| 症状 | 先に見る層 | 確かめ方 | 最初の修正 |
|---|---|---|---|
| 小さな変更でも推論が崩れる | モデル、runtime、量子化 | 余計なファイルを入れず、より高精度のローカル設定または hosted 基準で同じ小タスクを走らせる | 量子化、runtime、またはそのタスク用のモデルを変える |
| 関連ファイル、規則、過去の決定を失う | コンテキスト選択 | 対象ファイル、隣接 interface、失敗テスト、必須規則だけでクリーンに再実行する | コンテキストを狭め、正確な証拠を固定する |
| 説明は正しいのに patch、command、test で失敗する | Harness と tool feedback | 予定された patch、実際の tool log、command output、test result を比べる | edit 適用、権限、作業ディレクトリ、schema、test hook、retry を直す |
| 複数設定を変えた後だけ動く | まだ診断できていない | 同じ repo、同じ task、clean session、固定 files に戻し一つだけ変える | 再度コントロールを取ってから調整する |
Hosted 環境は優劣の証明ではなく、基準線として使います。同じ最小タスクが hosted で通り、ローカルで落ちるなら、ローカル側をまだ層別に調べます。両方で落ちるなら、タスク説明、対象ファイル、受け入れ条件が足りない可能性があります。公平な比較の後も品質、速度、tool reliability が届かない場合は、そのタスクのローカル調整を止めます。
素早い三層診断
ローカル coding agent を一つのモデルとして扱うと、原因を見失います。実際には、モデル重み、推論 runtime、量子化、KV cache、ファイル選択、規則、会話履歴、tool call、編集適用、shell command、test、権限、review signal が一つの作業ループを作っています。
| 層 | 受け持つもの | 失敗の見え方 | まだ言えないこと |
|---|---|---|---|
| モデルと runtime | model size、量子化、KV cache、CPU/GPU 配置、serving defaults | 小タスクで推論が弱い、structured output が崩れる、decode が遅い、context が伸びると OOM | ローカルモデル全体が悪いとは言えない |
| コンテキストと retrieval | 読ませる files、rules、history、summary、tool definitions、logs | 違うファイルを編集する、制約を忘れる、近くの symbol を見落とす | 窓を広げれば直るとは言えない |
| Harness と feedback | edit application、command runner、permissions、schemas、tests、sensors、retry | 考えは正しいが patch、cwd、test、permission で崩れる | モデルが解けなかったとは言えない |
勝負は設定名ではなく、同じ条件で一層だけ変える比較です。失敗を最小化し、観測と解釈を分けてください。
一つの変数だけを変える
比較条件を固定します。同じリポジトリ、同じタスク、同じ指示、同じファイル集合、クリーンなセッションです。最小の再現例は、失敗する test、一つの悪い edit、一つの command wrapper、一つの permission error、または agent が毎回読み違える file で十分です。
記録する項目は、model、quantization、runtime、context length、読み込ませた files、Harness、command output、test result、最終 patch です。そのうえで、変えるのは一つだけです。
| 変えるもの | 改善したら示すこと | 示さないこと | | --- | --- | --- | --- | | より高精度、より大きなローカルモデル、または hosted baseline | model/runtime がボトルネックの可能性 | context と Harness が健全とは限らない | | 対象ファイルだけの clean session | 広い context、古い履歴、retrieval が邪魔していた可能性 | 小さい model が full repo に十分とは限らない | | 同じ model を別 Harness で実行 | tool loop、edit application、test、permissions が関与した可能性 | 別 Harness が全タスクで優れているとは限らない | | model には patch 案だけを書かせ、人が適用して test | idea は正しいが execution が壊れた可能性 | 今後も人が毎回救うべきとは限らない |
ローカルとクラウドの使い分けは、失敗層が見えた後に判断します。必要なら local versus cloud coding agents を参照してください。
量子化や runtime を疑う場面
コンテキストや tool が原因になる前に小さな task が壊れるなら、model/runtime を疑います。二段階の edit を保持できない、短い tool JSON が壊れる、単純な syntax error を繰り返す、sequence が長くなると急に遅くなる、prefill で memory pressure が出る、といった症状です。
量子化は memory と計算量を下げますが、コード生成の精度を削ることもあります。ただし「Q4 で失敗した」だけで「ローカルは無理」とは言えません。同じ tiny task を、より保守的な量子化、coding 向きの大きなモデル、または hosted baseline で比べます。余計な files は入れず、retrieval の影響を混ぜないことが重要です。
runtime note には model id、quantization format、context-length setting、inference server、device placement、memory pressure、prefill speed、decode speed、KV cache 関連設定、同じ command と test の結果を書きます。これがないと、量子化が原因かどうかは印象にすぎません。
コンテキストを疑う場面
モデル単体では答えられるのに、repo に入ると正しい事実を使えないなら、コンテキストを疑います。隣の file を編集する、local convention を忘れる、interface を見落とす、以前の決定を混ぜる、読めば読むほど精度が落ちる、という形で現れます。
コンテキスト設計は repository dump ではありません。対象 file、failing test、nearest schema、governing instruction、最近の command output、短い file map を選びます。長い window は、関連証拠が取り出せるときだけ役に立ちます。
clean session で、対象 file、隣接 type、失敗 test、守るべき rule だけを与えます。見る必要のない directory も明示します。改善するなら、修正対象は model ではなく、stale history、noise、retrieval miss、過剰な tool definitions です。
Harness を疑う場面
説明は正しいのに実行が崩れるなら Harness を疑います。model は正しい file を指し、patch の方向も合っています。しかし edit tool が diff を適用できない、command が wrong cwd で走る、permission が test を止める、stderr が次の turn に入らない、retry が同じ失敗を繰り返すことがあります。
model の意図と実際の trace を分けて見ます。intended patch だけを書かせて手で適用する、または同じ model を別 Harness で試すと、execution loop の問題が見えます。idea が通るなら、直すべき場所は model ではなく tool schema、working directory、permissions、deterministic checks、sensors、review gate です。
良い Harness は派手である必要はありません。確実に編集し、固定 command を走らせ、test output を読ませ、止める条件を持ち、失敗を隠さないことが重要です。
再現できる証拠ログを作る
チームに相談するときや issue に残すときは、全会話ではなく最小の証拠ログで十分です。
| 項目 | 記録する内容 |
|---|---|
| Task | 失敗を再現できる最小 repo task |
| Model/runtime | model、quantization、runtime、device placement、context length |
| Context | files、rules、history、summary、retrieval、logs |
| Harness | tool wrapper、edit method、command runner、permission mode、test command |
| Symptom | 解釈ではなく正確な失敗 |
| Tool log | patch application、command output、test result、permission/schema error |
| Control comparison | 固定した条件、変えた一変数、結果の変化 |
| First fix | 一つだけ試した修正と pass/fail |
| Decision | tuning 継続、Harness 変更、hosted baseline、停止 |
「低精度のローカル設定は no-context 小タスクで落ち、高精度設定は通った」は証拠です。「量子化 agent は全部だめ」は証拠ではありません。
調整、切替、停止
一、二回の比較で次の行動を選びます。近そうに見えるからといって、設定調整を続けないでください。
model/runtime を調整するのは、context と Harness の影響前に失敗し、より強い local baseline で改善したときです。量子化を緩める、coding 向け model に変える、runtime setting を固定する、task boundary を小さくする、といった対応です。
手選びの files で成功し、広い session で失敗するなら context を縮めます。file map、exact tests、fresh command output、短い history を使います。小さな patch に巨大 window が必要なら、診断はまだ終わっていません。
idea は正しいが tool loop が壊れるなら Harness を直します。schemas、edit application、command wrappers、permission policy、project rules、sensors、review checks が修正対象です。
ローカル stack が品質や速度に届かない場合、hosted baseline を delivery route として使います。次の判断が Claude Code と Codex の比較なら Claude Code vs Codex、Codex の usage や context accounting なら Codex token usage、API key cost なら Codex CLI token cost estimate を使ってください。
よくある質問
量子化が一番多い原因ですか？
単独では決められません。量子化は精度を落とすことがありますが、ノイズの多い context や壊れた Harness も同じ失敗に見えます。最小 task、最小 context、高精度または hosted baseline で確かめます。
コンテキストが原因かどうかはどう見る？
clean session で target files、nearest tests、governing rules だけを与えます。改善するなら、広い session の noise、stale history、retrieval miss、tool definitions が疑わしいです。
Harness 失敗とは何ですか？
model の intended fix は妥当なのに、execution loop が閉じない状態です。failed patch、wrong cwd、permission loop、bad tool call、ignored test output、学習しない retry が含まれます。
すぐ Claude Code、Codex、hosted agent に替えるべきですか？
まず同じ最小 task で hosted route を基準にします。hosted が通り、local が層別診断後も落ちるなら、その task は hosted route に渡します。両方落ちるなら task description、files、tests、acceptance criteria を直します。
相談時に何を渡すべきですか？
model/runtime、quantization、loaded files、Harness、prompt、tool log、command output、test result、一つの control comparison を渡します。秘密情報と不要な private code は外します。