AGENTS.md·CLAUDE.md 작성법: AI가 프로젝트 규칙을 이해하게 하기

에이전트에게 필요한 것은 프로젝트의 숨은 전제입니다

Claude Code 문서는 사용자가 작성하는 프로젝트 지침과 도구가 축적하는 메모리를 구분합니다. AGENTS.md나 CLAUDE.md처럼 저장소에 두는 지침은 팀이 합의한 규칙을 전달하는 통로로 활용할 수 있습니다. 지원 파일명, 탐색 범위와 우선순위는 사용하는 도구와 버전의 문서에서 확인해야 합니다.

좋은 지침에는 '기존 스타일을 따르세요'보다 '금액은 원 단위 정수로 저장하며 화면에서만 쉼표를 표시한다'처럼 코드 일부만 봐서는 놓치기 쉬운 전제가 담깁니다. 설치된 프레임워크에 큰 변경이 있다면 해당 버전의 로컬 문서를 먼저 읽도록 경로를 알려주는 것도 효과적인 출발점입니다.

첫 파일에는 다섯 가지 정보만 정리해 보세요

공통 규칙과 특정 영역의 규칙을 나눕니다

앱과 백엔드의 실행 명령이 다르다면 루트 파일에는 공통 규칙과 진입 경로를 두고 세부 사항은 가까운 문서에 정리하세요. 다만 하위 지침을 자동으로 읽는다고 가정해서는 안 됩니다. 실제 도구가 어떤 파일을 로드했는지 확인하고, 자동 탐색이 없는 환경에서는 필요한 문서를 명시적으로 연결합니다.

모든 개발 지식을 지침 파일에 넣으면 현재 작업과 관계없는 정보가 늘어납니다. 자주 바뀌는 API 목록은 공식 문서나 코드로 안내하고, 팀만 아는 예외를 우선 남기세요. 같은 명령이 여러 문서에 복제돼 있다면 기준 문서를 하나 정해 링크하는 편이 수정 누락을 줄입니다.

문장으로 쓴 규칙을 실행 권한과 혼동하지 않습니다

'운영 DB를 수정하지 말 것'은 모델에 전달하는 지침입니다. 실제로 접근을 차단하려면 자격 증명, 네트워크, 실행 환경의 권한도 제한해야 합니다. 지침의 준수 여부는 작은 변경 작업을 맡겨 확인하고, 반복되는 실패가 생기면 문장을 늘리기 전에 도구 설정이나 프로젝트 구조가 원인인지 살펴보세요.

지침 파일 유지보수 체크리스트

• 명령을 새 작업 환경에서 그대로 실행할 수 있는가
• 규칙의 적용 경로와 예외가 명확한가
• 폐기된 패키지나 과거 폴더명을 참조하지 않는가
• API 키나 운영 접속 정보를 포함하지 않았는가
• 규칙을 바꾼 이유와 담당자가 변경 이력에 남는가