HARNESS ENGINEERING · 코딩 초심자 해설

하네스 엔지니어링이 뭐예요?

코딩 초심자를 위한 아주 쉬운 풀이

OpenAI 'Harness Engineering' 해설판 · 2026

— 코딩 초심자를 위한 아주 쉬운 풀이 —

원문: OpenAI, "하네스 엔지니어링: 에이전트 우선 세계에서 Codex 활용하기" (2026.2.11, Ryan Lopopolo) 이 문서는 위 글의 핵심 아이디어를 코딩을 막 배우는 사람도 이해할 수 있도록 다시 쓴 해설입니다.

0. 한 줄 요약

"사람은 더 이상 코드를 한 줄도 안 친다. 대신 AI가 코드를 잘 짤 수 있도록 '작업장(=하네스)'을 만들어 준다."

OpenAI의 한 팀은 5개월 동안 사람 손으로 코드를 한 줄도 안 치고, 오직 Codex라는 AI 에이전트만으로 진짜 사용 가능한 소프트웨어 제품을 만들었습니다. 그 과정에서 배운 교훈을 정리한 글이 바로 "하네스 엔지니어링" 입니다.

1. 먼저 이 단어들부터 알고 갑시다

코딩 초심자라면 글을 읽기 전에 단어 몇 개만 알아도 90%는 이해됩니다.

단어	쉬운 뜻
에이전트(Agent)	스스로 판단해서 일하는 AI. 시키면 알아서 코드를 짜고, 테스트하고, 고친다.
Codex	OpenAI가 만든 코딩 전문 에이전트. 이 글의 주인공.
리포지터리(repo)	코드와 문서를 모아 두는 폴더. 흔히 "프로젝트 폴더"라고 보면 된다.
PR (Pull Request)	"이 코드 바꿔도 될까요?" 하고 동료에게 검토를 요청하는 절차.
CI	코드를 올릴 때마다 자동으로 테스트를 돌려 주는 시스템.
린터(Linter)	"이 코드는 규칙에 어긋나" 라고 알려 주는 자동 검사기.
하네스(Harness)	말이나 개에 채우는 끈/장구. 여기서는 AI가 안전하고 잘 일할 수 있도록 둘러싸 주는 환경 전체를 비유.

🐶 비유: 썰매 끄는 개에게 마구(하네스)를 잘 채워 주면 개가 더 빠르고 안전하게 달립니다. AI 에이전트도 똑같아요. AI가 일할 수 있는 환경을 잘 만들어 주는 일, 그게 "하네스 엔지니어링" 입니다.

2. 어떤 실험이었나요?

기간: 약 5개월
사람 인원: 처음엔 3명, 나중에 7명
만든 코드 양: 약 100만 줄
PR 수: 약 1,500개
사람이 직접 친 코드 줄: 0줄
속도: 사람이 손으로 짰을 때보다 약 10배 빠름

진짜 사용자(내부 직원, 외부 알파 테스터)가 매일 쓰는 제품을 이렇게 만들었습니다. 모든 코드(앱 로직, 테스트, 설정, 문서, 모니터링 도구까지) 를 AI가 작성했어요.

3. 그럼 사람은 뭘 했나요?

사람의 역할이 통째로 바뀌었습니다.

옛날 엔지니어:

직접 코드를 친다 → 테스트한다 → 디버깅한다 → 배포한다.

새로운 엔지니어:

목표를 명확히 정의한다 ("이런 기능이 필요해")
AI가 일할 환경을 만든다 (도구, 규칙, 문서)
AI가 만든 결과물을 검증한다 (혹은 다른 AI에게 검증을 시킨다)
AI가 막히면 원인을 찾아 환경을 고쳐 준다

핵심 한 줄: "AI가 코드를 짜도록 시키려면, 사람은 'AI가 잘 일할 수 있는 작업장'을 설계해야 한다."

4. 처음에는 왜 느렸을까?

저자들은 "처음엔 의외로 진도가 안 나갔다"고 말합니다. 이유는 AI가 멍청해서가 아니라, AI가 일할 환경이 안 갖춰져서 였습니다.

비유하자면:

신입 직원에게 "보고서 써 와" 라고만 시키고, 회사 위키도, 문서함 비밀번호도, 양식도 안 알려 준 것과 같습니다.
신입은 똑똑해도 시작을 못 합니다.

그래서 엔지니어들은 매번 이렇게 자문했습니다:

"지금 AI가 못 하는 이유가 뭐지? 어떤 도구나 정보가 빠져 있길래?"

그 빈 곳을 채워 주는 게 바로 그들의 일이 되었습니다.

