AI와 코딩을 하다 보면 이런 순간이 옵니다. 지난주에 분명히 알려준 걸 또 물어보고, 이미 아니라고 한 방향을 다시 제안하고, 한 번 고생해서 찾은 해결책을 잊어버리고 원점으로 돌아갑니다.

세션이 끊기면 기억도 끊기니까 당연한 일이긴 해요.

그래서 프로젝트마다 CLAUDE.md를 두고 “이 프로젝트에서 이미 결론 난 것들”을 적기 시작했습니다. 몇 개 굴려보니 어떤 걸 적어야 실제로 쓸모 있는지 감이 잡혀서 정리해봅니다.

1. 코드를 봐도 알 수 없는 사실

가장 쓸모 있는 항목은 소스 코드 어디에도 안 적혀 있는 것들입니다. 수학 앱 프로젝트의 CLAUDE.md엔 이런 줄이 있어요.

Play 개발자 계정은 법인(조직) 계정 — 개인 계정에 적용되는 “비공개 테스트 테스터 모집 후 14일” 요건이 적용되지 않음. 바로 프로덕션 출시 가능. 이 요건 관련 안내를 사용자에게 다시 하지 말 것.

마지막 문장이 핵심입니다.

계정 종류는 코드에 없으니 AI는 매번 일반론을 꺼냈습니다. “14일 테스트가 필요합니다.” 그러면 저는 매번 “우리는 법인이라 해당 없다”고 답했고요. 이걸 적어두니 그 대화가 사라졌습니다.

2. 한 번 당한 환경 함정

두 번째로 유용한 건 디버깅에 시간을 크게 쓴 환경 문제입니다.

스크린샷은 adb exec-out screencap -p를 cmd /c 리다이렉션으로 저장할 것 (PowerShell >는 바이너리 깨뜨림).

PowerShell의 리다이렉션이 바이너리를 손상시켜서 스크린샷이 깨졌는데, 처음엔 에뮬레이터 문제인 줄 알고 한참 헤맸습니다. 이런 건 검색해도 잘 안 나오고 겪어야만 알아요.

다른 프로젝트(3D 러너)에도 비슷한 줄이 있습니다.

숨김 탭(헤드리스 프리뷰)에서는 크롬이 rAF를 멈춰 3D가 안 그려짐 — ?rafshim 쿼리로 우회

3. 위험한 중복

세 번째는 떨어져 있어서 같이 고치기 쉬운 것을 경고해두는 겁니다.

⚠️ 같은 문제 세트가 로블록스판에도 있음 — 문제 수정 시 양쪽 동기화할 것.

같은 게임을 웹과 로블록스 양쪽에 만들었더니 문제 은행이 두 벌이 됐습니다. 한쪽만 고치면 조용히 어긋나요.

코드를 아무리 읽어도 “다른 저장소에 쌍둥이가 있다”는 사실은 알 수 없습니다.

💡 쓰면서 정리된 원칙

• 팁: “AI가 두 번 이상 같은 걸 물었다”가 신호입니다. 그 순간이 한 줄 추가할 타이밍이에요. 미리 완벽하게 쓰려고 하면 오히려 안 쓰게 되더라고요. 겪을 때마다 한 줄씩 붙이는 게 현실적입니다.
• 주의할 점: 코드를 읽으면 알 수 있는 내용(폴더 구조, 함수 목록)은 적지 마세요. 금방 낡아서 틀린 정보가 되는데, 없느니만 못합니다. 코드가 바뀌어도 안 변하는 사실이나 사람만 아는 결정을 적으세요.

정리

CLAUDE.md를 “AI에게 주는 설명서”라고 생각하고 시작했는데, 쓰다 보니 성격이 좀 달랐습니다. 실제로는 프로젝트가 겪은 일을 쌓아두는 기록에 가까웠어요.

그리고 그 기록으로 제일 덕을 본 건 AI가 아니라, 두 달 뒤에 이 프로젝트로 돌아온 저 자신이더라고요.

---

태그: #클로드코드, #ClaudeCode, #CLAUDEmd, #AI코딩, #바이브코딩, #개발생산성, #AI개발, #프로젝트관리, #에이전트, #개발기록