08 레퍼런스 비교 Markdown

Codex CLI vs ai-rules — 비교 분석

OpenAI Codex CLI의 제품 내장 스킬 체계와 ai-rules 거버넌스 메타 레이어의 강제 메커니즘 비교

Source: src/content/docs/codex-vs-ai-rules-comparison.md
Order: 65

한눈에 보기

OpenAI 공식 코딩 CLI(openai/codex)가 자기 코드베이스를 운영하는 방식과, ai-rules의 규칙 생성·강제 체계를 11개 축으로 비교한 연구입니다.

핵심 질문: 제품에 내장된 스킬 체계와 메타 거버넌스 레이어는 서로 무엇을 배울 수 있는가?
읽는 대상: 에이전트 거버넌스 설계 패턴을 비교하려는 사람
연결 문서: Reference Comparison, ECC vs ai-rules 평가, Hermes vs ai-rules

작성일: 2026-04-30 분석 대상:

Codex CLI (openai/codex) — OpenAI 공식 AI 코딩 CLI. Rust(codex-rs) + TypeScript(codex-cli) 모노레포

ai-rules — 프로젝트별 AI 에이전트 거버넌스 규칙을 생성·배포하는 메타 프레임워크

1. 시스템 목적 및 범위

항목	Codex CLI	ai-rules
핵심 목적	AI가 터미널에서 코드를 작성·수정·실행하는 대화형 CLI	프로젝트마다 `CLAUDE.md` / `AI-RULES.md`를 자동 생성하는 거버넌스 프레임워크
사용자	개발자가 직접 사용하는 CLI 제품	AI 에이전트 자체 + 에이전트를 세팅하는 개발자
산출물	코드 변경, shell 명령 실행, PR 생성	규칙 문서(`CLAUDE.md`), hook 스크립트, skill 파일
언어	Rust (core) + TypeScript (CLI)	Markdown + Shell
빌드 시스템	Bazel + Cargo (`just` 래퍼)	없음 (순수 텍스트 배포)
배포 방식	npm/cargo 패키지	`scripts/sync.mjs`로 대상 프로젝트에 복사

핵심 차이

Codex는 제품 코드베이스 안에 에이전트 스킬을 내장한 구조이고, ai-rules는 에이전트가 따를 규칙 자체를 생성·관리하는 메타 레이어다. Codex의 .codex/ 디렉토리가 ai-rules의 ~/.claude/ 또는 프로젝트 .claude/에 해당한다.

2. 디렉토리 구조 비교

Codex — `.codex/` (에이전트 설정)

.codex/
├── skills/
│   ├── code-review/
│   │   └── SKILL.md          # 오케스트레이터 skill
│   ├── code-review-testing/
│   │   └── SKILL.md
│   ├── code-review-breaking-changes/
│   │   └── SKILL.md
│   ├── code-review-change-size/
│   │   └── SKILL.md
│   ├── code-review-context/
│   │   └── SKILL.md
│   ├── babysit-pr/
│   │   ├── SKILL.md
│   │   └── gh_pr_watch.py    # Python 보조 스크립트
│   ├── codex-pr-body/
│   │   └── SKILL.md
│   ├── codex-bug/
│   │   └── SKILL.md
│   ├── remote-tests/
│   │   └── SKILL.md
│   └── test-tui/
│       └── SKILL.md
└── config.md → docs/config.md # 리다이렉트

ai-rules — `core/` + `~/.claude/` (규칙 생성)

ai-rules/
├── core/
│   ├── 00-critical.md        # 최우선 HARD STOP 규칙
│   ├── 00-identity.md        # 페르소나·소통
│   ├── 01-git.md             # Git 작업 규칙
│   ├── 02-code.md            # 코드 아키텍처
│   ├── 03-security.md        # 보안
│   ├── 04-lifecycle.md       # 작업 라이프사이클
│   ├── 05-responses.md       # 응답 형식
│   ├── 07-db.md              # DB 규칙
│   └── 10-subagent-patterns.md  # 서브에이전트 권한
├── extensions/
│   ├── frontend-react.md
│   └── backend-fastapi.md
└── scripts/
    └── sync.mjs              # 프로젝트 배포 스크립트

