귀찮아서 AI 작업 방식 자체를 세팅해버렸다
같은 말 두 번 하기 싫어서 하네스 엔지니어링을 구축했다. init-harness가 CLAUDE.md + 커맨드 7개 + Hooks를 자동 생성한다. /workflow 하나로 브랜치부터 커밋까지 전체 파이프라인이 돌아간다.
On this page (10)
하네스 엔지니어링이란
하네스(harness)는 원래 말에 씌우는 마구(馬具)다. 여기서는 AI에게 씌우는 작업 틀을 말한다. 단순히 프롬프트를 잘 쓰는 게 아니라 Claude가 어떻게 일할지를 시스템으로 만들어두는 것이다.
구성 요소는 세 가지다. Rules는 프로젝트 루트의 CLAUDE.md다. "이 프로젝트에서 항상 지켜야 할 규칙"이다. Commands는 반복되는 작업 요청을 파일로 저장한 것이다. /workflow, /plan-and-spec 같은 것들이다. Hooks는 특정 동작 전후에 강제로 실행되는 로직이다. 이 중 가장 강력한 단계다.
Rules는 "무엇을 해야 하는지"를 정의한다. Commands는 "어떻게 할지"를 정의한다. Hooks는 "절대로 하지 말아야 할 것"을 강제한다. 세 레이어가 합쳐져서 하나의 틀이 된다.
이 구조가 생긴 배경
Anthropic의 Claude Code 공식 문서에 Commands, Hooks 개념이 있다. 하네스 엔지니어링은 이 기능들을 조합해서 개인 개발 워크플로우 전체를 자동화한 방식이다. 숨겨진 기능을 쓰는 게 아니라 공식 기능을 조합한 것이다.
전체 구조 한눈에
파일 구조를 먼저 보는 게 이해가 빠르다. 글로벌 영역과 프로젝트별 영역으로 나뉜다. 글로벌 영역은 컴퓨터 전체에서 공통으로 쓰는 것들이다. 최초 1회만 세팅하면 모든 프로젝트에서 그대로 쓴다.
commands/
init-harness.md ← 하네스 자동 구축 (이 파일)
new-project.md ← 아이디어 → 프로젝트 세팅
session-resume.md ← 세션 재개 컨텍스트 복원
hooks/
block-dangerous.sh ← 위험 명령어 차단
settings.json ← 훅 연결
프로젝트/ ← 프로젝트마다 자동 생성
CLAUDE.md ← 이 프로젝트 규칙
progress.md ← 현재 작업 상태
dev-log.md ← 기능 단위 개발 기록
docs/ ← 설계 문서 저장
screenshots/ ← 화면 캡처 저장
.claude/commands/
workflow.md ← 전체 파이프라인 오케스트레이터
plan-and-spec.md ← 설계 + 팩트체크 (Planner)
tdd.md ← 구현 (Generator)
ui-ux.md ← UI/UX 리서치
verify.md ← 검증 (Evaluator)
commit.md ← 커밋 + 머지
핵심은 분리다. 어느 프로젝트에서나 쓸 수 있는 것은 글로벌로, 이 프로젝트에서만 의미 있는 것은 프로젝트 안으로 넣는다. init-harness가 프로젝트 영역 전부를 자동으로 만들어준다.
init-harness: 분석부터 생성까지
새 프로젝트를 시작하거나 기존 프로젝트에 하네스를 붙일 때 /init-harness 하나만 실행하면 된다. 5단계로 자동 진행된다. 중간에 확인을 요청하지 않는다. 분석 요약을 한 번 보여주고 바로 생성으로 넘어간다.
1단계는 프로젝트 분석이다. package.json으로 스택을 파악하고, 폴더 구조 3depth를 확인하고, git log로 커밋 패턴을 읽는다. .env.example로 연동 서비스도 확인한다. 읽기만 한다. 아무것도 바꾸지 않는다.
git log --oneline -20 # 커밋 패턴 파악
git branch -a # 브랜치 전략 확인
# 분석 완료 후 요약 출력 형식
[프로젝트 분석]
- 스택: Next.js 15 / TypeScript / Supabase
- 구조 특징: App Router, src/ 없음, 기능별 폴더
- 커밋 패턴: feat/fix/refactor 접두사
- 브랜치 전략: feature/* → main 직접 머지
- 연동 서비스: Supabase, Resend, LemonSqueezy
- 생성할 커맨드: workflow, plan-and-spec, tdd, ui-ux, verify, commit
2단계는 CLAUDE.md 생성이다. 분석 결과로 기술 스택, 아키텍처 규칙, 절대 금지 사항을 채워 넣는다. 빈 템플릿이 아니라 프로젝트를 실제로 읽고 만드는 파일이다. "다국어는 i18n 키로만", "하드코딩 금지", "main force push 금지" 같은 항목이 자동으로 들어간다.
3단계는 커맨드 파일 생성이다. workflow, plan-and-spec, tdd, ui-ux, verify, commit이 .claude/commands/ 안에 만들어진다. 4단계는 progress.md, dev-log.md, docs/, screenshots/ 같은 프로젝트 기본 파일 생성이다. 5단계는 글로벌 파일 확인이다. session-resume, new-project, block-dangerous.sh가 없으면 만들고, 이미 있으면 건드리지 않는다.
커맨드 파이프라인
workflow.md가 전체 파이프라인의 오케스트레이터다. /workflow "기능명" 하나를 실행하면 나머지를 순서대로 호출한다. 각 단계가 완료되면 다음 단계로 자동으로 넘어간다.
0. 현재 상태 파악 # progress.md + git log --oneline -10
1. 브랜치 세팅 # feature/feedback-auto-classify
2. 설계 + 팩트체크 # /plan-and-spec 실행 → Planner
3. 구현 # /tdd 실행 → Generator
4. 검증 # /verify 실행 → Evaluator
5. 커밋 + 머지 # /commit 실행
# 검증 실패 시 → 3번으로 돌아가서 수정 후 재검증
plan-and-spec은 구현 전 웹서치로 팩트체크를 강제한다. 사용할 라이브러리가 실제로 존재하는지, 해당 API가 구현 가능한지 레퍼런스를 먼저 확인한다. 100% 구현 불가능한 부분이 있으면 대안을 제시한다. 설계 문서는 docs/spec-기능명.md로 저장된다.
tdd는 기능 단위로 나눠서 하나씩 구현한다. 구현 완료된 화면마다 목업 데이터를 주입해서 실제처럼 보이게 만들어두는 단계도 포함된다. EP.08에서 플랫폼별 위젯 구현이 끝날 때마다 스크린샷을 찍어뒀던 패턴을 커맨드로 박아둔 것이다.
verify는 설계 문서와 실제 구현을 대조하는 단계다. 누락된 기능, 다국어 미처리, 빌드 오류를 체크한다. 실패 항목이 있으면 수정 방법을 같이 출력하고 tdd로 돌아간다. 단순히 "돌아가나"가 아니라 "설계한 대로 만들었나"를 확인한다.
Planner → Generator → Evaluator
커맨드 파이프라인의 핵심은 3역할 분리다. 하나의 Claude가 역할을 바꿔가면서 작업한다. plan-and-spec이 Planner, tdd가 Generator, verify가 Evaluator 역할을 맡는다.
Planner는 구현 전에 설계하고 팩트체크한다. "이게 가능한가"를 먼저 검증한다. 웹서치로 라이브러리 실제 존재 여부, 비슷한 구현 사례, API 제약 사항을 확인하고 설계 문서를 만든다. 팩트체크 없이 구현부터 시작했다가 막히는 상황을 막기 위한 단계다.
Generator는 설계 문서를 보면서 기능 단위로 구현한다. 구현 중에 설계가 바뀌면 즉시 docs/spec-*.md를 수정하고 변경 이유를 명시한다. 설계와 코드가 동기화된 상태를 유지하는 게 핵심이다. "나중에 업데이트하겠다"는 없다.
Evaluator는 설계 문서와 실제 구현을 비교한다. 기능 누락, 다국어 미처리, 예외 처리 누락을 체크한다. Generator가 스스로 검증하지 않는다. 역할을 분리함으로써 구현자가 빠트리기 쉬운 것들을 다른 눈으로 잡아낸다.
EP.05 클러스터링 기능에서 실제로 쓴 결과
피드백 자동 클러스터링을 만들 때 Planner가 pgvector와 Voyage AI 임베딩 API의 실제 파라미터를 팩트체크했다. Generator가 clustering.ts 188줄을 기능 단위로 구현했다. Evaluator가 설계 문서와 대조해서 코사인 유사도 임계값 처리 누락을 찾아냈다. 그 전에는 완성 후 뒤늦게 발견하던 종류의 누락이었다.
훅으로 강제하는 것들
커맨드는 선택이지만 훅은 자동으로 돌아간다. Claude가 어떤 bash 명령을 실행하기 전에 block-dangerous.sh가 먼저 실행된다. exit 2를 반환하면 명령이 차단된다. 두 가지를 막는다.
INPUT=$(cat)
# main 직접 force push 차단
if echo "$INPUT" | grep -q "push.*--force.*main\|push.*main.*--force"; then
echo "main force push 차단" >&2
exit 2
fi
# .env 커밋 차단
if echo "$INPUT" | grep -q "git add.*\.env\b"; then
echo ".env 파일 커밋 차단" >&2
exit 2
fi
exit 0
이 스크립트를 settings.json의 PreToolUse 훅으로 연결한다. Claude가 Bash 툴을 실행하기 전에 자동으로 호출된다.
{
"hooks": {
"PreToolUse": [{
"matcher": "Bash",
"hooks": [{
"type": "command",
"command": "bash ~/.claude/hooks/block-dangerous.sh"
}]
}]
}
}
훅의 장점은 실수를 원천 차단한다는 점이다. 실수로 main에 force push 명령이 들어가더라도 시스템이 막는다. 인간이 확인하는 게 아니라 시스템이 막는다. 이 두 개만 잡혀 있어도 치명적인 실수는 방어된다.
완전 자동화 모드
하네스가 세팅된 상태에서 Claude Code를 --dangerously-skip-permissions 플래그와 함께 실행하면 확인 없이 끝까지 혼자 달린다. 중간에 "이렇게 해도 됩니까" 묻지 않는다. /workflow를 실행해두면 브랜치 생성부터 커밋, 머지까지 전부 자동으로 진행된다.
이 모드가 위험한 게 아니다. 훅 없이 쓰는 게 위험한 것이다. 훅이 main force push와 .env 커밋을 막아주기 때문에 치명적인 두 가지는 자동으로 방어된다. 하네스 먼저 세팅하고 그다음에 쓰는 게 순서다.
세션이 끊겼다 재개할 때는 /session-resume을 쓴다. progress.md, dev-log.md 마지막 30줄, git log, git status를 읽고 "어디까지 했고 다음은 뭐다"를 요약해서 바로 이어 진행한다. EP.01에서 만든 CLAUDE.md 자동화와 짝을 이루는 기능이다. 하나는 규칙을 유지하고, 하나는 상태를 복원한다.
달라진 것들
하네스를 만든 뒤로 달라진 게 몇 가지 있다. 수치로 보면 이렇다.
| 이전 | 이후 | |
|---|---|---|
| 새 프로젝트 시작 | 매번 규칙 설명 (10~15분) | /init-harness 한 줄 |
| 기능 개발 순서 | 매번 순서 설명 반복 | /workflow "기능명" |
| 세션 재개 | 컨텍스트 다시 설명 | /session-resume |
| UI 개발 리서치 | 매번 따로 요청 | ui-ux.md에 내장 |
| 설계 문서 | 잊고 안 씀 | 자동 생성 + 자동 수정 |
예상 못 한 결과가 있었다. 귀찮아서 만든 시스템인데 결과적으로 더 꼼꼼하게 작업하게 됐다. 설계 문서를 쓰게 되고, 팩트체크를 하게 됐다. 예전에는 귀찮아서 넘기던 단계들이 커맨드에 박혀 있으니까 그냥 돌아가는 거다.
자주 묻는 것들
Q. init-harness를 실행하면 CLAUDE.md를 직접 안 써도 되나?
자동 생성되지만 완전히 대체하진 않는다. init-harness가 만드는 건 프로젝트 분석 기반의 초안이다. 팀 컨벤션, 특정 라이브러리 제약, 배포 환경 같은 내용은 직접 추가해야 한다. 자동 생성 후 보완하는 방식으로 쓰면 된다.
Q. /workflow 같은 커맨드를 매번 써야 하나?
아니다. 간단한 버그 수정이나 작은 변경은 그냥 말로 요청하면 된다. 커맨드는 처음부터 끝까지 제대로 가야 하는 기능 개발에만 쓴다. 훅만 항상 백그라운드에서 돌고 있고 나머지는 전부 선택이다.
Q. --dangerously-skip-permissions 플래그는 위험하지 않나?
훅 없이 쓰면 위험하다. 훅이 main force push와 .env 커밋을 막아주기 때문에 하네스 먼저 세팅하고 쓰는 게 순서다. 위험한 게 아니라 훅 없이 쓰는 게 위험한 것이다. 이 두 개만 잡혀 있으면 완전 자동화 모드는 쓸 만하다.
Q. 이 구조를 팀 프로젝트에도 쓸 수 있나?
솔로 개발 기준으로 설계된 구조다. 팀에서 쓰려면 main 직접 머지 부분과 브랜치 전략을 수정해야 한다. CLAUDE.md를 팀 컨벤션에 맞게 바꾸고 commit.md에 PR 생성 단계를 추가하면 된다. 구조 자체는 팀에도 적용 가능하다.
마무리
이 구조를 세팅하는 데 하루 이틀 걸렸다. 커맨드 파일 쓰고, 훅 만들고, 흐름 테스트하고. 처음에는 이게 맞나 싶었다. 지금은 새 프로젝트를 시작할 때마다 /init-harness 하나로 전부 준비되니까 그 시간이 아깝지 않다.
하네스는 완성이 없다. 쓰다 보면 부족한 부분이 보이고 그때마다 커맨드 파일을 수정하게 된다. 완벽한 틀을 만들려는 게 아니라 귀찮은 걸 하나씩 줄여가는 거다. 그게 귀찮은개발자 방식이다.
관련 에피소드
이 글의 코드와 구조는 2026년 4월 기준으로 작성됐다. Claude Code 업데이트에 따라 훅 설정 방식이 바뀔 수 있다.
GoCodeLab · 귀찮은개발자 시리즈 · EP.17