Claude Code가 '수정했습니다'라고 보고해도 실제로는 고쳐지지 않은 문제, 지시사항에 한 줄을 추가하면 해결됩니다

AI 코딩 에이전트를 사용하면서 가장 실망스러운 순간은 '수정했습니다!'라는 보고를 받았는데 실제로 문제가 해결되지 않았을 때가 아닐까 합니다.

그 원인 대부분은 에이전트의 능력이 아니라, '완료(completion)'의 정의를 전달하지 않은 것에 있습니다.

로그인 관련 부분을 수정해줘

이렇게만 하면 에이전트는 '그럴듯하게 수정하면 완료'라고 판단할 수밖에 없습니다.

로그인 화면에서 비밀번호를 잘못 입력하면 화면이 하얗게 변합니다. 
'메일 주소 또는 비밀번호가 다릅니다'라는 메시지가 표시되도록 해줬으면 합니다.
완료 조건: 이 케이스에 대한 테스트를 하나 추가하고, npm test가 통과하는 것.

차이점은 마지막 한 줄입니다. 완료 조건이 있으면 에이전트는 스스로 검증한 후에 끝내려고 노력합니다.

테스트가 실패하면 스스로 고치고, 성공하면 보고하는 루프가 돌아갑니다.

종류	예시
테스트	`npm test`가 통과하거나, 특정 테스트 케이스를 추가하기
타입 체크/린트	`tsc --noEmit` / `ruff check`가 에러 0인 경우
동작 확인	'`npm run dev`로 접속하여 `/login`에서 재현되지 않는 것'
출력 형태	'결과를 `output/report.csv`에 저장하기'

테스트나 타입 체크 명령어는 매번 같으므로, 프로젝트 루트 디렉터리의 CLAUDE.md에 작성해 두는 것이 좋습니다. 세션 시작 시 자동으로 로드됩니다.

## 자주 사용하는 명령어
- 테스트: `npm test`
- 타입 체크: `npx tsc --noEmit`
...

'테스트를 통과하도록'이라고만 요청하면, 구현 자체를 수정하는 것이 아니라 테스트 코드를 수정해서 통과시키는 경우가 있습니다. 이것 역시 CLAUDE.md에 한 줄 적어두면 방지할 수 있습니다.

- 테스트를 통과하기 위해 테스트 쪽을 수정하지 않는다. 테스트가 잘못되었다고 판단되면 보고한다

CLAUDE.md를 처음부터 작성하는 것이 번거로운 분들을 위해, 질문에 답만 하면 CLAUDE.md와 권한 설정을 만들 수 있는 무료 도구를 만들었습니다: https://acerola-tools.acerola.workers.dev

지시사항의 12가지 패턴, CLAUDE.md 템플릿, 후크/스킬 설정 예시를 모은 책도 출간했습니다 (처음 2장은 무료로 읽을 수 있습니다): https://zenn.dev/acerola_jp/books/claude-code-practical-kit

요약