AI 코딩

MISTAKES.md와 Claude Code: 반복 오류를 규칙으로 바꾸기

간결한 MISTAKES.md, 제로 시크릿, 테스트·규칙 승격과 Claude Code 가드레일 검증을 설명합니다.

BetterToken

편집팀

2026년 8월 20일3 분 분량

복잡한 저장소에서 Claude Code를 사용하면 오래된 TypeScript 정의, 숨은 런타임 의존성, bundler 고유 동작처럼 분명하지 않은 환경 특성을 피할 수 없습니다. 같은 실수를 채팅에서 계속 고치면 문맥과 시간이 낭비됩니다. 반대로 여러 페이지의 세션 기록을 지침에 넣으면 prompt가 복잡해지고 모델의 주의력이 떨어집니다.

실용적인 패턴은 저장소 root에 가벼운 MISTAKES.md를 두는 것입니다. 재현 가능한 인시던트, 검증된 원인, 예방 조치만 기록하고, 나중에 프로젝트 테스트, Linter 규칙, 지속 구성으로 승격합니다.

1. MISTAKES.md와 세션 기록의 차이

인시던트 로그를 원시 terminal transcript와 혼동하지 마세요.

차원	세션 기록	MISTAKES.md 인시던트 로그
분량	수천 줄의 tool call과 중간 단계	인시던트당 구조화된 5–10줄
목적	한 번의 실행 디버깅과 감사	미래 재발 방지를 위한 참조 기반
시크릿 처리	원시 환경 변수나 token을 캡처할 수 있음	엄격히 금지: credential과 secret은 0개
수명	일시적 산출물	자동화될 때까지 지속되는 문서

MISTAKES.md는 Claude Code가 세션 시작 시 과도한 context token 없이 읽을 수 있도록 간결해야 합니다.

2. 인시던트 기록의 구조

각 인시던트 항목은 네 필수 필드를 가집니다.

Incident: 무엇이 어떤 조건에서 깨졌는가—error code, command, tool.
Impact: 깨진 build, 손상된 migration, 중단된 test suite 같은 하류 영향.
Root Cause: 확인된 기술 원인. 증명되지 않았으면 반드시 [Hypothesis]로 표시.
Prevention: 재발을 막는 구체적인 rule 또는 check.

인시던트 기록 예시

ERR-014: CASCADE 없는 DROP COLUMN에서 PostgreSQL migration 실패

Incident: Claude Code가 migration 0042에서 ALTER TABLE orders DROP COLUMN customer_ref;를 실행했다.
Impact: 종속 view v_active_orders 때문에 staging deployment가 실패했다.
Root Cause: base table을 참조하는 view에는 명시적 cascade 재생성 또는 사전 view 업데이트가 필요하다.
Prevention: column을 제거하는 모든 DDL migration은 실행 전 pg_depend로 종속 view를 확인해야 한다.



> [!IMPORTANT]
> **제로 시크릿 정책:** 실제 database connection string, private key, token, `.env` 조각을 `MISTAKES.md`에 commit하지 마세요. Claude Code API Key는 로컬 환경 변수로 관리합니다.

API provider와 함께 신뢰할 수 있게 Claude Code를 구성하려면 자신의 API Key를 사용하고 [BetterToken Claude Code 통합 안내](https://docs.bettertoken.ai/ai-tools/claude-code)를 따르세요.

---

3. 승격 임계값: 로그에서 테스트 또는 규칙으로

한 번의 typo마다 영구 규칙이 필요한 것은 아닙니다. 명확한 임계값으로 항목을 자동 gate로 승격합니다.


인시던트 발생
  │
  ├─> 첫 번째: MISTAKES.md에 4필드 항목 기록
  │
  └─> 두 번째(재발):
        │
        ├─> 기계적으로 검증할 수 있는가?
        │     └─> 예: unit test, ESLint rule, pre-commit hook 추가
        │
        └─> 아니오: CLAUDE.md / AGENTS.md에 엄격한 부정 지시 추가

첫 발생: MISTAKES.md에 간결한 기록을 추가합니다.
두 번째 발생: 문제를 결정적으로 잡을 수 있으면 test 또는 linter rule을 작성합니다. 자동 gate가 텍스트 prompt보다 낫습니다.
비기계적 검사: CLAUDE.md에 명시적 부정 규칙을 작성합니다. 예: “CI에서 --runInBand 없이 jest를 실행하지 않는다”.
보관: test나 hook을 배포하면 파일 비대화를 막기 위해 MISTAKES.md 항목을 archive하거나 제거합니다.

4. 다음 작업에서 검증

새 guardrail이 작동하는지 확인하려면:

새 Claude Code session을 시작합니다.
이전에 실패를 일으킨 prompt를 제공합니다.
agent가 새 rule을 지키거나 pre-commit hook에 의해 중지되는지 검사합니다.
agent가 텍스트 지시를 우회하면 제약을 엄격한 command wrapper 또는 자동 check로 바꿉니다.

이 feedback loop는 무작위 개발 실패를 견고하고 스스로 개선되는 engineering foundation으로 바꿉니다.

LLM 워크플로를 최적화할 준비가 되셨나요?

하나의 API로 모델을 연결하고 키와 AI 비용을 관리하세요.