AI 에이전트가 지시를 따르지 않을 때 수정하기: CLAUDE.md / AGENTS.md에 작성해야 할 것과 하지 말아야 할 것

서론

혹시 AI 에이전트에게 매번 '이 프로젝트의 방식'을 구두로 전달하고 있지는 않으신가요? CLAUDE.md나 AGENTS.md 같은 규칙 파일을 두어도, '작성했는데 지켜지지 않는다', '너무 길어져서 오히려 혼란스럽다'는 의견을 자주 접합니다.

이 글에서는 규칙 파일의 효과를 높이는 작성 방법을 정리합니다.

예상 독자: Claude Code / Codex / Cursor 등의 에이전트를 사용하기 시작한 사람

전제: 파일 이름이나 로딩 사양은 도구와 버전에 따라 다르므로, 반드시 공식 문서를 확인해 주세요.

결론

코드를 읽으면 알 수 있는 것은 작성하지 않습니다. 작성하는 것은 '읽어도 이해할 수 없는 것'만입니다.

형용사 대신 명령어와 구체적인 예시를 작성합니다.
규칙은 미리 완벽하게 만들려 하기보다, 실패할 때마다 한 줄씩 추가합니다.
절대 지키게 하고 싶은 것은 문장이 아니라 시스템(lint・hooks・CI)으로 강제해야 합니다.

작성해야 할 것

에이전트가 스스로 추측할 수 없는 정보로 제한합니다.

작성하지 않는 것이 좋은 것

코드에서 알 수 있는 내용('이 프로젝트는 React입니다' 등). 단순히 장황할 뿐입니다.
모호한 형용사('깔끔한 코드를 작성하기', '신중하게'). 지켜졌는지 판별할 수 없습니다.
긴 배경 설명. 길수록 중요한 내용이 묻힙니다.
기밀 정보(API 키, 미공개 사양). 규칙 파일은 리포지토리에 들어가는 것을 전제로 다루어야 합니다.

템플릿

• 테스트:
  npm run test -- --run

• Lint:
  npm run lint

• 타입 체크:
  npm run typecheck

• 컴포넌트는
  src/components/
  에 배치 (1파일 1컴포넌트) - 새로운 의존 패키지는 추가하지 않기. 필요하다면 이유를 적어 질문하기

• .env 및 secrets/
  아래 내용을 읽거나 출력하지 않기 - 기존 테스트를 삭제하거나 스킵하지 않기

• 운영 환경에 연결하는 명령을 실행하지 않기

• 테스트・lint・타입 체크가 모두 통과했는지 확인하기

• 변경점과, 확인할 수 없었던 점을 마지막에 목록으로 보고하기

• 사양이 모호하면, 추측하여 구현하지 않고 질문하기

규칙은 '실패'로부터 키워야 합니다.

처음부터 완벽한 규칙을 쓰려고 하면 반드시 길어집니다. 추천하는 것은 다음 루프입니다.
먼저 에이전트의 출력을 수정합니다. 그다음 '같은 지적을 다음 주에도 할 것인가?'라고 자문합니다. 한다면, 규칙에 한 줄 추가합니다. 안 한다면, 추가하지 않습니다.

이를 계속하면 파일은 '자신의 리뷰 관점 기록'이 됩니다.

효과가 없을 때 확인 포인트

읽혀지고 있는지: 에이전트에게 '지금 읽고 있는 규칙을 나열해 달라'고 물어보면 확인할 수 있습니다.
배치 위치는 적절한지: 파일 탐색 범위(루트 직하인지, 서브 디렉토리인지)는 도구에 따라 다릅니다.
규칙끼리 모순되지 않는지: '간결하게'와 '상세한 예시를 반드시 첨부할 것'이 공존하지 않는지 확인합니다.
너무 길지는 않은지: 한 화면에서 읽을 수 있는 양을 기준으로, 너무 커졌다면 용도별로 분할합니다.
도구마다 파일이 나뉘어 있지 않은지: 여러 에이전트를 병용하는 경우, 내용을 통일하는 방법(참조・심볼릭 링크 등)은 각 도구의 문서를 확인해 주세요.

문장으로는 강제할 수 없는 것들

규칙 파일의 지시는 어디까지나 부탁입니다. 항상 100% 지켜질 보장은 없습니다. 따라서 중대한 것은 시스템으로 막아야 합니다.

• 기밀 정보 유출 → .gitignore, 시크릿 스캔, 권한 분리
• 코드 품질 → lint・타입 체크・CI로 기계적으로 적용
• 위험한 명령어 → 도구 측의 허가 설정이나 hooks

'문장으로 부탁하기'와 '시스템으로 막기'를 구분하여 생각하면 규칙 파일을 짧게 유지할 수 있습니다.

요약

규칙 파일은 '읽어도 이해할 수 없는 것'만 구체적으로 작성합니다.
실패할 때마다 한 줄씩 추가하며 키워나갑니다.
절대 지키게 하고 싶은 것은 lint・CI・권한 설정에 맡깁니다.
우선, 최근 자신이 2회 이상 같은 지적을 했던 내용을 딱 한 줄부터 시작해 보세요.