🧩 14. 운영: 하네스 엔지니어링 실전

하네스 엔지니어링의 핵심은 “모델을 더 똑똑하게 쓰는 법”보다 팀이 흔들리지 않게 운영 구조를 설계하는 법에 있습니다. OpenAI가 공개한 Codex 운영 사례를 보면, 사람이 직접 코드를 덜 쓰는 대신 저장소 구조·가드레일·피드백 루프에 더 많은 시간을 투자했을 때 속도와 안정성이 함께 올라갑니다.

실무에서는 역할 전환, 저장소 지식구조, 자동 게이트, 주간 GC 루프처럼 바로 운영에 붙일 수 있는 축부터 적용하는 것이 효과적입니다.

안내: 이 문서는 생성형 AI를 활용해 초안을 작성했고, 공개 근거 문서를 바탕으로 사람이 검토·보정했습니다.

이 글의 근거 자료

• OpenAI Harness engineering (핵심 사례)
  • https://openai.com/index/harness-engineering/
• Codex execution plans (계획 아티팩트 운영)
  • https://cookbook.openai.com/articles/codex_exec_plans
• Prompt engineering guide (지시 명확성)
  • https://platform.openai.com/docs/guides/prompt-engineering
• GitHub Actions (게이트 자동화)
  • https://docs.github.com/en/actions

핵심 요약

• 하네스의 목적은 1회 성공이 아니라 반복 가능한 성공률을 높이는 것이다.
• 저장소는 코드 창고가 아니라 운영 지식의 시스템 오브 레코드가 되어야 한다.
• 규칙은 문장으로 권고하지 말고, 린트/테스트/게이트로 강제해야 오래 간다.
• 자율성을 높일수록 “기능”보다 “관측·복구·GC”가 더 중요해진다.

flowchart LR
    A["목표·범위 고정"] --> B["가드레일 정의\n(금지/허용/승인)"]
    B --> C["에이전트 실행"]
    C --> D["관측 로그 수집"]
    D --> E["자동 게이트 판정"]
    E --> F["피드백 반영\n(프롬프트/테스트)"]
    F --> A

시각화 (Excalidraw)

!

• 원본 편집 파일: Agent/Archive/OpenAI 비즈니스 활용/images/openai-biz-14-harness-loop.excalidraw

🧠 칠판 치트시트

• 사람은 방향을 정하고, 하네스는 반복 품질을 지킨다
• AGENTS는 백과사전이 아니라 “목차”여야 한다
• 로그 없이 복구는 없다, 게이트 없이 일관성은 없다
• 주간 GC는 대청소가 아니라 “매일 작은 부채 상환”이다

OpenAI 사례에서 반드시 가져와야 할 6가지

1) 엔지니어 역할 전환: 코드 작성자 → 환경 설계자

OpenAI 사례의 핵심 메시지는 명확합니다. 속도의 병목은 모델 성능보다 환경의 명확성에서 자주 발생합니다. 에이전트가 실패할 때 사람은 “더 좋은 프롬프트”를 고민하기보다, 어떤 능력이 저장소에 빠졌는지(도구/문서/검증)를 먼저 채워야 합니다.

실무 적용:

• 작업 실패를 “개인 실수”가 아니라 “시스템 누락 신호”로 분류
• 실패 티켓마다 누락 능력 1개를 문서 또는 도구로 환원
• 같은 실패가 2회 반복되면 자동 게이트 후보로 승격

참고: https://openai.com/index/harness-engineering/

2) AGENTS는 목차, 저장소가 시스템 오브 레코드

긴 AGENTS 1개에 다 넣는 방식은 금방 낡습니다. OpenAI 사례처럼 AGENTS를 짧은 목차로 두고, 상세 기준은 docs/로 분리하면 에이전트와 사람 모두 탐색 비용이 줄어듭니다.

실무 적용:

• AGENTS.md: 80~120줄 이내(원칙/링크/금지/승인)
• docs/ops/: runbook, error-codes, execution-plans 분리
• 문서 신선도 체크를 CI로 강제

참고: https://cookbook.openai.com/articles/codex_exec_plans

3) 애플리케이션 자체를 에이전트가 읽을 수 있게 만들기

OpenAI 사례에서 인상적인 부분은 UI/로그/메트릭을 에이전트가 직접 다루게 만든 점입니다. 즉 “코드만 읽는 에이전트”가 아니라 “실행 상태를 보는 에이전트”로 확장한 것입니다.

실무 적용:

• 작업 단위 환경(worktree/dev env) 분리
• DOM 스냅샷/스크린샷/로그 쿼리 경로를 표준화
• PR 템플릿에 재현 증거(스크린샷/로그) 첨부 강제

참고: https://openai.com/index/harness-engineering/

