Claude Code를 못 쓰게 만드는 10가지 습관

좋아진 모델은 프롬프트를 다듬는 노동을 거의 없애 주었습니다. 지시를 특정한 형태로 맞추거나, 같은 말을 몇 번씩 고쳐 말하거나, 파일을 일일이 지목할 이유가 예전보다 적습니다.

그러나 결과를 검증하는 노동은 줄여 주지 않았습니다. 아래 열 가지는 대부분 그 지점에서 생깁니다. 모델이 못해서 생기는 문제가 아닙니다. 잘한 것과 잘한 것처럼 보이는 것을 가르는 장치를 두지 않아서 생기는 문제입니다.

1. 문서에 쓴 규칙이 지켜지리라 기대합니다

CLAUDE.md에 쓴 문장은 참고 자료입니다. 대개 지켜지지만, 컨텍스트가 길어지거나 지시가 서로 경합하면 밀려납니다. 문서가 길수록 개별 규칙의 무게는 가벼워집니다.

“이것을 모르면 실수한다”는 문서에 쓰고, “이것을 안 하면 안 된다”는 훅으로 만드십시오. 후자를 문서에 쓰면 지켜지는지 확인할 방법이 없는 채로 지켜지길 바라게 됩니다.

스킬과 자동화는 만든 다음부터는 사람이 기억해야 쓸 수 있습니다. 매번 떠올려야 작동하는 도구는 몇 주 안에 잊힙니다.

만들기 전에 그 도구를 모델이 알아서 부를 수 있는지, 아니면 사람이 기억해야 부를 수 있는지 확인하십시오. 후자라면 도구가 아니라 훅이거나, 아예 필요 없는 것입니다.

디렉터리를 나눴다고 런타임이 나뉘지는 않습니다. 모듈 해석은 상위 디렉터리로 거슬러 올라가고, 테스트 러너는 하위 디렉터리를 수집합니다. 격리가 필요하면 모듈 해석과 테스트 수집이 실제로 분리되는지 확인하십시오.

jsdom은 레이아웃을 계산하지 않습니다. 폭이 변하지 않는다는 것을 원리적으로 잠글 수 없습니다. 통과한 테스트 수가 아무리 많아도 레이아웃 회귀는 그대로 지나갑니다.

픽셀을 잠그려 하지 말고 픽셀을 결정하는 조건(형제 관계, 자식 순서, 중첩)을 잠그십시오. 그리고 무엇을 잠갔는지 테스트 이름에 정직하게 쓰십시오.

종료 코드는 계약이 아닙니다. 일부 도구는 실패해도 0으로 끝납니다. 그 도구를 검사에 물려두면 검사는 영원히 통과합니다.

새로 쓰는 도구는 일부러 실패시켜 종료 코드를 확인한 뒤에 검사에 넣으십시오.

검사를 추가한 직후의 초록은 두 가지를 뜻할 수 있습니다. 문제가 없다는 뜻이거나, 검사가 아무것도 잡지 못한다는 뜻입니다. 정규식 하나가 어긋나면 그 축은 죽은 채로 초록이 됩니다.

순서를 지키십시오. 검사 추가, 알려진 위반으로 실패 확인, 수정, 초록 확인 순입니다. 두 번째 단계를 건너뛰면 나머지가 전부 의미를 잃습니다.

지적이 타당해도 함께 온 패치가 문제를 고치지 못하는 경우가 있습니다. 패치는 코드가 이미 붙어 있어 검증을 건너뛰기 쉽습니다.

제안된 패치는 경계값을 손으로 계산해 보십시오. 그리고 리뷰어를 여러 명 붙여도 모두 같은 기준 문서를 읽으면 같은 결함을 함께 놓칩니다. 리뷰어 수를 늘리는 것과 관점을 늘리는 것은 다른 일입니다.

병렬로 돌릴 생각이 있으면 시작할 때 격리하십시오. 충돌이 난 뒤에 옮기면 이미 섞인 것을 푸는 작업이 먼저 붙습니다.

재빌드 산출물과 소스 변경이 한 커밋에 들어가면 diff를 읽을 수 없고, 되돌릴 때 무엇이 딸려 나올지 알 수 없습니다. 리뷰가 어려워지는 것보다 되돌릴 수 없게 되는 것이 더 큰 비용입니다.

스크린샷은 “어떻게 보이는가”를 확인하는 도구입니다. “값이 얼마인가”를 알아내는 데 쓰면 찍고, 좌표를 추정하고, 다시 찍는 순환에 빠집니다. 구조와 값을 그대로 반환하는 읽기 도구가 있으면 그쪽을 먼저 쓰십시오.

열 가지는 모두 확인할 수 있는 것과 확인한 것을 구분하지 않은 데서 나옵니다. 문서에 썼으니 지켜질 것이고, 테스트가 통과했으니 안전할 것이고, 종료 코드가 0이니 성공했을 것이라고 넘어간 자리에서 전부 생깁니다.

고치는 방법은 넘어가려는 지점마다 “이것을 무엇으로 확인했는가”를 묻고, 답이 없으면 확인할 방법을 먼저 만드는 것입니다.