증상: RateLimitError: 429

원인: 분당·시간당 호출 한도 초과

해결: retry with backoff (1s·3s·9s) + 호출 분산. circuit breaker 결합.

증상: BadRequestError: context too long

원인: 입력 토큰 200K 초과

해결: 5파일 분할 입력 + prompt caching 적용. 옛 메시지 압축.

증상: 응답 30초+ 후 timeout

원인: max_tokens 너무 큼 (10K+) 또는 모델 복잡도

해결: max_tokens 1024~4096로 축소. Sonnet 권장.

증상: 페르소나가 JSON 파싱 X

원인: system prompt에 "JSON 외 출력 금지" X 명시

해결: system prompt에 명시 + 응답 끝에 </json> 같은 표지자.

증상: 페르소나가 "있어야 한다" 같은 추정 출력

원인: system prompt에 "추정 금지·누락 null" X 명시

해결: system prompt 강화 + cache_control + 자동 일관성 테스트.

증상: 비용 절감 X

원인: anthropic-beta: prompt-caching-2024-07-31 헤더 누락

해결: 헤더 박음 + 시스템 프롬프트 1024 토큰 이상.

증상: "implementation·request" 등 영문 단어 출력

원인: CLAUDE.md §1에 "한국어 답변 의무" X 명시

해결: §1 명시 + prompt에 매번 "한국어로" 명시.

증상: 1주 비용 $50+

원인: 모든 호출 Opus 사용

해결: 80~90% Sonnet 결합. Opus는 결정·검토만.

증상: 24시간 후도 결과 X

원인: batch 상태가 processing에서 completed로 X

해결: 상태 매시간 점검. failed 시 재발행.

증상: AI가 tool 호출 X

원인: tool 정의에 description X 명시

해결: 각 tool의 description 1~2문장 명시 + 예시 결합.

증상: git pull 후 <<<<<<< 표지자 박힘

원인: 같은 라인을 둘이 변경

해결: 손으로 정리 → git add → git commit. 또는 git mergetool.

증상: HEAD detached at abc1234

원인: 특정 commit으로 체크아웃

해결: git checkout main 또는 새 브랜치 만들기 — git checkout -b new-branch.

증상: 동료의 commit 사라짐

원인: git push --force 실수

해결: 동료의 commit hash 찾기 → git revert 또는 git reflog.

증상: Updates were rejected

원인: 원격이 로컬보다 앞섬

해결: git pull --rebase → 충돌 해결 → git push.

증상: large file detected

원인: 100MB+ 파일 commit

해결: git lfs install + git lfs track "*.zip" + 다시 commit.

증상: .gitignore X

원인: 처음에 .gitignore 없이 commit

해결: .gitignore 만들기 + git rm -r --cached node_modules → commit.

증상: .env 파일이 GitHub에

원인: .gitignore에 .env X

해결: 즉시 시크릿 회전 (Anthropic·Cloudflare 등). git filter-branch 또는 BFG로 history 청소.

증상: 실수로 git branch -D 후 복원 의식

원인: 브랜치 삭제 → 참조 사라짐

해결: git reflog + 직전 hash 찾기 → git branch new-branch [hash].

증상: --amend 후 git push 거부

원인: history 변경 → 원격 history와 차이

해결: git push --force-with-lease (안전) 또는 --force (위험).

증상: submodule 폴더 비어 있음

원인: clone 후 git submodule update --init X

해결: git submodule update --init --recursive.

증상: ERESOLVE unable to resolve dependency tree

원인: peer dependency 충돌

해결: npm install --legacy-peer-deps 또는 의존성 정정렬.

증상: Cannot find module '...'

원인: 부분 install 또는 캐시 깨짐

해결: rm -rf node_modules package-lock.json && npm install.

증상: npm ERR! code EACCES

원인: 글로벌 설치 권한 X

해결: npm config set prefix '~/.npm-global' + PATH 설정.

증상: 옛 버전 설치

원인: npm 캐시

해결: npm cache clean --force + 재설치.

증상: Could not find a version

원인: Python 버전 호환 X

해결: 가상 환경 만들기 — python -m venv venv && source venv/bin/activate && pip install [pkg].

