AI 코딩 에이전트가 같은 실수를 두 번 반복하지 않게 하는 방법

만약 당신이 실제 업무에 Claude Code, Cursor, Codex 등 무엇이든 AI 코딩 에이전트를 사용하고 있다면, 제가 말하는 특유의 좌절감을 이미 알고 있을 것입니다. 당신이 수정해 주면, 에이전트는 "전적으로 옳습니다"라고 말합니다. 그러고 나서 두 번의 프롬프트(prompt)가 지나면 정확히 똑같은 행동을 다시 합니다. 잘못된 테스트 러너(test runner)를 사용하거나, 잘못된 임포트(import) 스타일을 적용하거나, 건드리지 말라고 말한 파일을 다시 포맷하거나, 원하지 않는 의존성(dependency)을 추가하는 식입니다.

본능적으로 모델을 탓하게 되지만, 진짜 문제는 그 수정 사항이 당신의 채팅 기록(chat history)에만 머물러 있다는 점입니다. 채팅 기록은 메모리(memory)가 아닙니다. 모든 새로운 세션, 모든 컨텍스트 압축(context compaction), 모든 새로운 작업마다 그 수정 사항은 사라집니다.

해결책은 지루하지만 확실합니다. 에이전트가 실행될 때마다 읽는 파일에 규칙을 적어두는 것입니다. 아래는 제가 실제로 사용하는 워크플로우와, 그 파일에 들어가야 할 내용(그리고 절대 들어가서는 안 될 내용), 그리고 작동한다고 가정하는 대신 실제로 작동하는지 확인하는 방법입니다.

에이전트가 매번 읽는 파일

현재 대부분의 에이전트는 컨텍스트(context)에 자동으로 주입되는 프로젝트 루트(project-root) 지침 파일을 지원합니다:

