CLAUDE.md 작성법 7가지 원칙 — 안티패턴 4가지와 Spring Boot SI 템플릿 전문
클로드 코드(Claude Code)를 팀에 도입하면서 가장 많이 고친 파일이 CLAUDE.md 였습니다. 처음엔 "자세할수록 좋다"고 믿고 길게 썼는데, 결과는 반대였습니다. 이 글은 그 시행착오 끝에 정리한 작성 원칙 7가지와, 금융권 Spring Boot SI 프로젝트용 템플릿 전문입니다. 앞 글 금융권 망분리 환경 도입 5가지 의 후속입니다. CLAUDE.md는 문서가 아니라 지시문입니다 클로드 코드는 세션을 시작할 때 다음 위치의 CLAUDE.md 를 찾아 컨텍스트에 넣습니다. ~/.claude/CLAUDE.md — 개인 전역 (모든 프로젝트에 적용) 프로젝트 루트 CLAUDE.md — 팀 공용, git 커밋 대상 하위 폴더의 CLAUDE.md — 그 폴더의 파일을 다룰 때 추가로 로드 (모노레포에서 유용) CLAUDE.local.md — 개인용, .gitignore 에 넣음 핵심은 두 번째입니다. 프로젝트 루트 CLAUDE.md 하나가 팀 전체에 같은 규칙을 강제 합니다. 이 파일을 읽는 대상은 사람이 아니라 모델이라는 점을 잊지 마세요. 서술문이 아니라 명령문으로, 배경 설명이 아니라 규칙으로 씁니다. 잘 쓰는 CLAUDE.md의 7가지 원칙 1. 짧게. 300줄을 넘기지 않는다 길어질수록 모델이 각 규칙에 주는 가중치가 떨어집니다. 정확히 말하면 길이 자체보다 모든 규칙을 같은 우선순위로 한꺼번에 읽히게 만드는 것 이 문제입니다. 상세 내용은 docs/ 로 빼고 링크만 둡니다. 루트에는 자주 틀리는 치명 규칙과 실행 명령만 남깁니다. 2. "하지 말 것"이 "할 것"보다 중요하다 모델은 기본적으로 뭐든 해 보려 합니다. 금지 목록이 사고를 막습니다. 아래 템플릿마다 "절대 하지 말 것" 섹션이 있는 이유입니다. 그중 정말 치명적인 것(운영 설정 파일 수정, force push, 테스트 삭제)은 CLAUDE.md에 적는 것으로 끝내지 말고 ...