서론
최근 개인 개발 앱에 Claude Code의 하네스(CLAUDE.md / Hooks / Skills)를 도입한 기록을 작성했습니다.
지난번은 '실제로 무엇을 만들었는지'에 대한 경험담이었기 때문에, 이번에는 그 배경이 되는 하네스 엔지니어링 3원칙을 'Claude Code의 어떤 기능이 어떤 원칙을 담당하는가'라는 대응표로 정리해 보았습니다. 이 원칙 자체는 OpenAI의 기사에서 제창된 것이며, 저는 일본어 정리 기사(기사 말미의 '참고')를 통해 알게 되었습니다.
3원칙과 Claude Code 기능의 대응
| 원칙 | 한마디로 말하자면 | Claude Code에서의 담당 |
|---|
| ① 지도를 주고, 매뉴얼은 주지 않기 | 전체적인 개요와 '어디를 볼지'만 알려주기 | CLAUDE.md(+ docs/) |
| ... | | |
| 이 3줄에 담겨 있으니, 각각의 역할이 완전히 다르다는 것을 알 수 있습니다. 순서대로 살펴보겠습니다. | | |
① 지도 — CLAUDE.md는 200행 이내의 안내판
매뉴얼 전체를 다 주고 싶은 것이 사람 마음이지만, 긴 매뉴얼은 컨텍스트(context)를 압박할 뿐만 아니라 중요한 부분은 건너뛰기 쉽습니다. 지도의 원칙에서는 CLAUDE.md를 200행 이내의 안내판으로 제한하고, 상세 내용은 docs/에 맡겨 링크로 찾아가게 합니다.
구성 요소는 5개의 섹션이며, 맨 앞에는 프로젝트 개요가 위치합니다.
# CLAUDE.md(구조의 골격)
## 1. 프로젝트 개요 ← 반드시 가장 먼저 배치
## 2. 기술 스택과 자주 사용하는 명령어
...
지난번 제 프로젝트에서는 이 방침으로 줄여나간 결과 48행까지 축소되었습니다. 기본 동작은 '추가하는 것'보다 'docs/로 밀어내는 것'이 됩니다.
② 강제 — '요청(お願い)'과 불변 조건을 섞지 않기
자연어 지시는 본질적으로 모두 '요청(request)'이며, 확률적으로만 지켜집니다. 반면 .env 읽기나 네이티브 디렉터리 직접 수정 같은 사고는 단 한 번이라도 치명적입니다.
그래서 이 원칙에서는 깨뜨리면 사고가 나는 것들만을 PreToolUse Hook으로 기계적으로 차단(exit 2)하고, 그 외의 규약은 CLAUDE.md의 '권장 사항'에 머무르게 합니다. 여기서 중요한 것은 역방향으로, 구현하는 방식까지 Hook이나 규칙으로 묶지 않는 것입니다. 수단을 너무 많이 제한하면 모델이 가지고 있는 해결 방법의 창고를 막아버립니다. 지켜야 할 것은 조건이고, 맡겨야 할 것은 구현 방식입니다.
Hook의 구체적인 작성 방법과 테스트 방법은 지난 기사에 적었으니 그쪽을 참고해 주시기 바랍니다.
③ 축적 — Skill은 '실패 횟수만큼' 늘어난다
세 번째가 가장 평범하지만, 가장 효과적입니다. 무언가에 실패할 때마다 그 올바른 절차를 Skill로 문서화해 두는 것입니다. 다음부터는 호출만 하면 같은 실수를 반복하지 않게 됩니다.
---
name: new-screen
description: 새로운 화면을 추가할 때의 절차
...
하나하나가 작은 메모에 불과하지만, 프로젝트가 계속될수록 '넘어진 곳마다 난간이 늘어나는' 것과 같아 효과는 복리로 쌓입니다.
실천 플로우: 앱보다 먼저 하네스를 만들기
대응표가 머릿속에 들어오면, 새로운 프로젝트의 첫 단계가 달라집니다. 저는 첫 프롬프트에서 앱 본체가 아니라 하네스의 구조부터 생성하도록 지시했습니다.
이 리포지토리에 Claude Code용 하네스를 만들어 주세요.
1. CLAUDE.md(200행 이내・5섹션・맨 앞은 프로젝트 개요)
2. .claude/hooks/에 불변 조건을 지키는 PreToolUse Hook(.env 보호 등)
...
앱 구현 단계에서는 디자인과 검증의 조건을 처음부터 명시합니다. 예를 들어, '모노톤 기반', '이모지를 장식으로 사용하지 않기', '구현 후에는 lint → 타입 체크 → 테스트 검증 루프를 반드시 돌리기'와 같이 말입니다. 나중에 'AI 같은 디자인이 되었으니 고쳐줘'라며 왕복하는 것보다, 처음에 조건을 전달하는 것이 압도적으로 빠릅니다. 반면, 에셋이나 레이아웃의 미세 조정은 한 번에 결정되지 않는 전제하에 반복 지시로 채워나갑니다.
요약
- 지도(CLAUDE.md): 200행 이내 안내판. 상세 내용은 docs/로 밀어 넣고, 링크로 찾아가게 한다.
- 강제(Hooks): 깨뜨리면 사고가 나는 불변 조건만 기계적으로 차단한다. 구현 방식은 묶지 않는다.
- 축적(Skills): 실패할 때마다 절차를 문서화한다. 복리처럼 효과가 쌓인다.
'지도(Map)', '강제(Enforcement)', '축적(Accumulation)'의 세 층으로 나누어 생각하면, "같은 실패를 반복하지 않는 개발 환경"은 지시의 능숙함이 아니라 구조로 얻을 수 있습니다. 프롬프트를 다듬기보다 먼저 하네스(harness) 자체를 의심하게 됩니다. 최근에는 그런 순서로 생각하게 되었습니다.
참고
토론
