Harness 란?
코드 에이전트가 장시간 오랫동안 목적을 지속적으로 수행하도록 하기 위한 작업이다. 적절한 가이드를 제공함으로써 개발 과정의 효율을 높일 수도 있고 돌발 상황에 대한 안전장치가 될 수도 있다.
코드 에이전트 기술
Harness를 다루기 전에 코드 에이전트와 관련된 여러 가지 용어와 기술에 대해서 알아보자.
- AGENTS.md
- Skill
- MCP (Model Context Protocol)
- 멀티 에이전트
AGENTS.md
코드 에이전트에서 우선적으로 사용되는 규칙, 지침 파일이다.
코드 에이전트별로 다르며 Claude code에서는 CLAUDE.md 파일을 사용한다.
작동 방식
- Context Window에 사용자 입력과 AGENTS.md의 내용이 같이 들어간다.
context window:
모델이 한 번에 받아들이는 입력 내용의 영역으로 크기가 제한되어 있다.
AGENTS.md 작성 가이드
- 프로젝트 구성요소에 대한 설명 명시한다.
- 프로젝트의 행동 규칙(Rule) 명시한다.
- 최대한 변하지 않을 내용으로 작성한다.
- 자주 변경되면 Agent도 혼란을 겪을 수 있다.
- 간략하게 작성한다.
- 디테일할수록 context를 많이 차지하고, 토큰 소모량 증가하며, 변경될 확률이 증가한다.
- 디테일한 내용은 분리된 md 파일로 작성하여 필요할 때 읽도록 명시한다.
Skill
에이전트에게 특정 작업을 수행하는 방법을 정의하여, 재사용 가능한 지식, 능력 패키지이다. AGENTS.md와 달리, on-demand 방식으로 필요할 때만 동적으로 불러온다.
Skill metadata
각 Skill은 SKILL.md 파일을 가지는데 여기에는 Skill의 metadata (name, description) 정보가 함께 들어있다. 코드 에이전트는 스킬 목록에서 metadata를 불러와서 스킬을 로드할지 판단한다.
use case
- 자주 반복되는 프롬프트를 하나의 명령(skill)으로 생성
- 파일 편집 / 명령어 실행 / 인터넷 검색 같은 Tool을 사용하는 명령(skill)으로 생성
MCP (Model Context Protocol)
코드 에이전트에서 수많은 외부 서비스를 통일된 방식으로 연결하기 위한 표준 프로토콜이다.
멀티 에이전트
단일 에이전트에서 복잡한 업무를 처리할 때 Context Window에 입력된 많은 정보로 성능이 떨어질 수 있다. 멀티 에이전트는 복잡한 업무를 여러 단계로 나누어 각각의 전문가(서브 에이전트)에게 업무를 분배하고 다음과 같은 특성을 이용하여 효율적으로 처리한다.
- 격리(isolation) — 각 에이전트는 자신만의 독립된 Context를 가진다.
- 병렬성(parallelism) — 각 에이전트는 동시에 병렬로 작업할 수 있다.
궁금한 점
모델이 100k의 컨텍스트를 지원한다고 할 때, 멀티 에이전트로 구성할 경우 각 서브 에이전트는 100k의 컨텍스트를 가질까? => Yes
멀티 에이전트의 단점
토큰 소비량이 많아진다. 각 에이전트 별로 독립된 Context를 가지기 때문에, 초기화 비용이 중복으로 발생한다.
Harness 적용하여 개발하기
- Harness 구성
- 요구사항 문서 작성
- Phase 수립 및 개발
Harness 구성
- AGENTS.md 파일 생성 (claude의 경우 CLAUDE.md)
- 프로젝트 내용 작성
- 하네스 구성
- 주의사항 명시
- 프레임워크, 도구 명시
Andrej-karpathy skill
https://github.com/multica-ai/andrej-karpathy-skills
https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md
AI 코딩 에이전트의 흔한 실수를 줄이기 위해 사용되는 유명한 지침 (2026-07 기준 Github Stars 수 약 200k)
이런 기본적인 하네스를 구성하는 것도 좋지만, 이는 LLM, 코드 에이전트가 발전할수록 필요성이 떨어질 것이다.
나의 프로젝트에 맞게 최적화된 Harness를 구성하는 것이 더 중요하다.
요구사항 문서 작성
- PRD (Product Requirements Document) 작성
- Specification 문서 작성
PRD (Product Requirements Document) 작성
- 고객 입장에서 어떤 프로그램을 원하는지 작성한다.
- 개발적인 지식이 들어가면 안 된다.
Specification 문서 작성
- 요구사항 문서보다 디테일하게 기준을 정리하는 문서
Superpowers Skill의 /brainstorming을 사용하면 질의응답을 통해, 모도한 요구사항을 더 명확하게 만들 수 있다.
Phase 수립 및 개발 수행
- Phase 작성
- 서브 에이전트 구성
- Workflow 구성
- Feedback loop 구성
Phase 작성
단계별로 어떤 내용을 개발할지 계획
각 Phase 별로 동작되어야 하며 사람이 직접 테스트 가능해야 한다.
- ex) 로그분석 차트 개발
- Phase 1: UI 구성
- Phase 2: 파일 URL
- Phase 3: 데이터 파싱
- Phase 4: API 별 Latency 측정 통계 계산
- Phase 5: 차트 출력
서브 에이전트 구성
코드 품질을 높이기 위해 각 Phase 마다, 4단계 작업을 구성하고 각 에이전트가 이를 담당하게 구성한다.
- coding
- test
- review
- verify
ex) claude
.claude/
├── agents/
│ ├── coder.md # 구현 (Coding)
│ ├── tester.md # 테스트 작성·실행 (Test)
│ ├── reviewer.md # 정확성/보안/품질 리뷰 (Review)
│ └── verifier.md # end-to-end 동작 검증 (Verify)
Workflow 구성
- 각 서브 에이전트를 순서대로 실행하도록 Workflow를 구성한다.
Claude Code 전용 기능
서브 에이전트들의 Workflow를 구성하여 실행해 주는 JavaScript 코드를 만들어 준다.
Feedback loop 구성
일부 작업이 실패하더라도 개발 수행이 중단되지 않도록 하는 안전장치(Harness)가 필요하다. 각 에이전트 수행 중 실패 시 코드 수정 후, 다시 test 단계로 되돌아가는 피드백 루프를 추가한다.
More
Harness Engineering 잘하기 위해서 많이 사용되는 AI Harness를 적용해 보면 좋을 것 같다.
- Superpowers
- G-Stack
- Oh My Opencode (Oh My Claudecode)
- Hands off
- ...
