monorepo에서 Cursor Agent에게 결제 모듈 수정을 맡겼는데 사용자 센터 DTO를 건드립니다. Claude Code가 20회 bash 실행 뒤 갑자기 「내부 legacy 패키지 직접 import 금지」를 잊어버립니다——모델이 갑자기 멍청해진 게 아니라, 대형 프로젝트에서 가장 흔한 장애 패턴: 컨텍스트 손실입니다.
2026년 Cursor, Claude Code 모두 백만급 컨텍스트를 내세우지만, 현장에서는 약속을 잊는 빈도가 크게 줄지 않았습니다. 본문은 재현 가능한 5단계 점검법을 제공합니다. 먼저 어떤 「잃음」인지 구분하고, 예산·인덱스·경계·저장소 약속·세션 전략 순으로 확인합니다. 도구 버전 기준 2026-07-17(Cursor 1.x, Claude Code 최신 CLI).
Quick Answer: 5단계 점검 한눈에
| 단계 | 확인할 것 | 전형적 조치 | 효과 신호 |
|---|---|---|---|
| 1. 증상 분류 | 세션 절단 / 인덱스 미스 / 규칙 미로드 | 아래 표로 잃는 방식 판단. 바로 모델 교체 금지 | 「세션」 vs 「저장소」 문제인지 파악 |
| 2. 컨텍스트 예산 | 도구 호출 횟수·자동 주입이 창을 넘치는지 | 무관 탭 닫기, @ 파일 줄이기, 탐색용 작은 모델 | 반복 지시 감소, diff 모순 감소 |
| 3. 인덱스 재구축 | .cursorignore, 거대 디렉터리, 인덱스 노후 | Reindex, node_modules / DerivedData 제외 | Agent가 올바른 패키지 경로 자동 발견 |
| 4. 경계 설정 | 작업 범위가 과도한지 | 하위 디렉터리 워크스페이스, 명시 @ 호출 체인, Handoff 블록 | 변경 파일 수가 예상 모듈 내 |
| 5. 저장소 약속 | 구두 규칙이 검색 가능 텍스트에 없음 | AGENTS.md, .cursor/rules, 긴 세션 분할 | 새 세션에서도 같은 제약 준수 |
대형 프로젝트에서 「컨텍스트 손실」이란?
개념부터 맞춥니다. 긴 컨텍스트 창은 「지금 이 token을 담을 수 있는가」;유효 컨텍스트는 「이번 추론에 어떤 사실이 쓰였는가」. 대형 저장소에서는 이 간극이 커집니다——자세히는 AI 코딩 지속 기억 글 참고.
엔지니어가 말하는 「잊었다」는 보통 세 유형입니다:
| 유형 | 표면 증상 | 흔한 근본 원인 | 우선 점검 |
|---|---|---|---|
| A. 세션 절단 | 같은 스레드에서 갈수록 벗어남, 방금 제약을 뒤집음 | 다회 도구 출력이 초기 지시를 밀어냄; compact/요약으로 세부 손실 | 단계 2, 5 |
| B. 인덱스 미스 | 「모듈을 못 찾음」「테이블이 없다고 함」 | ignore 과다, 인덱스 미갱신, 저장소가 커서 검색 노이즈 | 단계 3, 4 |
| C. 규칙 미로드 | 새 세션에서 네이밍·금지 경로 전부 망각 | 약속이 채팅에만 있음, AGENTS.md 없거나 너무 길어 무효 | 단계 5 |
단계 1: 먼저 분류——모든 「망각」을 모델 탓으로 하지 말 것
오류나 엉뚱한 diff가 나오면 60초 결정 트리:
- 같은 세션에서 앞뒤 모순? → A 세션 절단, 단계 2.
- 새 세션에서만 약속 망각? → C 규칙 미로드, 단계 5.
- 모델은 「파일 없음」인데
grep으로는 보임? → B 인덱스 미스, 단계 3–4. context length exceeded/prompt is too long? → 명확한 예산 문제, 바로 단계 2.
Cursor와 Claude Code 초점이 약간 다릅니다. Cursor Composer/Agent는 열린 파일과 인덱스 조각을 자동 주입해 IDE에서 「조용히 창을 채움」. Claude Code 터미널 Agent는 긴 bash 체인 + 자동 compact 후 중간 결정을 잃기 쉽습니다. 도구 비교는 선택 가이드 참고.
단계 2: 컨텍스트 예산 확인——창이 크다고 절약하는 건 아님
한 Agent 작업의 실제 token 소비는 시스템 프롬프트 + 규칙 파일 + @ 파일 + 도구 출력(grep, 테스트 로그) + 이력 요약에서 옵니다. 12만 줄 TypeScript monorepo 실측에서 Cursor Agent가 관련 파일 8개 자동 읽기+전체 테스트 시 입력만 80K–120K token에 닿기 쉽고——다회 재시도는 아직 미포함.
2.1 Cursor
- 작업과 무관한 열린 파일 닫기. 거대 JSON/락 파일은 에디터에 두지 않기.
- 탐색 단계는 작은 컨텍스트 모델 또는 일반 Chat; 방향 확정 후 Agent로 코드 변경.
- 한 Composer에 「리팩터 + 테스트 + CI 변경」 연쇄 금지——3작업으로 나누고 매번 파일 목록 명시.
- Settings의 Codebase indexing 상태 확인. 인덱스 실패 시 Agent가 grep으로 버티며 팽창 가속.
2.2 Claude Code
- 긴 작업에서 auto-compact 발생 여부 관찰. compact 후 고정 템플릿으로 「위반 불가 제약」 한 줄 보강.
- 거대 명령 출력은 파일로 리다이렉트, Agent는
tail로 핵심 줄만. 5000줄 로그를 대화에 넣지 않기. /clear또는 새 세션 전 결론을HANDOFF.md나 issue 댓글에 기록.
| 신호 | 가능 원인 | 즉시 할 일 |
|---|---|---|
| 후반으로 갈수록 엉뚱한 수정 | 초기 제약이 창에서 밀려남 | 새 세션 + Handoff + 더 짧은 작업 |
| API 청구가 작업당 급증 | 대용량 파일 반복 읽기 / 전체 테스트 출력 | 테스트 범위 제한, head/tail 사용 |
| context exceeded | 하드 한도 초과 | @ 파일 축소, 작업 분할, 탐색 모델로 |
단계 3: 인덱스 재구축과 ignore 정리——Agent가 「찾게」 만들기
유형 B의 핵심: 모델이 안 보려는 게 아니라, 검색 체인이 올바른 파일을 안 넘김.
3.1 .cursorignore / .claudeignore 확인
적절한 ignore는 인덱스 시간을 줄이지만, 과도하면 「유령 사각」이 생깁니다. 제외 유지 대상:
node_modules/,.git/,dist/,build/,DerivedData/- 생성 코드가 거대한 디렉터리(생성물 수정 시 명시 @ 단일 파일)
- 바이너리·미디어
피할 것: 비즈니스 소스 패키지를 함부로 ignore——legacy/ 통째 제외 시 Agent는 호환 계층을 영원히 「못 봄」.
3.2 Reindex 실행
Cursor: Settings → Indexing & Docs → Resync Index(문구는 버전마다 약간 다름). 대형 저장소 첫 인덱스는 M4에서 15–40분 흔함. 로컬에서 Ollama + Xcode도 돌리면 인덱스를 전용 클라우드 Mac 노드에서 완료해 swap으로 IDE·Agent 동시 타임아웃 방지——M4 AI 코딩 실측 메모리 결론과 일치.
git ls-files | wc -l과 인덱스 파일 수 비교를 넣고, 커버리지가 크게 떨어지면 일괄 Reindex. 각자 Cursor 재시작보다 시간 절약.단계 4: 경계 설정——대형 저장소에서 가장 무서운 「전체 한 방」
컨텍스트 손실은 작업 정의가 너무 큼에서도 납니다. 「결제 최적화」라고 하면 40개 패키지에 조금씩 손댐.
4.1 워크스페이스 축소
- VS Code/Cursor 멀티 루트 워크스페이스로
apps/checkout+packages/payment-sdk만. - Claude Code는 하위 디렉터리에서:
cd apps/checkout && claude, 무관 경로 검색 감소.
4.2 명시 @ 호출 체인
API 변경 시 최소 @: 인터페이스 정의 → 서버 구현 → 실제 호출처 1개 → 관련 테스트. Vue + Spring Boot 풀스택 저장소 실측에서 호출 체인 @ 보강 시 프론트 누락 확률이 약 40%에서 10% 미만으로——더 체계적 방법은 CodeGraph 사례 참고.
4.3 Handoff 템플릿
긴 작업에서 세션 교체 전 고정 구조 붙여넣기:
## Handoff
- 목표:
- 완료:
- 미완료:
- 위반 불가: (경로/네이밍/금지 import)
- 다음에 열 파일:「위 요약해줘」보다 제약을 잃기 어렵습니다. 항목이 검증 가능하고 산문 요약이 아니기 때문.
단계 5: 약속을 저장소에 쓰고 세션 분할 익히기
유형 C의 근본 해결: 규칙을 저장소의 일부로. 채팅의 일부가 아님.
5.1 AGENTS.md와 Cursor Rules
저장소 루트에 짧고 실행 가능한 약속 유지(< 200줄 권장, 길면 분할):
- 모듈 경계와 「AI 수정 금지」 경로(예
generated/,vendor/) - 네이밍·에러 처리 스타일(좋은/나쁜 예 각 1개)
- API 변경 시 함께 고칠 레이어 checklist
- 필수 명령:
pnpm test payment --filter=...
Cursor는 .cursor/rules, Claude Code는 AGENTS.md와 CLAUDE.md를 읽음. 내용 사실 일치, 두 곳에서 모순 금지.
5.2 언제 세션을 나눌까
| 상황 | 권장 |
|---|---|
| 한 기능 머지 완료, 다음 기능 시작 | 새 세션 + Handoff |
| Agent가 연속 3회 이해 빗나감 | 중단, Handoff 작성, @ 범위 축소 |
| compact 발생 / 컨텍스트 바 절반 초과 | 약속을 디스크에 기록 후 계속 |
| 날짜를 넘겨 재개 | 항상 새 세션 + PR/issue 링크 |
호출 체인이 수십 패키지에 걸치고 @만으로 부족하면 코드 지식 그래프류 도구 평가——단계 5 이후 강화이지 첫걸음 아님.
실측 사례: 12만 줄 monorepo에서 45분 점검
어떤 B2B SaaS 팀(백엔드 8 + 프론트 4)이 Cursor + Claude Code로 pnpm monorepo(약 118k LOC, app 6, package 23) 유지. 현상: Agent가 billing-api 수정할 때마다 auth-middleware 타입 export를 깨뜨리고 새 세션에서도 반복.
| 점검 순서 | 발견 | 조치 | 결과 |
|---|---|---|---|
| 단계 1 | 새 세션에서도 제약 망각 → 유형 C | AGENTS.md 없음 확인 | 근본 원인 특정 |
| 단계 3 | .cursorignore가 packages/auth 오제외 | ignore 수정 + Reindex | Agent가 middleware 참조 가능 |
| 단계 4 | 「billing 수정」 작업 과도하게 넓음 | 워크스페이스 billing+auth 2패키지, @ 테스트 | 변경 파일 19→6 |
| 단계 5 | 구두 약속 미기록 | 120줄 AGENTS.md + CI import 경계 검사 | 1주 PR 동종 회귀 없음 |
더 비싼 모델로 바꾸지 않고 작업당 token 평균 약 35% 감소——Agent가 전체 저장소 grep을 반복하지 않게 됨. Reindex와 야간 테스트를 Macstripe 24GB 클라우드 노드로 옮기고 로컬 노트북은 SSH로 코드만——인덱스 단계 swap 경고 사라짐.
자가 점검: 착수 전 2분
- ☐ 이번 작업이 A/B/C 중 어떤 잃음인지 말할 수 있음
- ☐ 에디터에 관련 파일만; 거대 로그 미오픈
- ☐
.cursorignore가 비즈니스 소스를 오해하지 않음 - ☐ 인덱스 상태 정상 또는 Reindex 예정
- ☐ 워크스페이스 범위 ≤ 관련 패키지 2–3개
- ☐ 호출 체인 핵심 파일(테스트 1개 포함) @ 완료
- ☐
AGENTS.md에 이번 「위반 불가」 항목 있음 - ☐ 긴 작업용 Handoff 템플릿 준비
FAQ
컨텍스트 창이 200K인데 왜 잃을까?
창은 용량 상한이지 주의력 보장이 아님. Agent 다회 도구 호출이 초기 지시를 유효 주의 영역에서 밀어냄; compact 요약도 세부 손실. 검색 가능한 저장소 약속이 긴 채팅보다 신뢰됨.
Cursor와 Claude Code 중 누가 더 잃기 쉬운가?
Cursor는 IDE 자동 주입과 긴 Composer 체인에서 경계 상실. Claude Code는 긴 bash와 compact 후 중간 결정 상실. 둘 다 능동 @, AGENTS.md, 작업 분할 필요——「더 편한 쪽」은 없음.
.cursorignore가 @ 수동 참조에 영향?
단일 파일 수동 @는 보통 읽힘; 영향은 전체 저장소 인덱스와 자동 검색. ignore된 디렉터리는 명시 @ 필요.
코드 지식 그래프를 도입해야 할까?
호출 체인이 여러 패키지에 걸치고 @로도 누락 시 시범 가치. 작고 경계 명확하면 AGENTS.md+CI 먼저가 ROI 높음.
Mac 변경/클라우드로 개선되나?
모델 컨텍스트는 늘지 않지만 24GB 전용 M4는 인덱스·테스트 swap을 줄여 Agent 타임아웃 방지. 팀 공통 중량 작업 환경 가능. 일 단위 체험으로 검증.
요약
대형 프로젝트에서 Cursor/Claude Code 「컨텍스트 손실」은 대부분 엔지니어링 문제이며 새 모델로 사라지는 유형이 아님. 이 5단계——증상 분류 → 예산 확인 → 인덱스 재구축 → 경계 설정 → AGENTS.md 작성과 세션 분할——은 맹목적 Max 모드보다 저렴하고 안정적인 경우가 많음.
- 세션 내 이탈: 주입 줄이기, 작업 분할, Handoff.
- 파일 못 찾음: ignore 수정, Reindex, 워크스페이스 축소.
- 새 세션 즉시 망각: 약속을 저장소에 쓰고 CI로 보완.
