AI 개발 하네스(Harness) 구축기

이런 상상을 해본 적이 있다..

"그냥 아이디어만 말하면 앱 만들어주는 거 없나?"

개발자라면 한 번쯤 해봤을 생각이다. 물론 현실에서는 기획서 쓰고, 디자인 받고, 코드 짜고, 빌드 터지면 고치고, QA하고... 이 지난한 과정을 묵묵히 반복한다.

그런데 Claude Code를 쓰다 보니 문득 이런 생각이 들었다.

"이거, 제대로 세팅하면 진짜 되는 거 아닌가?"

그래서 해봤다. 오늘은 그 과정에서 배운 것들을 공유한다.
나처럼 AI를 활용하기는 하지만 제대로 쓰고 싶은 사람이나 하네스에 대해서 학습하거나 구축하여 적용하고 있는 사람이 해당 글을 읽으면 도움이 아주 조금 될 것 같다. 잘못된 정보나 조언 해줄 부분이 있다면 댓글로 해주면 너무 좋을 것 같다. 

하네스(Harness)가 대체 뭔데?

처음엔 아무것도 몰랐다. "AI 하네스 구축하고 싶다"라고 생각는데, 정작 하네스가 뭔지 제대로 설명하기가 어려웠다.

찾아보니 원래 말에 채우는 마구(馬具)라는 뜻이다. 말이 혼자 뛰어다니면 소용없기 때문에, 마구를 채워야 수레를 끌 수 있다. 소프트웨어에서도 똑같다.

하네스 = AI 모델이 원하는 방향으로 작동하도록 연결하고 제어하는 인프라

Claude라는 말(🐴)이 있어도, 그냥 두면 알아서 뛰어다닐 뿐이다. 하네스를 채워야 "서비스 개발"이라는 수레를 끌 수 있게 된다.

제품 퀄리티를 결정하는 세 가지

하네스를 구축하면서 퀄리티가 어디서 결정되는지 정리해봤다.

한 마디로 제품 퀄리티 = 모델 x 하네스 인 것 같다.

1. AI 모델 - 능력의 상한선

모델이 좋을수록 코드 품질, 판단력, 엣지 케이스 처리가 좋아진다. 하네스가 아무리 잘 만들어져도 모델의 한계를 넘을 수는 없다고 생각한다.

2. 스킬 / 에이전트 - 방향을 결정하는 지시서

모델의 능력을 "서비스 개발"이라는 방향으로 정렬하는 역할이다. 스킬이 정교할수록 Claude가 매번 혼자 판단해야 하는 영역이 줄어든다.

스킬은 단순히 "무엇을 해라"가 아니라 "어떤 기준으로 판단해라"를 얼마나 잘 정의했느냐가 핵심이다.

❌ 나쁜 예시: "특정 컴포넌트를 써라"
⭕ 좋은 예시: "이 화면 유형에서는 ListRow를 쓰고, 액션이 2개 이상이면 BottomSheet로 분리해라"

➔ 실제로 테스트를 했을 때, 결과가 완전히 달랐다.

3. 인프라 - 연결하고 자동화하는 뼈대

MCP 서버, 훅, 설정 등이 올바르게 연결되어야 스킬이 실제로 외부 도구를 쓸 수 있다.

학습할 때, 공장 비유가 제일 와닿았다

처음에 사람 비유로 설명했는데, 이 비유가 더 정확했다.

구성 요소	공장 비유
AI 모델	공장 기계의 성능
스킬 / 에이전트	공정 설계, 작업 지시서, 품질 기준
하네스 전체	공장 그 자체

원자재(아이디어)가 들어오면 공장(하네스)이 돌아가서 완제품(서비스)이 나오는 구조다.
그리고 공장의 진짜 목적은 반복 생산이다. 한 번 잘 만드는 게 아니라, 어떤 아이디어가 들어와도 일정 수준 이상의 결과를 안정적으로 뽑아내는 것. 그게 하네스를 잘 만든다는 의미다.

실제로 만든 것들

구조

.claude/
├── commands/          # 사용자가 호출하는 슬래시 커맨드
│   ├── build.md       # 오케스트레이터 (단일 진입점)
│   ├── workflow-*.md  # 단계별 수동 실행 커맨드
│   └── ref-*.md       # 레퍼런스 조회
├── agents/            # 오케스트레이터가 자율 실행하는 에이전트
│   ├── plan.md        # 기획 에이전트
│   ├── design.md      # 디자인 에이전트
│   ├── implement.md   # 개발 에이전트
│   └── validate.md    # 검증 에이전트
├── hooks/             # 자동 실행 스크립트
└── settings.json      # 훅 설정

핵심은 오케스트레이터 + 에이전트 구조이다

