(하네스 엔지니어링 실전) Codex의 Skill 파이프라인으로 재현성을 높이기

최근 개인 개발에서는 Codex로 구현하는 일이 상당히 많아졌습니다.

구현은 빨라집니다. 하지만 매번 같은 품질로 진행된다는 보장은 없습니다.

• 요구사항이 모호한 채로 구현에 들어감
• 테스트는 통과했지만, 의도한 사양과 어긋나 있음
• 몇 주 후에 "왜 이런 판단을 했는지" 알 수 없음

그래서 최근에는 Codex의 Skill을 공정별로 나누어, 요구사항 정리부터 PR 생성까지를 파이프라인(pipeline)으로서 진행하고 있습니다.

목표는 "AI에게 전부 맡기는 것"이 아닙니다.

같은 종류의 태스크를, 같은 확인 순서와 판단 기준으로 진행하기 쉽게 만드는 것입니다.

지금까지는 cursor 하나로 해왔지만, 스마트폰에서는 GPT를 사용하고 있기 때문에, 그럴 바에는 GPT Plus로 전환하여 codex도 사용하는 것이 가성비가 좋다고 생각했습니다. 또한 언젠가는 스마트폰에서 태스크를 실행하고 싶다는 생각도 있어 그 예행연습도 겸하고 있습니다.

다만, github copilot도 병용하여 미세 수정 등을 보완하고 있습니다. (github와의 친화성도 높습니다)

본론입니다. 평소의 개발 플로우를 다음과 같은 Skill로 나누고 있습니다.

이하에서는 프로젝트 고유의 이름이 아닌 역할을 알 수 있는 이름으로 표기합니다.

Skill	역할
task-pipeline	현재 지점을 판단하고, 다음 Skill과 gate를 결정
task-planner	브레인스토밍(벽치기), 요구사항 정리, task document / issue 작성
task-builder	task document에 기반한 구현
backend-test-runner	backend 실행 검증
frontend-screen-checker	브라우저에서의 화면 확인
task-evaluator	사양, diff, 검증 결과를 본 독립 평가
task-release-handoff	commit, push, PR 생성 전의 최종 확인

부모 역할을 하는 task-pipeline은 무엇이든 스스로 실행하는 Skill이 아닙니다.

• 지금은 계획 단계인가
• 구현이 끝나 검증으로 넘어갈 수 있는가
• 검증 결과가 갖춰져 평가해도 되는가
• commit이나 PR 전에 멈춰야 할 문제가 있는가

를 확인하고, 담당 Skill에 넘겨주는 역할을 합니다.

각 태스크에서는 처음에 Markdown 형식의 task document를 만듭니다. GitHub Issue 등으로 관리해도 같은 방식입니다.

남기는 내용은 예를 들어 다음과 같습니다.

• 배경과 목적
• 이번에 할 것 / 하지 않을 것
• 수락 조건 (Acceptance Criteria)
• 브레인스토밍(벽치기) 시 결정한 방침
• 그 시점에서는 보류한 판단
• 구현 내용과 검증 결과
• commit / PR까지 진행되었는지에 대한 상태

상태는 다음과 같이 간단한 형식으로 기록하고 있습니다.

## 파이프라인 상태
- 상태: planned | changed | verified | pushed | pr-opened | blocked
- Backend 검증: pending | pass | fail | gap | not-applicable
...

이하 템플릿입니다. 참고하시기 바랍니다.

# <태스크 타이틀>
## 개요
- 목적:
...

이것이 개인 개발에서는 상당히 편리합니다.

• 새로운 Codex 세션에서도 전제 조건을 다시 읽고 재개할 수 있음
• 자기 자신도 나중에 "왜 이렇게 했는지" 추적할 수 있음
• 브레인스토밍(벽치기) 시의 망설임이나 작은 메모도 남음
• 깔끔한 사양서는 아니지만, 과거 태스크가 잡다한 지식(knowledge)으로서 축적됨

코드만 보면 "무엇을 바꿨는지"는 알 수 있지만, "왜 그 선택을 했는지"는 남기 어렵습니다. task document나 issue가 남음으로써 판단의 이력도 개발 자산이 됩니다.

Skill에는 "무엇을 하는가"뿐만 아니라 "무엇이 갖춰지면 다음으로 넘어가는가"를 적어두었습니다.

전이	gate
계획 -> 구현	목적, 스코프, 수락 조건이 명확함
구현 -> 검증	변경 내용과 영향 범위가 기록됨
검증 -> 평가	필요한 검증이 pass이거나, 리스크를 이해한 gap 상태임
평가 -> release	독립 평가가 PASS임
release -> commit / PR	대상 diff와 전송 내용을 인간이 확인

또한, 다음과 같은 경우에는 멈추도록 하고 있습니다.

• 검증 (Verification)이 실패했을 때
• 검증할 수 없는 항목이 있어 리스크를 아직 수용하지 않았을 때
• 평가 (Evaluation)에서 수정이 필요해졌을 때
• .env, credential, 생성물, 무관한 차분 (diff)이 commit에 섞였을 때
• CI가 실패했을 때

