Agent Harness Engineering: Codex를 만든 OpenAI가 말한 개발 방식
OpenAI가 Codex 관련 글에서 Harness Engineering이라는 개념을 강조했다.
엄밀히 말해 완전히 새로운 개념은 아닐 수 있다. 그래도 지금 AI 코딩 흐름에서 이걸 이렇게 명확하게 정리한 건 의미가
크다.
내가 참고한 문서는 아래 두 개다.
- OpenAI: https://openai.com/index/harness-engineering/
Harness engineering: leveraging Codex in an agent-first world
By Ryan Lopopolo, Member of the Technical Staff
openai.com
- Anthropic: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
Effective harnesses for long-running agents
Anthropic is an AI safety and research company that's working to build reliable, interpretable, and steerable AI systems.
www.anthropic.com
나는 개인적으로 Claude Code보다 Codex 쪽에 더 끌리는 편이다.
그래서 이 글을 읽으면서 느낀 점이 꽤 많았다. 이 글에서는 OpenAI가 말한 핵심을 정리하고, 내가 실제로 받아들인
해석까지 같이 적어보려고 한다.
Harness Engineering이 중요한 이유
하네스 엔지니어링은 한마디로, AI 에이전트가 코딩을 안정적으로 수행하도록 시스템을 설계하는 방식이다.
기존 바이브 코딩은 보통 이렇게 흘러간다.
- “기능 만들어줘” 하면 일단 만든다.
- 사람이 직접 테스트한다.
- 기능이 늘어나면 합쳐지는 지점에서 에러가 난다.
- 특히 입출력 스키마가 어긋나는 순간 문제가 터진다.
- 다시 “고쳐줘”를 반복한다.
겉으로는 빨라 보이는데, 실제로는 같은 문제가 형태만 바꿔 다시 나온다.
왜냐하면 구조, 경계, 실제 데이터 흐름이 검증된 상태로 관리되지 않기 때문이다.
그래서 나온 게 SDD(스펙 주도 개발), 검증 자동화, 에이전트 분업 같은 흐름이다.
내가 보기엔 Harness Engineering은 이걸 코딩 시스템으로 묶은 개념이다.
핵심은 이거다.
사람이 프롬프트를 한 줄씩 넣는 방식이 아니라,
에이전트가 구현 → 검증 → 피드백 반영 → 재검증을 반복하는 루프 자체를 설계하는 것.
이 지점에서 사람 역할도 바뀐다.
직접 코드를 다 치는 사람에서, 문제를 쪼개고 규칙/도구/피드백 루프를 설계하는 사람으로 무게중심이 이동한다.
Harness Engineering의 핵심 원칙 5가지
1) 규칙은 문서가 아니라 검사로 강제한다
2) AGENTS.md는 백과사전이 아니라 목차로 둔다
3) 실패는 “모델 탓”보다 “빠진 능력 신호”로 해석한다
4) 기술 부채는 주기적으로 자동 정리한다
5) 작은 자동화부터 시작해 복리로 확장한다
에이전트 하네스, 어떻게 시작하면 되나
하네스 엔지니어링이라는 말에 쫄 필요는 없다.
읽어보면 의외로 기본은 단순하다.
AI가 코딩하고, 검증하고, 고치고, 다시 검증하는 루프를 자동화하면 된다.
중요한 건 처음부터 완벽하게 하려는 게 아니라,
돌아가는 최소 루프를 먼저 만드는 것이다.
최소 CI 루프부터 차근차근 (lint / test / build)
처음부터 거대한 설계를 들고 들어가면 바로 지친다.
작게 쪼개서 시작하는 게 맞다.
- lint: 코드 규칙 위반 잡기
- test: 기능이 깨졌는지 확인
- build: 배포 가능한 상태인지 확인
포인트는 단순하다.
“내 로컬에서만 되는데요?”를 줄이는 것.
에이전트 규칙 3개만 먼저 만든다
규칙이 없으면 AI는 그 순간 그럴듯한 답을 낸다.
규칙이 있으면 AI는 기준 안에서 일한다.
1. 경계 데이터는 반드시 검증한다
- API 응답, 사용자 입력을 “맞겠지”로 넘기지 않는다.
- (문맥상 흔히 YOLO 데이터 처리라고 부르는 패턴 금지)
2. UI 단에서 Service/Repo 직접 접근을 제한한다
- 레이어 경계를 깨면 디버깅 비용이 급증한다.
3. 테스트 통과 전 완료 처리 금지
- “고친 것 같음”은 완료가 아니다.
핵심은 규칙을 AGENTS.md에 문장으로만 쓰는 게 아니라,
린트/테스트와 연결해 어기면 실패하게 만드는 것이다.
실패 기준은 숫자로 정의한다
“빠르게”, “안정적으로”는 사람마다 해석이 다르다.
실패 기준은 숫자로 박아야 한다.
예시:
- “핵심 API p95 500ms 이하”
- “핵심 플로우 e2e 3개 전부 통과”
- “PR 기준 error log 0건”
이렇게 되면 AI와 사람 간 해석 충돌이 줄어든다.
Harness Engineering에서 자주 하는 오해
- 모델만 좋아지면 자동으로 잘 된다
→ 아니다. 환경/규칙/검증이 더 중요하다.
- 문서를 길게 쓰면 컨텍스트가 풍부해진다
→ 아니다. 긴 문서보다 구조화된 인덱스가 훨씬 효과적이다.
개인적인 느낀점
나는 원래 Codex 쪽을 더 선호하는 편이다.
그래서 이 글이 더 크게 와닿았다.
가장 크게 느낀 건, 실력의 기준이 바뀌고 있다는 점이다.
예전에는 “코드를 얼마나 잘 짜느냐”가 핵심이었다면,
지금은 “AI가 안정적으로 일하게 시스템을 어떻게 설계하느냐”가 더 중요해지고 있다.
나도 처음에는 프롬프트 잘 쓰면 대부분 해결될 줄 알았다.
그런데 실제로는 그렇지 않았다.
프롬프트 한두 번으로 눈앞 문제는 고쳐도, 시간이 지나면 비슷한 문제가 다시 튀어나왔다.
결국 필요한 건 규칙, 검증, 자동화 루프였다.
내 결론은 세 가지다.
- 코드 생성 능력보다 루프 설계 능력이 더 중요하다.
- 프롬프트 장인보다 시스템 설계자가 오래 간다.
- 하네스 엔지니어링은 “AI 활용 팁”이 아니라 개발 체질을 바꾸는 방법론에 가깝다.
한 줄로 정리하면:
AI 시대 개발의 본질은 코드를 쓰는 일이 아니라, 코드를 계속 맞게 유지되게 만드는 일이다.
CTA
하네스 엔지니어링은 거창한 이론이 아니다.
핵심은 단순하다.
규칙을 정의하고, 검사로 강제하고, 반복 루프를 자동화하는 것.
3줄 요약
1. AI 코딩의 성패는 모델 성능보다 환경/규칙/검증 시스템에 달려 있다.
2. AGENTS.md는 장문 지시서보다 짧은 목차 + 구조화된 링크가 효과적이다.
3. 기술 부채는 나중에 몰아서 정리하지 말고, 주기적으로 자동 상환해야 한다.
처음부터 완벽할 필요 없다.
lint/test/build 자동화 + 규칙 3개 강제 + 주간 자동정리 루프만 시작해도 체감이 온다.
다음 글에서는 내가 실제로 쓰는 최소 CI 템플릿과
에이전트 규칙 3종(검증/레이어/완료 조건) 샘플을 공유해보겠다.
'AI > 공부' 카테고리의 다른 글
| SpecKit 완벽 가이드 - AI와 함께하는 스펙 주도 개발(SDD) (0) | 2026.01.03 |
|---|---|
| AI 에이전트가 똑똑해지려면 무엇이 필요한가: 세션과 메모리의 모든 것 (0) | 2025.11.30 |
| 📚 머신러닝과 딥러닝 완벽 정리 | 개념부터 모델 종류까지 한눈에 보기 (0) | 2025.03.21 |
