AI에게 개발 도움을 받을 때, '작동할 것이다'라는 믿음을 신뢰하지 않기 위해 정한 규칙

개인 개발 도구 모음집인 '犬の手(이누노테)'를 AI (Claude Code)와 함께 만들고 있습니다. 69개의 도구를 약 일주일 만에 만들 수 있었던 것은 AI 덕분입니다.

반면에, AI는 자신감 넘치는 어조로 실수를 합니다. 실제로 작동하지 않았는데도 '구현했으니 작동할 겁니다'라고 말하는 경우가 있었습니다.

그래서 AI에게 작업을 시킬 때의 규칙을, AI가 매번 읽도록 설정 파일(CLAUDE.md)에 적기로 했습니다. 실제로 효과를 본 것들을 소개합니다.

완료 선언에는 증거(Evidence)가 필수입니다. '구현했으니 작동할 겁니다'라는 말만으로 완료라고 하지 않습니다. 파일:행 번호・명령어 출력・테스트 결과 중 하나를 첨부해야 합니다.

AI에게 단순히 '끝났습니다'라고만 말하게 하지 않습니다. 테스트 결과, 명령어 출력, 어떤 파일의 몇 번째 행을 변경했는지 등을 반드시 명시하도록 합니다.

효과적이었던 점은, 증거를 제시하려 하는 순간 AI 스스로가 오류를 발견한다는 것입니다. 테스트를 돌리게 하면 실패하고, '사실은 고쳐지지 않았다'는 것을 완료 전에 알 수 있습니다.

영향 범위・'변하지 않는 것'・'회귀(Degrade) 없음'을 답변할 때는 반드시 '확인됨(무엇으로 확인했는지)'과 '미확인'으로 나누어 작성합니다.

이 규칙은 실패로부터 탄생했습니다. 한 기능 변경에서, AI가 확인하지 않은 채 '영향은 이 경로에만 있습니다'라고 답했지만, 실제로는 다른 경로에도 영향을 미치고 있었습니다.

그 이후로 보고는 반드시 다음과 같은 형식으로 하도록 했습니다.

'미확인'이 하나라도 남아있는 동안에는 '문제없음'이라고 단정 짓지 못하게 합니다.

실패 경로를 try/catch・기본값(Default Value)・optional화로 막아 '작동한 것처럼 만들지 않습니다'. 실패는 사용자에게 보이는 형태로 실패하도록 만듭니다.

AI는 에러가 발생하면, try/catch로 감싸서 기본값을 반환하는 '수정 방법'을 자주 제안합니다. 테스트는 통과하게 되지만, 실제로는 고장 난 채 계속 작동합니다.

화면에 이유와 수정 방법을 표시합니다. 수리할 수 없다면 멈춥니다. 이것을 결정한 후 AI의 제안 품질이 달라졌습니다.

commit / push / merge / PR 생성 / 배포(Deploy)는 사용자 명시 승인 후에만 진행합니다. 완료 시에는 명령어 안내문을 제시하고 중지합니다.

AI는 작업 속도가 빠르기 때문에, 기세에 눌려 프로덕션 환경까지 내보내 버릴 수 있습니다. commit 이후부터는 반드시 제가 내용을 보고 '진행해도 좋다'라고 말한 후에 작동시킵니다. 배포 명령어는 AI가 아닌 제가 입력합니다.

조사・질문에 대한 결과물은 보고일 뿐 수정이 아닙니다. 발견한 다른 문제도 임의로 고치지 않고 보고만 합니다.

'왜 안 되나요?'라고 물어보기만 했는데, AI가 코드를 수정하기 시작하는 경우가 있습니다. 조사해 달라고 하면 원인 보고에서 멈추게 했습니다. 발견한 다른 문제도 임의로 고치지 않고 보고하게 했습니다. 차이점(Diff)을 작게 유지할 수 있어 리뷰가 쉬워졌습니다.

• AI가 틀리지 않게 된 것은 아닙니다.
  실수가 완료 전에 발견되도록 바뀐 것입니다 - 특히 효과적이었던 것은 정답을 AI 외부(공식 표, 테스트, CI)에 두는 것이었습니다. AI가 작성한 테스트의 기대값 자체가 잘못된 경우도 있었지만, 공식 표를 정답으로 삼았기 때문에 알아차릴 수 있었습니다.

작업 속도는 빨라졌지만, 확인하는 노력은 줄지 않았습니다. 오히려 어떻게 확인할지를 미리 결정해 두는 것이 AI와 개발할 때 가장 중요한 작업이라고 느낍니다.

AI가 작성한 코드 리뷰로 어려움을 겪고 계신 분들의 참고가 되기를 바랍니다.