Codex로 에이전트 주도 개발 플랫폼을 설계하기

1. Harness Engineering이란 무엇인가

정의

Harness Engineering이란 AI 에이전트 주변에 구조적인 레이어(Layer)를 구축하는 엔지니어링 기법입니다.

Agent = Model + Harness

모델(Model, Codex)은 두뇌이며, **하네스(Harness)**는 그 모델이 실제 업무를 수행할 수 있도록 감싸는 「발판·환경·제어 시스템」 전체를 가리킵니다.

기존 개발 vs Harness Engineering

관점	기존 개발	Harness Engineering
엔지니어의 업무	코드를 작성함	환경을 설계함
...	...	...

왜 필요한가

에이전트가 코드를 작성하는 속도는 인간보다 수십 배 빠릅니다. 그러면 다음 병목 현상은 「인간이 리뷰를 다 할 수 없다」는 문제가 됩니다. 하네스는 그 문제를 자동화로 해결합니다.

2. OpenAI의 실험에서 배울 수 있는 것

실험 개요

기간: 2025년 8월 ~ 2026년 2월 (약 5개월) -
팀: 엔지니어 3~7명 -
결과물: 상용 프로덕트, 약 100만 행의 코드 -
제약: 인간이 작성한 소스 코드 0행 -
PR 수: 약 1,500개 (1인당 하루 평균 3.5개)

타임라인

3. 하네스의 전체 아키텍처 (Architecture)

Step 1 — 리포지토리(Repository) 구조 설계

에이전트가 길을 잃지 않는 리포지토리 구조를 만드는 것이 첫 번째 업무입니다.

권장 디렉토리 구성

my-project/
├── AGENTS.md # 에이전트를 위한 목차 (100행 이내)
├── docs/ # 지식 베이스 (유일한 진실의 원천, Single Source of Truth)
...

왜 모노레포(Monorepo)인가

에이전트는 여러 패키지에 걸친 변경 사항을 한 번의 PR(Pull Request)로 처리할 수 있습니다. 모노레포는 그 전제에 가장 부합하는 구성입니다.

Step 2 — AGENTS.md 작성법

기본 원칙: 목차일 것

AGENTS.md는 「백과사전」이 되어서는 안 됩니다. **목차 (100행 이내)**여야 합니다.

AGENTS.md 템플릿

# AGENTS.md
이 파일은 Codex 에이전트에 대한 작업 지시의 입구입니다.
상세 내용은 모두 docs/ 이하를 참조하십시오.
...

포인트

AGENTS.md에 직접 쓰는 것은 「최우선적이며 짧은 불변 규칙」뿐입니다. 그 외에는 반드시 docs/를 참조하도록 합니다.

Step 3 — 레이어드 아키텍처 (Layered Architecture) 강제

의존성 방향 규칙

OpenAI가 채택한 의존성 레이어의 기본 형태:

화살표 방향 = 허용된 import 방향. 상위 레이어에서 하위 레이어로의 의존성만 허용합니다.

금지 패턴

types가 service를 임포트(import)하는 등, 역방향 의존성은 구조 테스트(Structure Test)가 즉시 탐지합니다.

Step 4 — 커스텀 린터 (Custom Linter) 구현

중요한 설계 사상

에러 메시지에 수정 지시를 포함할 것

에이전트는 에러 메시지를 그대로 컨텍스트(Context)로 읽습니다. 즉, 에러 메시지가 좋으면 에이전트는 자율적으로 수정할 수 있습니다.

나쁜 에러 메시지 vs 좋은 에러 메시지

# ❌ 나쁜 예 (인간용)
Error: Dependency violation detected in packages/service/src/index.ts
# ✅ 좋은 예 (에이전트용)
...

린터 구현 예시 (Node.js)

// tools/linters/check-dependencies.mjs
import { readFileSync, readdirSync } from 'fs';
import { resolve, relative } from 'path';
...

린터가 검사해야 할 항목 목록

카테고리	체크 내용	에러 코드
의존 관계	레이어 위반	DEP-001
로깅	console.log 사용 (구조화된 로깅 (Structured Logging)을 사용할 것)	LOG-001
파일 크기	500행 초과	SIZE-001
명명 규칙	스키마 타입 명명 (XxxSchema 형식)	NAME-001
명명 규칙	서비스 함수 명명 (verbNoun 형식)	NAME-002
타입 안전성	any 사용	TYPE-001

Step 5 — 문서 지식 베이스 구축

docs/ 디렉토리 구성과 역할

quality/scores.md 작성법

품질 점수는 에이전트가 "어디에 집중해야 하는가"를 판단하는 정보원입니다.

# 품질 점수 (2026-02-01 업데이트)
## 도메인별 점수
| 도메인 | 테스트 커버리지 | 타입 안전성 | 문서화 | 종합 |
...

문서의 기계적 검증

문서가 노후화되지 않도록 CI에서 링크 깨짐을 검증합니다.

# .github/workflows/docs-check.yml
name: Docs Check
on: [pull_request]
...

Step 6 — CI/CD 파이프라인 설계

에이전트의 PR 흐름

CI 설정 예시

# .github/workflows/ci.yml
name: CI
on:
...

피드백 속도가 중요

