프로그래머들은 클로드를 위해서는 문서를 남기지만, 서로에게는 남기지 않는다.
Source: Hacker News
Mon, 09 Mar 2026
Programmers will document for Claude, but not for each other
A couple of days ago I recounted a common complaint:
나는 프로그래머들이 사람들이 Claude가 사용할 수 있도록 상세한
CLAUDE.md와PROJECT.md파일을 기꺼이 작성하는 것에 화가 난다고 말하는 모습을 계속 보고 있다. 하지만 그들은 동료들을 위해 그런 파일을 작성하려 하지 않는다.큰 프로젝트에서는 Claude에게 다음 Claude가 읽을 수 있는 인수 인계 문서를 유지하게 하고 있다. 그 문서에는 우리가 계획한 내용, 진행된 내용, 그리고 기타 중요한 정보가 적힌다. 그런 다음 한 Claude를 종료하고 다음 Claude가 그 파일을 읽어 상황을 파악하게 한다. 그리고 Claude !!n+1!!이 Claude !!n+2!!를 위해 문서를 업데이트하도록 한다.
이 흔한 불만을 여러 번 보면서 나는 기분 좋은 영감을 얻었다. 나는 매 프로젝트가 끝날 때마다 Claude의 인수 인계 문서를 버리고 있었다. 왜 그럴까? 파일을 저장소에 복사하고 커밋하는 데는 전혀 문제가 되지 않는다. 미래에 누군가 무슨 일이 있었는지 궁금해 할 때, git grep으로 올바른 문서를 찾아 유용한 정보를 얻을 수도 있다.
나는 약간 느리기 때문에 이번 주까지 더 나은 방법을 생각해냈다: 프로젝트가 끝날 때 Claude에게 문제 정의와 우리가 수행한 변경 사항을 고수준으로 상세히 설명하는 문서를 처음부터 작성하도록 요청하고, 그 문서를 커밋한다. 단순한 메모가 아니라 전체 프로젝트에 대한 구조화된 개요이다.
나는 이 개요들을 꼼꼼히 검토하고 필요에 따라 수정한 뒤 커밋한다. 커밋 서명은 내 것이고, 급여를 받는 내 은행 계좌와 연결돼 있기 때문에, 내가 직접 읽고 이해하지 않은 내용이 저장소에 들어가지 않는다. 마치 Claude가 내 감독 하에 일하는 인간 프로그래머인 것과 같다.
하지만 Claude의 설명은 별다른 편집이 필요하지 않았다. Claude가 만든 최신 프로젝트 요약은 내가 직접 썼을 법한 수준과 거의 비슷했으며, 약간 더 나쁘거나 더 좋을 수도 있었다. 하지만 한 시간 대신 10초 만에 작성됐고, 검토에도 한 시간 정도 걸리지 않았다.
마지막으로 고쳐야 했던 심각한 문제는 Claude가 이전에 작성된 관련 보고서를 모델로 사용했는데, 그 보고서의 마지막에 내가 추가한 문단이 있었다는 점이다:
# Approved-by Claude abstracted these notes from our discussions of the issue. Mark Dominus has read, reviewed, edited, and approved these notes.Claude의 새 문서에도 동일한 섹션이 그대로 들어갔다. 운 좋게도 내가 그걸 발견했을 때는 이미 사실이었기 때문에 삭제할 필요가 없었다. 나는 Claude에게
CLAUDE.md에 이런 일이 다시 일어나지 않도록 한 문장을 추가하도록 했다.오늘의 조언:
- Claude에게 메모를 작성하게 한 뒤, 작업이 끝나면 그 메모를 저장소에 커밋하세요. 해가 될 일은 거의 없으며 도움이 될 수도 있습니다.
- Claude에게 프로젝트 요약을 작성하게 하고, 그 요약을 저장소에 커밋하세요.
혹시 너무 명백해 보일 수도 있겠지만, 나에게는 그랬던 적이 없었습니다. 아직도 이 새로운 세상에 적응하고 있습니다.