AI 반복 실수(3회 이상) 패턴 추출 및 하네스 등록 가이드
1. 개념 정리
1.1 하네스(Harness)란
하네스는 AI에게 매번 자동으로 적용되는 상시 규칙 모음을 말한다. 사용자가 대화할 때마다 일일이 지시하지 않아도, AI가 작업을 시작하기 전에 항상 먼저 읽는 규칙 파일이다. 말의 방향을 잡아 주는 말고삐(harness)에 비유한 표현이다.
도구별로 하네스에 해당하는 위치는 다음과 같다.
- Claude Code → 프로젝트 폴더의
CLAUDE.md파일 - Claude(웹/앱) → 프로젝트의 "지침(Instructions)" 또는 스타일 설정
- ChatGPT → "맞춤 설정(Custom Instructions)" 또는 프로젝트 지침
- Cursor →
.cursorrules또는.cursor/rules파일 - Gemini CLI →
GEMINI.md파일
1.2 3회 규칙(3-Strike Rule)이란
AI의 실수를 규칙으로 만들지 판단하는 기준선이다.
- 1회 발생 → 우연일 수 있다. 기록만 한다.
- 2회 발생 → 의심 단계. 기록을 이어 가며 지켜본다.
- 3회 발생 → 패턴으로 확정한다. 규칙 문장으로 바꿔 하네스에 등록한다.
3회를 기준으로 삼는 이유는 두 가지다. 첫째, 모든 실수를 즉시 규칙으로 만들면 하네스가 금방 수십 줄로 불어나고, 규칙이 많아질수록 AI가 각 규칙을 지키는 정확도는 떨어진다. 둘째, 1~2회 실수는 그날의 대화 맥락 때문에 생긴 일회성일 가능성이 커서, 규칙으로 만들어도 효과가 없는 경우가 많다.
2. 전체 절차 (5단계)
절차는 "기록 → 집계 → 패턴 추출 → 규칙화 → 등록·검증" 순서로 진행한다.
2.1 1단계: 실수 기록
AI가 기대와 다르게 동작할 때마다 아래 양식으로 한 줄씩 기록한다. 기록은 실수 직후에 바로 하는 것이 핵심이다. 나중에 몰아서 쓰면 상황 재현이 안 된다.
기록 파일은 프로젝트 폴더에 mistakes.md(실수 장부) 같은 이름으로 하나만 만들어 계속 누적한다.
2.2 2단계: 집계
하루 작업이 끝날 때(또는 실습 차시가 끝날 때) 실수 장부를 열어 같은 종류끼리 묶는다. 이때 "같은 종류"의 판단 기준은 표면적 현상이 아니라 원인이다. 예를 들어 "버튼 색이 틀렸다"와 "글자 크기가 틀렸다"는 현상은 다르지만, 원인이 둘 다 "디자인 시안을 확인하지 않고 임의 값을 넣음"이라면 같은 패턴 하나로 묶는다.
2.3 3단계: 패턴 추출 (3회 판정)
묶은 결과에서 발생 횟수가 3회 이상인 항목을 골라낸다. 이것이 "패턴"이다. 패턴은 아래 한 문장 형태로 정리한다.
AI는 [어떤 상황]에서 [어떤 실수]를 반복한다. 원인은 [무엇] 때문이다.
예시: "AI는 새 컴포넌트를 만들 때 기존 공통 컴포넌트를 확인하지 않고 새로 만든다. 원인은 프로젝트 구조를 먼저 읽으라는 지시가 없기 때문이다."
2.4 4단계: 규칙화 (패턴 → 규칙 문장 변환)
패턴을 AI에게 줄 규칙 문장으로 바꾼다. 좋은 규칙의 조건은 세 가지다.
- 행동 지시형으로 쓴다. "~하지 마라"보다 "~할 때는 반드시 ~를 먼저 하라"처럼 대신 할 행동을 알려 준다.
- 조건을 붙인다. "항상 조심하라" 같은 막연한 말 대신 "어떤 상황에서"를 명시한다.
- 확인 가능한 문장으로 쓴다. 지켰는지 안 지켰는지 사람이 판정할 수 있어야 한다.
나쁜 규칙과 좋은 규칙 비교:
| 구분 | 예시 |
|---|---|
| 나쁜 규칙 | 코드를 잘 짜라 |
| 나쁜 규칙 | 실수하지 마라 |
| 좋은 규칙 | 새 컴포넌트를 만들기 전에 src/components 폴더를 먼저 확인하고, 같은 역할의 컴포넌트가 있으면 그것을 재사용한다 |
| 좋은 규칙 | 색상 값은 임의로 정하지 말고 tailwind.config에 정의된 토큰만 사용한다 |
2.5 5단계: 하네스 등록과 검증
규칙 문장을 하네스 파일(CLAUDE.md 등)에 추가한다. 등록만 하고 끝내지 않고 반드시 검증한다.
- 등록 직후, 그 실수가 나오던 것과 같은 종류의 작업을 한 번 시켜 본다.
- 실수가 재발하면 규칙 문장이 모호한 것이므로 조건과 행동을 더 구체적으로 고쳐 쓴다.
- 2주 이상 재발하지 않은 규칙 중 도구 업데이트 등으로 더 이상 필요 없어진 것은 삭제한다. 하네스는 짧게 유지할수록 잘 작동한다.
3. 실수 기록 템플릿
3.1 개별 실수 기록표 (mistakes.md에 누적)
| 번호 | 날짜 | 작업 내용 | AI의 실수 (무엇을 잘못했나) | 내가 준 지시 (원문 요약) | 추정 원인 | 같은 실수 횟수 |
|---|---|---|---|---|---|---|
| 1 | 7/21 | 카드 컴포넌트 제작 | 기존 Button 컴포넌트를 안 쓰고 새로 만듦 | "상품 카드 만들어 줘" | 기존 코드 확인 지시 없음 | 1회 |
| 2 | 7/21 | 헤더 수정 | 시안에 없는 색상을 임의로 사용 | "헤더 색 바꿔 줘" | 색상 기준(토큰) 미지정 | 1회 |
| 3 | 7/22 | 로그인 폼 제작 | 기존 Input 컴포넌트를 안 쓰고 새로 만듦 | "로그인 폼 만들어 줘" | 기존 코드 확인 지시 없음 | 2회 |
기록 요령:
- "AI의 실수" 칸에는 결과가 아니라 행동을 쓴다. "화면이 깨짐"(결과)이 아니라 "반응형 처리를 빼먹음"(행동)으로 쓴다.
- "내가 준 지시" 칸을 꼭 채운다. 실수의 절반은 지시가 모호해서 생기며, 이 칸이 있어야 원인 분석이 된다.
- "같은 실수 횟수" 칸은 추정 원인이 같은 이전 기록을 세어서 적는다.
3.2 패턴 판정표 (3회 도달 시 작성)
| 항목 | 내용 |
|---|---|
| 패턴 이름 | 기존 컴포넌트 미확인 후 중복 생성 |
| 발생 기록 번호 | 1, 3, 7 |
| 발생 상황 | 새 UI 요소를 만들어 달라고 요청할 때 |
| 반복된 실수 | 기존 공통 컴포넌트를 확인하지 않고 비슷한 것을 새로 만듦 |
| 추정 원인 | 프로젝트 구조를 먼저 읽으라는 상시 지시가 없음 |
| 규칙 문장(초안) | 새 컴포넌트를 만들기 전에 src/components를 먼저 확인하고, 같은 역할이 있으면 재사용한다 |
| 등록 위치 | CLAUDE.md의 "컴포넌트 규칙" 절 |
| 등록 날짜 / 검증 결과 | 7/23 등록 / 7/23 재작업 1회 통과 |
3.3 하네스 파일 작성 예시 (CLAUDE.md 기준)
# 프로젝트 규칙
## 반복 실수 방지 규칙 (3회 규칙으로 등록됨)
1. 새 컴포넌트를 만들기 전에 src/components 폴더를 먼저 확인하고,
같은 역할의 컴포넌트가 있으면 그것을 재사용한다. (등록: 7/23)
2. 색상 값은 임의로 정하지 말고 tailwind.config에 정의된
토큰만 사용한다. (등록: 7/24)
3. 파일을 수정하기 전에 해당 파일 전체를 먼저 읽는다. (등록: 7/25)등록 날짜를 함께 적어 두면, 나중에 어떤 규칙이 오래됐는지 정리할 때 기준이 된다.
4. 수업 운영 팁 (학습자에게 시킬 때)
- 실습 첫날에 빈
mistakes.md를 만들게 하고, "AI가 이상하게 동작하면 무조건 한 줄 기록"을 습관으로 잡는다. - 차시 마무리 10분을 "실수 장부 정리 시간"으로 고정하면 2단계(집계)가 자연스럽게 수업 루틴이 된다.
- 팀 프로젝트라면 팀원 각자의 장부를 합쳐서 집계한다. 서로 다른 사람에게 같은 실수가 나오면 횟수를 합산해도 된다. 오히려 더 확실한 패턴이다.
- 흔한 실패 사례를 미리 알려 준다. 규칙을 한 번에 20개씩 등록하면 AI가 규칙을 지키는 비율이 떨어진다. 하네스 규칙은 10개 내외를 권장하고, 넘치면 오래된 것부터 정리한다.
5. 요약
- 실수가 나올 때마다 즉시 한 줄 기록한다. (현상이 아니라 행동과 원인 중심)
- 원인이 같은 실수를 묶어 세고, 3회가 되면 패턴으로 확정한다.
- 패턴을 "조건 + 대신 할 행동" 형태의 규칙 문장으로 바꾼다.
- 하네스 파일(CLAUDE.md 등)에 등록하고, 같은 작업을 다시 시켜 재발 여부를 검증한다.
- 하네스는 짧게 유지한다. 안 쓰는 규칙은 삭제한다.