이슈 하나가 PR이 되기까지: 코덱스로 하네스와 '소프트웨어 팩토리' 직접 만들기

이슈 하나를 올려 뒀더니, 코덱스가 테스트부터 쓰고, 고치고, 고치기 전과 후 화면 사진까지 붙여서 PR을 열어 놨습니다. 만 원을 세 명이 나누면 받은 돈 합계가 9,999원이 나오는 버그였습니다. 사람이 한 일은 명령 한 줄이었습니다.

이렇게 이슈가 들어오면 분류하고, 고치고, 증명해서 PR까지 보내는 줄을 이 글에서는 소프트웨어 팩토리라고 부르겠습니다. OpenAI가 쓴 용어는 아니고, 이 글에서 정한 이름입니다.

이 글에서는 다음을 차례로 봅니다.

출발점: OpenAI의 하네스 엔지니어링 글
하네스와 팩토리, 두 층 구조
하네스 입히기와 두 번의 시험
팩토리 돌리기: 분류 → 수정 → 스펙 → 자동 실행
가져갈 것과 한계

숫자 읽는 법. [공식 문서] 는 OpenAI가 직접 낸 글과 Codex 문서, [직접 측정] 은 저희가 직접 돌려 본 값입니다. 실습은 2026년 10월 13일, Codex CLI 0.162.1, 모델 GPT-6.1-Sol(추론 medium), macOS에서 했고, 각 단계는 한 번씩 돌렸습니다.

1. 출발점: OpenAI의 하네스 엔지니어링 글

2026년 2월 OpenAI가 엔지니어링 글 「Harness engineering: leveraging Codex in an agent-first world」를 올렸습니다. 하네스(harness) 는 원래 말에 채우는 마구입니다. 여기서는 AI 에이전트가 제멋대로 가지 않도록 둘러 두는 규칙과 장치를 뜻합니다.

OpenAI의 한 팀이 5개월 동안, 사람이 직접 쓴 코드 0줄로 제품 하나를 만들었습니다. 코드는 약 100만 줄, 열고 머지한 PR은 약 1,500개입니다 [공식 문서].
그 팀 엔지니어의 일은 코드를 쓰는 게 아니라 코덱스가 일할 환경을 설계하고, 하려는 일을 정리하고, 결과가 돌아오는 고리를 만드는 것이었습니다. 글은 이걸 "Humans steer. Agents execute." 로 줄입니다. 사람은 방향을 잡고, 에이전트가 실행한다는 뜻입니다 [공식 문서].

눈에 띈 교훈은 두 가지입니다.

천 쪽짜리 설명서 말고 지도를 줘라. AGENTS.md(코덱스가 저장소에서 가장 먼저 읽는 안내 파일)를 백과사전이 아니라 목차로 쓰라는 얘기입니다.
오류 메시지에 고치는 방법을 적어라. 규칙을 어기면 어디를 어떻게 고치라는 방법까지 메시지에 넣어, 에이전트가 읽고 바로 고치게 합니다.

단서도 있습니다. 한 번의 지시로 처음부터 끝까지 해내는 건 그 저장소의 구조와 도구에 크게 기대고 있어서, 비슷한 투자 없이 다른 곳에서도 된다고 가정하면 안 된다고 적었습니다 [공식 문서]. 그래서 작은 앱 하나에 같은 종류의 투자를 직접 해 봤습니다.

2. 하네스와 팩토리, 두 층 구조

아래층, 하네스. 코덱스 한 번의 작업이 정직하게 끝나도록 붙여 두는 장치입니다. 규칙을 적은 AGENTS.md, 테스트를 못 건드리게 막는 가드, 끝내기 직전에 테스트를 돌리는 검증이 여기 들어갑니다.
위층, 팩토리. 이슈가 들어오면 분류하고, 이슈마다 따로 떼어 둔 작업 공간에서 고치고, 리뷰어를 거쳐 PR로 내보냅니다. 머지는 사람이 합니다.

실습 앱은 총액과 인원을 넣으면 1인당 금액을 계산하는 N빵 계산기입니다. 이슈는 세 개를 올려 뒀습니다.

합계가 안 맞는다는 버그
술 마신 사람만 더 내게 해 달라는 기능 요청
뭐가 문제인지 알 수 없는 짧은 제보

저장소에 넣은 팩토리 파일은 다섯 개입니다. 스킬 세 개(분류·수정·스펙), 리뷰어 하나, 실행 스크립트 하나입니다.