5. 가장 중요한 교훈: "AI에게 보이는 만큼이 전부다"

이게 이 글에서 가장 중요한 한 문장입니다.

"에이전트 입장에서, 실행 중에 자기 눈에 안 보이는 것은 존재하지 않는 것이다."

무슨 뜻이냐면:

회의에서 결정한 내용이 슬랙(채팅) 에만 있으면? → AI는 모릅니다.
구글 docs 에 적어 둔 설계 문서? → AI는 못 봅니다.
어느 선배의 머릿속에만 있는 노하우? → AI는 0% 모릅니다.

AI가 볼 수 있는 건 오직 코드 폴더(repo) 안에 있는 파일들뿐입니다. 그래서 모든 중요한 정보(설계, 규칙, 문화, 심지어 "이 팀은 이모지를 좋아함" 같은 것까지)를 코드 폴더 안에 글로 적어 둬야 합니다.

👉 핵심 비유: AI는 "3개월 후에 입사한 신입사원" 같은 존재. 그 신입이 못 찾는 정보는, AI도 못 찾습니다.

6. AI에게 매뉴얼을 어떻게 줄까?

처음에 그들은 AGENTS.md 라는 거대한 파일 하나에 모든 규칙을 다 적어 봤습니다. 결과는 실패.

왜 실패했나?

규칙이 너무 많으면 → 규칙이 안 된다

"전부 다 중요해" 라고 하면, AI 입장에선 "아무것도 안 중요해" 가 됩니다.

금방 낡는다

거대한 파일은 아무도 안 고치게 되고, 옛날 규칙들의 무덤이 됩니다.

AI의 "주의력"이 분산된다

문서가 길수록 AI가 진짜 중요한 제약을 놓칩니다.

그래서 어떻게 바꿨나?

"백과사전" 대신 "목차" 로 만들었습니다.

AGENTS.md 는 짧게 (약 100줄). 지도 역할만.
진짜 내용은 docs/ 폴더 안에 종류별로 잘 쪼개서 정리.
design-docs/ (설계 결정)
exec-plans/ (실행 계획)
product-specs/ (제품 사양)
references/ (참고 자료)
등등...
그리고 이 문서들이 낡지 않게 정리하는 일조차 AI(doc-gardening agent)에게 맡깁니다.

7. AI가 "보고 만질 수 있게" 만들기

코드만 짜는 게 아니라, AI가 앱을 직접 실행하고, 화면을 보고, 로그를 읽을 수 있게 환경을 꾸몄습니다.

AI가 가진 능력	어떻게 가능해졌나
앱을 띄워서 직접 써 보기	작업마다 격리된 앱 인스턴스를 자동으로 부팅
화면 캡처하고 클릭하기	Chrome DevTools 와 연결
로그/지표 읽기	로컬 모니터링 스택을 AI에게 노출, LogQL/PromQL 로 쿼리 가능
버그 재현하고 수정 검증	위 도구들의 조합

덕분에 AI는 사람처럼 "어? 이거 버그네 → 재현해 보기 → 고치기 → 다시 실행해서 잘 됐는지 확인" 을 스스로 합니다.

한 번에 6시간 이상(주로 사람이 자는 동안) AI가 혼자 한 가지 일에 매달리는 경우도 흔합니다.

8. 규칙은 글이 아니라 "검사기"로

문서로 "이렇게 짜 주세요" 라고 적어 두는 것만으로는 일관성이 안 지켜집니다. 그래서 규칙을 코드로 만들어 자동 검사 합니다.

각 비즈니스 영역은 정해진 층(layer) 순서로만 코드가 흐르게 합니다.
예: Types → Config → Repo → Service → Runtime → UI
이 순서를 어기면? 자동 린터가 잡아 냅니다.
린터의 에러 메시지에는 고치는 방법까지 적어 둡니다 → AI가 그걸 읽고 스스로 고침.

💡 비유: 사람한테는 "이 규칙 좀 지나치다" 싶은 자동 검사도, AI한테는 매우 효과적입니다. 한 번 만들어 두면 모든 코드에, 매번, 자동으로 적용되니까요.

핵심: "중앙에서 경계는 엄격하게, 그 안에서는 자유롭게."

9. 처리량이 많아지니 "PR 문화"도 바뀌었다

옛날 개발 관습 중 일부는 AI 시대에 오히려 방해가 됩니다.

옛 관습	새 관습
PR 하나를 며칠씩 신중히 검토	PR 수명이 매우 짧음
테스트 깜빡임이 있으면 무한 차단	보통은 그냥 다시 돌려서 해결
사람이 모든 PR 검토	거의 모든 검토를 다른 AI에게 위임

