하네스 엔지니어링 기초

같은 모델을 쓰는데 어떤 팀은 성과가 나고 어떤 팀은 안 납니다. 차이는 대개 모델이 아니라 하네스에 있습니다.

하네스란

모델을 둘러싼 모든 것입니다.

• 어떤 도구를 쓸 수 있는가
• 어떤 지침이 항상 주입되는가
• 무엇이 자동으로 차단되는가
• 결과를 어떻게 검증하는가
• 실패했을 때 무슨 정보가 돌아오는가

모델은 재료이고 하네스는 주방입니다. 좋은 재료를 나쁜 주방에 넣으면 결과가 나쁩니다.

하네스 설계의 네 축

1. 컨텍스트 — 무엇을 보여줄 것인가

• CLAUDE.md에 무엇을 넣고 무엇을 뺄 것인가
• 조사는 서브 에이전트에 위임하는가
• 로그 출력을 잘라서 주는가

2. 권한 — 무엇을 허용할 것인가

• 읽기 전용 명령은 자동 승인
• 파괴적 명령은 훅으로 차단
• 배포·전송은 항상 사람 확인

3. 검증 — 성공을 어떻게 판정할 것인가

이것이 가장 중요합니다. 자동으로 실행 가능한 검증 명령이 있으면 에이전트가 스스로 고칩니다.

검증 명령이 있는 프로젝트: 실패 → 원인 파악 → 수정 → 재실행 (자율)
검증 명령이 없는 프로젝트: 그럴듯한 코드 생성 → 사람이 확인 (수동)

테스트, 타입 체크, 린트를 갖추는 것은 사람을 위한 것만이 아닙니다.

4. 피드백 — 실패가 얼마나 친절한가

오류 메시지가 "Error occurred"면 다음 시도가 개선되지 않습니다. 무엇이 왜 실패했는지 알려주는 메시지가 에이전트 성능을 직접 끌어올립니다.

실전 체크리스트

• [ ] CLAUDE.md가 100줄 이내이고 전부 검증 가능한 문장인가
• [ ] 표준 검증 명령(test, typecheck, lint)이 한 줄로 실행되는가
• [ ] 위험 명령이 훅으로 차단되는가
• [ ] 자주 쓰는 절차가 Skill이나 명령어로 묶여 있는가
• [ ] 오류 메시지가 원인을 알려주는가

흔한 오해

"더 좋은 모델을 쓰면 해결된다"

모델을 올리면 일부는 개선됩니다. 하지만 검증 수단이 없는 프로젝트에서는 더 그럴듯한 오답이 나올 뿐입니다.

"프롬프트를 잘 쓰면 된다"

프롬프트는 한 번의 요청에만 영향을 줍니다. 하네스는 모든 요청에 영향을 줍니다. 반복되는 것은 하네스로 옮기세요.

투자 순서

1. 검증 자동화 — 가장 큰 효과. 테스트·타입체크를 갖춥니다
2. 지침 정비 — CLAUDE.md를 검증 가능한 문장으로
3. 안전장치 — 훅으로 사고 가능성 제거
4. 절차 패키징 — 반복 작업을 Skill로

이 순서를 뒤집으면 효과가 크게 떨어집니다.

다음 레슨

팀 도입 워크플로