스킬은 .agents/skills/<이름>/SKILL.md에 적는 작업 절차서입니다. $이름으로 불러 씁니다 [공식 문서].
리뷰어는 서브에이전트, 즉 코덱스가 일하는 도중 따로 띄우는 또 하나의 코덱스입니다. .codex/agents/ 아래 TOML 파일 하나로 정의했고, 코드를 고치지 않고 판정만 하도록 읽기 전용으로 두었습니다. 문서에는 이 형식이 바뀔 수 있다고 적혀 있습니다 [공식 문서].
AGENTS.md는 짧게 썼습니다. 격리 → 구현 → 증명 → 출하 네 단계만 적고, 자세한 절차는 스킬에 있다고 가리키기만 합니다. 앞의 "목차" 원칙 그대로입니다.

3. 하네스 입히기와 두 번의 시험

하네스는 공개 저장소 codex-harness-kit(0.2.1)으로 입혔습니다. 코덱스의 훅으로 만든 키트입니다. 훅은 코덱스가 도구를 쓰기 직전(PreToolUse)이나 일을 끝내기 직전(Stop)에 내 스크립트를 끼워 넣는 기능입니다 [공식 문서].

설치 스크립트를 한 번 돌리면 훅 세 개(UserPromptSubmit·PreToolUse·Stop)와 설정 파일이 들어옵니다. doctor로 점검하면 가드가 실제로 막는지까지 확인합니다 [직접 측정].
기본 설정은 test/ 폴더를 통째로 보호합니다. 그런데 팩토리에서는 코덱스가 재현 테스트(버그를 다시 일으켜 실패하는 걸 보여 주는 테스트)를 새로 써야 합니다. 그래서 네 줄을 더했습니다. 리뷰어·스킬·실행 스크립트도 못 고치게 잠그고, 재현 테스트가 들어갈 test/regression/만 열어 뒀습니다.
코덱스는 사람이 검토하고 신뢰하기 전에는 새 훅을 돌리지 않습니다 [공식 문서]. 처음 열면 "Hooks need review: 3 hooks" 창이 뜨고, 검토 화면에서 신뢰해야 켜집니다.

이제 두 번 시험했습니다 [직접 측정].

시험 1. 테스트를 지워 달라고 하기. "인원이 0명이면 오류" 테스트를 지워 달라고 했습니다. 훅이 막았습니다("Blocked by hook"). 테스트는 사람이 정한 기준이니 바꾸려면 사람이 하라는 메시지가 코덱스에게 돌아갔고, 코덱스는 멈추고 이유를 보고했습니다. 파일은 바뀌지 않았습니다.

시험 2. 테스트는 돌리지 말라고 하기. 인원 검사 조건을 느슨하게 고치라고 하면서 "테스트는 돌리지 마"라고 덧붙였습니다. 코덱스는 말한 대로 고치고 끝내려 했습니다. 그런데 끝내기 직전 Stop 훅이 테스트를 돌렸고, 실패했습니다. 그 실패가 코덱스에게 돌아가자 조건을 원래대로 되돌렸고, 테스트 3개가 통과한 뒤에야 끝났습니다. 저장소에 남은 변경은 없었습니다.

4. 팩토리 돌리기

분류

scripts/factory는 코덱스를 열면서 스킬 이름을 대신 입력해 주는 짧은 스크립트입니다. 분류 스킬은 이슈 세 개를 읽고, 입력값으로 코드를 직접 불러서 증상이 재현되는지 보고 나눕니다 [직접 측정].

이슈	판단	근거	라벨
#1 합계가 9,999원	바로 수정	`splitBill(10000, 3)`을 불러 합계 9,999원 재현	`factory:fix`
#2 술값 따로	스펙 먼저	새 기능	`factory:spec`, `needs-human`
#3 짧은 제보	정보 부족	재현할 값이 없음	`needs-info` + 질문 댓글

코덱스가 분류에 쓴 시간은 46초였습니다.

수정: 이슈 #1

scripts/factory fix 1처럼 이슈 번호만 줍니다. 스크립트가 이 이슈만을 위한 워크트리를 만들고 그 안에서 코덱스를 엽니다. 워크트리는 같은 저장소를 다른 폴더에 하나 더 꺼내 둔 작업 공간이라, 이슈 여러 개가 동시에 돌아도 서로 파일을 덮어쓰지 않습니다.

코덱스는 순서대로 움직였습니다 [직접 측정].

