1. 이 글은 무엇에 관한 글인가?

한 줄로 요약하면 이렇습니다.

AI가 같은 실수를 반복할 때, 그 실수를 막도록 AI 설정 파일을 스스로 고쳐주는 도구 이야기입니다. 단, 실제로 파일을 바꾸기 전엔 항상 사람에게 “이렇게 고쳐도 될까요?”라고 물어봅니다.

먼저, “하네스”가 뭐죠?

하네스(harness) 는 AI 주위를 둘러싼 설정과 코드 를 통틀어 부르는 말입니다. AI에게 “우리 프로젝트에서는 이렇게 일해줘”라고 알려주는 문서·규칙 묶음이라고 생각하면 됩니다. Claude Code 기준으로는 보통 이런 파일들입니다.

이전 글 Frontend 하네스 엔지니어링에서는 이 하네스를 잘 만드는 법 을 다뤘습니다. 이번 글은 한 발 더 나아갑니다. 하네스가 스스로를 고치게 만드는 법 입니다.

정적 하네스의 불편함

잘 만든 하네스도 한 번 만들면 그 자리에 가만히 멈춰 있습니다. AI가 같은 실수를 반복해도, 하네스는 스스로 배우지 못합니다. 그래서 매번 사람이 이렇게 개입해야 합니다.

AI: (또 같은 실수)
나: "아까도 말했잖아, 이렇게 하지 말라고..."
나: (직접 SKILL.md 열어서 규칙 추가)
   → 다음에 또 다른 실수 → 또 반복...

이 반복을 자동화하자는 것이 이번 글의 주제입니다.

핵심은 딱 하나입니다. “하네스를 사람이 고친다” → “하네스가 스스로 고칠 준비를 하고, 최종 승인만 사람이 한다.”

이걸 실제로 구현한 도구가 이번 글의 주인공 meta-harness 입니다. (이름 그대로 “하네스를 고치는 하네스”, 즉 메타 하네스입니다.)

2. 안전이 먼저다 — 3가지 약속

“AI가 스스로 파일을 고친다”는 말은 살짝 무섭게 들립니다. 폭주하면 어쩌죠? 그래서 meta-harness는 절대 어기지 않는 3가지 약속 을 지킵니다. 이 세 가지만 이해하면 나머지는 쉽습니다.

약속 1 — 사람 승인 없이는 절대 안 고친다

이게 가장 중요합니다. meta-harness는 원인 분석과 “이렇게 고치면 어때요?” 제안까지만 자동 으로 하고, 실제 파일 수정은 사람이 “OK” 해야만 합니다.

실수 기록  →  원인 진단  →  수정안 작성  ──┐
                                          │  여기까지만 자동
        ┌──────────────────────────────────┘
        ▼
   [ 사람에게 물어봄 ]   "1번 고칠까요? 2번은요?"
        │
        ▼  OK 한 것만
   실제 파일 수정

승인은 항목별로 골라서 답할 수 있습니다.

• “1번은 적용해줘” → 적용
• “2번은 하지 마, 일부러 그런 거야” → 거절
• “3번은 나중에 볼게” → 보류

승인하지 않은 항목은 파일을 단 한 글자도 건드리지 않습니다.

약속 2 — 고치면서 다른 걸 망가뜨리지 않는다

흔한 함정이 있습니다. “정확도를 높이려다 규칙이 너무 길고 복잡해지는” 경우죠. meta-harness는 수정안을 채택하기 전에 4가지를 동시에 확인 합니다. 하나라도 나빠지면 그 수정안은 버립니다.

그리고 수정 방식도 보수적입니다. 기존 줄은 지우지 않고, 필요한 규칙만 “추가” 하는 것을 우선합니다. (이걸 additive, 더하기 방식이라고 부릅니다.)

약속 3 — 요약하지 않고 원본을 그대로 남긴다

AI가 실수한 순간의 기록을 요약하지 않고 통째로 저장합니다. 왜냐하면 요약하는 순간 진짜 원인의 단서가 사라지기 때문입니다. meta-harness가 참고한 논문의 실험이 이걸 뒷받침합니다.

원본 전체를 보존한 쪽이 요약본보다 성능이 좋았다 — 56.7점 vs 38.7점

그래서 진단할 때도 “요약본 느낌”이 아니라, 원본 기록을 직접 뒤져서 “몇 번째 단계, 어느 파일에서 문제가 생겼다” 처럼 근거를 콕 집어 말합니다.