증상: 다른 PC에서 같은 의존성 X

원인: pip freeze X

해결: pip freeze > requirements.txt + git commit.

증상: SyntaxError

원인: 코드가 Python 3.10+ 문법, 환경은 3.8

해결: pyenv·conda로 버전 통일.

증상: SyntaxError: Unexpected token

원인: Node 14에서 Node 18 문법

해결: nvm — nvm use 18 또는 package.json engines 명시.

증상: yarn.lock vs package-lock.json 둘 다

원인: 일부는 npm·일부는 yarn

해결: 한 도구 선택 + 다른 lock 파일 삭제.

증상: monorepo workspace 패키지 X 인식

원인: package.json workspaces 정의 X

해결: root package.json에 "workspaces": ["packages/*"] 박음.

증상: Type 'X' is not assignable to 'Y'

원인: 타입 정의 X

해결: npm run typecheck 로컬 점검 + 타입 정정.

증상: process.env.X is undefined

원인: Cloudflare·Vercel·Worker 환경 변수 X 박음

해결: dashboard에서 env 박음 + 재배포.

증상: Access-Control-Allow-Origin 누락

원인: 백엔드 CORS 헤더 X

해결: Express — cors 패키지 / Cloudflare Worker — Response headers 박음.

증상: NET::ERR_CERT_INVALID

원인: 도메인 SSL 미적용

해결: Cloudflare·Vercel 자동 SSL 의식 + 도메인 결합 후 5~10분 대기.

증상: 사이트 502

원인: 백엔드 X 응답 또는 timeout

해결: 로그 점검 (pm2 logs·wrangler tail) + 백엔드 재시작.

증상: 30초+ 응답

원인: 백엔드 처리 시간 너무 김

해결: 작업 분리·async·캐시 결합.

증상: 새로고침 후 404

원인: 정적 호스팅이 SPA 라우팅 X

해결: Cloudflare Pages — _redirects 파일 / Vercel — vercel.json 박음.

증상: 빌드 10분+

원인: 의존성·이미지·번들 사이즈

해결: 의존성 정정렬 + 이미지 압축 + 코드 splitting.

증상: DNS 적용 X

원인: DNS propagation 시간

해결: 24~48시간 대기. 또는 dig domain.com 점검.

증상: wrangler deploy 후 옛 버전

원인: 캐시 또는 배포 X

해결: wrangler tail로 로그 점검 + wrangler deploy --verbose.

증상: AI 답변이 SPEC와 충돌

원인: CLAUDE.md X 적용 또는 누락

해결: CLAUDE.md 200줄 의무 + 매 세션 자동 입력 점검.

증상: AI가 1쪽 → 5쪽 답변

원인: prompt에 "간결" X 명시

해결: prompt에 "1쪽 안 답" 명시 + max_tokens 1024.

증상: AI가 "이 프로젝트가 뭐" 묻음

원인: /clear 후 CLAUDE.md X 입력

해결: 매 세션 시작 시 CLAUDE.md 자동 입력 의식.

증상: AI가 SPEC.md 수정

원인: CLAUDE.md §3에 "임의 수정 금지" X 명시

해결: §3 강화 + 매 작업 전 "변경 파일 목록" 의무.

증상: AI 코드에 import { foo } from 'bar' (bar 없음)

원인: 모델 환각

해결: TypeScript 의무 + 컴파일 점검 + Sonnet → Opus 전환 (어려운 결정).

증상: "~예요" → "~야" 잠입

원인: prompt에 톤 X 명시

해결: CLAUDE.md §1 + prompt 양식 박음.

증상: AI가 옛 API·옛 흐름 답변

원인: 모델 학습 시점 차이

해결: 명시적 "2026년 기준" 박음 + 외부 docs 인용.

증상: 절반 정답·절반 X

원인: 모델·prompt 결합 함정

해결: 두 검토자 (Claude + Gemini) E3 흐름 적용.

증상: MCP 결합 후 X 호출

원인: tool description X 명시

해결: description 1~2문장 + 예시 박음.

증상: 매일 비용 $30+

원인: cache 미적용·Opus 100%·과도 호출

해결: prompt caching 의식 + Sonnet 80% + batch API 결합.