AI를 똑똑하게 쓰는 방법, 하네스(Harness) 개념 정리
소개
지난주에 하네스(Harness)에 대해 간단히 정의해 두었지만, 정확히 무엇이고 왜 필요한지 명확하게 정리되지 않은 상태였다.
그래서 관련 책과 강의를 참고하여 하네스의 개념과 설계 원칙, 그리고 실제로 왜 필요한지에 대해 다시 정리해보았다.
하네스(Harness)는 원래 말에 씌우는 마구를 의미한다. 말은 힘이 강하지만 방향을 잡아주지 않으면 원하는 곳으로 움직이기 어렵 다. 하지만 하네스를 장착하면 말의 힘을 원하는 방향으로 이끌 수 있다.
AI도 마찬가지다. AI는 강력한 능력을 가지고 있지만 적절한 제약과 규칙이 없다면 사용자가 원하는 방향에서 벗어날 수 있다. 따라서 하네스는 AI가 정해진 방향성을 유지하도록 돕는 장치라고 볼 수 있다.
진행 방법
1. 지시 파일(Instruction File)
AI에게 업무 매뉴얼을 제공하는 단계이다.
대표적으로 CLAUDE.md, AGENT.md 같은 파일에 프로젝트 규칙을 정리할 수 있다.
개발 관련 지시 파일
코드베이스 구조
레이어 순서
빌드 명령어
테스트 방법
코딩 스타일 규칙
프로젝트 디렉터리 구조
과거 실수를 방지하기 위한 규칙
개발 외 공통 지시 파일
업무 역할 및 전문 분야 정의
출력 형식 및 분량 기준
말투와 톤
금지 표현 목록
참고해야 할 자료 및 위치
과거 수정 요청에서 추출한 규칙
예시 구조
역할
[구체적인 역할 정의, 전문분야, 타겟 독자, 톤]
형식
[출력물의 구조와 분량]
금지
[절대 사용하지 말아야 할 표현이나 행동]
참고
[AI가 참조해야 할 자료나 기준]
주의
[자주 발생하는 실수와 방지 규칙]
2. 규칙 체크리스트(Checklist)
AI의 행동 범위를 제한하는 방법이다.
[입력 규칙]
[출력 규칙]
[행동 규칙]
AI가 작업을 완료한 후 체크리스트를 기준으로 스스로 검증하도록 구성할 수 있다.
이를 통해 결과물의 품질을 일정 수준 이상으로 유지할 수 있다.
3. 생성-검증 루프(Generate-Verify Loop)
AI가 생성한 결과를 AI가 다시 검토하게 만드는 방법이다.
예를 들어 역할을 분리하여 운영할 수 있다.
생성 담당 AI
검토 담당 AI
최종 승인 담당 AI
이렇게 역할을 분리하면 단순 생성보다 오류를 줄일 수 있다.
4. 컨텍스트 관리(Context Management)
AI가 긴 작업을 하면서도 품질을 유지하도록 돕는 방법이다.
1) 컴팩션(Compaction)
컨텍스트 창이 가득 차기 전에 내용을 요약하여 저장한다.
2) 하위 에이전트(Sub Agent)
독립적인 컨텍스트를 가진 에이전트에게 작업을 분산한다.
3) 진행 파일(Progress File)
현재 진행 상태를 파일로 관리하여 세션이 변경되어도 작업 흐름을 유지한다.
하네스가 필요한 이유
공부하면서 자주 발생하는 AI의 실패 패턴을 정리해보았다.
1. 환각(Hallucination) 반복
증상
존재하지 않는 통계 제시
실제 없는 인용문 생성
확인되지 않은 사실을 단정적으로 설명
해결 방법
체크리스트에 팩트 체크 규칙을 추가한다.
검증 불가능한 수치는 추정으로 표시
인용문은 출처 확인 필수
확인되지 않은 정보는 "확인 필요" 표기
2. 지시 무시
증상
지시 파일에 "하지 말라"고 적어두었지만 반복적으로 같은 행동을 수행한다.
해결 방법
금지 규칙을 지시 파일 최상단에 배치한다.
추가로 동일한 규칙을 첫 줄과 마지막 줄에 반복 배치하면 효과가 높아질 수 있다.
3. 형식 불일치
증상
같은 보고서를 요청해도 매번 다른 형식으로 출력된다.
해결 방법
설명보다 템플릿을 제공한다.
# 제목
## 요약
## 문제점
## 해결방안
## 결론
AI는 설명보다 예시 패턴을 더 잘 학습하고 따른다.
4. 과도한 자신감
증상
모르는 내용도 확신을 가지고 답변한다.
해결 방법
확실하지 않은 내용은 추정으로 표시
검증이 필요한 내용은 별도 표기
규칙을 명확하게 정의한다.
5. 무관한 정보 삽입
증상
제품 설명을 요청했는데 관련 없는 배경 설명이나 추가 정보가 포함된다.
해결 방법
지시 파일에 다음과 같은 제한을 명시한다.
실제 적용 : 뉴스 보고서 하네스 만들기
개념만 공부하는 것이 아니라 실제로 하네스를 만들어보았다.
진행 방법
사용 도구
이번 실습에서는 다음 도구를 활용했다.
Claude Code
Harness 플러그인
멀티 에이전트 구조
HTML 카드뉴스 렌더링
초기 하네스 구성은 아래 플러그인을 설치하여 사용해보았다.
<https://github.com/revfactory/harness>1. 뉴스 보고서 생성 하네스 만들기
먼저 키워드를 받아 뉴스를 모으고, 그 내용을 보고서로 정리하는 하네스를 만들었다.
사용한 프롬프트는 다음과 같다.
/harness
키워드를 받아서 뉴스 모으고 보고서 만드는 하네스 만들어줘
규칙
- 보고서 순서: 요약 -> 주요 이슈 3개 -> 시사점
- 출처 URL은 꼭 같이 적기
이 프롬프트의 핵심은 단순히 뉴스를 모으는 것이 아니라, 결과물의 구조를 미리 정해두는 것이었다.
보고서의 순서를 다음처럼 고정했다.
요약
주요 이슈 3개
시사점
출처 URL
이렇게 해두면 AI가 매번 다른 형식으로 답변하는 문제를 줄일 수 있다.
2. 뉴스 보고서를 카드뉴스로 바꾸는 하네스 만들기
다음으로는 뉴스 보고서를 기반으로 카드뉴스 7장을 만드는 하네스를 구성했다.
/harness 뉴스 보고서로 카드 뉴스 7장 만드는 하네스 만들어줘
규칙:
- 카드 구성: 1장 표지(핵심 메시지) / 2~6장 이슈별 / 7장 CTA
- 1080x1350 기준
- 출처는 캡션에 작게 표시
여기서는 카드뉴스의 구성 규칙을 명확히 정했다.
1장: 표지
2~6장: 주요 이슈별 카드
7장: CTA(Call To Action)
이미지 기준: 1080x1350
출처: 각 카드 캡션에 작게 표시
카드뉴스는 보는 사람이 빠르게 이해해야 하기 때문에, 처음부터 장수와 역할을 나누는 것이 중요하다고 느꼈다.
3. 멀티 에이전트 구조 설계
이번 실습에서 가장 흥미로웠던 부분은 역할을 분리한 것이다.
프로젝트 구조는 다음과 같이 구성했다.
.claude/
├─ agents/
│ ├─ news-collector.md
│ ├─ report-writer.md
│ ├─ card-designer.md
│ └─ card-renderer.md
│
└─ skills/
├─ news-collector
├─ report-writer
├─ card-designer
├─ card-renderer
└─ card-news-maker
각 에이전트는 하나의 역할만 담당하도록 설계했다.
에이전트
역할
news-collector
뉴스 수집
report-writer
보고서 작성
card-designer
카드뉴스 기획
card-renderer
HTML 카드뉴스 생성
작업 흐름은 다음과 같다.
뉴스 수집
↓
news-collector
보고서 작성
↓
report-writer
카드뉴스 설계
↓
card-designer
HTML 렌더링
↓
card-renderer
하나의 AI가 모든 작업을 처리하는 것이 아니라 역할별로 책임을 분리한 구조다.
4. 생성결과
결과와 배운 점
이번 실습을 통해 느낀 점은 하네스의 핵심은 프롬프트가 아니라 구조라는 것이다.
좋은 하네스는
역할을 분리하고
규칙을 정의하고
검증 과정을 만들고
컨텍스트를 관리하는 것
에 더 가깝다.
특히 이번 카드뉴스 프로젝트에서는
뉴스 수집
→ 보고서 작성
→ 카드 설계
→ HTML 생성이라는 작업 흐름을 에이전트로 분리하면서 하네스의 효과를 직접 체감할 수 있었다.
아직 완벽한 하네스를 만들지는 못했지만, 단순한 프롬프트보다 훨씬 안정적이고 재사용 가능한 구조를 만들 수 있다는 가능성을 확인할 수 있었다.
다음 단계로는 개발 업무에 적용할 수 있는 개발자 전용 하네스를 만들어 볼 예정이다.
코드 스타일, 테스트 규칙, 코드 리뷰 체크리스트 등을 포함하여 실제 개발 생산성을 높이는 방향으로 확장해보고자 한다.
도움 받은 글
revfactory Harness 플러그인
하네스 관련 책과 강의
