로컬 coding agent가 실패하면 모델, 양자화, 컨텍스트 길이, 도구 환경을 한꺼번에 바꾸지 마세요. 같은 잘못된 수정도 세 계층에서 나올 수 있습니다. 모델이나 runtime의 정밀도가 부족하거나, 필요한 증거가 컨텍스트에 없거나, Harness가 편집, 명령, 테스트, 피드백 루프를 제대로 닫지 못한 경우입니다.
| 증상 | 먼저 의심할 계층 | 확인 방법 | 첫 수정 |
|---|---|---|---|
| 도구가 중요하지 않은 아주 작은 수정도 실패한다 | 모델, runtime, 양자화 | 불필요한 파일 없이 더 높은 정밀도 설정 또는 hosted 기준으로 같은 작은 작업을 실행 | 해당 작업에 맞게 양자화, runtime, 모델을 조정 |
| 관련 파일, 규칙, 이전 결정을 잃는다 | 컨텍스트 선택 | 대상 파일, 가까운 interface, 실패 테스트, 필수 규칙만 둔 깨끗한 세션으로 재실행 | 컨텍스트를 줄이고 정확한 증거를 고정 |
| 설명은 맞지만 patch, command, test에서 무너진다 | Harness와 tool feedback | 모델의 의도 patch, 실제 tool log, command output, test result를 비교 | edit 적용, 권한, cwd, schema, test hook, retry를 수정 |
| 여러 설정을 바꾼 뒤에만 우연히 된다 | 아직 진단되지 않음 | 같은 repo, 같은 task, clean session, fixed files로 돌리고 하나만 변경 | 다시 단일 변수 실험부터 수행 |
Hosted 환경은 판정이 아니라 기준선입니다. 같은 최소 작업이 hosted에서 통과하고 로컬에서 실패하면 로컬 stack을 계속 계층별로 봅니다. 둘 다 실패하면 작업 설명, 파일 선택, acceptance criteria가 부족할 수 있습니다. 공정한 비교 뒤에도 품질, 속도, 도구 신뢰성이 기준에 못 미치면 그 작업의 로컬 튜닝은 멈춥니다.
빠른 세 계층 진단
로컬 coding agent를 단일 모델로 보면 원인을 놓칩니다. 실제 실행에는 model weights, inference runtime, 양자화, KV cache, 파일 선택, 규칙, 이전 대화, tool calls, 파일 편집, shell command, tests, permissions, review signals가 모두 들어갑니다. 밖에서는 모두 “agent가 틀렸다”처럼 보이지만 내부 원인은 다를 수 있습니다.
| 계층 | 담당하는 것 | 실패 패턴 | 아직 말할 수 없는 결론 |
|---|---|---|---|
| 모델과 runtime | 모델 크기, 양자화, KV cache, CPU/GPU 배치, serving defaults | 작은 작업에서 약한 추론, 잘못된 structured output, 느린 decode, 긴 sequence에서 OOM | 모든 로컬 모델이 나쁘다는 결론 |
| 컨텍스트와 retrieval | 로드한 files, rules, history, summaries, tool definitions, logs | 다른 파일 수정, 제약 누락, 가까운 symbol 무시, 읽을수록 혼란 | 큰 context window가 해결한다는 결론 |
| Harness와 feedback | edit application, command runner, permissions, schemas, tests, sensors, retry | 설명은 맞지만 patch, cwd, permission, test output에서 실패 | 모델이 작업을 못 한다는 결론 |
좋은 첫 단계는 설정 이름을 고르는 것이 아니라 같은 조건에서 한 계층만 바꿔 보는 것입니다. 실패를 작게 만들고 관찰과 해석을 분리해야 합니다.
하나의 변수만 바꾸기
비교가 공정해야 진단이 됩니다. 같은 저장소, 같은 작업, 같은 지시, 같은 파일 세트, 깨끗한 세션을 유지하세요. 최소 재현 작업은 하나의 failing test, 하나의 잘못된 edit, 하나의 command wrapper, 하나의 permission error, 또는 agent가 계속 잘못 읽는 file이면 충분합니다.
기록에는 model, quantization, runtime, context length, loaded files, Harness, command output, test result, final patch가 들어가야 합니다. 그 다음에는 하나만 바꿉니다.
| 바꾸는 것 | 좋아지면 의미하는 것 | 의미하지 않는 것 | | --- | --- | --- | --- | | 더 높은 정밀도, 더 큰 로컬 모델, hosted baseline | model/runtime이 병목일 가능성 | context와 Harness가 건강하다는 뜻은 아님 | | target files만 둔 clean session | 넓은 context, old history, retrieval이 방해했을 가능성 | 작은 model이 full repo에 충분하다는 뜻은 아님 | | 같은 model을 다른 Harness에서 실행 | tool loop, edit application, tests, permissions가 원인일 가능성 | 다른 Harness가 모든 작업에 낫다는 뜻은 아님 | | model은 patch 의도만 쓰고 사람이 적용/test | 아이디어는 맞고 실행 루프가 실패했을 가능성 | 앞으로 사람이 계속 구조해야 한다는 뜻은 아님 |
로컬과 클라우드 경로 선택은 실패 계층을 찾은 뒤에 하세요. 그 다음에 local versus cloud coding agents를 보면 경로 판단이 훨씬 정확합니다.
양자화나 runtime을 의심할 때
컨텍스트와 도구가 영향을 주기 전에 작은 작업이 깨지면 model/runtime을 의심합니다. 두 단계 편집을 못 유지하거나, 짧은 tool JSON도 깨지거나, 단순 syntax error를 반복하거나, sequence가 길어질 때 갑자기 느려지거나, prefill에서 memory pressure가 커지는 경우입니다.
양자화는 메모리와 계산량을 줄이지만 코드 추론 정밀도를 떨어뜨릴 수 있습니다. 그러나 “Q4가 실패했다”가 곧 “로컬은 불가능하다”는 뜻은 아닙니다. 같은 tiny task를 덜 공격적인 양자화, coding에 강한 더 큰 모델, 또는 hosted baseline에서 비교하세요. 이때 불필요한 파일을 넣지 않아야 retrieval 문제를 섞지 않습니다.
runtime 기록에는 model id, quantization format, context-length setting, inference server, device placement, memory pressure, prefill speed, decode speed, KV cache 설정, 같은 command와 test의 결과를 남깁니다. 이 정보가 없으면 양자화 원인은 추측입니다.
컨텍스트를 의심할 때
모델이 고립된 작은 문제는 풀지만 저장소 안에서는 올바른 사실을 쓰지 못하면 컨텍스트를 의심합니다. 옆 파일을 수정하고, local convention을 잊고, interface를 놓치고, 이전 결정을 섞고, 더 많은 파일을 읽어도 결과가 좋아지지 않는 형태입니다.
컨텍스트 설계는 저장소 전체를 던지는 일이 아닙니다. 대상 file, failing test, nearest schema, governing instruction, 최신 command output, 짧은 file map을 고르는 일입니다. 긴 window는 관련 증거를 실제로 꺼낼 수 있을 때만 도움이 됩니다.
clean session으로 target file, adjacent type, failing 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가 같은 실패를 반복할 수 있습니다.
모델의 의도와 실제 trace를 분리하세요. intended patch만 쓰게 한 뒤 사람이 적용하거나, 같은 model을 다른 Harness에서 실행합니다. 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 | loaded files, rules, history, summaries, 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에 맞는 모델을 선택하고, runtime setting을 고정하고, task boundary를 줄입니다.
손으로 고른 files에서는 성공하고 넓은 session에서는 실패하면 context를 줄입니다. file map, exact tests, fresh command output, 짧은 history가 필요합니다. 작은 patch에 거대한 window가 필요하면 진단이 아직 끝나지 않았다는 뜻입니다.
아이디어는 맞지만 tool loop가 깨지면 Harness를 고칩니다. schemas, edit application, command wrappers, permission policy, project rules, sensors, review checks가 수정 지점입니다.
로컬 stack이 품질이나 속도 기준을 못 맞추면 hosted baseline을 작업 경로로 사용합니다. 다음 질문이 Claude Code와 Codex 비교라면 Claude Code vs Codex를, Codex usage와 context accounting이면 Codex token usage를, API key cost이면 Codex CLI token cost estimate를 보세요.
자주 묻는 질문
양자화가 가장 흔한 원인인가요?
단독으로 판단할 수 없습니다. 양자화는 정밀도를 낮출 수 있지만, noisy 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, learning 없는 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, 단일 변수 비교를 보내세요. 비밀값과 불필요한 private code는 제외합니다.