3. 실제로 어떻게 동작하나?

meta-harness는 별도 명령어를 외울 필요가 없습니다. 평소 말투로 부탁하면 알아서 발동합니다. 내부는 아래처럼 흘러갑니다. 겁먹지 마세요 — 앞의 3가지 약속이 이 흐름 곳곳에 들어있을 뿐입니다.

① 상황 파악    지금이 첫 실행인지, 이어하기인지 자동 판단
② 무엇을 고칠지  "이번엔 어떤 종류의 요청이지?" 판별
③ 실수 기록     문제의 순간(발화 + 직전 결과물)을 원본 그대로 저장
④ 원인 진단     "왜 이런 일이 생겼지?" — 여러 실수를 동시에 분석
⑤ 수정안 작성   "이렇게 고치면 됩니다" — 실수별로 하나씩
⑥ 간단 검증     오타·깨진 링크 같은 명백한 문제 미리 거르기
⑦ 사람에게 확인  ★ "1번 고칠까요? 2번은요?" (반드시 거침)
⑧ 실제 적용     OK 한 것만 파일 수정
⑨ 이력 저장     이번에 뭘 고쳤는지 기록으로 남김
   └─ 마지막: '무엇을 / 왜 / 어디를' 고쳤는지 표로 보고

일을 나눠 맡는 보조 AI들

meta-harness는 혼자 다 하지 않고, 역할을 나눠 맡깁니다. 마치 작은 팀처럼요.

진단은 여럿이 동시에(실수들이 서로 독립적이니까), 수정은 하나씩 순서대로 진행합니다. 앞 수정 결과를 봐가며 다음 수정을 만들어야 하기 때문입니다.

3가지 부탁 방식 (R1 / R2 / R3)

어떻게 말하느냐에 따라 고치는 범위가 달라집니다.

• R1 — 지금 이 실수를 막아줘

  “방금 그거 말고 다시 해줘. 왜 그랬는지 보고, 쓰던 규칙이랑 CLAUDE.md를 고쳐줘.”

  → 프로젝트 규칙과 지금 쓰던 매뉴얼을 손봅니다.

• R2 — 이 플러그인 자체를 손봐줘

  “이 도구가 자꾸 엉뚱하게 굴어. 안쪽 설정까지 들어가서 고쳐줘.”

  → 플러그인 내부 파일 전체를 손봅니다.

• R3 — 이 문서를 만든 범인을 찾아 고쳐줘

  “이 spec.md가 부실한데, 이거 만든 AI/매뉴얼을 고쳐줘.”

  → 문서를 거꾸로 추적해 그걸 만든 원인을 손봅니다.

4. 명령어 없이도 알아서 기억한다

여기가 “자가치유”라는 이름값을 하는 부분입니다. 매번 도구를 직접 부르지 않아도, 여러분의 불만·수정 요청이 자동으로 쌓입니다.

[ 오늘 세션 ]  "이거 다시 해줘 / 틀렸어 / 방향 다시"
    │
    ▼  자동 감지 (파일에 조용히 기록만, 흐름 안 막음)
    signals/2026-07-05.jsonl  ← 여러분 말을 원본 그대로 저장
    │
    ┈┈┈┈┈┈┈  (며칠 뒤, 새 세션)  ┈┈┈┈┈┈┈
    │
[ 다음 세션 ]  시작하자마자 한 줄 알림:
    "최근 self-heal 신호 N건이 쌓였어요 — 지금 진단해볼까요?"
    │
    ▼  "그래" 하면
    쌓인 기록을 꺼내 원인 분석 시작

여기서 중요한 점: 자동으로 하는 건 “기록”과 “알림”까지 입니다. 실제 수정은 여전히 약속 1(사람 승인) 을 거칩니다. 즉 “기억해뒀다가 나중에 고친다” 는 맞지만, 그 고침은 언제나 사람 승인과 함께 일어납니다. 몰래 고치는 일은 없습니다.

잠깐 — 왜 “규칙” 대신 “자동 스크립트(hook)“를 쓰나요?

같은 것을 막더라도, 성격에 따라 두는 곳이 다릅니다.

포인트는 이겁니다. “반드시 막아야 하는 것”을 문서에 글로만 적어두면 AI가 놓칠 수 있으니, 처음부터 자동 스크립트로 확실히 막는다. 문서 규칙은 어디까지나 “권고”일 뿐, 강제력은 hook·permission에서 나옵니다.