4) 아키텍처와 취향은 “불변식”으로 강제

문서만으로 구조를 지키긴 어렵습니다. OpenAI 사례처럼 경계/의존 방향/로깅 규칙을 린트와 구조 테스트로 자동 판정해야, 속도가 올라가도 구조가 무너지지 않습니다.

실무 적용:

• 의존 방향 위반은 CI 즉시 실패
• 경계 입력 파싱(typed schema) 강제
• 파일 크기/네이밍/로그 형식 같은 취향 규칙도 코드화

참고: https://platform.openai.com/docs/guides/prompt-engineering

5) 처리량이 바뀌면 병합 철학도 바뀐다

에이전트 처리량이 사람 리뷰 처리량을 넘기면, 전통적인 “무거운 선차단” 방식은 병목이 됩니다. 핵심은 무조건 느슨하게 가는 게 아니라, 짧은 PR + 자동 복구 가능한 게이트로 리스크를 관리하는 것입니다.

실무 적용:

• PR 크기 제한(작게 쪼개기)
• flaky 테스트는 장기 블로킹 대신 후속 복구 루프로 처리
• 치명 게이트와 권장 게이트를 분리해 운영

참고: https://docs.github.com/en/actions

6) 엔트로피는 주간 GC로 관리

OpenAI 사례에서 “금요일마다 AI slop 정리”가 확장 불가능하다고 밝힌 부분이 중요합니다. 해법은 회고가 아니라 지속 GC 자동화입니다.

실무 적용:

• golden principles 5개 내외로 명시
• 백그라운드 정리 에이전트(중복/죽은 코드/규칙 위반) 운영
• 저위험 리팩토링은 자동머지 후보로 분리

참고: https://openai.com/index/harness-engineering/

바로 쓰는 코드 2종

A) AGENTS를 “목차”로 유지하는 최소 템플릿

# AGENTS.md (요약본)
- 목표: 반복업무 자동화 안정 운영
- 우선순위: 정확성 > 안정성 > 속도
- 금지: 승인 없는 외부 발송 / 원본 데이터 직접 변형
- 필수 로그: error_code, failed_step, next_action, owner
- 상세 운영 기준: docs/ops/runbook.md
- 장애 코드 사전: docs/ops/error-codes.md
- 실행 계획: docs/ops/execution-plans/

B) Harness 로그 스키마 검사기

# scripts/harness_check.py
import json
import sys
from pathlib import Path
 
REQUIRED = {"error_code", "failed_step", "next_action", "owner"}
 
 
def main(path: str) -> int:
    p = Path(path)
    if not p.exists():
        print(f"[FAIL] log file not found: {path}")
        return 1
 
    missing_count = 0
    for i, line in enumerate(p.read_text(encoding="utf-8").splitlines(), start=1):
        if not line.strip():
            continue
        row = json.loads(line)
        missing = [k for k in REQUIRED if not row.get(k)]
        if missing:
            missing_count += 1
            print(f"[FAIL] line {i}: missing {missing}")
 
    if missing_count:
        print(f"[RESULT] failed rows: {missing_count}")
        return 1
 
    print("[PASS] harness log schema ok")
    return 0
 
 
if __name__ == "__main__":
    sys.exit(main(sys.argv[1]))

30분 도입 루틴 (오늘 바로 적용)

1. 8분: AGENTS를 목차형으로 줄이고 상세 규칙을 docs로 분리
2. 7분: 로그 4필드(error_code, failed_step, next_action, owner) 고정
3. 10분: CI에 harness_check.py + 테스트 연결
4. 5분: GC 큐 1건 등록(중복/미사용/규칙위반 중 택1)

완료 기준:

• 장애 재현 시간 단축
• 동일 원인 장애 재발 감소
• PR 편차(품질/형식) 감소

미니 사례 2개

사례 A) 속도는 빠른데 QA가 병목인 팀

초기엔 PR이 빠르게 늘었지만 사람 QA가 따라가지 못했습니다. 이후 로그/게이트/증거 첨부를 표준화하자, QA가 “탐정”이 아니라 “판정자” 역할로 바뀌어 처리량이 안정화됐습니다.

사례 B) 문서는 많은데 실행이 흔들리는 팀

AGENTS 장문 문서를 쌓아도 실제 행동은 일관되지 않았습니다. AGENTS를 목차형으로 줄이고 docs를 린트로 관리하자, 문서 최신성이 유지되고 에이전트의 재현성이 올라갔습니다.

다음 읽기

• 🧩 11. 운영: 반복업무 자동화 실전
• 🧩 12. 운영: 11편 다음 자동화 꿀팁
• 🧩 13. 운영: 자동화 실패복구·승인흐름 꿀팁
• 🧩15-운영-프롬프트-캐싱-실전