클로드 마크다운 파일

클로드 마크다운 파일은 클로드 코드에게 일을 시키기 전에 읽히는 사용 설명서 같은 것이다. 새 직원이 출근 첫날 책상에서 발견하는 사내 규칙집을 떠올리면 된다. "이 회사에서는 이렇게 일해요"라고 적어두면, 직원이 매번 물어보지 않고도 그 방식을 따르게 되는 것과 비슷하다.

이 파일이 필요한 이유는 AI 코딩 도구가 자주 저지르는 실수들 때문이다. 사용자에게 확인하지 않고 마음대로 짐작해서 진행하거나, 간단히 끝날 일을 필요 이상으로 복잡하게 만들거나, 요청하지 않은 부분까지 손대는 경우가 있다. 프로젝트 폴더에 클로드 마크다운 파일을 하나 두고 "짐작하지 말고 물어봐라", "필요한 만큼만 코드를 써라", "요청한 부분만 고쳐라" 같은 원칙을 적어두면, 도구가 새로운 대화를 시작할 때마다 이 규칙을 참고해서 움직인다.

특정 프로젝트에만 적용할 수도 있고, 여러 프로젝트에 공통으로 쓰이는 원칙을 담아 공유할 수도 있다. 팀 전체가 같은 방식으로 도구를 쓰게 만드는 손쉬운 방법인 셈이다.

기사에서는 "핵심 지침은 CLAUDE.md 한 장에 담겼다"처럼 쓰인다. 흔한 오해는 이 파일이 코드 자체를 담고 있다고 생각하는 것인데, 실제로는 코드가 아니라 AI 도구가 작업할 때 지켜야 할 규칙과 원칙을 적어둔 텍스트 문서다.

프로젝트 폴더 맨 위에 CLAUDE.md라는 이름의 텍스트 파일을 하나 만들고 아래와 같은 내용을 적어보자.

• 확실하지 않은 부분이 있으면 짐작해서 진행하지 말고 먼저 물어봐라
• 문제를 해결하는 데 필요한 최소한의 코드만 작성해라
• 요청과 관련 없는 코드는 건드리지 마라
• 작업을 마치기 전에 성공 기준을 스스로 정하고 확인해라

이후 같은 폴더에서 클로드 코드로 작업을 시작하면, 도구가 이 파일의 내용을 참고해서 답변과 코드를 조정하는지 비교해 볼 수 있다.