Spec-Driven Development를 위해 Codex를 설정하는 방법

Source: Dev.to

내게 효과적이었던 전환은 간단했습니다: 승인된 사양이 없으면 → 코드 변경도 없음.
아래는 spec‑driven‑template‑codex의 init.md 청사진을 기반으로 한 실제 설정 흐름이며, 기능을 구축할 때 일상적으로 사용하는 방법입니다.

워크플로우 다이어그램

User request
   |
   v
spec‑architect drafts task spec
   |
   v
human approval gate
   |
   v
agent‑router picks specialist
   |
   v
specialist implements inside scope_in only
   |
   v
validation (npm run verify)
   |
   v
commit with spec deletion + evidence
   |
   v
full‑branch PR review

Note: This ordering matters more than any individual prompt trick.
참고: 이 순서는 개별 프롬프트 트릭보다 더 중요합니다.

여섯 가지 기본 레이어

내 init.md는 설정을 명시적인 작업으로 나눈다. 실제로는 이를 여섯 개의 기본 레이어로 취급한다.

1. CODEX.md + AGENTS.md

두 개의 최상위 파일을 유지한다:

두 파일 모두 직접적이며 협상 불가이다. 규칙이 선택 사항이면 그냥 삭제한다.

2. .codex/WORKFLOW.md

“이 파일은 행동이 암시되는 것이 아니라 인코딩되는 곳이다.”

핵심 블록:

first principle: never implement without an approved spec
spec‑first gate on every request
architect mode when no spec exists
mandatory sub‑agent chain (spec‑architect → agent‑router → specialist)
model enforcement (model + model_reasoning_effort on every agent)
evidence gate tied to deleted specs

사용하는 파일:

• .codex/STRATEGY.md – 안정적인 “왜”.
• .codex/WORKFLOW.md – 실행 가능한 “어떻게”.

3. .codex/agents/*.toml

책임을 분리하여 하나의 에이전트가 모든 결정을 끝‑끝까지 내리지 않도록 한다.

핵심 에이전트

모델 고정 – 모든 에이전트 파일은 model과 model_reasoning_effort를 모두 고정한다. 상속은 절대 허용하지 않는다.

전형적인 패턴

4. 작업 사양 파일

각 작업은 TASK-YYYY-MM-DD-###.spec.md 형태이며 엄격한 front‑matter를 가진다:

goal: 
scope_in: 
scope_out: 

constraints: 
validation: 
status: draft | approved | in_progress | done | blocked
collaborators: 
design_flags: 

핵심은 관료주의가 아니라, 편집을 시작하기 전에 명확성을 강제하는 것이다.

작업은 약 30 분 안에 끝낼 수 있을 정도로 작게 유지한다. 만약 그렇게 정확히 설명할 수 없으면 복잡성을 숨기고 있는 것이다.

5. 가드 훅

.codex/hooks/workflow-guard.sh 를 추가하고 **.codex/hooks.json**(또는 .codex/config.toml 안에 인라인)으로 연결한다. 가드는 품질을 은밀히 해치는 패턴을 차단한다:

• git commit --no-verify
• 광범위 스테이징(git add .)
• 스테이징된 사양 삭제 없이 커밋 시도
• 필수 에이전트 파일 누락
• model 또는 model_reasoning_effort 필드 누락
• 삭제된 사양에 대한 증거 JSON 누락 또는 잘못된 형식
• 증거 모델 값과 고정된 에이전트 모델 간 불일치

정책은 명령 실행 시 강제되며, 수동으로 기억하지 않는다.

6. 증거 추적

완료된 각 사양에 대해 체인 증거를 다음 위치에 저장한다:

.codex/evidence/agent-chain/.json

각 JSON 항목은 다음과 같이 기록한다:

{
  "agent_name": "spec-architect",
  "model_used": "gpt‑4‑turbo",
  "chain_step": "architect",
  "timestamp": "2026-05-06T12:34:56Z",
  "success": true
}

또한 .codex/memory/ 를 초기화해 지속적인 선호도와 제약조건을 저장함으로써 세션이 재탐색 없이 컨텍스트와 함께 시작되도록 한다.

Source: …

일일 흐름

1. spec-architect 스폰 → 사양을 생성하거나 업데이트합니다.
2. 승인된 사양이 없으면 → 구현이 허용되지 않습니다.
3. 사양을 명시된 상태 흐름으로 이동합니다: draft → approved → in_progress → done|blocked.
4. 승인된 사양에 agent-router 를 스폰합니다.
   • 도메인이 명확하면 → 한 명의 전문가에게 라우팅합니다.
   • 혼합된 경우 → 먼저 사양을 분할합니다.
5. 전문가는 scope_in 내에서만 작업합니다. “여기 있는 동안”이라는 변경은 허용되지 않습니다.
6. npm run verify 를 실행합니다.
7. 엄격한 포맷과 사양 삭제 + 일치 증거를 포함하여 커밋합니다.
8. 전체 브랜치 PR 리뷰를 수행하여 단일 작업 수준에서는 보이지 않는 회귀를 잡아냅니다.

관찰된 실질적 개선 사항

Quick‑Start Checklist (for a fresh repo)

1. CODEX.md와 AGENTS.md를 생성합니다.
2. specs/templates/TASK.spec.template.md를 추가합니다.
3. .codex/WORKFLOW.md와 .codex/STRATEGY.md를 추가합니다.
4. .codex/agents/에 핵심 에이전트를 생성합니다.
5. .codex/config.toml에서 훅을 활성화하고 workflow-guard.sh를 연결합니다.
6. .codex/evidence/agent-chain/ 아래에 증거 스키마 경로를 추가합니다.
7. 차단된 커밋과 허용된 커밋 시나리오를 테스트합니다 (step 7을 건너뛰면 → 규칙이 아직 실제가 아닙니다).

요약

내 Codex 설정은 문서화된 프로세스를 실행으로 전환하기 때문에 작동합니다:

• Specs는 의도를 정의합니다.
• Agents는 책임을 분리합니다.
• Hooks는 협상 불가능한 정책을 강제합니다.
• Evidence는 실제로 실행된 것을 증명합니다.
• PR review는 시스템 수준의 안전성을 검증합니다.

이 구조를 통해 Codex는 예측 불가능한 자동완성이 아니라 신뢰할 수 있는 팀원이 됩니다.

Iterate prompts, but prompts are now the smallest part of the system.  
The bigger win is having a workflow that stays stable even when tasks, tools, or models change.