이슈를 읽고, 재현 테스트를 먼저 써서 실패하는 걸 확인합니다.
고치기 전 화면을 찍습니다.
코드를 고치고, 고친 뒤 화면을 다시 찍습니다.
리뷰어 서브에이전트(factory_reviewer)를 띄워 변경 범위, 테스트, 전후 화면, 경계값을 확인하게 하고 PASS를 받습니다.
PASS를 받은 뒤에야 커밋하고 푸시해서 PR을 엽니다.

여기까지 2분 14초가 걸렸습니다.

원인은 1인당 금액을 내림하고 남은 1원을 아무에게도 주지 않은 것이었습니다. 이제 앞 번호부터 1원씩 더 내서 한 명은 3,334원, 두 명은 3,333원, 합계가 딱 10,000원입니다.

PR #4에는 왜 고쳤는지, 원인, 바꾼 내용, 전후 화면이 붙어 있습니다. 바뀐 파일은 네 개(증거 사진 2장, src/split.js, test/regression/issue-1.test.js)이고 +26 −2줄, 테스트 6개가 통과했습니다.

맨 아래에는 리뷰어 판정이 PASS로 적혀 있습니다. 머지는 하지 않았습니다. 그건 사람이 정합니다.

스펙 먼저: 이슈 #2

새 기능은 코드 대신 스펙(무엇을 어떻게 만들지 적은 문서)부터 씁니다. 2분 39초 만에 draft PR이 열렸고, 스펙 문서 하나만 들어 있었습니다 [직접 측정].

PR #5는 사람이 정할 것을 따로 뽑아 줍니다. 금액을 어떻게 입력할지, 술 마신 사람을 어떻게 지정할지, 남는 몇 원은 누가 낼지 같은 것들입니다. 예시 계산도 있습니다. 12만 원을 다섯 명이 나누고 그중 3만 원이 술값이며 두 명이 마셨다면, 마신 두 사람은 3만 3,000원, 나머지 세 사람은 1만 8,000원입니다(33,000×2 + 18,000×3 = 120,000). 이 방향이 맞는지는 사람이 정합니다.

자동 실행: 이슈 #3

세 번째 이슈에는 질문 댓글만 달아 뒀었습니다. 이슈를 올린 사람이 값을 알려 줬다고 하고, 이번에는 같은 분류 스킬을 codex exec로 돌렸습니다. codex exec는 화면 없이 코덱스를 한 번 실행하고 끝나는 모드라서, 정해진 시간에 돌리는 자동화나 CI에 씁니다. 기본 샌드박스는 읽기 전용입니다 [공식 문서].

코덱스는 그 값으로 직접 돌려 보고 첫 번째 이슈와 원인이 같다고 판단했습니다. 새로 고치지 않고, 이슈 #3을 factory:fix로 다시 분류한 뒤 열려 있는 PR #4로 연결하는 댓글만 남겼습니다. 새 PR은 만들지 않았습니다 [직접 측정].

5. 가져갈 것과 한계

하네스에서 가져갈 것 세 가지

AGENTS.md는 목차처럼 짧게 씁니다.
테스트는 사람이 정한 기준으로 지키고, 에이전트에게는 재현 테스트를 쓸 자리만 열어 줍니다.
끝내기 직전에 테스트를 돌리는 훅을 겁니다.

팩토리에서 가져갈 것 두 가지

이슈마다 워크트리 하나.
고치는 쪽과 판정하는 쪽을 나누는 리뷰어.

한계

이 실습은 일회용 연습 저장소라 샌드박스와 승인 질문을 끄고 돌렸습니다. 훅은 테스트와 설정을 지키는 장치이지 샌드박스가 아닙니다. 실제 프로젝트에서는 컨테이너나 승인 규칙과 함께 쓰세요.
시간(46초, 2분 14초, 2분 39초)은 이 저장소에서 각 한 번 돌린 값입니다. 모델·버전·저장소가 바뀌면 달라집니다.
macOS에서만 확인했습니다. Windows에서 훅이 같은 식으로 동작하는지는 보지 않았습니다.
서브에이전트 설정 형식은 문서에 "바뀔 수 있다"고 적혀 있습니다.
OpenAI 글의 단서처럼, 이 방식은 구조와 도구에 투자한 저장소에서 잘 됩니다. 테스트가 없는 프로젝트라면 테스트부터 갖추는 게 먼저입니다.

먼저 AGENTS.md와 테스트가 있는 프로젝트에서 이슈 하나만 흘려 보세요.