~/.claude/
├── CLAUDE.md                 # 전역 사용자 설정
├── rules/                    # 자동 학습 규칙 (self-improve)
├── skills/                   # 사용자 정의 스킬
│   └── user-proxy-agent/
│       └── SKILL.md
└── sessions/                 # 세션 핸드오프 파일

3. Skill/Rule 포맷 비교

3.1 Codex SKILL.md 포맷

---
name: code-review
description: Run all code review sub-skills in parallel
---

## Workflow

[Markdown 본문 — 자연어 지시 + 단계별 절차]

YAML frontmatter: name + description 두 필드가 전부
본문: 완전 자유형 Markdown — 순서 목록, 코드 블록, 주의사항
오케스트레이터 패턴: code-review SKILL이 code-review-* 서브스킬을 병렬 서브에이전트로 소환
보조 파일 허용: babysit-pr/gh_pr_watch.py 같은 Python 스크립트를 같은 폴더에 배치

3.2 ai-rules 규칙 포맷

# 01-git — Git 규칙         ← H1이 규칙 ID + 제목
## 에이전트 금지 명령        ← H2가 섹션
| 항목 | 판단 |              ← 표로 구조화
...
### 변명 방지 테이블         ← H3이 세부 패턴

번호 접두사: 00- → 10- 순서가 우선순위를 명시
테이블 중심 구조: 판단 기준을 표로 명시 (텍스트 추론 최소화)
변명 방지 테이블: “에이전트가 내세울 변명 → 실제 올바른 행동” 대조
레이블 시스템: [검증됨], [추론], [차단:위험] 등 신뢰도 분류

3.3 차이 요약