5. 실제 예시 — 파일을 안 알려줘도 알아서 찾는다

가장 인상적인 장면은 이겁니다. “어느 파일을 고쳐”라고 콕 집어주지 않아도 meta-harness가 스스로 고칠 곳을 찾아냅니다.

내가 한 말 (파일 언급 없음):

“또 아이콘 버튼에 이름표(접근성 라벨)를 안 붙였네. 이 실수 좀 그만 반복하게 고쳐줘.”

도구가 한 일:

1. 기록 — 방금 만든 결과물(라벨 빠진 버튼)과 내 불만을 원본 그대로 저장.
2. 범인 찾기 — 어느 파일인지 안 알려줬으니 프로젝트를 직접 뒤집니다. 매뉴얼 파일들을 아이콘 버튼, 접근성 라벨 같은 키워드로 검색.
3. 판정 — 진짜 범인은 웹접근성 매뉴얼(a11y/SKILL.md)이라고 결론. 관련 없어 보이는 다른 파일들은 이유를 대며 후보에서 제외.
4. 수정 → 확인 → 적용 — 수정안을 만들고, 사람에게 물어보고, OK 하면 적용.

적용된 수정 (기존 줄은 그대로, 규칙만 추가):

+ - **인터랙티브 요소 이름 점검(필수)** — 버튼·링크·입력창 각각에 이름표가 있는지 확인한다.
+   - **Why:** 아이콘만 있는 버튼은 글자가 없어서, 이름표가 없으면
+     화면 낭독기가 "무슨 버튼인지" 읽어주지 못한다.

실제로, 파일을 하나도 안 알려준 상태에서 도구가 매뉴얼 27개를 훑어 정확히 test/SKILL.md를 범인으로 지목 했습니다. 게다가 원인을 “규칙이 없어서”가 아니라 “규칙은 있는데 만드는 순간에 강제되지 않아서” 로 더 정확하게 짚어냈습니다.

마지막 보고 — ‘무엇을 / 왜 / 어디를’

모든 작업은 이런 요약표로 마무리됩니다. 한눈에 뭘 했는지 보이죠.

6. 개선 기록은 어디에 쌓이나?

모든 작업 기록은 프로젝트 안 .claude/ 폴더에 정리됩니다. (여러분 작업 폴더를 어지럽히지 않습니다.)

.claude/experience-store/
├── history.jsonl              # "언제 뭘 고쳤나" 전체 이력
├── signals/2026-07-05.jsonl   # 자동 감지된 불만 발화 모음
├── patches/                   # 실제 적용한 수정 사본
└── run-.../traces/*.jsonl     # 문제 순간의 원본 기록 (요약 안 함)

같은 곳을 3번 고치면? — “구조를 다시 보세요”

같은 파일을 자꾸 고치게 되면 카운트가 올라가고, 3번째부터는 잔손질 대신 “이 부분은 구조 자체를 다시 설계하는 게 낫겠어요” 라고 권합니다. 계속 반창고만 붙이지 말라는 신호죠. 자기개선이 무한정 규칙만 늘리는 걸 막는 안전장치이기도 합니다.

7. 정리 — 어디까지 왔고, 어디로 가나

하네스는 이렇게 단계적으로 진화하고 있습니다.

핵심 메시지는 딱 하나입니다.

AI가 자기 자신을 개선하되, “고쳐도 되는지”의 열쇠는 언제나 사람이 쥔다.

그 열쇠 역할을 하는 것이 앞서 본 3가지 약속 — 사람 승인 · 다른 걸 망가뜨리지 않기 · 원본 보존 — 입니다. 정적 하네스가 “무엇을 만들 것인가” 를 도왔다면, 자가치유 하네스는 “하네스 자신을 어떻게 더 낫게 만들 것인가” 를 자동화합니다. 개발자는 목표와 경계만 정하고, 나머지 개선은 시스템이 승인 아래에서 스스로 굴려갑니다.

참고 문서

• Meta-Harness: End-to-End Optimization of Model Harnesses, arXiv 2603.28052
• Anthropic, Effective Context Engineering for AI Agents (2025)
• Anthropic, Agent Skills (2025)
• Reflexion (arXiv 2303.11366) · GEPA (arXiv 2507.19457) — 자기개선의 한계와 안전장치 근거