AI 지원 레포지토리에서 가장 활용도가 높은 파일은 CLAUDE.md (또는 AGENTS.md)입니다

만약 Claude Code, Cursor 또는 Copilot을 매일 사용하면서도 레포지토리에 규칙 파일을 가지고 있지 않다면, 많은 것을 놓치고 있는 것입니다. 잘 작성된 CLAUDE.md / AGENTS.md / .cursorrules 파일은 AI 에이전트가 토큰 낭비를 멈추게 하고, 유틸리티를 재창조하는 것을 멈추게 하며, 여러분의 컨벤션을 따르도록 만드는 가장 저렴한 변경 사항입니다.

실제로 여기에 무엇을 넣어야 하는지 — 그리고 무엇을 제외해야 하는지를 알려드리겠습니다.

이러한 파일이란 무엇인가요

이것들은 레포지토리 루트에 있는 작은 Markdown 파일이며, 에이전트가 지침으로 읽는 역할을 합니다:

• CLAUDE.md: Claude Code에서 자동으로 읽습니다.
• AGENTS.md: 현재 여러 도구가 존중하는 새롭게 등장한 크로스-에이전트 컨벤션입니다.
• .cursorrules: Cursor의 이에 상응하는 파일입니다.

아이디어는 같고, 파일 이름만 다릅니다. 많은 팀들이 거의 동일한 내용으로 이 세 가지 파일을 모두 유지하고 있습니다.

무엇을 넣어야 할까요

간결하고 신호가 명확해야 합니다. 2,000줄 분량의 규칙이 담긴 에이전트는 그 어떤 것도 따르지 않습니다.

1. 스택(Stack)을 명료하게 기술합니다.

- Languages: TypeScript, Python
- Framework: Next.js (App Router)
- Package manager: pnpm
...

이것만으로도 에이전트가 pnpm 레포지토리에서 npm install을 제안하거나, hooks 기반 코드베이스에서 클래스 컴포넌트를 제안하는 것을 막을 수 있습니다.

2. 중요한 명령어들을 명시합니다.

- Install: pnpm install
- Dev: pnpm dev
- Test: pnpm test
...

이제 에이전트는 추측하는 대신 자신의 작업을 검증할 수 있습니다.

3. 여기서 작업하는 방법 — 컨벤션입니다.

• 편집하기 전에 관련 파일을 읽고, 기존 스타일을 따르세요.
• 작업을 해결하는 가장 작은 변경만 하세요. 무관한 코드를 리팩토링하지 마세요.
• 새로운 의존성보다 기존 유틸리티를 선호하세요.

4. 가드레일(Guardrails) — 하지 말아야 할 것들입니다.

• API나 파일 경로를 임의로 만들지 마세요. 존재 여부를 확인하세요.
• 비밀 정보를 커밋하지 마세요.
• 주석 처리된 코드나 콘솔 스팸을 남기지 마세요.

무엇을 제외해야 할까요

• 새로운 길이의 철학. 실행 가능한 내용이 아니면 노이즈입니다.
• 에이전트가 코드에서 읽을 수 있는 것들. 모든 폴더의 목적을 반복해서 설명하지 마세요. 어디를 봐야 하는지 알려주세요.
• 비밀 정보, 내부 URL, 커밋하면 안 되는 모든 것.

유지하기 (Keep it alive)

이 파일을 코드처럼 취급하세요. 에이전트가 짜증나게 같은 행동을 두 번 한다면, 그것을 금지하는 한 줄을 추가하세요. 몇 주에 걸쳐 당신의 규칙 파일은 복리 자산(compounding asset)이 됩니다. 모든 미래 세션이 더 똑똑하게 시작될 것입니다.

2초 만에 초안 생성하기 (Generate a first draft in two seconds)

첫 버전을 손으로 작성하는 것은 지루합니다. 저는 사용자의 스택을 감지하고 세 파일 모두를 자동으로 구성해주는 무료 VS Code / Cursor 확장 프로그램(Agent Rules)을 만들었습니다 (오픈 소스). 하나의 명령어를 실행하고, 파일을 선택한 다음, 원하는 대로 편집하세요.

만약 더 깊고 역할별로 특화된 사전 설정(프레임워크 구성, MCP 서버 설정, 서브 에이전트 정의, 검토 체크리스트 등)을 원한다면, 유료 Agentic Coding Starter Kit가 있습니다. 하지만 이 확장 프로그램과 위의 개요만으로도 대부분의 사람들은 무료로 괜찮은 규칙 파일을 얻을 수 있습니다.

당신의 CLAUDE.md에는 무엇이 있나요? 저는 좋은 패턴들을 모으고 있습니다. 최고의 규칙을 공유해 주세요.