대부분의 AI 에이전트가 실패하는 이유는 모델이 나빠서가 아닙니다.
매 세션이 시작될 때마다 기억을 잃은 채로 깨어나기 때문입니다.
Claude에게 "우리는 pnpm을 사용합니다, npm이 아닙니다"라고 알려주면,
다음 세션에서 다시 npm을 시도합니다.
"여기서는 default export를 사용하지 마세요"라고 알려주면,
다음 세션에서 default export를 작성합니다.
매번 수정한 내용이 세션이 끝나는 순간 사라집니다.
이 문제를 해결하는 한 가지 파일이 있습니다.
이걸 찾기 위해 3개월 동안 같은 말을 반복해야 했습니다.
제가 배운 모든 것을 공유합니다.
대부분의 AI 에이전트가 실패하는 이유
모델 탓이 아닙니다.
모델 아래에 있는 누락된 레이어가 문제입니다.
→ 프롬프트를 작성합니다
→ 에이전트가 작업을 수행합니다
→ 세션이 종료됩니다
→ 메모리가 사라집니다
→ 다음 세션: 같은 실수를 반복합니다
→ 같은 지시를 반복합니다
→ 영원히
이 루프는 AI 코딩에서 시간 낭비의 가장 큰 원인입니다.
나쁜 코드도, 환각도 아닙니다.
바로 반복입니다.
누락된 레이어: 메모리
모든 사람이 어떤 모델이 가장 똑똑한지에 집착합니다.
잘못된 레이어입니다.
진짜 업그레이드는 더 똑똑한 모델이 아닙니다.
모델이 배운 것을 저장할 공간을 제공하는 것입니다.
→ 프롬프트 → 에이전트에게 지금 해야 할 일을 알려줍니다
→ 에이전트 → 작업을 실행합니다
→ 메모리 → 세션 간에 컨텍스트를 유지합니다
→ 지속적인 컨텍스트 → 더 이상 반복적인 수정이 필요 없습니다
→ 학습 시스템 → 에이전트가 시간이 지남에 따라 실제로 개선됩니다
이것이 도구와 팀원의 차이입니다.
도구는 매번 처음부터 다시 시작합니다.
팀원은 어제의 일을 기억합니다.
모든 AI 에이전트가 필요한 5가지 메모리 파일
메모리가 누락된 레이어라는 것을 받아들이면, 다음 질문은 그것이 어디에 위치해야 하는가입니다.
다섯 개의 파일입니다. 각각 다른 역할을 합니다.
→ CLAUDE.md — Claude 전용 브리핑 문서
→ AGENTS.md — 모든 주요 도구가 읽는 범용 표준
→ CLAUDE.local.md — git에 커밋되지 않는 개인 환경 설정
→ MEMORY.md — AI가 스스로 작성하는 메모
→ README.md — 에이전트가 아닌 사람을 위한 문서
각각을 살펴보겠습니다.
CLAUDE.md — 모든 것을 시작한 파일
프로젝트 루트에 이 파일을 넣으세요.
Claude는 모든 세션이 시작될 때 이 파일을 읽습니다.
기억 상실증이 있는 새 팀원을 위한 브리핑 문서라고 생각하세요.
좋은 CLAUDE.md는 네 가지 섹션으로 구성됩니다:
→ 프로젝트 컨텍스트 — 한 줄. "Stripe 및 Postgres를 사용하는 Next.js 전자상거래 앱"
→ 코드 스타일 — "코드를 적절히 포맷하세요"가 아닌 "ES 모듈, named export, 2칸 들여쓰기 사용"
→ 명령어 — 정확한 문자열. "테스트 실행"이 아닌 pnpm test:integration
→ 아키텍처 — "API 라우트는 /src/api/[resource]/route.ts에 위치. DB 액세스는 레포지토리 패턴 사용"
1# CLAUDE.md23## 프로젝트 컨텍스트4Next.js 14 전자상거래 앱. Postgres + Stripe 통합.56## 코드 스타일7- ES 모듈만 사용8- default export 금지, named export 사용9- 2칸 들여쓰기10- TypeScript strict 모드1112## 명령어13- 설치: pnpm install14- 개발: pnpm dev15- 테스트: pnpm test:integration16- 린트: pnpm lint:fix1718## 아키텍처19- API 라우트: /src/api/[resource]/route.ts20- DB 액세스: 레포지토리 패턴만 사용21- 컴포넌트: /src/components, 파일당 하나의 컴포넌트
목표: 300줄 미만.
모든 줄이 실제 작업과 주목을 놓고 경쟁합니다.
/init 을 실행하면 Claude가 자동으로 시작 파일을 생성합니다.
그런 다음 대부분을 삭제하세요.
기본 파일에는 Claude가 package.json에서 이미 알고 있는 내용이 포함되어 있습니다. 파일이 없으면 Claude가 잘못 이해할 수 있는 내용만 유지하세요.
@imports 시스템 — 간결하게 유지
CLAUDE.md가 모든 것을 담을 필요는 없습니다.
다른 파일을 가져올(import) 수 있습니다:
참고:
@README .md — 프로젝트 개요 참고:
@docs/api-patterns .md — API 규칙 참고:
@package .json — 사용 가능한 npm 스크립트
가져오기는 최대 5단계까지 재귀적으로 가능합니다.
이것이 "하나의 거대한 파일" 문제를 해결합니다.
팀의 경우: 프론트엔드 팀은 docs/frontend-rules.md를 관리합니다.
보안 팀은 docs/security.md를 관리합니다.
CLAUDE.md는 이 모든 파일을 가져오기만 하면 됩니다.
하나의 루트 파일. 여러 전문 소스.
AGENTS.md — 범용 표준
CLAUDE.md는 Claude에서만 작동합니다.
팀에서 Cursor, Copilot 또는 Gemini CLI도 사용한다면, 이 도구들은 CLAUDE.md를 읽지 않습니다.
AGENTS.md가 이 문제를 해결합니다.
하나의 파일. 모든 주요 에이전트가 읽습니다.
Claude Code, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Aider, Zed, Warp 등에서 지원됩니다.
표준 마크다운입니다. 특별한 스키마나 YAML이 필요하지 않습니다.
1# AGENTS.md23## 프로젝트 개요4Next.js 14, Postgres 및 Stripe로 구축된 전자상거래 플랫폼.56## 빌드 및 테스트7- 설치: pnpm install8- 개발: pnpm dev9- 테스트: pnpm test10- 린트: pnpm lint:fix1112## 코드 표준13- TypeScript strict 모드14- default export보다 named export 우선15- API 라우트는 /src/api/에서 REST 규칙을 따름1617## 테스트 요구사항18- 모든 PR에는 테스트 포함 필수19- 단위 테스트는 vitest, e2e 테스트는 playwright 사용
AI 에이전트를 위한 README라고 생각하세요.
README.md는 사람을 위한 것입니다. AGENTS.md는 벤더에 관계없이 모든 에이전트를 위한 것입니다. CLAUDE.md는 그 위에 Claude 전용 추가 정보를 제공합니다.
서로 보완적입니다. 경쟁하지 않습니다.
자동 메모리 — 스스로 메모를 작성하는 AI
이것은 가장 새롭고 흥미로운 레이어입니다.
Claude Code는 이제 세션 중에 자체 메모리 파일을 작성합니다.
memory/ ├── MEMORY.md ← 인덱스, 모든 세션에서 로드됨 ├── debugging.md ← 디버깅 패턴에 대한 메모 ├── api-conventions.md ← API 설계 결정 └── ...
핵심 변화:
당신이 CLAUDE.md를 작성합니다. 지침을 제공합니다.
Claude가 MEMORY.md를 작성합니다. 배운 내용을 기록합니다.
→ 사람이 규칙을 작성합니다
→ 에이전트가 작업하면서 패턴을 발견합니다
→ 에이전트가 자신의 메모를 작성합니다
→ 이후 세션은 더 똑똑하게 시작됩니다
직접 트리거할 수 있습니다. 생산적인 세션이 끝날 때 다음과 같이 말하세요:
"오늘 코드베이스에 대해 배운 내용을 메모리 파일에 업데이트하세요."
학습한 내용이 유지됩니다. 다섯 번째로 커스텀 ORM 래퍼를 다시 설명할 필요가 없습니다.
/memory 를 실행하면 Claude가 저장한 내용을 검토하거나 편집할 수 있습니다.
/init 후 삭제 워크플로우
새 프로젝트에서 메모리 파일을 가장 빠르게 부트스트랩하는 방법:
- 프로젝트 디렉토리에서 /init 실행
- Claude가 코드베이스를 기반으로 시작용 CLAUDE.md 생성
- 필요 없는 부분 삭제
3단계에서 대부분의 사람들이 실수합니다.
생성된 파일은 초안일 뿐, 완성된 제품이 아닙니다.
종종 불필요한 내용이 포함됩니다. "이 프로젝트는 JavaScript를 사용합니다." — 감사합니다. package.json에서 이미 확인 가능합니다.
괜찮은 초안에서 편집하는 것이 빈 파일에서 시작하는 것보다 낫습니다.
설정 후에는 유기적으로 구축하세요.
Claude가 잘못된 가정을 할 때 — 예를 들어, 계속해서 더 이상 사용되지 않는 패키지를 가져오려고 한다면 — 한 번만 수정하지 마세요.
다음과 같이 지시하세요: "내 CLAUDE.md에 추가: 항상 @company/utils가 아닌 @company/utils-v2에서 가져오기."
이 지침은 모든 향후 세션에 대해 유지됩니다.
몇 주마다 Claude에게 CLAUDE.md를 검토하고 정리하도록 요청하세요.
지침이 누적됩니다. 일부는 중복되고, 다른 것들은 충돌하기 시작합니다. 빠른 정리로 깔끔하게 유지할 수 있습니다.
실제 설정
여러 프로덕션 프로젝트에서 이 모든 것을 테스트한 결과, 다음 설정이 가장 효과적이었습니다:
→ AGENTS.md (프로젝트 루트) — 모든 AI 도구가 읽는 공유 지침. 빌드 명령어, 코드 표준, 테스트 요구사항.
→ @imports를 사용하는 CLAUDE.md — Claude 특정 동작용. 100줄 미만으로 유지하며, 대부분 docs/ 파일을 가리킵니다.
→ CLAUDE.local.md — 개인 설정용 (테스트 데이터, 샌드박스 URL, 단축 명령어). git에 커밋되지 않음.
→ 자동 메모리 활성화. Claude가 스스로 메모를 작성하며, 월간 검토.
→ 나머지는 모두 AGENTS.md를 가리키는 심볼릭 링크로 대체. 하나의 진실 공급원.
1# 다중 도구 일관성을 위한 심볼릭 링크 설정2ln -sfn AGENTS.md .github/copilot-instructions.md3mkdir -p .cursor/rules && ln -sfn ../../AGENTS.md .cursor/rules/main.mdc
우아하지는 않습니다.
하지만 팀 내 모든 도구에서 지침 불일치를 없애줍니다.
더 큰 변화
대부분의 개발자는 이렇게 생각합니다:
더 나은 모델 = 더 나은 에이전트
틀렸습니다.
진짜 공식은:
모델 + 메모리 + 검색 + 피드백 = 유용한 에이전트
메모리가 없는 더 똑똑한 모델은 내일 당신의 테스트 명령어를 잊어버립니다.
메모리가 뛰어난 보통 모델은 매주 더 정교해집니다.
메모리가 복리 효과를 내는 변수입니다.
모델 지능은 그렇지 않습니다.
제 AI 워크플로우에 가장 큰 개선을 가져온 것은 모델을 바꾼 것이 아니었습니다.
모델에 메모리를 부여한 것이었습니다.
다음의 차이:
"Claude, 우리는 pnpm을 사용합니다" — 매 세션마다
그리고:
"Claude는 이미 알고 있습니다" — 매 세션마다
이것이 도구와 팀원의 차이입니다.
도움이 되었다면:
→ 매번 Claude에게 같은 말을 반복하는 모든 개발자와 공유하기 위해 리포스트해주세요
→ @sairahul1을 팔로우하여 잠자는 동안에도 복리 효과를 내는 더 많은 시스템을 확인하세요
→ 북마크에 저장 — 오늘 밤 설정하고, 내일부터 수정을 중단하세요
저는 AI, 제품 구축, 그리고 당신 없이도 작동하는 시스템에 대해 글을 씁니다.
