CodexSpec 사례 연구: 프로젝트에 PR 설명 생성기 추가¶

이 문서는 CodexSpec 도구 체인으로 CodexSpec 프로젝트 자체에 새 기능을 추가하는 전 과정을 기록한 것으로, 명세 기반 개발(SDD)을 실전에서 보여 줍니다.

개요¶

대상 기능: 구조화된 GitHub PR / GitLab MR 설명을 생성하는 /codexspec:pr 명령어 추가. (출하된 명령어의 사용자용 요약은 프로젝트 README 의 /codexspec:pr 항목을 참조하세요.)

개발 흐름: specify → generate-spec → review-spec → clarify → spec-to-plan

핵심 특징: 중간에 요구사항 이슈가 하나 드러났고 clarify 명령을 통해 수정되었습니다. 이는 SDD 의 유연성을 보여 줍니다. 동시에 CodexSpec 컨펌 게이트(Confirmation Gate) 의 구체적인 사례이기도 합니다. 명시적으로 확인하기 전에는 그 어떤 것도 확정되지 않으며, 한 번 수락된 결정도 clarify 체크포인트에서 다시 열어 뒤집을 수 있습니다.

1단계: 초기 요구사항 명확화 (`/codexspec:specify`)¶

사용자 초기 입력¶

프로젝트에 새 기능을 추가하고 싶습니다. 정확하고 상세하며 규범에 맞는 GitHub PR 설명(또는 GitLab 의 MR 설명)을 생성해 주는 새 Git 관련 명령어입니다. 참고용으로, 다른 프로젝트에서 써 본 두 가지 PR 명령어를 아래에 첨부합니다.

[참고 예시 1 - 구조화된 설명]
이제 프로젝트 메인테이너 역할을 맡아, 지금까지의 모든 작업을 바탕으로 이번 제출에 대한 명확한 Pull Request 설명을 작성해 주세요.
PR 설명은 팀의 다른 리뷰어를 독자로 하며 다음 섹션을 포함해야 합니다:
1. 배경(Context)
2. 구현(Implementation)
3. 테스트(Testing)
4. 검증 방법(How to Verify)

[참고 예시 2 - 간단한 설명]
현재 브랜치와 origin/main 사이의 코드 diff 를 바탕으로, Git 관례를 따르는 Merge Request 제목과 설명을 Markdown 으로 작성해 주세요. (중국어로 작성)

명확화 과정¶

Q1: 출력 언어

옵션: 프로젝트 설정을 따름 / 중국어 / 자동 감지
사용자 선택: 프로젝트 설정을 따름(현재: en)

Q2: 플랫폼 지원

옵션: GitHub 와 GitLab 모두 지원 / GitHub 만 / 플랫폼 자동 감지
사용자 선택: 플랫폼 자동 감지

Q3: PR 설명 내용

옵션: 상세 구조화 설명 / 간결한 설명 / 사용자 정의 템플릿
사용자 선택: 상세 구조화 설명(권장)

Q4: 트리거 조건

옵션: 현재 브랜치 vs origin/main / 푸시되지 않은 커밋 / 대상 브랜치 설정 가능
사용자 선택: 대상 브랜치 설정 가능

Q5: Spec 소스

옵션: spec.md 우선 / git 정보만 / 모든 소스 통합
사용자 선택: 모든 소스 통합(권장)

Q6: 명명

옵션: codexspec.pr / codexspec.create-pr / codexspec.create-mr
사용자 선택: codexspec.pr(권장)

Q7: spec 이 없을 때 처리

옵션: 그냥 생성, Context 건너뜀 / 먼저 spec 생성을 권유 / 경고하고 계속
사용자 선택: 그냥 생성, Context 건너뜀

Q8: 출력 방식

옵션: 터미널 출력 / 파일로 저장 / 터미널 + 선택적 파일
사용자 선택: 터미널 + 선택적 파일(권장)

Q9: 기본 섹션

