CodexSpec 사용 사례: 프로젝트에 PR 설명 생성 기능 추가¶
이 문서는 CodexSpec 도구 체인을 사용하여 CodexSpec 프로젝트 자체에 새 기능을 추가하는 전체 과정을 기록하며, Spec-Driven Development (SDD)의 실제 적용을 보여줍니다.
개요¶
목표 기능: 구조화된 GitHub PR / GitLab MR 설명을 생성하는 /pr 명령 추가.
개발 프로세스: specify → generate-spec → review-spec → clarify → spec-to-plan
주요 특징: 개발 과정에서 요구사항 문제를 발견하고 clarify 명령을 통해 조정하여 SDD의 유연성을 보여줍니다.
단계 1: 초기 요구사항 명확화 (/specify)¶
사용자 초기 입력¶
프로젝트에 새로운 기능을 추가하고 싶습니다: 정확하고 상세하며 규범에 맞는 GitHub PR 정보(또는 GitLab의 MR 정보)를 생성하는 새로운 Git 관련 명령을 제공합니다. 다음은 다른 프로젝트에서 사용한 두 가지 PR 명령 내용입니다. 참고용으로 제공합니다.
[참고 예시 1 - 구조화된 설명]
이제 프로젝트 유지 관리자 역할을 하고, 지금까지의 모든 작업을 기반으로 이번 제출을 위한 명확한 Pull Request 설명을 작성해 주세요.
PR 설명은 팀의 다른 검토자를 대상으로 하며, 다음 섹션을 포함해야 합니다:
1. 배경 (Context)
2. 구현 방안 (Implementation)
3. 테스트 (Testing)
4. 수동 검증 방법 (How to Verify)
[참고 예시 2 - 간단한 설명]
현재 브랜치와 origin/main 브랜치의 코드 차이를 기반으로 Git 규범에 맞는 Merge Request의 제목과 설명을 Markdown 형식으로 정리해 주세요. (중국어로 설명)
명확화 과정¶
Q1: 출력 언어
- 옵션: 프로젝트 구성 따르기 / 중국어 / 자동 감지
- 사용자 선택: 프로젝트 구성 따르기 (현재: en)
Q2: 플랫폼 지원
- 옵션: GitHub와 GitLab 모두 지원 / GitHub만 / 플랫폼 자동 감지
- 사용자 선택: 플랫폼 자동 감지
Q3: PR 설명 내용
- 옵션: 상세 구조화된 설명 / 간단한 설명 / 사용자 정의 템플릿 가능
- 사용자 선택: 상세 구조화된 설명 (권장)
Q4: 트리거 조건
- 옵션: 현재 브랜치 vs origin/main / 푸시되지 않은 commits / 대상 브랜치 지정 가능
- 사용자 선택: 대상 브랜치 지정 가능
Q5: Spec 출처
- 옵션: spec.md 우선 / git 정보만 / 모든 출처 종합
- 사용자 선택: 모든 출처 종합 (권장)
Q6: 명명
- 옵션: codexspec.pr / codexspec.create-pr / codexspec.create-mr
- 사용자 선택: codexspec.pr (권장)
Q7: Spec 없음 처리
- 옵션: 계속 생성, 배경 건너뛰기 / 사용자에게 먼저 spec 생성 요청 / 경고하고 계속
- 사용자 선택: 계속 생성, 배경 건너뛰기
Q8: 출력 방식
- 옵션: 터미널 출력 / 파일로 저장 / 터미널 + 선택적 파일
- 사용자 선택: 터미널 + 선택적 파일 (권장)
Q9: 기본 섹션
- 옵션: 배경, 구현 방안, 테스트, 검증 방법 (모두 선택)
- 사용자 선택: 네 섹션 모두
Q10: 명령 매개변수
- 사용자 선택: 모든 매개변수는 선택적 매개변수
--target-branch: 기본값 origin/main--output: 지정하지 않으면 기본적으로 터미널에만 출력--sections: 지정하지 않으면 기본값 따름--no-spec: spec.md 파일 검색 건너뛰기
언어 구성 수정¶
사용자 피드백: 언어는 /commit-staged 명령과 마찬가지로 config.yml의 language.commit 매개변수를 우선으로 해야 하며, language.commit 매개변수 설정이 없으면 language.output을 따라야 합니다.
업데이트된 요구사항 요약:
단계 2: 명세서 문서 생성 (/generate-spec)¶
생성된 문서 구조¶
생성된 spec.md는 다음 섹션을 포함합니다:
- Overview: 기능 개요
- Goals: 4개 목표
- User Stories: 수락 기준이 있는 4개 사용자 스토리
- Functional Requirements: 8개 요구사항 (REQ-001 to 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: 명세서 검토 (/review-spec)¶
검토 결과¶
- 전체 상태: ✅ 통과
- 품질 점수: 92/100
- 준비 상태: Ready for Planning
발견된 문제¶
경고 (Should Fix):
- SPEC-001: 테스트 파일 발견 논리가 명확히 지정되지 않음
- SPEC-002: 여러 spec.md가 있을 때 "가장 최근 수정" 선택이 부정확할 수 있음
제안 (Nice to Have):
--title매개변수 추가 고려- 출력 형식 검증 요구사항 추가
- GitHub Enterprise URL 패턴 지원 고려
검토 보고서 저장 위치¶
.codexspec/specs/001-pr-description-generator/review-spec.md
단계 4: 요구사항 명확화 및 조정 (/clarify) ⚠️ 핵심 전환점¶
발견된 문제¶
사용자 피드백:
spec.md 사용에 문제가 있다는 것을 깨달았습니다. 예를 들어 사용자가 실제로 아주 작은 변경을 수행하고 있어서 codexspec의 표준화된 프로세스 specify->plan->tasks->implement를 사용하지 않고 직접 대화로 수정하거나 claude code 내장 plan mode를 사용한 다음, 수정 완료 후 codexspec 명령을 별도로 호출하여 규범적인 pr 정보를 생성하려는 경우입니다. 이 경우 가장 최근에 수정된 spec.md를 기본으로 사용하면 이번 수정과 무관한 이전 spec.md 내용을 사용하게 될 수 있습니다.
명확화 질문 과정¶
Q1: Spec 선택 전략
Context: 현재 EC-004는 "여러 spec.md → 가장 최근 수정된 것 사용"으로 규정. 하지만 사용자가 작은 변경을 수행할 때 SDD 프로세스를 사용하지 않았을 수 있으며, 가장 최근 spec.md가 현재 수정과 무관할 수 있음.
| 옵션 | 설명 |
|---|---|
| A | 사용자가 명시적으로 --spec 매개변수를 지정하지 않으면 기본적으로 spec.md 사용 안 함 |
| B | 브랜치 이름 기반 매칭 |
| C | 사용자에게 선택 요청 |
| D | 파일 변경 기반 매칭 |
사용자 선택: 옵션 A
이유: 잘못된 참조 방지, --spec 매개변수로 SDD 통합이 필요한 사용자가 명시적으로 지정.
Q2: Spec 내용 추출 전략
Context: 사용자가 --spec을 사용할 때, spec.md 구조가 불완전하면 어떻게 하나요?
| 옵션 | 설명 |
|---|---|
| A | 최선을 다해 추출, 누락된 부분 건너뛰기 |
| B | 경고하고 Context 건너뛰기 |
| C | 완전한 구조 요구, 그렇지 않으면 오류 |
사용자 선택: 옵션 A 이유: spec 형식 문제로 워크플로우 차단 방지.
Q3: 테스트 파일 발견
Context: Testing 섹션에서 테스트 파일을 어떻게 발견하나요?
| 옵션 | 설명 |
|---|---|
| A | 일반 디렉토리 패턴 (tests/, test/) |
| B | 언어 독립적 휴리스틱 (디렉토리 + 파일명 패턴) |
| C | 적극적으로 발견하지 않음, commit 메시지에서만 추론 |
사용자 선택: 옵션 B 이유: 다른 언어의 다양한 프로젝트 구조 커버.
Q4: PR 제목 생성
Context: PR 제목을 어떻게 생성하나요?
| 옵션 | 설명 |
|---|---|
| A | 브랜치 이름 파싱 우선 |
| B | 첫 번째 commit 메시지 우선 |
| C | 종합 생성 (git diff + 브랜치 이름 + commit 메시지) |
사용자 선택: 옵션 C 사용자 이유: 첫 번째 commit은 작은 부분 변경일 수 있음; 브랜치 이름은 명명 규범 요구. 많은 git 정보와 코드 변경을 참조할 수 있으므로 종합 분석이 더 정확함.
Q5: 검증 명령 생성
Context: "How to Verify" 섹션에서 검증 명령을 어떻게 생성하나요?
| 옵션 | 설명 |
|---|---|
| A | 일반 템플릿 |
| B | 프로젝트 감지 (pyproject.toml → pytest, package.json → npm test) |
| C | commit 메시지에서 추론 |
사용자 선택: 옵션 B 이유: 프로젝트 감지가 더 실용적인 검증 명령 생성 가능.
명확화 세션 요약¶
| 문제 | 결정 | 영향 |
|---|---|---|
| Spec 선택 전략 | --spec으로 opt-in |
REQ-007, EC-004, 매개변수 표 |
| Spec 내용 추출 | 최선 노력 추출 | REQ-005b, EC-004c |
| 테스트 파일 발견 | 언어 독립적 휴리스틱 | REQ-006b |
| PR 제목 생성 | 종합 분석 | REQ-008a |
| 검증 명령 생성 | 프로젝트 파일 감지 | REQ-010 |
핵심 변경: 매개변수 논리 반전¶
단계 5: 기술 구현 계획 (/spec-to-plan)¶
계획 개요¶
구현 방식: Markdown 템플릿 파일 (/commit-staged와 일치)
새 의존성 없음 - 기능이 slash command 템플릿으로 구현되며 Python 코드 불필요.
기술 결정 요약¶
| 결정 | 선택 | 이유 |
|---|---|---|
| 구현 방식 | Markdown 템플릿 | 기존 명령과 일치, 유지보수 쉬움 |
| 언어 우선순위 | commit > output > en | /commit-staged 명령과 일치 |
| 플랫폼 감지 | Remote URL 파싱 | 간단하고 신뢰할 수 있음 |
| Spec 통합 | Opt-in (--spec) |
잘못된 참조 방지 |
| 내용 추출 | 최선 노력 | 워크플로우 차단 안 함 |
| 테스트 발견 | 디렉토리+파일명 패턴 | 언어 독립적 |
| 제목 생성 | 종합 분석 | 가장 정확 |
| 명령 감지 | 프로젝트 파일 감지 | 더 실용적 |
| 출력 모드 | 터미널 우선, 선택적 파일 | 유연함 |
구현 단계¶
- Phase 1: 템플릿 생성 (YAML frontmatter, 언어 구성, Git 컨텍스트)
- Phase 2: 핵심 기능 (Spec 통합, 테스트 발견, 명령 감지, 제목 생성)
- Phase 3: 경계 상황 처리
- Phase 4: 테스트
- Phase 5: 문서 업데이트
파일 목록¶
생성:
templates/commands/pr.md
수정:
CLAUDE.md- 명령 설명 추가README.md- 명령을 목록에 추가
테스트:
tests/test_pr_template.py
전체 흐름도¶
┌─────────────────────────────────────────────────────────────────────────┐
│ CodexSpec SDD 개발 프로세스 │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ /specify │
│ ├─ 질문답변으로 요구사항 명확화 │
│ ├─ 사용자가 참고 예시 제공 │
│ └─ 10개 질문, 언어, 플랫폼, 내용, 매개변수 등 커버 │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ /generate-spec │
│ ├─ 완전한 spec.md 생성 │
│ ├─ 4개 사용자 스토리, 8개 기능 요구사항, 10개 테스트 케이스 │
│ └─ .codexspec/specs/001-pr-description-generator/spec.md에 저장 │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ /review-spec │
│ ├─ 품질 점수: 92/100 │
│ ├─ 2개 경고 발견 (테스트 파일 발견, 다중 spec 처리) │
│ └─ 상태: 통과, 계획 단계로 진입 가능 │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ /clarify ⚠️ 핵심 조정 │
│ ├─ 사용자가 실제 사용 시나리오 문제 발견 │
│ ├─ 5개 명확화 질문, 모두 답변 받음 │
│ ├─ 핵심 변경: --no-spec → --spec (opt-in) │
│ └─ 5개 요구사항 신규 추가 (REQ-005b, 006b, 008a, 010, 007 업데이트) │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ /spec-to-plan │
│ ├─ 기술 구현 계획 업데이트 │
│ ├─ 9개 기술 결정, 5개 신규 결정 포함 │
│ ├─ 5개 구현 단계 │
│ └─ .codexspec/specs/001-pr-description-generator/plan.md에 저장 │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 후속 단계 (이 세션에서 완료되지 않음) │
│ ├─ /review-plan - 계획 품질 검증 │
│ ├─ /plan-to-tasks - 실행 가능한 작업으로 분해 │
│ └─ /implement-tasks - 구현 실행 │
└─────────────────────────────────────────────────────────────────────────┘
핵심 학습 포인트¶
1. 명확화 단계의 가치¶
이 사례는 clarify 명령의 핵심 역할을 보여줍니다:
- 사용자가 사용 중에 실제 문제 발견 - 작은 변경 시나리오에서 spec.md 오용 위험
- 명확화 질문으로 설계 결함 해결 - 자동 감지에서 opt-in 모드로 변경
- 요구사항 변경이 체계적으로 기록 - 모든 변경이 spec.md의 Clarifications 섹션에 저장
2. SDD 프로세스의 유연성¶
- 선형 프로세스가 아니며 어떤 단계에서든 돌아가서 조정 가능
clarify는review-spec후,spec-to-plan전에 삽입 가능- 명세서 문서와 기술 계획이 모두 변경을 반영하도록 업데이트
3. 매개변수 설계의 진화¶
이 변화는 "기본 SDD 워크플로우"에서 "비SDD 워크플로우 지원"으로의 설계 전환을 반영하여 도구를 더 범용적으로 만듭니다.
4. 문서 산출물¶
| 단계 | 산출 파일 | 내용 |
|---|---|---|
| generate-spec | spec.md | 완전한 명세서 문서 |
| review-spec | review-spec.md | 품질 검토 보고서 |
| clarify | (spec.md 업데이트) | 명확화 기록 + 요구사항 업데이트 |
| spec-to-plan | plan.md | 기술 구현 계획 |
부록: 명령 사용 빠른 참조¶
# 1. 초기 요구사항 명확화
/specify
# 2. 명세서 문서 생성
/generate-spec
# 3. 명세서 품질 검토
/review-spec
# 4. 명확화/요구사항 조정 (선택, 문제 발견 후 사용)
/clarify [문제 설명]
# 5. 기술 계획 생성
/spec-to-plan
# 6. 계획 품질 검토 (선택)
/review-plan
# 7. 작업으로 분해
/plan-to-tasks
# 8. 구현 실행
/implement-tasks
이 문서는 CodexSpec SDD 워크플로우로 자동 생성되었으며, 실제 개발 대화 과정을 기록합니다.