Codex Harness 간단 적용 방법

목적

Codex harness는 "Codex가 이 프로젝트에서 무엇을 읽고, 어떤 순서로 작업하고, 무엇으로 검증할지"를 고정해 주는 최소 작업 틀이다.

즉, 아래 3가지를 빠르게 정리하는 용도다.

1. 작업 범위
2. 작업 규칙
3. 실행/검증 루프

---

가장 단순한 구성

작은 프로젝트에서는 아래 4개만 있어도 충분하다.

• AGENTS.md
• .ai/MEMORY.md
• .ai/PLAN.md
• .ai/RULES.md

필요하면 나중에 추가:

• .ai/CODEX_HARNESS.md
• docs/ARCHITECTURE.md
• .ai/TASKS.md

---

각 파일 역할

AGENTS.md

루트에 두는 진입 문서.

역할:

• Codex가 가장 먼저 읽기 좋은 안내문
• 작업 대상 디렉터리
• 중요한 파일 위치
• 기본 작업 루프 안내

예:

• 이 프로젝트에서 어디를 수정해야 하는지
• 어떤 문서를 먼저 읽어야 하는지
• 어떤 테스트 명령을 돌려야 하는지

---

.ai/MEMORY.md

장기적으로 유지해야 할 사실을 기록.

예:

• 작업 대상 프로젝트
• 참고용 프로젝트
• upstream 기준 커밋
• 중요한 기술적 제약
• 현재 환경 제약
• 절대 잊으면 안 되는 목표

핵심:
자주 바뀌지 않는 정보만 넣는다.

---

.ai/PLAN.md

현재 구현 방향과 작업 포인트를 정리.

예:

• 목표 변경사항
• 코드 핫스팟
• 다음 단계
• 아직 결정되지 않은 설계 이슈

핵심:
작업이 진행되면 갱신되는 문서다.

---

.ai/RULES.md

프로젝트 작업 규칙을 정리.

예:

• 어느 디렉터리만 수정 가능한지
• API 호환을 유지해야 하는지
• 테스트는 어떤 순서로 도는지
• 변경 시 문서를 갱신해야 하는지

핵심:
"무엇을 지켜야 하는가"를 적는다.

---

있으면 좋은 실행 스크립트

Codex는 문서만 있는 것보다 실행 가능한 검증 명령이 있을 때 훨씬 안정적으로 작업한다.

예:

• npm run harness:smoke
• npm run harness:report
• npm test

보통 역할은 이렇다.

harness:smoke

빠른 기본 점검

• 모듈이 불러와지는지
• 핵심 함수가 죽지 않는지
• 최소 주요 시나리오가 통과하는지

harness:report

민감 구간 출력 확인

• 경계 날짜
• 시간대 문제
• 윤년/달력 정책 차이
• 포맷 차이

test

정식 테스트 스위트

---

적용 순서

1. 루트에 AGENTS.md 추가

가장 먼저 Codex가 읽을 문서를 만든다.

최소 포함 내용:

• 작업 대상
• 참고용 디렉터리
• 주요 파일
• 기본 작업 순서

---

2. .ai/ 폴더 생성

숨김 폴더로 AI 컨텍스트를 분리한다.

mkdir -p .ai

3. .ai/MEMORY.md 작성

변하지 않는 사실을 적는다.

예:

• 이 프로젝트의 목적
• upstream 기준
• 작업 범위
• 환경 제약

4. .ai/PLAN.md 작성

지금 당장 해야 할 방향을 적는다.

예:

• 구현 목표
• 수정해야 할 코드 위치
• 다음 작업 순서

5. .ai/RULES.md 작성

작업 수칙을 적는다.

예:

• 수정 허용 범위
• 검증 우선순위
• 문서 업데이트 규칙

6. 가능하면 package.json에 harness 명령 추가

예:

{
  "scripts": {
    "harness:smoke": "node scripts/codex-smoke.cjs",
    "harness:report": "node scripts/codex-report.cjs",
    "test": "jest --runInBand"
  }
}

7. scripts/에 간단한 스모크 스크립트 추가

예:

• 최소 import 확인
• 핵심 함수 1~3개 확인
• 실패 시 exit code 1 반환

추천 작업 루프

Codex에게는 아래 순서를 고정해 두는 게 좋다.

1. AGENTS.md 읽기
2. .ai/MEMORY.md 읽기
3. .ai/RULES.md 읽기
4. .ai/PLAN.md 읽기
5. 코드 수정
6. harness:smoke 실행
7. harness:report 실행
8. 필요 시 전체 테스트 실행

문서 배치 원칙

추천 구조:

project/
├─ AGENTS.md
├─ .ai/
│ ├─ MEMORY.md
│ ├─ PLAN.md
│ └─ RULES.md
├─ docs/
│ └─ ARCHITECTURE.md
├─ scripts/
│ ├─ codex-smoke.cjs
│ └─ codex-report.cjs
└─ package.json

구분 기준:

• .ai/ = Codex 작업 컨텍스트
• docs/ = 사람과 AI가 함께 보는 설계 문서

언제 문서를 더 늘릴까

처음부터 많이 만들 필요는 없다.

다음 경우에만 추가하면 된다.

• docs/ARCHITECTURE.md
  • 구조가 복잡해졌을 때
• .ai/TASKS.md
  • 작업 큐를 계속 이어갈 때
• .ai/CODEX_HARNESS.md
  • 검증 루프가 길어져서 별도 설명이 필요할 때
• docs/ADR-*.md
  • 중요한 설계 결정을 기록할 때

작은 프로젝트 기준 최소 결론

아주 간단히 시작하려면 이것만 해도 된다.

• AGENTS.md
• .ai/MEMORY.md
• .ai/PLAN.md
• .ai/RULES.md
• package.json의 간단한 harness 명령

이 정도면 Codex가 프로젝트를 읽고, 수정하고, 검증하는 기본 루프를 안정적으로 만들 수 있다.