옵션: Context, Implementation, Testing, How to Verify(모두 선택)
사용자 선택: 네 섹션 모두

Q10: 명령어 매개변수

사용자 선택: 모든 매개변수는 선택적
--target-branch: 기본값 origin/main
--output: 지정하지 않으면 기본적으로 터미널 출력만
--sections: 지정하지 않으면 기본값을 따름
--no-spec: spec.md 조회를 건너뜀

언어 설정 정정¶

사용자 피드백: 언어 동작은 /codexspec:commit-staged 명령어와 같아야 합니다. 즉 config.yml의 language.commit을 먼저 따르고, language.commit이 설정되지 않았을 때만 language.output으로 폴백.

수정된 요구사항 요약:

언어 우선순위: language.commit > language.output > English(기본값)

2단계: 명세 문서 생성 (`/codexspec:generate-spec`)¶

생성된 문서 구조¶

생성된 spec.md는 다음 섹션을 담습니다:

Overview: 기능 개요
Goals: 4개 목표
User Stories: 수용 기준이 붙은 4개 사용자 스토리
Functional Requirements: 8개 요구사항(REQ-001 ~ REQ-008)
Command Parameters: 4개 매개변수 정의
Non-Functional Requirements: 3개 요구사항(성능, 호환성, 오류 처리)
Acceptance Criteria (Test Cases): 10개 테스트 케이스
Edge Cases: 6개 엣지 케이스
Output Format Example: GitHub PR 과 GitLab MR 예시
Out of Scope: 명시적으로 제외된 기능
Dependencies: 의존성
Related Commands: 관련 명령어

핵심 요구사항 발췌¶

### REQ-003: Language Configuration
The command shall determine output language in the following priority order:
1. `language.commit` in `.codexspec/config.yml` (highest priority)
2. `language.output` in `.codexspec/config.yml` (fallback)
3. English (default if no configuration)

3단계: 명세 리뷰 (`/codexspec:review-spec`)¶

리뷰 결과¶

전체 상태: ✅ Pass
품질 점수: 92/100
준비도: Ready for Planning

발견된 이슈¶

경고(Should Fix):

SPEC-001: 테스트 파일 발견 로직이 명시적으로 정해지지 않음
SPEC-002: spec.md 파일이 여러 개일 때 "가장 최근 수정"으로 고르는 것이 부정확할 수 있음

제안(Nice to Have):

--title 매개변수 추가를 고려
출력 형식 검증 요구사항 추가
GitHub Enterprise URL 패턴 지원을 고려

리뷰 보고서 위치¶

.codexspec/specs/2026-0613-1200ab-pr-description-generator/review-spec.md

이것은 증거 기반 리뷰입니다. 위의 모든 경고와 제안은 spec 안의 구체적이고 식별 가능한 빈틀에 연결되어 있으며, 권고 항목(Nice to Have)은 수용 여부에 영향을 주지도, 자동 변경을 트리거하지도 않습니다.

4단계: 요구사항 명확화와 조정 (`/codexspec:clarify`) — 결정적 전환점¶

발견된 이슈¶

사용자 피드백:

spec.md 사용 방식에 문제가 하나 있습니다. 예를 들어 사용자가 아주 작은 변경을 하느라 CodexSpec 의 표준 흐름인 specify → plan → tasks → implement 를 밟지 않았을 수 있습니다. 대신 대화로 곧장 변경하거나 Claude Code 의 내장 플랜 모드를 썼고, 변경을 마친 뒤에야 별도로 CodexSpec 명령어를 불러 규범에 맞는 PR 설명을 만들려는 경우입니다. 이때 "가장 최근에 수정된" spec.md 가 기본값이면 이번 변경과 아무 상관없는 이전 spec.md 의 내용을 끌어오게 됩니다.

