정의

term/claude-md 모듈별 5 질문 중 가장 결정적인 항목 — AI 가 절대 가지 말아야 할 길 을 명시적으로 표시. 코드만 봐서는 obvious 하지 않은(non-obvious) 규칙. AI 가 잘못 갈 수 있는 길을 아예 차단. entity/jaesang-ha 의 5 개월 시행착오 결론 + entity/boris-cherny 의 "하면 안 되는 일을 못 하게 막는 것이 잘하는 일을 더 잘하게 만드는 것보다 훨씬 중요" 와 정확히 일치.

핵심 운영 규칙

"AI 가 실패할 때마다 CLAUDE.md 에 무조건 한 줄 추가." AI 가 절대 그 길로 다시 가지 않을 수 있도록 표지판을 세워라.

예시

## ⚠ Non-obvious Patterns (절대 하면 안 되는 것)

- 이 함수는 *프로덕션에서 호출 금지* (3년 전 PR #1234 컨센서스)
- `price` 와 `amount` 는 *같은 값* — 한 쪽 변경 시 다른 쪽도
- `// Legacy` 주석 API 는 *다른 마이크로서비스가 의존* — 삭제 금지
- 마이그레이션 파일은 *사용자 승인 없이 수정 ❌*
- `eval()` 사용 ❌ (보안 정책)
- 핵심 인증 모듈은 *수정하지 않는다*

term/non-goals 와의 관계

• Non-goals = concept/five-checklist 의 작업 단위 금지 (단발성 명세)
• Non-obvious Pattern = 프로젝트 영구 의 코드베이스 단위 금지 (CLAUDE.md 누적)
• 두 카드 기능 등가, 시점 차이. 함께 사용.

강의 활용

03 HRN concept/ai-ready-codebase / 04 DSL lesson/dsl-claudemd-as-language 결정적 어휘:

• 멘트: "AI 가 실패할 때마다 한 줄 추가. 다음에는 그 길로 안 갑니다."
• 5 질문 중 3 번이 결정 — 다른 4 개를 빼더라도 이건 절대.

주의사항

• 번역 통일: Non-obvious Pattern 영어 권장. 비자명 패턴 / 암묵 규칙 등 한국어는 부수.
• 무한 누적 위험: 너무 많이 누적되면 컨텍스트 압박 → 모듈별 분할 + Lazy Loading (term/lazy-loading-claudemd).
• 사람 손 누적의 한계: 자동 감지 도구(예: 정적 분석 + 리뷰 봇)가 Non-obvious Pattern 후보 를 자동 제안하면 효율 극대화.
• 신입 비유: 신입에게 "하지 마라" 만 1,000 줄 던지면 마비됨. 5~10 개 핵심 + 나머지는 모듈별 lazy.