내 AI 에이전트가 나랑 싸우는 걸 멈추게 한 40줄의 마크다운
The 40 lines of markdown that stopped my AI agent from fighting me
핵심 요약
AI 에이전트의 반복적인 실수를 방지하기 위해 CLAUDE.md 파일을 활용하여 구체적인 지침을 설정하는 방법 공유.
- CLAUDE.md 활용 — 에이전트가 세션마다 읽는 설정 파일로 반복적인 실수를 방지함.
- 지침 작성 원칙 — 모호한 설명 대신 에이전트가 즉시 수행할 수 있는 구체적인 명령어로 작성함.
- 반복 오류 해결 — 에이전트가 같은 실수를 반복하면 프롬프트 수정 대신 규칙을 추가함.
- 추가 도구 활용 — CLAUDE.md 외에도 커스텀 훅을 사용하여 에이전트의 동작을 강제로 제어함.
모든 프로젝트에는 AI가 세션마다 틀리는 한 가지가 있다. 잘못된 패키지 매니저, 두 번째 개발 서버 실행, migrations 폴더 건드리기. 수정해주고 사과받아도 다음 세션에 또 똑같이 한다.
해결책은 지루하지만 확실하다. 레포 루트에 CLAUDE.md 파일을 두는 것이다. Claude Code(그리고 AGENTS.md를 통해 대부분의 다른 에이전트들)는 매 세션 시작마다 이걸 읽는다. 하지만 대부분 잘못 작성하니까, 우리 방식을 바꾼 규칙을 공유한다.
모든 줄은 에이전트가 '하는 행동'을 바꿔야 한다. "우리는 pnpm을 사용하고 일관된 도구를 중요하게 생각함"은 장식일 뿐이다. "패키지 매니저는 pnpm임. npm이나 yarn 절대 쓰지 마."는 지침이다. 에이전트는 파일 트리는 읽을 수 있지만, 당신의 마음은 읽을 수 없다.
포함해야 할 내용:
- 실제 스크립트 이름이 포함된 정확한 명령어 (pnpm typecheck, "타입 체크해"가 아님)
- 절대/항상 규칙, 명확하게 서술
- 한 시간을 낭비하게 만드는 함정들 (비워야 하는 캐시, Docker 실행이 필요한 테스트 스위트)
포함하지 말아야 할 내용: 폴더 구조, 기술 스택 목록, 에이전트가 스스로 볼 수 있는 모든 것.
그리고 에이전트가 같은 실수를 두 번 하면, 그건 프롬프트 문제가 아니라 규칙이 빠진 거다. 더 긴 프롬프트가 아니라 규칙을 추가해라.
우리가 만든 5가지 템플릿(Next.js, Python, monorepo, API 서비스, lean starter)을 무료로 공개함, MIT 라이선스: https://techpotions.com/products/claude-md-templates
세 번째로 같은 실수를 했을 때 당신이 적어둬야 했던 규칙은 무엇인가?