이것이 바로 컨펌 게이트가 작동하는 모습입니다. 앞선 결정("기본값: 가장 최근에 수정된 spec.md 사용")은 기록되어 있었지만 되돌릴 수 없을 정도로 확정된 것은 아니었습니다. 사용자가 실제 사용 패턴에 대한 새 정보를 가지고 clarify 체크포인트에서 다시 열었고, 이전에 수락된 기본값이 뒤집어졌습니다.

명확화 Q&A 과정¶

Q1: spec 선택 전략

맥락: 현재 EC-004는 "spec.md 가 여러 개 → 가장 최근 수정된 것 사용"이라고 되어 있습니다. 하지만 사용자가 SDD 흐름을 밟지 않고 작은 변경을 했다면, 가장 최근의 spec.md 가 현재 변경과 무관할 수 있습니다.

옵션	설명
A	사용자가 명시적으로 `--spec`을 넘기지 않으면 기본으로 spec.md 사용 안 함
B	브랜치 이름으로 매칭
C	사용자에게 고르라고 프롬프트
D	파일 변경으로 매칭

사용자 선택: 옵션 A 이유: 잘못된 참조를 피합니다. --spec 매개변수로 SDD 연동을 원하는 사용자가 명시적으로 옵트인하게 합니다.

Q2: spec 내용 추출 전략

맥락: 사용자가 --spec을 넘길 때, spec.md 구조가 불완전하면 어떻게 할까요?

옵션	설명
A	베스트에포트 추출, 누락 섹션은 건너뜀
B	경고하고 Context 건너뜀
C	완전한 구조를 요구, 아니면 에러

사용자 선택: 옵션 A 이유: spec 형식 이슈가 워크플로우를 막지 않게 합니다.

Q3: 테스트 파일 발견

맥락: Testing 섹션은 테스트 파일을 어떻게 발견해야 할까요?

옵션	설명
A	일반적인 디렉토리 패턴(tests/, test/)
B	언어 비의존 휴리스틱(디렉토리 + 파일명 패턴)
C	능동적 발견은 하지 않고 커밋 메시지에서만 추론

사용자 선택: 옵션 B 이유: 여러 언어의 다양한 프로젝트 구조를 두루 덮습니다.

Q4: PR 제목 생성

맥락: PR 제목을 어떻게 생성할까요?

옵션	설명
A	브랜치명 파싱을 먼저
B	첫 커밋 메시지를 먼저
C	종합(git diff + 브랜치명 + 커밋 메시지)

사용자 선택: 옵션 C 사용자 이유: 첫 커밋은 변경의 일부분만 대표할 수 있고, 브랜치명은 강한 명명 규율을 가정합니다. 참고할 수 있는 풍부한 git 정보와 코드 변경이 있으니 종합 분석이 더 정확합니다.

Q5: 검증 명령 생성

맥락: "How to Verify" 섹션은 검증 명령을 어떻게 생성할까요?

옵션	설명
A	일반 템플릿
B	프로젝트 감지(pyproject.toml → pytest, package.json → npm test)
C	커밋 메시지에서 추론

사용자 선택: 옵션 B 이유: 프로젝트 감지가 더 실용적인 검증 명령을 만듭니다.

명확화 세션 요약¶

질문	결정	영향
spec 선택 전략	`--spec`으로 옵트인	REQ-007, EC-004, 매개변수 표
spec 내용 추출	베스트에포트 추출	REQ-005b, EC-004c
테스트 파일 발견	언어 비의존 휴리스틱	REQ-006b
PR 제목 생성	종합 분석	REQ-008a
검증 명령 생성	프로젝트 파일 감지	REQ-010

핵심 변경: 매개변수 논리의 반전¶

원래 설계: --no-spec(spec 건너뜀)
새 설계:   --spec(spec 활성화, 옵트인)

이 반전이 본 사례에서 컨펌 게이트가 가장 선명하게 드러나는 부분입니다. 원래 "확정"이었던 기본값(--no-spec, 즉 spec 이 기본 켜짐)이, 사용자가 그것을 망가뜨릴 실제 워크플로우를 발견하면서 다시 열리고, 뒤집히고, 옵트인으로 재확정되었습니다.