자율적으로 진행하는 범위를 넓힐수록, 정지 조건의 명시가 효과를 발휘합니다.

구현한 Codex에게 그대로 "문제없지?"라고 판단하게 하는 것만으로는 불안함이 남습니다.

그렇기 때문에 역할을 나누고 있습니다.

• task-builder: task document에 따라 변경 수행
• backend-test-runner / frontend-screen-checker: 동작의 증거를 수집
• task-evaluator: 수락 조건 (Acceptance Criteria), 사양 (Specification), diff, 검증 결과를 대조
• task-release-handoff: 공개해도 좋은 차분만을 확인

테스트가 통과하는 것과, 만들어야 할 것을 올바르게 만든 것은 별개입니다.

• 사양을 잘못 읽지는 않았는가
• UI 변경임에도 화면 확인이 누락되지 않았는가
• 문서 업데이트가 필요하지 않은가
• 무관한 파일이 commit에 포함되지 않았는가

위 사항들을 별도 공정에서 확인함으로써, PR까지 진행할지에 대한 판단이 안정됩니다.

파이프라인을 만들어도 Skill의 지시문이 모호하다면, 매번 똑같이 동작하지 않습니다.

Skill 조정에서는 mizchi 님의 프롬프트의 재현성을 AI에게 자동 튜닝시키는 방법을 참고하고 있습니다.

생각은 간단합니다.

• Skill을 작성한 본인의 맥락을 모르는 AI에게, 실제 시나리오로 실행하게 한다
• "불명확했던 점", "지시가 없어 재량으로 보완한 점"을 보고하게 한다
• 전형적인 케이스뿐만 아니라, 엣지 케이스 (Edge Case)에서도 테스트한다
• 지적된 모호함을 Skill에 다시 반영하고, 다른 새로운 실행을 통해 재평가한다

Skill을 작성한 직후에는 자신의 머릿속에 있는 전제를 보완하며 읽게 됩니다. 다른 컨텍스트에서 실행하면, 의외로 판단 기준의 누락이나 모호한 표현이 발견됩니다.

이 방법을 도입함으로써, 파이프라인의 재현성을 '자신의 감각'에만 의존하는 것이 아니라 실행 결과로부터 개선하기 쉬워집니다.

예를 들어 최근에는 Andrej Karpathy 님의 Skill 설계 사례를 참고하며, 각 Skill의 책무와 정지 조건을 조금씩 튜닝하고 있습니다.

GitHub 작업에서는 환경에 따라 이용 가능한 CLI나 커넥터 (Connector)가 다를 수 있습니다.

따라서 특정 명령어를 필수 조건으로 삼지 않고, 다음과 같이 생각하고 있습니다.

• commit이나 push는 이용 가능한 안전한 수단으로 진행한다
• PR 생성이나 CI 확인을 할 수 없는 경우에는, 마지막으로 안전하게 완료된 지점에서 멈춘다
• 무엇이 부족해서 멈췄는지를 task document에 남긴다

실행 환경의 차이로 모든 공정이 멈추는 것보다, 어디까지 안전하게 완료되었는지가 명확한 편이 다루기 쉽습니다.

이 스타일은 Harness Engineering의 작은 실천 사례라고 부를 수 있다고 생각합니다.

OpenAI는 Harness engineering: leveraging Codex in an agent-first world에서, agent가 신뢰할 수 있는 업무를 수행할 수 있도록 환경, 의도, 피드백 루프를 설계하는 것의 중요성을 설명하고 있습니다.

개인 개발의 Skill 파이프라인은 대규모 자율 개발 기반은 아닙니다. 그럼에도 하고 있는 일은 같은 방향입니다.

• 작업을 공정으로 분해한다
• 상태와 판단을 task document / issue에 남긴다
• 검증과 평가의 루프를 만든다
• Skill 자체도 실행 결과로부터 개선한다
• 위험한 조작 전에는 멈출 수 있도록 한다

Codex의 성능에만 기대는 것이 아니라, Codex가 재현성을 가지고 일할 수 있는 공정을 만드는 것이 최근 개인 개발에서 의식하고 있는 점입니다.

Codex의 Skill 파이프라인을 만든 이후, 개인 개발에서 의식하는 바가 조금 변했습니다.

• 구현을 빠르게 하는 것뿐만 아니라, 판단 근거를 남긴다
• 한 번의 좋은 결과가 아니라, 다른 태스크에서도 재현 가능한 형태로 만든다
• 실패했을 때 주의해서 사용하는 것이 아니라, Skill이나 게이트 (Gate)를 업데이트한다
• 과거의 task document / issue를 잡다한 것이라도 사용할 수 있는 지식으로 축적한다

개인 개발에서는 공정을 정비하는 작업도 자신의 프로덕트 개발의 일부입니다.

Codex가 코드를 쓰는 시간을 줄여준다면, 나는 Codex가 안정적으로 업무를 진행할 수 있는 메커니즘을 키운다. 지금은 그 균형이 꽤 잘 맞고 있습니다.