Claude Code가 잔여 과제를 방치하는 이유와 대책

서론

Claude Code로 개발하다 보면, 이런 경험이 있지 않은가?

"구현해 달라고 했는데, 중요한 처리가 미완성인 채로 '잔여 과제'라고 적어두고 끝나버렸다."

이것은 CLAUDE.md 작성 방식의 문제뿐만 아니라, 모델의 행동 특성·지시 설계·태스크 요청 방법이라는 3층 구조의 문제가 얽혀 있다.

본 기사에서는 각 층의 원인을 정리하고, 정밀도를 높이는 실천적인 대책을 정리한다.

문제의 3층 구조

층 1: 완료 판정은 "검증"이 아니라 "겉모습"

공식 문서에는 다음과 같이 명시되어 있다.

Claude stops when the work looks done. Without a check it can run, "looks done" is the only signal available.

즉, 테스트나 빌드와 같은 기계적인 완료 시그널이 없는 한, Claude는 자신의 판단으로 완료를 결정한다. 잔여 과제를 "보고한" 것이 "완료한" 것의 대체 시그널이 되어버리는 것이 "적고 끝내기"의 정체다.

층 2: CLAUDE.md가 "작성 후 어떻게 할지"를 정의하지 않음

흔히 있는 작성 방식:

## 태스크 완료 후
잔여 과제(있을 경우)를 기재한다.

"기재한 후에 무엇을 할지"가 적혀 있지 않기 때문에, 적는 시점에서 태스크가 종료된다.

공식은 CLAUDE.md를 "강제 설정이 아닌 컨텍스트 (Context)"로 위치시키고 있으며, 모호하고 추상적인 지시는 특히 지켜지기 어렵다.

층 3: 기능의 일부만을 요청함

× "프론트엔드 UI를 수정해줘"
→ 백엔드 처리는 "범위 외의 잔여 과제"로 기록되고 종료됨
○ "사용자 조작부터 DB로의 데이터 저장까지 동작하는 것을 완료로 한다"
...

대책

대책 1: CLAUDE.md에 강제 명령으로 작성

## 미완료 플로우에 대한 대응 (필수)
범위 외의 미완료 플로우가 발생한 경우, 태스크를 마치기 전에 반드시 사용자에게
보고하고, 계속할지 확인할 것. 기록만 남기고 묵묵히 끝내는 것은 금지.

공식에는 "IMPORTANT나 YOU MUST와 같은 강조로 준수율이 개선된다"라고 기재되어 있다. "금지", "반드시", "확인할 것"이 효과적이다.

단, CLAUDE.md는 비대해지면 중요한 규칙이 묻히게 된다 (공식 가이드는 파일당 200행 이내). 확실하게 실행시키고 싶은 처리에는 Stop 훅과 같은 hooks를 사용하는 것이 정석이다.

대책 2: 요청 시 완료 정의를 작성

× "외부 API의 폴링 (Polling) 처리를 구현해줘"
○ "외부 API가 완료 상태를 반환했을 때,
DB의 결과 컬럼이 자동으로 업데이트될 때까지를 완료로 한다"

더 나아가서, 완료 정의에 Claude가 실행할 수 있는 검증 수단(테스트·스크립트)까지 포함하면, 층 1의 "겉모습으로 완료 판정을 하는" 동작 자체를 차단할 수 있다.

대책 3: backlog.md로 잔여 과제를 집약 관리

개별 작업 기록에 잔여 과제를 묻히게 하지 않고, 전용 파일에 집약한다.

# CLAUDE.md 추가 예시
잔여 과제가 발생한 경우 memo/backlog.md에 추가한다.
새로운 세션을 시작할 때, 먼저 backlog.md를 확인한 후 착수한다.

대책 4: /plan으로 먼저 합의한 후 구현

복잡한 기능은 구현 전에 플랜 모드 (Plan mode)로 계획을 확인하고, "잔여 과제가 될 것 같은 부분"을 사전에 골라낸다.

환경	사용법
CLI	Shift+Tab으로 모드 전환, 또는 /plan 접두사 사용
VS Code 확장	프롬프트 박스 하단의 모드 인디케이터에서 선택
프로젝트 공통	.claude/settings.json의 permissions.defaultMode에 "plan" 설정

※ VS Code 확장

요약

우선순위	대책	효과
높음	요청 시 완료 정의를 작성	범위 외 상황이 생기기 어려움. 가장 확실함
...

Claude Code에게 CLAUDE.md는 "컨텍스트"이며, 적혀 있지 않은 것은 자유 재량으로 취급된다. "요청 시의 완료 정의"와 "CLAUDE.md에 대한 강제 명령" 이 두 가지만이라도 체감되는 정밀도는 크게 달라진다.

참고 문헌

Discussion