5단계: 기술 구현 계획 (`/codexspec:spec-to-plan`)¶

계획 개요¶

구현 방식: Markdown 템플릿 파일(/codexspec:commit-staged와 일관되게)

새 의존성 없음 — 슬래시 명령어 템플릿 하나로 기능을 전달하며 Python 코드는 필요하지 않습니다.

기술 결정 요약¶

결정	선택	이유
구현 방식	Markdown 템플릿	기존 명령어와 일관, 유지보수 용이
언어 우선순위	commit > output > en	`/codexspec:commit-staged`와 일관
플랫폼 감지	Remote URL 파싱	단순하고 신뢰 가능
spec 연동	옵트인(`--spec`)	잘못된 참조 회피
내용 추출	베스트에포트	워크플로우를 막지 않음
테스트 발견	디렉토리 + 파일명 패턴	언어 비의존
제목 생성	종합 분석	가장 정확
명령 감지	프로젝트 파일 감지	더 실용적
출력 모드	터미널 먼저, 파일은 선택	유연

구현 단계¶

1단계: 템플릿 작성(YAML frontmatter, 언어 설정, Git 컨텍스트)
2단계: 핵심 기능(spec 연동, 테스트 발견, 명령 감지, 제목 생성)
3단계: 엣지 케이스 처리
4단계: 테스트
5단계: 문서 업데이트

파일 목록¶

생성:

templates/commands/pr.md

수정:

CLAUDE.md - 명령어 설명 추가
README.md - 명령어를 목록에 추가

테스트:

tests/test_pr_template.py

전체 흐름도¶

┌─────────────────────────────────────────────────────────────────────────┐
│                   CodexSpec SDD 개발 흐름                                │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  /codexspec:specify                                                     │
│  ├─ Q&A 로 요구사항 명확화                                               │
│  ├─ 사용자가 참고 예시 제공                                              │
│  └─ 언어·플랫폼·내용·매개변수 등를 다루는 10개 질문                       │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  /codexspec:generate-spec                                               │
│  ├─ 완전한 spec.md 생성                                                  │
│  ├─ 사용자 스토리 4개, 기능 요구사항 8개, 테스트 케이스 10개              │
│  └─ .codexspec/specs/2026-0613-1200ab-pr-description-generator/spec.md 에 저장 │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  /codexspec:review-spec                                                 │
│  ├─ 품질 점수: 92/100                                                   │
│  ├─ 경고 2개 발견(테스트 파일 발견, 다중 spec 처리)                       │
│  └─ 상태: Pass, 계획 단계로 진행 가능                                   │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  /codexspec:clarify  (결정적 조정)                                       │
│  ├─ 사용자가 실사용 이슈를 발견                                          │
│  ├─ 명확화 질문 5개, 모두 답변                                          │
│  ├─ 핵심 변경: --no-spec → --spec(옵트인)                                │
│  └─ 요구사항 5개 추가(REQ-005b, 006b, 008a, 010, 007 갱신)               │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  /codexspec:spec-to-plan                                                │
│  ├─ 기술 구현 계획 갱신                                                  │
│  ├─ 기술 결정 9개, 새로운 결정 5개 포함                                  │
│  ├─ 구현 단계 5개                                                        │
│  └─ .codexspec/specs/2026-0613-1200ab-pr-description-generator/plan.md 에 저장 │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  후속 단계(이번 세션에서는 완료하지 않음)                                 │
│  ├─ /codexspec:review-plan - 계획 품질 검증                              │
│  ├─ /codexspec:plan-to-tasks - 실행 가능한 태스크로 분해                  │
│  └─ /codexspec:implement-tasks - 구현 실행                                │
└─────────────────────────────────────────────────────────────────────────┘

핵심 교훈¶

1. clarify 단계의 가치¶

