Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Claude Code 사용 시 발생하는 '잔여 과제 방치' 문제의 원인을 3층 구조로 분석하고, 이를 해결하기 위한 실천적인 대책을 제시합니다. CLAUDE.md 작성법 개선, 명확한 완료 정의, 백로그 관리 및 플랜 모드 활용법을 다룹니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기Claude Code로 개발하다 보면, 이런 경험이 있지 않은가?
"구현해 달라고 했는데, 중요한 처리가 미완성인 채로 '잔여 과제'라고 적어두고 끝나버렸다."
이것은 CLAUDE.md 작성 방식의 문제뿐만 아니라, 모델의 행동 특성·지시 설계·태스크 요청 방법이라는 3층 구조의 문제가 얽혀 있다.
본 기사에서는 각 층의 원인을 정리하고, 정밀도를 높이는 실천적인 대책을 정리한다.
공식 문서에는 다음과 같이 명시되어 있다.
Claude stops when the work looks done. Without a check it can run, "looks done" is the only signal available.
즉, 테스트나 빌드와 같은 기계적인 완료 시그널이 없는 한, Claude는 자신의 판단으로 완료를 결정한다. 잔여 과제를 "보고한" 것이 "완료한" 것의 대체 시그널이 되어버리는 것이 "적고 끝내기"의 정체다.
흔히 있는 작성 방식:
## 태스크 완료 후
잔여 과제(있을 경우)를 기재한다.
"기재한 후에 무엇을 할지"가 적혀 있지 않기 때문에, 적는 시점에서 태스크가 종료된다.
공식은 CLAUDE.md를 "강제 설정이 아닌 컨텍스트 (Context)"로 위치시키고 있으며, 모호하고 추상적인 지시는 특히 지켜지기 어렵다.
× "프론트엔드 UI를 수정해줘"
→ 백엔드 처리는 "범위 외의 잔여 과제"로 기록되고 종료됨
○ "사용자 조작부터 DB로의 데이터 저장까지 동작하는 것을 완료로 한다"
...
## 미완료 플로우에 대한 대응 (필수)
범위 외의 미완료 플로우가 발생한 경우, 태스크를 마치기 전에 반드시 사용자에게
보고하고, 계속할지 확인할 것. 기록만 남기고 묵묵히 끝내는 것은 금지.
공식에는 "IMPORTANT나 YOU MUST와 같은 강조로 준수율이 개선된다"라고 기재되어 있다. "금지", "반드시", "확인할 것"이 효과적이다.
단, CLAUDE.md는 비대해지면 중요한 규칙이 묻히게 된다 (공식 가이드는 파일당 200행 이내). 확실하게 실행시키고 싶은 처리에는 Stop 훅과 같은 hooks를 사용하는 것이 정석이다.
× "외부 API의 폴링 (Polling) 처리를 구현해줘"
○ "외부 API가 완료 상태를 반환했을 때,
DB의 결과 컬럼이 자동으로 업데이트될 때까지를 완료로 한다"
더 나아가서, 완료 정의에 Claude가 실행할 수 있는 검증 수단(테스트·스크립트)까지 포함하면, 층 1의 "겉모습으로 완료 판정을 하는" 동작 자체를 차단할 수 있다.
개별 작업 기록에 잔여 과제를 묻히게 하지 않고, 전용 파일에 집약한다.
# CLAUDE.md 추가 예시
잔여 과제가 발생한 경우 memo/backlog.md에 추가한다.
새로운 세션을 시작할 때, 먼저 backlog.md를 확인한 후 착수한다.
복잡한 기능은 구현 전에 플랜 모드 (Plan mode)로 계획을 확인하고, "잔여 과제가 될 것 같은 부분"을 사전에 골라낸다.
| 환경 | 사용법 |
|---|---|
| CLI | Shift+Tab으로 모드 전환, 또는 /plan 접두사 사용 |
| VS Code 확장 | 프롬프트 박스 하단의 모드 인디케이터에서 선택 |
| 프로젝트 공통 | .claude/settings.json의 permissions.defaultMode에 "plan" 설정 |
※ VS Code 확장
| 우선순위 | 대책 | 효과 |
|---|---|---|
| 높음 | 요청 시 완료 정의를 작성 | 범위 외 상황이 생기기 어려움. 가장 확실함 |
| ... |
Claude Code에게 CLAUDE.md는 "컨텍스트"이며, 적혀 있지 않은 것은 자유 재량으로 취급된다. "요청 시의 완료 정의"와 "CLAUDE.md에 대한 강제 명령" 이 두 가지만이라도 체감되는 정밀도는 크게 달라진다.