축	Codex SKILL.md	ai-rules core/*.md
목적	”이 작업을 이렇게 수행하라” (절차)	“이 조건에서 이렇게 판단하라” (규칙)
구조	자유 산문 + 단계 목록	테이블 + 판단 트리
우선순위 표현	없음 (호출 순서에 의존)	파일명 번호 (`00 > 01 > 02`)
재사용 단위	스킬 폴더 전체	규칙 파일 단위
학습/진화	수동 편집	`self-improve`로 자동 보강

4. 강제(Enforcement) 메커니즘 비교

4.1 Codex — CI + Python 스크립트

빌드 시스템 강제:

just fmt — 커밋 전 Rust 포매팅 강제
just fix -p <project> — Clippy lint 자동 수정
just bazel-lock-update — Cargo.toml 변경 시 Bazel lockfile 동기화
just write-config-schema — ConfigToml 변경 시 JSON Schema 갱신
cargo insta accept — TUI snapshot 변경 시 시각 확인 필수

CI 기반 강제 (AGENTS.md에서 정의):

- 모듈 크기: 500 LoC 목표, 800 LoC 초과 시 신규 모듈 분리 의무
- 비동기 trait: #[async_trait] 금지, native RPITIT 사용
- UI 변경: insta snapshot 업데이트 필수

자동화 스크립트:

babysit-pr/gh_pr_watch.py — CI 폴링 + 자동 수정 + review thread 해결 (Python)
code-review SKILL — 4개 서브스킬 병렬 실행 후 결과 집계

4.2 ai-rules — Git Hooks + Shell 스크립트

Pre-commit/Pre-push hooks:

guard-branch.sh          # 보호 브랜치 직접 커밋 차단 (exit 2)
guard-secrets.sh         # API 키·토큰 하드코딩 탐지
guard-push-force.sh      # force-push 차단
no-localstorage.sh       # localStorage 사용 탐지
no-env-commit.sh         # .env 파일 git add 차단
code-quality-check.sh    # as any, @ts-ignore 탐지
qa-gate-before-push.sh   # .qa-cycle-passed 없으면 push 차단

lint-staged (pre-commit):

TS 파일: eslint --fix
Python 파일: ruff check --fix + ruff format --check

규칙 기반 강제 (CLAUDE.md):

- Plan Mode: 20줄+, 3파일+ 변경 시 자동 발동
- R2 작업: 확인 문구 재입력 필수
- Convergence Loop: 반복 검증 중 중간 질문 금지

4.3 차이 요약

축	Codex	ai-rules
강제 레이어	빌드 도구(Bazel/Cargo) + CI	Git hooks + Shell 스크립트
언어	Rust 도구체인 / Python	Bash
적용 시점	커밋 후 CI	커밋 전 로컬 gate
자동 수정	`just fmt`, `cargo insta`	`eslint --fix`, `ruff --fix`
위반 시	CI 실패 → PR 차단	`exit 2` → push 차단
복잡도	도구체인 설치 필요	Bash만 있으면 동작

5. 에이전트/서브에이전트 모델 비교

5.1 Codex — 스킬 기반 오케스트레이션

# code-review SKILL.md
Invoke all code-review-* sub-skills as parallel subagents.
Each subagent returns findings with file:line references.

오케스트레이터-워커 패턴: code-review → 4개 서브스킬 병렬 실행
스킬 단위 위임: 각 스킬이 독립된 검증 영역을 담당
결과 집계: 오케스트레이터가 서브스킬 결과를 합산하여 반환
모델 지시: 스킬 설명에 사용 모델을 명시하지 않음 (Claude 기본 설정 사용)

5.2 ai-rules — 역할 기반 권한 분리 (`10-subagent-patterns.md`)

| 역할 | 도구 | 모델 |
|------|------|------|
| planner | Read/Glob/Grep/WebSearch | 기본 |
| builder | 모든 도구 | 기본 |
| investigator | Read/Glob/Grep/Bash (no Edit/Write) | 기본 |
| reviewer | Read/Glob/Grep only | claude-opus-4-6 |
| qa | Read/Glob/Grep/Bash (no Edit/Write) | 기본 |
| security | Read/Glob/Grep only | claude-opus-4-6 |

에이전트 정의 파일 (.claude/agents/{name}.md):

---
name: reviewer
model: claude-opus-4-6
tools:
  - Read
  - Glob
  - Grep
description: 코드 품질·보안 리뷰 전담
---

파이프라인 순서: planner → builder → [investigator] → [qa] → spec-reviewer → code-reviewer → [security]

5.3 차이 요약

축	Codex	ai-rules
위임 단위	스킬(작업 절차)	역할(권한 프로필)
권한 제어	없음 (모델 자율)	도구 화이트리스트 HARD 제한
모델 선택	스킬별 미지정	역할별 명시 (`claude-opus-4-6`)
병렬화	스킬 오케스트레이터에서 명시	`Promise.all` / 병렬 Task 호출
에스컬레이션	스킬이 “사람 도움 필요” 명시	3단계 escalation (L1→L2→L3)

6. PR 워크플로우 비교

6.1 Codex — `babysit-pr` + `codex-pr-body`

babysit-pr (지속형 자동화):

1. PR 생성 직후 시작
2. CI 상태 1분 간격 폴링 (pending 동안)
3. CI 실패 분류:
   - branch-related 실패 → 자동 수정 커밋
   - flaky test → 재실행 요청
4. Review 코멘트 자동 해결
5. PR merged 또는 closed 까지 반복
6. 사람 도움 필요 시에만 종료

codex-pr-body 규칙:

WHY를 WHAT보다 먼저 설명
기존 PR body 이미지 절대 삭제 금지
net change만 서술 (시도했다가 되돌린 것 제외)
Sapling SCM 지원 (sl log --template '{github_pull_request_url}')
Stacked PR에서는 base→head 순증분만 서술

6.2 ai-rules — `auto-push` 모드 + hook 기반

auto-push 파이프라인 (기본 모드):

1. feature 커밋 → push
2. feature → develop PR 자동 생성+병합
3. develop → stg/main PR 자동 생성만 (병합 대기)
4. 사용자 "stg 배포" 명시 시 병합 진행

PR body 규칙 (02-pr-template.md):

## Summary
## Test plan
- [ ] Build passes
- [ ] QA cycle completed

CI 자동 수정: 없음 (bug-fixer 에이전트를 4회 로테이션으로 호출)

6.3 차이 요약

축	Codex (`babysit-pr`)	ai-rules
CI 폴링	1분 간격 자동 폴링 (Python)	없음
자동 수정	PR 열린 동안 무한 루프	bug-fixer 최대 4회
PR body	WHY 우선, Sapling 지원	Summary + Test plan
Stacked PR	지원 (`sl sl`)	미지원
병합 자동화	사람 개입 없이 merged까지	develop까지 자동, stg/main은 명시 필요
종료 조건	merged / closed / 사람 요청	push 성공

7. 자동화 깊이 비교

7.1 Codex의 `babysit-pr` 패턴 — 완전 자율 루프

Codex의 가장 강력한 자동화는 PR을 병합까지 끌고 가는 지속형 자율 루프다:

LOOP:
  poll_ci() → classify_failure() → auto_fix() → commit() → push()
  resolve_review_threads()
  if pr_merged: BREAK
  if needs_human: report() → BREAK
  sleep(60)

이는 “사람 개입 없이 PR 라이프사이클을 완주”하는 것을 목표로 한다.

7.2 ai-rules의 `convergence-loop-no-mid-question` 패턴

ai-rules의 자동화 철학은 유사하나 원칙이 다르다:

RULE: 수렴(CRITICAL=0) 또는 EXHAUSTED까지 사용자 개입 0
BANNED: "계속 진행할까요?" 중간 질문
ALLOWED: 중간 보고 (질문 없이 상태만 보고)
ESCALATION: 5개 에스컬레이션 조건에서만 중단

ai-rules는 루프 자체보다 “루프 중 질문하지 말라”는 원칙을 강조하며, Codex처럼 Python 폴링 스크립트를 제공하지는 않는다.

8. 코드 품질 게이트 비교

8.1 Codex — 변경 크기 + 컨텍스트 크기

code-review-change-size:

총 800줄 초과 → 분리 필수
복잡 로직 500줄 초과 → 분리 필수
초과 시 staging(분리 PR) 제안

code-review-context:

Context 아이템당 10K 토큰 하드 캡
1K 토큰 초과 → P0 플래그
무한 증가 Context 금지
모든 fragment → ContextualUserFragment trait 구현 의무

AGENTS.md의 모듈 크기 규칙:

Target: 500 LoC (테스트 제외)
Hard limit: 800 LoC → 새 모듈로 분리

8.2 ai-rules — 파일 크기 + 토큰 예산

02-code.md:

컴포넌트 200줄 이하
비슷한 코드 3줄 이하 추상화 금지
과도한 엔지니어링 금지

04-lifecycle.md:

1000줄+ diff → 경고
토큰 예산 초과 → L3 직행 (에스컬레이션)

context-compression-pipeline.md (rules/):

10K 토큰 초과 시 SemanticDedup + DiffCrunch 압축
0 LLM 추론 비용으로 15~82% 압축

8.3 차이

축	Codex	ai-rules
모듈 크기	500/800 LoC (Rust)	200줄 (컴포넌트)
컨텍스트 캡	10K 토큰/아이템	토큰 예산 yaml 파라미터
압축	없음 (분리로 해결)	claw-compactor 파이프라인
변경 크기	800줄 gate	1000줄 경고
강제력	CI 리뷰 (SOFT)	HARD 레이어 없음 (경고만)

9. 가역성 분류 시스템

9.1 ai-rules — R0/R1/R2 Tier

R0: 완전 가역 → 자동 실행
R1: 제한적 가역 → 사용자 1줄 경고 + Y/N
R2: 비가역 → 확인 문구 재입력 필수

R2 예시: migrate reset, DROP TABLE, force-push, cross-push, .env 수정

9.2 Codex — 명시적 분류 없음

AGENTS.md와 스킬 파일에 R0/R1/R2 같은 공식 tier는 없다. 대신:

babysit-pr: “사람 도움이 필요하면 멈춘다” (자연어)
codex-bug: “verify / request-info / not-a-bug” 3분류 (진단용)
code-review-breaking-changes: 특정 파일 경로 변경 시 경고

ai-rules의 R-tier 시스템은 Codex에 없는 구조적 안전망이다.

10. 테스트 패턴 비교

10.1 Codex — Rust 테스트 컨벤션

AGENTS.md에서 정의:

- 에이전트 변경: 통합 테스트 필수 (단위 테스트 불충분)
- 위치: core/suite 의 test_codex 유틸리티 사용
- 단위 테스트: 동일 파일 내 *_tests.rs 모듈
- 객체 전체 비교: assert_eq! on full objects (필드별 X)
- pretty_assertions::assert_eq 사용
- TUI 변경: insta snapshot 필수

스냅샷 테스트 워크플로우:

cargo test -p codex-tui
cargo insta pending-snapshots -p codex-tui
cargo insta accept -p codex-tui  # 변경 승인

10.2 ai-rules — QA 사이클 + 브라우저 테스트

qa-cycle: build → type-check → lint → web-qa-tester
web-qa-tester: Chrome DevTools Protocol 기반
3도구 크로스체크: web-qa-tester + agent-browser + expect-cli

강제 증거 파일:

// .qa-evidence.json
{
  "browser_test": { "executed": true, "console_errors": 0 },
  "checks": { "ui_render": "PASS", "mobile_375px": "PASS" },
  "verdict": "PASS"
}

10.3 차이

축	Codex	ai-rules
테스트 종류	단위/통합/스냅샷 (Rust)	브라우저 QA (web)
에이전트 변경	통합 테스트 의무	qa-cycle 의무
시각 확인	insta 스냅샷	스크린샷 + agent-browser
증거 파일	없음	`.qa-cycle-passed`, `.qa-evidence.json`
push gate	CI 통과	`.qa-cycle-passed` 파일 존재 여부

11. 문서화 패턴 비교

11.1 Codex

AGENTS.md — Rust/TUI 코딩 컨벤션 단일 파일 (80+ 항목)
docs/config.md — 설정 문서 (별도 파일)
app-server/README.md — API 문서
변경 시 의무: just write-config-schema, just write-app-server-schema 자동 갱신

11.2 ai-rules

core/*.md — 규칙 분리 파일 (번호 우선순위)
extensions/*.md — 스택별 확장 규칙
docs/reference/*.md — 참조 문서 (이 파일 포함)
~/.claude/rules/ — self-improve 자동 생성 규칙
변경 시 의무: scripts/sync.mjs 로 프로젝트 배포

12. ai-rules가 Codex에서 채택할 수 있는 패턴

12.1 우선순위 HIGH

① `babysit-pr` 등가 스킬

현재 ai-rules에는 PR을 merge까지 자동으로 끌고 가는 메커니즘이 없다. babysit-pr 패턴을 도입하면:

# 제안: ~/.claude/skills/babysit-pr/SKILL.md
# - gh pr view {pr} --json statusCheckRollup 폴링
# - CI 실패 → bug-fixer 자동 호출 (기존 4회 로테이션 재활용)
# - Review 코멘트 → 자동 응답 커밋
# - merge까지 무정지 루프

② `code-review-change-size` 게이트 HARD화

현재 ai-rules의 “1000줄 경고”는 SOFT다. Codex의 800줄 gate를 HARD hook으로:

# 제안: hooks/change-size-gate.sh
DIFF_LINES=$(git diff origin/develop --stat | tail -1 | grep -oP '\d+(?= insertion)')
if [ "${DIFF_LINES:-0}" -gt 800 ]; then
  echo "변경 크기 ${DIFF_LINES}줄 > 800줄 한도. 분리 PR을 검토하세요."
  exit 2
fi

③ Context 크기 하드 캡

Codex의 “아이템당 10K 토큰” 규칙을 ai-rules의 context-compression-pipeline.md에 수치로 추가하고, 이를 트리거로 압축 파이프라인 자동 실행.

12.2 우선순위 MEDIUM

④ `code-review` 오케스트레이터 스킬

현재 ai-rules는 code-reviewer 에이전트를 단일 호출한다. Codex처럼 분야별 서브스킬로 분리하면 병렬 실행이 가능:

code-review (오케스트레이터)
├── code-review-security
├── code-review-types
├── code-review-tests
└── code-review-breaking-changes

⑤ Sapling SCM 지원

Stacked PR 워크플로우 사용 시 codex-pr-body 의 Sapling 패턴 참조.

⑥ `codex-bug` 스타일 이슈 진단 스킬

GitHub 이슈 URL → 자동 분류(verify/request-info/not-a-bug) 스킬 도입.

12.3 우선순위 LOW

⑦ 스냅샷 테스트 도입 (UI 변경 시)

현재 브라우저 스크린샷 기반 시각 확인을 보완하는 snapshot 비교 레이어.

⑧ `argument_comment_lint` 패턴

Rust 한정이나, TypeScript에서도 불투명한 boolean/null 인수에 /* paramName */ 주석 강제하는 린트 규칙 추가 검토.