1. 사용자: /build 투두 앱 만들어줘
2. Phase 1 (사용자와 소통)
   • 기획 에이전트, 3라운드 질문 ➔ 사용자 승인 ➔ docs/plan.md
3. Phase 2 (자율)
   • 디자인 에이전트, plan.md 읽기 ➔ TDS 컴포넌트 맵핑 ➔ docs/design.md
4. Phase 3 (자율)
   • 개발 에이전트, design.md 읽기 ➔ 코드 구현
5. Phase 4 (자율, 루프)
   • 검증 에이전트, 타입 체크 ➔ 빌드 ➔ 에러 수정 ➔ 재시도
6. 완료
   • 기획 단계만 사용자와 충분히 소통하고, 나머지는 알아서 달린다. "아이디어만 던지면 나온다"에 가장 가까운 구조다.

에이전트 간 통신은 파일로

에이전트끼리 직접 대화하지 않고, 파일을 통해 결과를 넘긴다.

• plan.md 생성 ➔ design 에이전트가 읽음
• design.md 생성 ➔ implement 에이전트가 읽음
• 코드 생성 ➔ validate 에이전트가 검증

단순하지만 가장 안정적인 방법이다.

삽질하면서 배운 것들

1. "하네스 = 인프라"가 아니었다

처음에 하네스를 MCP, 훅, 설정 같은 인프라 레이어로만 생각했다. 틀렸다. 스킬과 에이전트도 하네스의 일부다. 인프라는 필요 조건(없으면 안 됨)이고, 스킬/에이전트는 충분 조건(얼마나 잘 만드냐)이다.
인프라는 한 번 잘 세팅하면 끝이지만, 스킬과 에이전트는 계속 다듬어야 한다. 시간과 노력의 대부분을 스킬에 투자하는 게 맞다.

2. 기획 단계를 자율화하면 안 된다

처음 설계할 때 모든 단계를 자율화하려 했다. "아이디어 던지면 다 알아서 해줘"라는 목표로 말이다.
그런데 생각해보면, 기획이 잘못되면 아무리 개발을 잘해도 소용없다. "투두 앱 만들어줘"라고 하면 Claude가 알아서 판단해서 만드는데, 그게 내가 원하는 방향과 다를 가능성이 높다.
그래서 기획 에이전트는 3라운드 질문을 통해 사용자의 의도를 충분히 파악하고, 명확한 승인을 받은 뒤에만 기획안을 작성하도록 만들었다.

3. 컴포넌트만 쥐여준다고 디자인이 나오지 않는다

디자인 에이전트가 특정 UI 컴포넌트를 사용해 화면을 그리도록 구현했다. 규격화된 컴포넌트를 가져다 쓰니 당연히 잘 나올 줄 알았다. 하지만 오산이었다. 컴포넌트는 올바르게 매핑하는데, 완성된 화면은 생각한 대로 예쁘게 나오지 않았다. 배치나 여백, 컴포넌트 간의 조합에 대한 구체적인 기준이 없으니 어색하고 조잡한 화면이 그려졌다. 그래서 특정 UI 패턴과 레이아웃 템플릿을 미리 만들어 디자인 에이전트가 참조하도록 학습시켰고, 개발 에이전트 역시 이 규칙을 따르도록 가이드를 고도화했다. 템플릿이라는 명확한 기준을 준 덕분에 이전보다 훨씬 조화롭고 완성도 높은 결과물을 얻을 수 있게 되었다.

4. 오답노트는 처음부터 만들어라

결과물이 마음에 안 들면 스킬을 고치게 된다. 그런데 "왜 이렇게 고쳤는지"를 기록해두지 않으면, 나중에 또 같은 실수를 한다.

docs/harness-log.md를 만들어서 이렇게 기록한다.

## 2026-05-01 | validate 에이전트 | 에러 수정하다가 더 큰 에러 만들어냄

### 현상
타입 에러 하나 고치려다 전체 타입 구조를 바꿔버림

### 원인
에러 범위를 최소화하라는 지시가 없었음

### 해결
"에러 수정 범위는 최소화, 전체 구조 변경 금지" 규칙 추가

### 반영된 곳
.claude/agents/validate.md

오답만 기록하지 말고, 잘 됐던 패턴도 같이 기록하려고 한다.

마치며

에이전트가 실제로 서비스를 만들어봐야 어디가 부족한지 보인다. 지금은 구조만 잡은 상태고, 실전에서 오답노트가 쌓이면서 진짜 품질이 올라갈 것으로 예상한다.

하네스를 구축한다는 건 결국 모델의 능력을 최대한 끌어내는 스킬을 만들고, 그 스킬들이 필요한 도구들과 막힘 없이 연결되어, 사람의 개입 없이 목표까지 도달하는 구조를 만드는 것이라고 생각한다.