이 사례는 clarify 명령의 결정적 역할을 보여 줍니다:

사용 중에 실제 문제를 발견 — 작은 변경 시나리오에서 spec.md 가 잘못 쓰일 위험
명확화 Q&A 로 설계 결함을 해결 — 자동 감지에서 옵트인으로 전환
요구사항 변화를 체계적으로 기록 — 모든 변경이 spec.md 의 Clarifications 섹션에 저장

2. SDD 흐름의 유연성¶

선형 흐름이 아니며, 어느 단계에서든 돌아가 조정할 수 있습니다.
clarify는 review-spec 이후, spec-to-plan 이전에 끼워 넣을 수 있습니다.
명세 문서와 기술 계획 모두 변경을 반영하도록 갱신됩니다.

3. 매개변수 설계의 진화¶

초기 설계:
  --no-spec: spec.md 건너뜀(기본으로 사용)

최종 설계:
  --spec: spec.md 활성화(기본으로 사용하지 않음)

이 변화는 "기본 SDD 워크플로우"에서 "비-SDD 워크플로우도 함께 지원"으로의 설계 전환을 반영하며, 도구를 더 범용으로 만듭니다.

4. 문서 산출물¶

단계	산출 파일	내용
generate-spec	spec.md	완전한 명세 문서
review-spec	review-spec.md	품질 리뷰 보고서
clarify	(spec.md 갱신)	명확화 기록 + 요구사항 갱신
spec-to-plan	plan.md	기술 구현 계획

부록: 명령어 빠른 참조¶

# 1. 초기 요구사항 명확화
/codexspec:specify

# 2. 명세 문서 생성
/codexspec:generate-spec

# 3. 명세 품질 리뷰
/codexspec:review-spec

# 4. 요구사항 명확화/조정(선택, 이슈를 발견했을 때 사용)
/codexspec:clarify [이슈 설명]

# 5. 기술 계획 생성
/codexspec:spec-to-plan

# 6. 계획 품질 리뷰(선택)
/codexspec:review-plan

# 7. 태스크로 분해
/codexspec:plan-to-tasks

# 8. 구현 실행
/codexspec:implement-tasks

이 문서는 CodexSpec SDD 워크플로우로 생성되었으며, 실제 개발 대화를 기록합니다.

CodexSpec 사례 연구: 프로젝트에 PR 설명 생성기 추가¶

개요¶

1단계: 초기 요구사항 명확화 (/codexspec:specify)¶

사용자 초기 입력¶

명확화 과정¶

언어 설정 정정¶

2단계: 명세 문서 생성 (/codexspec:generate-spec)¶

생성된 문서 구조¶

핵심 요구사항 발췌¶

3단계: 명세 리뷰 (/codexspec:review-spec)¶

리뷰 결과¶

발견된 이슈¶

리뷰 보고서 위치¶

4단계: 요구사항 명확화와 조정 (/codexspec:clarify) — 결정적 전환점¶

발견된 이슈¶

명확화 Q&A 과정¶

명확화 세션 요약¶

핵심 변경: 매개변수 논리의 반전¶

5단계: 기술 구현 계획 (/codexspec:spec-to-plan)¶

계획 개요¶

기술 결정 요약¶

구현 단계¶

파일 목록¶

전체 흐름도¶

핵심 교훈¶

1. clarify 단계의 가치¶

2. SDD 흐름의 유연성¶

3. 매개변수 설계의 진화¶

4. 문서 산출물¶

부록: 명령어 빠른 참조¶

1단계: 초기 요구사항 명확화 (`/codexspec:specify`)¶

2단계: 명세 문서 생성 (`/codexspec:generate-spec`)¶

3단계: 명세 리뷰 (`/codexspec:review-spec`)¶

4단계: 요구사항 명확화와 조정 (`/codexspec:clarify`) — 결정적 전환점¶

5단계: 기술 구현 계획 (`/codexspec:spec-to-plan`)¶