13. Codex가 ai-rules에서 채택할 수 있는 패턴

13.1 R0/R1/R2 가역성 분류

Codex의 에이전트 스킬에 명시적 risk tier를 부여하면 “자동 실행 vs 사람 확인” 판단이 구조화된다.

13.2 번호 기반 규칙 우선순위

.codex/skills/ 폴더의 스킬 간 충돌 시 해결 기준이 없다. ai-rules의 00-critical > 01-git 같은 번호 우선순위 시스템이 유용할 수 있다.

13.3 세션 핸드오프 파일

장기 세션이나 컨텍스트 압축 후 재개 시 HANDOFF 블록 형식이 Codex에도 도입되면 컨텍스트 연속성이 향상된다.

14. 요약 비교표

차원	Codex CLI	ai-rules
시스템 성격	AI 코딩 CLI 제품	에이전트 거버넌스 메타 프레임워크
규칙 형식	자유형 SKILL.md (절차)	번호 우선순위 규칙 파일 (판단 트리)
강제 레이어	빌드 도구 + CI	Git hooks + Shell
에이전트 모델	스킬 오케스트레이션	역할 기반 권한 분리
PR 자동화	완전 자율 루프 (`babysit-pr`)	auto-push 모드 (develop까지)
가역성 분류	없음	R0/R1/R2 명시
컨텍스트 관리	10K 토큰 하드 캡	압축 파이프라인
테스트 강제	insta 스냅샷 의무	.qa-cycle-passed gate
모듈 크기 게이트	800 LoC HARD (CI)	경고만 (SOFT)
학습/진화	수동 편집	self-improve 자동 보강
Stacked PR	Sapling 지원	미지원
언어	Rust + TypeScript	Markdown + Shell

Source Notes

이 문서는 2026-04-30 기준으로 작성된 비교 연구를 공개용으로 정리한 것입니다. Codex CLI는 공개 저장소 openai/codex, ai-rules는 글로벌/프로젝트 규칙 구조를 기반으로 분석했습니다. Provenance: reference-only (외부 공개 저장소 비교 조사).