이유는 단순합니다: AI는 빠르고, 사람의 주의력은 부족합니다. 그래서 고치는 비용은 싸고, 기다리는 비용은 비쌉니다.

(주의: 이건 처리량이 매우 많은 환경에만 맞는 얘기. 일반 팀에선 다를 수 있음.)

10. AI가 한 번의 명령으로 할 수 있는 일

이제는 사람이 한 마디만 던지면, AI가 다음을 혼자서 처리합니다.

현재 코드 상태를 살펴본다
보고된 버그를 재현해 본다
실패 장면을 동영상으로 녹화한다
원인을 찾아 수정한다
앱을 직접 실행해 수정이 됐는지 확인한다
해결 장면을 동영상으로 녹화한다
PR(코드 변경 요청)을 연다
리뷰 코멘트에 답한다
빌드가 깨지면 다시 고친다
판단이 필요한 부분만 사람에게 물어본다
통과되면 스스로 코드를 합친다

사람의 개입은 진짜 판단이 필요한 순간에만 일어납니다.

11. 코드의 "쓰레기 청소"도 자동화

AI가 자율적으로 일하면 새로운 문제가 생깁니다.

AI는 "이미 있는 패턴을 따라 한다." 그래서 나쁜 패턴이 한 번 들어가면 점점 퍼집니다.

이걸 옛날엔 매주 금요일에 사람이 한 주의 20%를 써서 청소했습니다. 당연히 한계가 옴.

해결책: "황금 원칙(golden rules)" 을 코드로 만들어, AI 백그라운드 청소부가 매일 자동으로 검사 → 작은 리팩터링 PR을 자동으로 열고 자동 병합.

비유: "기술 부채는 고금리 대출이다." 한 번에 갚으면 너무 아프니까, 매일 조금씩 자동으로 갚는 시스템을 만든 거죠.

12. 아직도 모르는 것

저자도 솔직히 인정합니다. 모든 게 해결된 게 아닙니다.

AI가 만든 시스템이 수년에 걸쳐 일관성을 유지할 수 있을지는 아직 모름.
사람의 판단이 정확히 어디에서 가장 큰 가치를 내는지도 계속 배우는 중.
AI 모델이 더 똑똑해지면 이 방식 자체가 또 바뀔 것.

다만 분명해진 한 가지가 있습니다:

"소프트웨어를 만드는 데 여전히 규율이 필요하다. 다만 그 규율은 코드보다는 '스캐폴딩(받침대)'에서 더 많이 드러난다."

13. 코딩 초심자를 위한 5문장 정리

AI 에이전트(Codex 같은) 는 이제 코드를 직접 잘 짭니다.
그래서 사람의 일은 "코드 작성" 에서 "AI가 잘 일할 환경 만들기" 로 바뀌고 있어요.
AI가 일할 환경 = 도구 + 규칙 + 문서 + 자동 검사 + 피드백 루프 = 하네스(Harness) 입니다.
가장 중요한 원칙: "AI 눈에 안 보이는 정보는 없는 것과 같다." → 모든 중요한 걸 코드 폴더 안에 글로 남기세요.
AI는 빠르니까, 사람은 검토와 판단, 환경 설계에 집중하세요. 막히면 "AI가 게으르다"고 탓하지 말고, "내 환경에서 뭐가 빠졌나?" 를 물어 보세요.

14. 그래서 나(초심자)는 뭘 해야 하나요?

만약 여러분이 코딩을 막 배우는 사람이라면:

✅ README / 문서를 잘 쓰는 연습을 하세요. AI 시대엔 "글로 잘 정리하는 능력"이 무기가 됩니다.
✅ 폴더 구조와 파일 이름을 일관성 있게 짓는 연습을 하세요. AI도 사람도 길을 잃지 않습니다.
✅ 테스트 코드를 짜는 법을 익혀 두세요. AI가 만든 코드를 검증할 줄 알아야 합니다.
✅ "내가 무엇을 원하는지 명확히 글로 쓰는 능력" 을 키우세요. 그게 곧 프롬프트 능력입니다.
✅ AI가 막혔을 때 "환경을 고쳐 주는 사람" 이 되겠다고 마음먹으세요. 그게 미래의 엔지니어입니다.

📖 원문(영문/한국어): https://openai.com/ko-KR/index/harness-engineering/ 작성자: Ryan Lopopolo (OpenAI 기술 스태프) 본 해설본은 코딩 입문자를 위한 재구성판입니다.