Claude Code에 MISTAKES.md 파일을 유지하게 했더니 벌어진 일

MISTAKES.md 파일을 유지하자는 내 댓글에 반응이 꽤 뜨거워서, 아예 따로 글을 하나 파기로 했다.

설정은 별거 없다. 레포지토리에 MISTAKES.md 파일을 하나 만들고, CLAUDE.md에 딱 한 줄만 추가하면 끝이다.
Log mistakes in MISTAKES.md (what happened, root cause, prevention).

에이전트가 뭘 망가뜨리거나 네가 수정을 해줄 때마다, 항목을 하나씩 추가해라. 무슨 일이 있었는지 / 근본 원인이 뭔지 / 결과는 어떤지 / 재발 방지 규칙은 뭔지 적으면 된다. 최신순으로 정렬하고. 별도의 툴이나 플러그인, 벡터 스토어 같은 거 필요 없다.

이 짓을 할 가치가 있는 이유는 크게 두 가지다.

첫째, 에이전트가 알아서 이걸 찾아본다. "이 방식은 예전에 XYZ 문제를 일으켰던 적이 있어서 피했습니다. MISTAKES.md에 기록되어 있거든요." 같은 소리를 하는 걸 보게 될 거다. 더 좋은 건, 나중엔 아예 그 지식이 로그를 넘어선다는 점이다. 파일이 단순한 일기장을 넘어 에이전트가 스스로 참조하는 지침서가 되는 거지.

둘째, 반복되는 항목은 결국 '강제 규칙'으로 승격된다. 이건 나도 예상 못 했던 부분인데, 똑같은 실수가 4~5번 반복되면 그건 더 이상 실수가 아니라 CLAUDE.md의 법이 된다. MISTAKES.md는 증거가 쌓이는 곳이고, CLAUDE.md는 그걸 강제하는 곳이다. 이런 로그가 없으면 그냥 "거기 좀 불안정한데?"라는 막연한 느낌만 남지만, 로그가 있으면 해결책이 있는 명확한 패턴으로 관리할 수 있다.