빠른 피드백을 왼쪽으로 배치하라. 에이전트는 에러를 받으면 즉시 재시도하기 때문에, 30초 만에 돌아오는 린터(Linter) 에러는 매우 가치가 있습니다.

Step 7 — 옵저버빌리티 (Observability) 통합

에이전트가 관측할 수 있는 환경 구축

에이전트는 스스로 "동작 확인"을 할 수 없습니다. 그렇기 때문에 메트릭(Metrics), 로그(Logs), 트레이스(Traces)를 정비하여, 에이전트가 이를 읽고 자율적으로 개선할 수 있는 상태를 만들어야 합니다.

에이전트를 위한 옵저버빌리티 활용 프롬프트 예시

다음 조건을 만족하도록 구현을 최적화하세요:
- 메트릭: `service_startup_duration_ms`의 p95가 800ms 이내
- 로그: 기동 시 `{"event": "ready", "duration_ms": <값>}`를 출력
...

구조화된 로깅 강제 (린터 연동)

// ❌ 금지 (린터가 LOG-001 에러를 발생시킴)
console.log('Service started', { duration: 123 });
// ✅ 필수
...

Step 8 — 가비지 컬렉션 (드리프트 모니터링)

코드베이스는 시간이 흐름에 따라 "드리프트 (Drift, 열화/불일치)"가 발생합니다. 이를 방치하면 에이전트가 잘못된 판단을 하기 시작합니다.

드리프트의 종류와 대책

가비지 컬렉션 구현

주간 Codex 에이전트 태스크로 정의합니다.

# docs/execution/gc-runbook.md
## 가비지 컬렉션 (주간)
### 실행 빈도: 매주 월요일
...

인간의 역할: 무엇을 해야 하고 무엇을 하지 말아야 하는가

인간의 희소 자원 (가장 희귀한 자원)

OpenAI의 기사에서 강조한 핵심: 인간의 시간과 주의력이야말로 가장 희귀한 자원입니다.

따라서 인간은 "에이전트가 실수하기 어려운 환경을 설계하는 것"에 시간을 쓰고, "개별 코드를 작성하는 것"에서는 멀어져야 합니다.

흔한 실패 패턴

❌ 패턴 1: AGENTS.md 비대화

문제: 모든 규칙, 예외, 배경을 AGENTS.md에 작성함
결과: 파일이 노후화되어 무엇이 유효한지 알 수 없게 됨
컨텍스트 제한(Context Limit)에 걸려 에이전트가 정보를 놓침
...

❌ 패턴 2: 인간용 에러 메시지

문제: "Error: invalid import"와 같이 짧은 에러를 반환함
결과: 에이전트가 무엇을 고쳐야 할지 몰라 시행착오를 반복함
대책: 에러에 "무엇이 잘못되었는지", "어떻게 고치는지", "어디를 참조해야 하는지"를 명시할 것.

❌ 패턴 3: 제약 없는 자유도

❌ 패턴 3: 제약 없는 자유도

문제: 에이전트에게 아키텍처의 자유도를 너무 많이 부여함
결과: 매번 다른 패턴이 생성되어 코드베이스가 발산함
대책: 린터 (Linter)와 구조 테스트 (Structure Test)를 통해 제약을 기계적으로 강제함.
...

❌ 패턴 4: 너무 느린 피드백

문제: CI가 완료될 때까지 30분이 소요됨
결과: 에이전트가 장시간 차단(Block)되어 처리량 (Throughput)이 급감함
대책: 가장 빠른 체크 (린터)를 최우선으로 실행.
...

체크리스트

Phase 1: 기반 설정 (Base Setup)

• 모노레포 (Monorepo) 구조 생성 (packages/ 디렉토리)
• AGENTS.md 생성 (100행 이내, 목차만 포함)
• docs/ 디렉토리 생성 및 INDEX.md 작성
• docs/architecture/overview.md에 레이어 구조 정의

Phase 2: 제약 레이어 (Constraint Layer)

• 의존성 체크 린터 (Dependency Check Linter) 구현
• 파일 크기 체크 린터 (File Size Check Linter) 구현
• 명명 규칙 체크 린터 (Naming Convention Check Linter) 구현
• 구조 테스트 (Structure Test) 구현 (레이어 위반 탐지)
• 에러 메시지에 에이전트용 수정 지시 추가

Phase 3: CI 파이프라인 (CI Pipeline)

• GitHub Actions에서 린터 실행
• CI에 구조 테스트 추가
• CI에 문서 링크 검증 추가
• fail-fast: true 설정

Phase 4: 관측 가능성 및 GC (Observability & GC)

• 구조화된 로깅 (Structured Logging) 도입
• 메트릭 (Metrics) 수집 기반 구축
• 가비지 컬렉션 (Garbage Collection)의 런북 (Runbook)을 docs/에 기술
• 주간 GC 태스크 스케줄링 설정

완료 정의 (Definition of Done)

• 에이전트가 신규 기능을 구현하고, CI가 자동으로 피드백을 보낼 수 있음
• 에이전트가 에러를 수신하고, 자율적으로 수정할 수 있음
• 문서와 코드의 정합성이 CI를 통해 검증됨
• 인간의 리뷰 없이 머지(Merge)할 수 있는 PR이 존재함 (단, 권한은 인간이 보유)

참고 리소스

리소스	URL
OpenAI 원문 기사	https://openai.com/index/harness-engineering/
...