AI를 위한 규칙을 적는다

GitHub에 생각을 적는다에서 README와 Issue를 세웠다면, 이번 글은 AI에게 넘기기 전에 적어 둘 파일 하나를 더 다룹니다. 바로 CLAUDE.md — 매번 말하지 않아도 AI에게 전달되는 약속 파일입니다. 이 글이 끝나면 리포지토리에 생각과 약속이 갖춰지고, 다음 글 폴더 구성과 기술 선정에서 기술 결정까지 더합니다.

README에 생각을 적고 Issue를 세웠습니다. 넘기기 전에 적어 둘 파일이 하나 더 있습니다.

CLAUDE.md — AI와의 약속을 적어 두는 파일입니다.

CLAUDE.md는 AI와의 약속

Claude Code는 작업을 시작할 때 리포지토리 안의 CLAUDE.md라는 파일을 자동으로 읽습니다. 여기 적은 건 매번 말하지 않아도 이미 전달된 상태가 된다는 뜻입니다. (파일의 동작 원리가 궁금하다면 CLAUDE.md 작성법을 함께 보세요.)

이게 없으면 어떻게 될까요. AI에게는 기억이 이어지지 않습니다. 오늘 "디자인은 블랙 톤으로 부탁해"라고 해도 내일 작업에선 잊고 있습니다. 매번 같은 주문을 반복하게 되고, 말하는 걸 깜빡한 날만큼 다른 톤의 결과물이 섞입니다.

매번 말할 건 파일에 적는다. 이게 원칙입니다.

새로 온 사람에게 건네는 업무 매뉴얼이라고 생각하고 적는다

뭘 적어야 할지 막막하면 이렇게 생각해 보세요.

내일부터 도와주러 오는, 실력은 좋은데 우리 사정은 하나도 모르는 사람에게 첫날 건네는 메모를 적는다.

그 사람은 우수합니다. 기술은 여러분보다 훨씬 잘 압니다. 하지만 여러분 사정은 하나도 모릅니다.

• 이 프로젝트가 뭔지 → README를 읽게 하면 전달된다
• 어떤 톤을 좋아하는지 → 말하지 않으면 전달 안 된다
• 뭘 당하면 곤란한지 → 말하지 않으면 악의 없이 당한다

CLAUDE.md에 적는 건 이 "말하지 않으면 전달 안 되는 사정"입니다.

적어야 할 것

처음에는 다섯 항목이면 충분합니다.

# CLAUDE.md

## 이 프로젝트에 대해
먼저 README.md를 읽어 주세요. 만드는 이유와 최종 목표는 거기 있습니다.

## 지켜 줬으면 하는 것
- 폰으로 보는 사람이 90%. 항상 모바일 화면을 우선한다
- 화려함보다, 사진이 주인공으로 보이는 것
- 애매하면 기능을 더하는 게 아니라 줄이는 방향으로 제안한다

## 하지 말았으면 하는 것
- 부탁하지 않은 기능을 추가하지 않는다 (제안은 환영, 구현은 확인 후)
- 기존 데이터를 지우는 조작은 반드시 사전에 확인받는다

## 말투
- 설명은 전문 용어를 피하고 초보자 눈높이로
- 제안할 때는 선택지 2~3개와 추천안, 그 이유를 붙인다

## 판단이 애매하면
작업을 멈추고 물어보세요. 추측으로 진행하지 마세요.

특히 효과가 큰 건 "하지 말았으면 하는 것"과 "판단이 애매하면 물어보기" 둘입니다. AI의 실패 대부분은 능력 부족이 아니라 "과한 배려"에서 나옵니다. 앞서가기를 멈추는 한 문장이 여러분을 지켜 줍니다.

안 적어도 되는 것

반대로 적고 싶어지지만 불필요한 것도 있습니다.

• 기술 세부 지정 — "◯◯ 라이브러리를 쓸 것" 같은 지정은 지식이 없는 동안엔 안 하는 게 안전합니다. 수단은 AI의 영역입니다
• 지나치게 공들인 배경 설명 — 긴 얘기는 README에. CLAUDE.md는 지시서라서 짧을수록 잘 먹힙니다
• 한 번만 말할 것 — 이번만인 주문은 넘길 때 말하면 충분합니다. 매번 말할 것만 여기 적습니다

규칙은 키우는 것

처음부터 완벽한 CLAUDE.md는 못 씁니다. 못 써도 됩니다.

운영은 이렇게 합니다. AI에게 같은 지적을 두 번 했으면, 그걸 CLAUDE.md에 한 줄 보탠다.

"또 영어로 주석 달았네. 한국어로 써 달라고 했는데" — 두 번째라는 걸 알아챘다면 그 자리에서 이렇게 부탁합니다.

"방금 한 지적을 앞으로도 지켜 줘. CLAUDE.md에 추가해 놔."

그렇습니다, 추가하는 작업 자체도 AI에게 시킵니다. 여러분은 "두 번째다"를 알아채는 담당입니다. 이렇게 CLAUDE.md는 나와 AI 사이에 오간 지적의 축적 — 진짜 업무 매뉴얼로 자라 갑니다.

해 보기

위 템플릿을 밑그림 삼아 CLAUDE.md를 만듭니다. 물론 쓰는 건 AI입니다.

"CLAUDE.md를 만들고 싶어. README를 읽은 다음, 나한테 질문하면서 '지켜 줬으면 하는 것'과 '하지 말았으면 하는 것'을 채워 줘."

10분 문답이면 초판이 나옵니다. 프로젝트 종류별로 밑그림이 더 필요하면 CLAUDE.md 템플릿도 참고하세요.

다음 글: 폴더 구성과 기술 선정