• Claude Code는 프로젝트 루트에서 CLAUDE.md를 읽습니다 (또한 작업 중인 하위 디렉토리의 중첩된 파일들도 병합합니다).
• Cursor는 .cursor/rules/*.mdc 파일을 사용합니다 (기존의 .cursorrules도 여전히 작동합니다).
• 새롭게 떠오르는 도구 간 표준 규약은 **AGENTS.md**입니다. 이는 OpenAI의 Codex, Cursor, 그리고 점점 늘어나고 있는 다양한 도구들이 표준화하고 있는 일반 마크다운(markdown) 파일입니다. 단순한 마크다운일 뿐이며, 학습해야 할 스키마(schema)도 없습니다. (agents.md 및 OpenAI의 Codex 문서를 참조하세요.)

작동 메커니즘은 어디나 동일합니다. 파일의 내용이 매 작업마다 모델의 컨텍스트 앞에 추가되므로, 모델이 단 한 줄을 쓰기 전에 규칙이 이미 존재하게 됩니다. 이것이 핵심 비결입니다. 당신은 무엇인가를 파인튜닝(fine-tuning)하는 것이 아닙니다. 그저 지속적인 사실(durable facts)을 위해 채팅 기록에 의존하기를 거부하는 것뿐입니다.

실제로 포함되어야 할 내용

사람들이 흔히 실수하는 부분이 바로 여기입니다. 그들은 희망 사항만 가득 담긴 가치 목록("깨끗하고, 유지보수가 용이하며, 문서화가 잘 된 코드를 작성하라")을 쏟아붓고는 왜 아무것도 변하지 않는지 의아해합니다. 모호한 미덕은 행동을 제약하지 못합니다. 구체적이고 테스트 가능한 규칙만이 행동을 제약합니다.

제가 모든 문장에 적용하는 테스트 기준은 다음과 같습니다: 에이전트가 이 규칙을 따랐는지 스스로 확인할 수 있는가? 만약 그렇지 않다면, 삭제하거나 구체화하십시오.

Node 프로젝트에서 가져온 실제 축약된 예시입니다:

# Project Rules

## Commands
...

여기에 없는 내용에 주목하십시오: 우리의 미션에 대한 에세이도 없고, "도움이 되도록 행동하라"는 말도 없으며, 해당 언어가 이미 수행하는 기능을 재진술하는 내용도 없습니다. 모든 문장은 모델이 스스로 대조하여 확인할 수 있는 규칙입니다. 제가 규칙을 추가할 때는 거의 항상 에이전트가 정확히 그 부분에서 저를 실망시켰을 때입니다. 이 파일은 일종의 '흉터 기록(scar log)'입니다.

수정을 커밋(commit)으로 전환하기

이것은 복리 효과를 내는 습관입니다. 에이전트가 당신이 방금 수정한 실수를 저질렀을 때, 단순히 채팅에서 수정하고 넘어가기만 하지 마십시오. 같은 세션 내에서 해당 규칙을 파일에 추가하십시오. 단 한 줄이면 됩니다. 그러면 그것은 영구적이 됩니다.

Claude Code에서는 루프를 벗어나지 않고도 다음과 같이 수행할 수 있습니다:

# 현재 디렉토리에 대한 규칙을 CLAUDE.md에 추가
Append to CLAUDE.md: "npm 대신 `pnpm`을 사용하십시오 — 이 레포지토리에는 pnpm-lock.yaml이 있습니다."

몇 주가 지나면 이 파일은 한 번 작성하고 마는 것이 아니라, 코드베이스에 존재하는 모든 함정(trap)을 기록한 살아있는 기록이 됩니다. 새로운 기여자(사람이든 AI든)는 이 모든 것을 공짜로 물려받게 됩니다.

짧게 유지하십시오 — 컨텍스트(context)는 예산입니다

직관에 어긋나지만 중요한 사실은, 규칙 파일이 길다고 해서 더 좋은 것은 아니라는 점입니다. CLAUDE.md / AGENTS.md에 있는 모든 내용은 모든 작업 시 컨텍스트(context)에 주입되며, 실제 코드 및 사용자의 실제 요청과 주의력(attention)을 두고 경쟁합니다. 2,000줄짜리 선언문은 정작 중요한 10가지 규칙을 희석시킵니다.

저의 가이드라인은 다음과 같습니다: 만약 내용이 대략 150~200줄을 넘어간다면, 그중 무언가는 너무 당연하거나, 오래되었거나, 혹은 실제 문서(documentation)에 들어가야 할 내용입니다. 코드를 관리하듯 가지치기를 하십시오. 어떤 규칙이 한 달 동안 위반되지 않는다면, 때때로 그 규칙을 삭제하고 습관이 정착되었는지 확인하곤 합니다.

진정으로 규모가 크거나 참조할 내용이 많은 것 — 아키텍처 개요(architecture overview), API 계약(API contract) 등 — 은 일반 문서에 작성하고, 규칙 파일에서 해당 경로를 참조(reference the path) 하십시오. 이렇게 하면 에이전트가 매 키 입력마다 불러오는 대신, 관련이 있을 때만 해당 내용을 가져오게 됩니다.

실제로 작동하는지 확인하기

파일이 읽히고 있다고 그냥 믿지 마십시오. 테스트하십시오. 파일 상단 근처에 의도적으로 확인할 수 있는 규칙을 추가해 보세요:

- 작업을 시작할 때, 먼저 테스트를 실행하기 위해 어떤 명령어를 사용할지 명시하십시오.

그런 다음 새로운 세션을 시작하고 작은 작업을 하나 맡겨보십시오. 만약 에이전트가 당신의 테스트 명령어를 언급하며 시작한다면, 파일이 컨텍스트(context)에 포함되어 있으며 규칙이 준수되고 있는 것입니다. 만약 그렇지 않다면, 파일 이름과 위치가 도구가 기대하는 것과 정확히 일치하는지 확인하십시오 (CLAUDE.md는 프로젝트 루트, AGENTS.md는 루트, Cursor의 경우 .cursor/rules/). 파일 위치가 잘못되었거나 이름이 틀리면 조용히 무시되는데, 이것이 사람들이 "이건 작동하지 않는다"라고 결론 내리는 가장 흔한 이유입니다.

이것이 대안들보다 나은 이유

모든 프롬프트에 규칙을 붙여넣을 수도 있겠지만, 일관되게 그러기는 어려울 것이며, 당신이 잊어버리는 순간 시스템은 깨집니다. 거대한 시스템 프롬프트(system prompt)를 사용할 수도 있겠지만, 이는 도구마다 다르고 저장소(repo)와 함께 이동하지 않으며 코드 리뷰 시에도 나타나지 않습니다. 커밋된 규칙 파일은 버전 관리(version-controlled)가 가능하고, 차이점 확인(diffable)이 가능하며, 검토(reviewable)가 가능하고, 팀 전체 및 프로젝트를 여는 모든 에이전트와 공유됩니다. 이것은 에이전트를 단순히 교정하는 것과 에이전트를 설정(configuring) 하는 것의 차이입니다.

전체 과정을 4단계로 요약

1. 프로젝트 루트에 CLAUDE.md (또는 AGENTS.md)를 생성합니다.
2. 구체적이고 스스로 확인할 수 있는 규칙 — 명령어, 스타일 제약 사항, 엄격한 경계, 완료 정의(definition of done) — 만 작성합니다.
3. 에이전트가 실수를 할 때마다, 동일한 세션 내에서 한 줄을 추가합니다. 짧게 유지하고, 오래된 규칙은 가지치기하십시오.
4. 신뢰하기 전에 새로운 세션과 확인 가능한 규칙으로 검증하십시오.

이 방법 중 영리한 것은 아무것도 없습니다. 바로 그렇기 때문에 작동하는 것입니다. 에이전트들은 계속 똑똑해지고 있지만, 당신이 에이전트가 실제로 읽을 수 있는 곳에 적어두지 않는 한 어제 말한 내용을 기억하지는 못합니다.

출처: agents.md (AGENTS.md 컨벤션); Anthropic — Claude Code memory / CLAUDE.md docs; Cursor rules documentation. 파일 이름 및 메커니즘은 2026년 중반 기준으로 해당 문서들을 통해 검증되었습니다. 컨벤션이 여전히 변화하고 있으므로, 사용 중인 도구의 최신 문서를 통해 확인하시기 바랍니다.