명령¶

CodexSpec의 슬래시 명령에 대한 참조입니다. 이 명령들은 Claude Code의 채팅 인터페이스에서 호출됩니다.

워크플로우 패턴과 각 명령을 사용하는 시기에 대해서는 워크플로우를 참조하세요. CLI 명령에 대해서는 CLI를 참조하세요.

빠른 참조¶

명령	목적
`/constitution`	교차 산출물 검증으로 프로젝트 constitution 생성 또는 업데이트
`/specify`	대화형 Q&A로 요구사항 명확화
`/generate-spec`	명확화된 요구사항에서 spec.md 문서 생성
`/clarify`	기존 spec 스캔하여 모호성 발견 (반복적 정제)
`/spec-to-plan`	명세서를 기술 구현 계획으로 변환
`/plan-to-tasks`	계획을 원자적이고 TDD가 적용된 작업으로 분해
`/implement-tasks`	조건부 TDD 워크플로우로 작업 실행
`/review-spec`	완전성과 품질을 위한 명세서 검증
`/review-plan`	실행 가능성과 정렬을 위한 기술 계획 검토
`/review-tasks`	TDD 준수를 위한 작업 분해 검증
`/analyze`	교차 산출물 일관성 분석 (읽기 전용)
`/checklist`	요구사항 품질 체크리스트 생성
`/tasks-to-issues`	작업을 GitHub 이슈로 변환
`/codexspec:commit-staged`	스테이징된 변경에서 커밋 메시지 생성 (세션 컨텍스트 인식 포함)

명령 카테고리¶

핵심 워크플로우 명령¶

기본 SDD 워크플로우를 위한 명령: Constitution → Specification → Plan → Tasks → Implementation.

리뷰 명령 (품질 게이트)¶

각 워크플로우 단계에서 산출물을 검증하는 명령. 다음 단계로 진행하기 전에 권장됩니다.

고급 명령¶

반복적 정제, 교차 산출물 검증 및 프로젝트 관리 통합을 위한 명령.

명령 참조¶

`/constitution`¶

프로젝트 constitution을 생성하거나 업데이트합니다. constitution은 모든 후속 개발 결정을 안내하는 아키텍처 원칙, 기술 스택, 코드 표준 및 거버넌스 규칙을 정의합니다.

구문:

/constitution [원칙 설명]

인자:

인자	필수	설명
`원칙 설명`	아니오	포함할 원칙에 대한 설명 (제공되지 않으면 요청됨)

수행 작업:

존재하지 않으면 .codexspec/memory/constitution.md 생성
새 원칙으로 기존 constitution 업데이트
템플릿과의 교차 산출물 일관성 검증
변경 사항과 영향을 받는 파일을 보여주는 Sync Impact Report 생성
의존 템플릿에 대한 constitutionality 리뷰 포함

생성하는 파일:

.codexspec/
└── memory/
    └── constitution.md    # 프로젝트 거버넌스 문서

예시:

You: /constitution 코드 품질, 테스트 표준 및 클린 아키텍처에 중점

AI:  constitution 생성 중...

     ✓ .codexspec/memory/constitution.md 생성됨
     버전: 1.0.0

     Sync Impact Report:
     - plan-template-*.md: ✅ 정렬됨
     - spec-template-*.md: ✅ 정렬됨
     - tasks-template-*.md: ✅ 정렬됨

     핵심 원칙:
     1. 코드 품질 우선
     2. 테스트 주도 개발
     3. 클린 아키텍처

     제안 커밋: docs: constitution v1.0.0 생성

팁:

일관된 의사결정을 위해 프로젝트 초기에 원칙 정의
기술 및 프로세스 원칙 모두 포함
주요 기능 개발 전 constitution 리뷰
Constitution 변경은 교차 산출물 검증 트리거

`/specify`¶

대화형 Q&A를 통해 요구사항을 명확화합니다. 이 명령은 어떤 파일도 생성하지 않고 초기 아이디어를 탐색합니다 - 사용자가 완전한 제어권을 유지합니다.

구문:

/specify [아이디어 또는 요구사항]

인자:

인자	필수	설명
`아이디어 또는 요구사항`	아니오	구축하고자 하는 것에 대한 초기 설명 (제공되지 않으면 요청됨)

수행 작업:

아이디어를 이해하기 위한 명확화 질문
고려하지 못했을 수 있는 경계 사례 탐색
대화를 통한 고품질 요구사항 공동 창작
"무엇"과 "왜"에 집중, 기술 구현이 아님
파일을 생성하지 않음 - 사용자가 문서화 시점 결정

생성하지 않는 것:

이 명령 중에 생성되는 파일 없음
승인할 때까지 요구사항이 대화에 유지

예시:

You: /specify 작업 관리 앱을 구축하고 싶습니다

AI:  좋습니다! 요구사항을 명확히 도와드리겠습니다.

     첫째, 이 앱의 대상 사용자는 누구인가요?
     - 개인 전문가
     - 소규모 팀
     - 기업 조직
     - 위의 모든 것

You: 소규모 팀, 주로 소프트웨어 개발 팀

AI:  알겠습니다. 소규모 개발 팀의 경우:
     - 실시간 협업 기능이 필요한가요?
     - 작업이 하위 작업을 지원해야 하나요, 아니면 평면 목록인가요?
     - 통합 요구사항이 있나요 (GitHub, Slack 등)?

You: 실시간이 중요합니다. 하위 작업 예. GitHub 통합이 있으면 좋겠습니다.

AI:  [요구사항 계속 탐색...]

     명확화된 요구사항 요약:
     - 대상: 소규모 개발 팀 (5-20명)
     - 핵심: 하위 작업이 있는 작업, 실시간 업데이트
     - 통합: GitHub (선택적)
     - 우선순위: 실시간 협업 > 하위 작업 > GitHub

     spec 문서를 생성할 준비가 되셨나요?
     /generate-spec을 사용하여 spec.md 생성

팁:

초기 요구사항 탐색에 사용
완전할 필요 없음 - 정제는 반복적
AI가 가정을 하면 질문하기
spec 생성 전 요약 검토

`/generate-spec`¶

명확화된 요구사항에서 spec.md 문서를 생성합니다. 이 명령은 명확화된 요구사항을 구조화된 명세서로 변환하는 "요구사항 컴파일러" 역할을 합니다.

구문:

/generate-spec

인자:

인자	필수	설명
없음	-	이전 `/specify` 세션의 컨텍스트 사용

수행 작업:

.codexspec/specs/{NNN}-{feature-name}/ 디렉토리 생성
다음을 포함한 포괄적인 spec.md 생성:
기능 개요 및 목표
수락 기준이 있는 사용자 스토리
기능 요구사항 (REQ-XXX 형식)
비기능 요구사항 (NFR-XXX 형식)
경계 사례 및 처리 접근법
범위 외 항목

생성하는 파일:

.codexspec/
└── specs/
    └── 001-task-management/
        └── spec.md

예시:

You: /generate-spec

AI:  명세서 생성 중...

     ✓ .codexspec/specs/001-task-management/spec.md 생성됨

     포함된 섹션:
     - 개요: 소규모 개발 팀을 위한 작업 관리
     - 수락 기준이 있는 4개 사용자 스토리
     - 12개 기능 요구사항 (REQ-001 to REQ-012)
     - 3개 비기능 요구사항 (NFR-001 to NFR-003)
     - 5개 경계 사례 문서화
     - 범위 외: 모바일 앱, 기업 SSO

     다음 단계:
     - /review-spec으로 spec 검토
     - 또는 /spec-to-plan으로 진행

팁:

/specify가 요구사항을 명확화한 후 실행
진행 전에 생성된 spec 검토
품질 검증을 위해 /review-spec 사용
사소한 조정이 필요하면 spec.md 직접 편집

`/clarify`¶

기존 명세서에서 모호성과 간극을 스캔합니다. 초기 spec 생성 후 반복적 정제에 사용합니다.

구문:

/clarify [spec.md 경로]

인자:

인자	필수	설명
`spec.md 경로`	아니오	spec 파일 경로 (제공되지 않으면 자동 감지)

수행 작업:

4개 집중 모호성 카테고리로 spec 스캔
대상화된 명확화 질문 (최대 5개)
명확화 답변으로 spec.md 업데이트
사용 가능한 경우 review-spec 발견 사항과 통합

모호성 카테고리:

카테고리	감지 내용
완전성 간극	누락된 섹션, 빈 콘텐츠, 부재한 수락 기준
구체성 문제	모호한 용어 ("빠른", "확장 가능한"), 정의되지 않은 제약 조건
동작 명확성	오류 처리 간극, 정의되지 않은 상태 전환
측정 가능성 문제	메트릭이 없는 비기능 요구사항

예시:

You: /clarify

AI:  spec.md에서 모호성 스캔 중...

     3개 카테고리에서 문제 발견.

     ## 질문 1/5: 구체성

     **컨텍스트**: NFR-001이 "시스템이 빠르게 응답해야 함"이라고 명시

     **질문**: 목표 응답 시간은 무엇인가요?

     | 옵션 | 설명 | 영향 |
     |--------|-------------|--------|
     | A | 모든 작업 < 100ms | 높은 성능 요구사항 |
     | B | 읽기 < 500ms, 쓰기 < 1s | 균형 잡힌 접근법 |
     | Custom | 다른 답변 제공 | - |

     **권장사항**: 옵션 B - 일반적인 웹 앱에 균형 잡힘

You: B

AI:  ✓ NFR-001 업데이트됨: 응답 시간 읽기 < 500ms, 쓰기 < 1s
     spec.md의 Clarifications 섹션에 추가됨

팁:

spec.md가 존재하지만 정제가 필요할 때 사용
/review-spec 발견 사항과 통합
세션당 최대 5개 질문
복잡한 명세서의 경우 여러 번 실행

`/spec-to-plan`¶

기능 명세서를 기술 구현 계획으로 변환합니다. 여기서 기능이 어떻게 구축될지 정의합니다.

구문:

/spec-to-plan [spec.md 경로]

인자:

인자	필수	설명
`spec.md 경로`	아니오	spec 파일 경로 (제공되지 않으면 `.codexspec/specs/`에서 자동 감지)

수행 작업:

명세서와 constitution 읽기
버전 제약 조건이 있는 기술 스택 정의
constitutionality 리뷰 수행 (constitution이 존재하면 필수)
모듈 의존성 그래프가 있는 아키텍처 생성
근거가 있는 기술 결정 문서화
구현 단계 계획

생성하는 파일:

.codexspec/
└── specs/
    └── 001-task-management/
        └── plan.md    # 기술 구현 계획

예시:

You: /spec-to-plan 백엔드에 Python FastAPI, 프론트엔드에 React, 데이터베이스에 PostgreSQL 사용

AI:  기술 계획 생성 중...

     Constitutionality 리뷰:
     ✓ 클린 아키텍처: 명확한 경계가 있는 모듈식 설계
     ✓ TDD: 단계에서 테스트 우선 접근법 적용
     ✓ 코드 품질: 린팅 및 타입 힌트 필수

     아키텍처:
     - 백엔드: 계층화된 아키텍처가 있는 FastAPI
     - 프론트엔드: 컴포넌트 구조가 있는 React
     - 데이터베이스: 마이그레이션 전략이 있는 PostgreSQL

     모듈 의존성 그래프:
     ┌─────────────┐
     │    API      │
     └──────┬──────┘
            │
     ┌──────▼──────┐
     │  Services   │
     └──────┬──────┘
            │
     ┌──────▼──────┐
     │    Data     │
     └─────────────┘

     ✓ plan.md 생성됨
     5개 구현 단계 정의됨

팁:

spec이 검토되고 안정된 후 실행
constitution이 존재하면 constitutionality 리뷰가 필수
프로젝트 유형에 따라 관련 섹션 포함
작업으로 진행 전에 계획 검토

`/plan-to-tasks`¶

기술 계획을 TDD가 적용된 원자적이고 실행 가능한 작업으로 분해합니다.

구문:

/plan-to-tasks [spec.md 경로 plan.md 경로]

인자:

인자	필수	설명
`경로`	아니오	spec과 plan의 경로 (제공되지 않으면 자동 감지)

수행 작업:

원자적 작업 생성 (작업당 하나의 기본 파일)
TDD 적용: 테스트 작업이 구현 작업 선행
[P]로 병렬화 가능한 작업 표시
각 작업에 대한 정확한 파일 경로 지정
단계 체크포인트 정의

생성하는 파일:

.codexspec/
└── specs/
    └── 001-task-management/
        └── tasks.md    # 작업 분해

작업 구조:

### Task 2.1: Entity A 테스트 작성 [P]
- **유형**: 테스트
- **파일**: `tests/test_entity_a.py`
- **설명**: Entity A에 대한 단위 테스트 작성
- **의존성**: Task 1.3
- **예상 복잡도**: 낮음

예시:

You: /plan-to-tasks

AI:  계획을 작업으로 분해 중...

     ✓ tasks.md 생성됨
     총: 24개 작업
     병렬화 가능: 8개 작업 (33%)

     Phase 1: 기반 (4개 작업)
     Phase 2: 핵심 구현 - TDD (10개 작업)
     Phase 3: 통합 (4개 작업)
     Phase 4: 인터페이스 계층 (3개 작업)
     Phase 5: 테스트 및 문서화 (3개 작업)

     실행 순서:
     Phase 1 → [Phase 2 작업을 병렬 그룹으로] → Phase 3 → Phase 4 → Phase 5

     각 단계 경계에 체크포인트 정의됨.

팁:

각 작업은 하나의 기본 파일만 관련해야 함
테스트 작업이 항상 구현 작업 선행
[P]는 진정으로 독립적인 병렬화 가능 작업 표시
구현 전에 의존성 검토

`/implement-tasks`¶

조건부 TDD 워크플로우로 구현 작업을 실행합니다. 작업 목록을 체계적으로 진행합니다.

구문:

/implement-tasks [tasks_경로]
/implement-tasks [spec_경로 plan_경로 tasks_경로]

인자:

인자	필수	설명
`tasks_경로`	아니오	tasks.md 경로 (제공되지 않으면 자동 감지)
`spec_경로 plan_경로 tasks_경로`	아니오	세 문서 모두에 대한 명시적 경로

파일 해결:

인자 없음: .codexspec/specs/에서 자동 감지
하나의 인자: tasks.md 경로로 처리, 같은 디렉토리에서 다른 것 도출
세 개의 인자: spec.md, plan.md, tasks.md에 대한 명시적 경로

수행 작업:

tasks.md 읽고 미완료 작업 식별
코드 작업에 TDD 워크플로우 적용:
Red: 먼저 실패하는 테스트 작성
Green: 테스트 통과하도록 구현
Verify: 모든 테스트 실행
Refactor: 테스트가 녹색인 상태로 개선
테스트 불가능한 작업 (문서, 구성)에 직접 구현
작업 진행에 따라 작업 체크박스 업데이트
문제 발생 시 issues.md에 차단 요소 기록

코드 작업을 위한 TDD 워크플로우:

Red → Green → Verify → Refactor → 완료 표시

테스트 불가능한 작업을 위한 직접 구현:

문서 파일
구성 파일
정적 자산
인프라 파일

예시:

You: /implement-tasks

AI:  구현 시작...

     컨텍스트 로드 중:
     - spec.md ✓
     - plan.md ✓
     - tasks.md ✓
     - constitution.md ✓

     기술 스택: Python 3.11+ / FastAPI / PostgreSQL / pytest

     Task 1.1 작업 중: 프로젝트 구조 설정
     ✓ src/taskman/__init__.py 생성됨
     ✓ pyproject.toml 생성됨
     [x] Task 1.1 완료

     Task 2.1 작업 중: Task Entity 테스트 작성 [P]
     ✓ tests/test_task.py 생성됨
     테스트 실행 중... 5개 통과 (모두 예상된 실패)
     [x] Task 2.1 완료

     Task 2.2 작업 중: Task Entity 구현
     ✓ src/taskman/models/task.py 생성됨
     테스트 실행 중... 5개 통과
     [x] Task 2.2 완료

     ...

팁:

중단된 경우 중단된 곳에서 재개 가능
차단 요소는 issues.md에 기록
중요한 작업/단계 후에 커밋 수행
검증을 위해 먼저 /review-tasks 실행

`/review-spec`¶

완전성, 명확성, 일관성 및 기술 계획 준비 상태를 위해 명세서를 검증합니다.

구문:

/review-spec [spec.md 경로]

인자:

인자	필수	설명
`spec.md 경로`	아니오	spec 파일 경로 (제공되지 않으면 자동 감지)

수행 작업:

모든 필수 섹션의 완전성 확인
명확성과 구체성 평가
내부 일관성 검증
요구사항의 테스트 가능성 평가
constitution 정렬 확인
점수가 매겨진 리뷰 보고서 생성

리뷰 차원:

차원	가중치	검증 내용
완전성	25%	모든 섹션이 존재하고 실질적
명확성	25%	모호한 언어 없음, 단일 해석
일관성	20%	내부 모순 없음
테스트 가능성	20%	요구사항을 검증할 수 있음
Constitution 정렬	10%	프로젝트 원칙과 정렬

예시:

You: /review-spec

AI:  명세서 리뷰 중...

     # 명세서 리뷰 보고서

     ## 요약
     - **전체 상태**: ⚠️ 작업 필요
     - **품질 점수**: 72/100
     - **준비 상태**: 수정 필요

     ## 섹션 분석
     | 섹션 | 상태 | 완전성 | 품질 |
     |---------|--------|--------------|---------|
     | 개요 | ✅ | 100% | 높음 |
     | 목표 | ✅ | 100% | 높음 |
     | 사용자 스토리 | ⚠️ | 80% | 중간 |
     | 기능 요구사항 | ✅ | 100% | 높음 |
     | 비기능 요구사항 | ⚠️ | 50% | 중간 |
     | 경계 사례 | ❌ | 0% | 해당 없음 |

     ## 치명적 문제 (반드시 수정)
     - [SPEC-001]: 경계 사례 섹션이 비어 있음
       - 영향: 중요한 실패 시나리오를 놓칠 수 있음
       - 제안: 최소 3-5개 경계 사례 문서화

     ## 경고 (수정 권장)
     - [SPEC-002]: NFR-001이 모호한 용어 "빠른" 사용
       - 영향: 메트릭 없이 검증할 수 없음
       - 제안: 구체적인 응답 시간 지정

     ## 권장사항
     1. 처리 접근법과 함께 경계 사례 섹션 추가
     2. 비기능 요구사항 정량화
     3. 사용자 스토리 3에 수락 기준 추가

     사용 가능한 후속 조치:
     - /clarify - 모호성 해결
     - /spec-to-plan - 문제가 해결되면

팁:

/spec-to-plan 전에 실행
진행 전에 치명적 문제 해결
경고는 차단하지 않지만 위험을 나타냄
수정 후 다시 실행

`/review-plan`¶

실행 가능성, 아키텍처 품질 및 명세서 정렬을 위해 기술 구현 계획을 검토합니다.

구문:

/review-plan [plan.md 경로]

인자:

인자	필수	설명
`plan.md 경로`	아니오	plan 파일 경로 (제공되지 않으면 자동 감지)

수행 작업:

spec 요구사항이 계획 커버리지를 가지고 있는지 확인
기술 스택 선택 평가
아키텍처 결정 평가
구현 단계 검증
constitution 정렬 확인
점수가 매겨진 리뷰 보고서 생성

리뷰 차원:

차원	가중치	검증 내용
Spec 정렬	30%	모든 요구사항에 구현이 있음
기술 스택	15%	적절한 기술 선택
아키텍처 품질	25%	건전한 설계 및 패턴
단계 계획	15%	논리적이고 현실적인 단계
Constitution 정렬	15%	프로젝트 원칙 따름

예시:

You: /review-plan

AI:  기술 계획 리뷰 중...

     # 계획 리뷰 보고서

     ## 요약
     - **전체 상태**: ✅ 통과
     - **품질 점수**: 85/100
     - **준비 상태**: 작업 분해 준비 완료

     ## Spec 정렬
     | 요구사항 | 커버리지 | 상태 |
     |-------------|----------|--------|
     | REQ-001 to REQ-012 | ✅ 전체 | 모두 커버됨 |
     | US-001 to US-004 | ✅ 전체 | 모두 커버됨 |
     | NFR-001 to NFR-003 | ⚠️ 부분 | 캐싱이 상세하지 않음 |

     ## 아키텍처 리뷰
     강점:
     - 관심사의 명확한 분리
     - 잘 정의된 모듈 경계
     - 적절한 설계 패턴

     우려 사항:
     - 오류 처리 전략 문서화 누락

     ## Constitution 정렬
     | 원칙 | 준수 |
     |-----------|------------|
     | 클린 아키텍처 | ✅ |
     | TDD | ✅ |
     | 코드 품질 | ✅ |

     /plan-to-tasks 준비 완료

팁:

/plan-to-tasks 전에 실행
치명적 문제는 해결해야 함
아키텍처 문제를 조기에 포착하는 데 사용
기술 스택이 팀 역량과 정렬되는지 확인

`/review-tasks`¶

완전성, TDD 준수, 올바른 순서 및 적절한 의존성을 위해 작업 분해를 검증합니다.

구문:

/review-tasks [tasks.md 경로]

인자:

인자	필수	설명
`tasks.md 경로`	아니오	tasks 파일 경로 (제공되지 않으면 자동 감지)

수행 작업:

모든 계획 항목이 작업 커버리지를 가지고 있는지 확인
TDD 준수 검증 (구현 전 테스트)
작업 세분성 검증 (원자적, 단일 파일 중심)
의존성 검증 (순환 없음, 올바른 순서)
병렬화 마커 검토
파일 경로 검증

리뷰 차원:

차원	가중치	검증 내용
계획 커버리지	30%	모든 계획 항목에 작업이 있음
TDD 준수	25%	테스트 우선 워크플로우 적용
의존성 및 순서	20%	올바른 의존성, 순환 없음
작업 세분성	15%	원자적, 적절한 범위
병렬화 및 파일	10%	올바른 마커 및 경로

예시:

You: /review-tasks

AI:  작업 분해 리뷰 중...

     # 작업 리뷰 보고서

     ## 요약
     - **전체 상태**: ⚠️ 작업 필요
     - **품질 점수**: 78/100
     - **총 작업**: 24개
     - **병렬화 가능**: 8개 (33%)

     ## TDD 준수
     | 컴포넌트 | 테스트 작업 | 구현 전 테스트 | 상태 |
     |-----------|-----------|------------------|--------|
     | Task Entity | ✅ | ✅ | ✅ |
     | User Entity | ✅ | ✅ | ✅ |
     | TaskService | ❌ 누락 | 해당 없음 | ❌ |

     ## TDD 위반
     - [TDD-001]: TaskService에 테스트 작업 누락

     ## 의존성 문제
     - [DEP-001]: Task 2.5가 [P]로 표시되었지만 2.4에 의존

     ## 권장사항
     1. 구현 전 TaskService에 대한 테스트 작업 추가
     2. Task 2.5의 병렬화 마커 수정

     /implement-tasks 전에 문제 수정

팁:

/implement-tasks 전에 실행
TDD 위반은 코드 품질에 치명적
병렬화 마커가 정확한지 확인
파일 경로가 프로젝트 구조와 일치하는지 검증

`/analyze`¶

spec.md, plan.md, tasks.md에 걸쳐 비파괴적인 교차 산출물 일관성 분석을 수행합니다. 불일치, 중복 및 커버리지 간극을 식별합니다.

구문:

/analyze

인자:

인자	필수	설명
없음	-	현재 기능의 산출물 분석

수행 작업:

산출물 간 중복 감지
측정 가능한 기준이 없는 모호성 식별
불충분하게 명시된 항목 발견
constitution 정렬 확인
작업에 대한 요구사항 커버리지 매핑
용어 및 순서의 불일치 보고

심각도 수준:

수준	정의
CRITICAL	Constitution 위반, 핵심 산출물 누락, 제로 커버리지
HIGH	중복/충돌하는 요구사항, 모호한 보안 속성
MEDIUM	용어 표류, 비기능 커버리지 누락
LOW	스타일/표현 개선

예시:

You: /analyze

AI:  산출물 분석 중...

     # 명세서 분석 보고서

     ## 커버리지 요약
     | 요구사항 키 | 작업 있음? | 작업 ID |
     |-----------------|-----------|----------|
     | REQ-001 | ✅ | 2.1, 2.2 |
     | REQ-002 | ✅ | 2.3, 2.4 |
     | REQ-003 | ❌ | 없음 |

     ## 발견된 문제

     | ID | 카테고리 | 심각도 | 요약 |
     |----|----------|----------|---------|
     | A1 | 커버리지 | CRITICAL | REQ-003에 작업 커버리지 없음 |
     | A2 | 중복 | HIGH | REQ-005와 REQ-008이 중복됨 |
     | A3 | 모호성 | MEDIUM | NFR-002의 "보안"이 정의되지 않음 |

     ## 메트릭
     - 총 요구사항: 12개
     - 총 작업: 24개
     - 커버리지: 92% (11/12 요구사항)
     - 치명적 문제: 1개

     ## 다음 작업
     1. REQ-003에 대한 작업 추가 (CRITICAL)
     2. REQ-005와 REQ-008 병합 고려
     3. NFR-002에서 "보안" 정의

     /implement-tasks 전에 CRITICAL 문제 해결

팁:

/plan-to-tasks 후, 구현 전에 실행
CRITICAL 문제는 구현을 차단해야 함
읽기 전용 분석 - 파일이 수정되지 않음
발견 사항을 사용하여 산출물 품질 개선

`/checklist`¶

요구사항 완전성, 명확성 및 일관성 검증을 위한 품질 체크리스트를 생성합니다. 이는 "요구사항 작성을 위한 단위 테스트"입니다.

구문:

/checklist [집중_영역]

인자:

인자	필수	설명
`집중_영역`	아니오	도메인 중점 (예: "ux", "api", "security", "performance")

수행 작업:

품질 차원별로 구성된 체크리스트 생성
FEATURE_DIR/checklists/ 디렉토리에 체크리스트 생성
항목은 구현 테스트가 아닌 요구사항 품질에 중점

품질 차원:

요구사항 완전성: 필요한 모든 요구사항이 있는가?
요구사항 명확성: 요구사항이 구체적이고 모호하지 않은가?
요구사항 일관성: 요구사항이 충돌 없이 정렬되는가?
수락 기준 품질: 성공 기준이 측정 가능한가?
시나리오 커버리지: 모든 흐름/케이스가 다루어졌는가?
경계 사례 커버리지: 경계 조건이 정의되었는가?
비기능 요구사항: 성능, 보안, 접근성이 명시되었는가?
의존성 및 가정: 문서화되었는가?

체크리스트 유형 예시:

ux.md - 시각적 계층, 상호작용 상태, 접근성
api.md - 오류 형식, 속도 제한, 인증
security.md - 데이터 보호, 위협 모델, 유출 대응
performance.md - 메트릭, 부하 조건, 저하

예시:

You: /checklist security

AI:  보안 체크리스트 생성 중...

     ✓ .codexspec/specs/001-task-management/checklists/security.md 생성됨

     ## 보안 요구사항 품질 체크리스트

     ### 인증 요구사항
     - [ ] CHK001 - 모든 보호된 엔드포인트에 대한 인증 요구사항이 정의되었는가? [완전성]
     - [ ] CHK002 - 비밀번호 복잡성이 명시적으로 지정되었는가? [명확성]
     - [ ] CHK003 - 세션 시간 초과 요구사항이 정량화되었는가? [측정 가능성]

     ### 데이터 보호
     - [ ] CHK004 - 저장 시 데이터 암호화 요구사항이 지정되었는가? [완전성]
     - [ ] CHK005 - 전송 중 데이터 암호화 요구사항이 지정되었는가? [완전성]
     - [ ] CHK006 - PII 처리가 명시적으로 문서화되었는가? [명확성]

     총: 4개 카테고리에 걸쳐 15개 항목

팁:

체크리스트는 구현 정확성이 아닌 요구사항 품질 검증
요구사항 리뷰 및 개선에 사용
집중된 검증을 위한 도메인별 체크리스트 생성
기술 계획 진행 전에 실행

`/tasks-to-issues`¶

tasks.md의 작업을 프로젝트 추적 및 협업을 위한 GitHub 이슈로 변환합니다.

구문:

/tasks-to-issues

인자:

인자	필수	설명
없음	-	현재 기능의 모든 작업 변환

수행 작업:

작업 ID, 설명, 의존성 및 파일 경로 파싱
구조화된 본문이 있는 GitHub 이슈 생성
작업 유형에 따라 레이블 추가 (setup, implementation, testing, documentation)
이슈 간 의존성 연결
URL과 함께 생성된 이슈 보고

사전 요구사항:

GitHub remote가 있는 Git 저장소
GitHub CLI (gh)가 설치되고 인증됨
tasks.md 파일이 존재

예시:

You: /tasks-to-issues

AI:  작업을 GitHub 이슈로 변환 중...

     저장소: github.com/example/taskman

     이슈 생성 중:
     ✓ #42: Task 1.1 - 프로젝트 구조 설정 (setup)
     ✓ #43: Task 2.1 - Task Entity 테스트 작성 (testing)
     ✓ #44: Task 2.2 - Task Entity 구현 (implementation)
     ...

     요약:
     - 생성된 이슈: 24개
     - 적용된 레이블: setup(4), implementation(12), testing(5), documentation(3)
     - 연결된 의존성: 18개

     이슈 보기: https://github.com/example/taskman/issues

팁:

GitHub CLI 인증 필요 (gh auth login)
GitHub 저장소에서만 작동
저장소의 기본 구성에 이슈 생성
실행 전에 중복 확인

`/codexspec:commit-staged`¶

스테이징된 git 변경을 기반으로 Conventional Commits 호환 커밋 메시지를 생성하며, 세션 컨텍스트 인식 기능을 갖추고 있습니다. 이 명령은 개발 세션을 이해하여 의미 있는 커밋 메시지를 생성합니다.

구문:

/codexspec:commit-staged [-p]

인자:

인자	필수	설명
`-p`	아니오	미리보기 모드 - 커밋하지 않고 메시지 표시

수행 작업:

git diff --staged를 실행하여 스테이징된 변경 검색
의도 이해를 위해 변경과 세션 컨텍스트 분석
Conventional Commits 사양 따름
실행 모드 (기본값): 메시지 생성 후 즉시 커밋
미리보기 모드 (-p): 커밋하지 않고 메시지만 표시
스테이징된 변경이 없으면 오류 보고

예시:

You: /codexspec:commit-staged

AI:  스테이징된 변경 분석 중...

     스테이징된 파일:
     - src/auth/service.py
     - tests/test_auth.py

     생성된 커밋 메시지:
     feat(auth): 토큰 새로고침 논리 구현

     - 새로고침 토큰 생성 추가
     - 토큰 만료 처리 포함
     - 새로고침 흐름에 대한 테스트 추가

     커밋 실행 중...

     ✓ 커밋됨: def5678

미리보기 모드 예시:

You: /codexspec:commit-staged -p

AI:  미리보기 모드 - 커밋이 실행되지 않습니다

     제안된 커밋 메시지:
     feat(auth): 토큰 새로고침 논리 구현

     - 새로고침 토큰 생성 추가
     - 토큰 만료 처리 포함
     - 새로고침 흐름에 대한 테스트 추가

팁:

먼저 git add로 변경 스테이징
스테이징된 콘텐츠만 분석 - Git의 2단계 커밋 워크플로우 존중
의미 있는 커밋 메시지를 위해 세션 컨텍스트 고려
커밋 전에 미리보려면 -p 플래그 사용
기본적으로 Conventional Commits 사양 따름

워크플로우 개요¶

┌──────────────────────────────────────────────────────────────────────────┐
│                    CodexSpec 인간-AI 협업 워크플로우                       │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  1. Constitution  ──►  교차 산출물 검증과 함께                            │
│         │               프로젝트 원칙 정의                                │
│         ▼                                                                │
│  2. Specify  ───────►  요구사항 명확화를 위한 대화형 Q&A                  │
│         │               (파일 생성 안 됨 - 인간 제어)                     │
│         ▼                                                                │
│  3. Generate Spec  ─►  spec.md 문서 생성                                 │
│         │                                                                │
│         ▼                                                                │
│  ╔═══════════════════════════════════════════════════════════════════╗   │
│  ║  ★ 리뷰 게이트 1: /review-spec ★                                  ║   │
│  ║  검증: 완전성, 명확성, 테스트 가능성, Constitution                 ║   │
│  ╚═══════════════════════════════════════════════════════════════════╝   │
│         │                                                                │
│         ▼                                                                │
│  4. Clarify  ───────►  모호성 해결 (반복적)                              │
│         │               4개 대상 카테고리, 최대 5개 질문                  │
│         ▼                                                                │
│  5. Spec to Plan  ──►  다음과 함께 기술 계획 생성:                       │
│         │               • Constitutionality 리뷰 (필수)                  │
│         │               • 모듈 의존성 그래프                              │
│         ▼                                                                │
│  ╔═══════════════════════════════════════════════════════════════════╗   │
│  ║  ★ 리뷰 게이트 2: /review-plan ★                                  ║   │
│  ║  검증: Spec 정렬, 아키텍처, 기술 스택, 단계                         ║   │
│  ╚═══════════════════════════════════════════════════════════════════╝   │
│         │                                                                │
│         ▼                                                                │
│  6. Plan to Tasks  ─►  다음과 함께 원자적 작업 생성:                     │
│         │               • TDD 적용 (구현 전 테스트)                      │
│         │               • 병렬 마커 [P]                                  │
│         │               • 파일 경로 지정                                 │
│         ▼                                                                │
│  ╔═══════════════════════════════════════════════════════════════════╗   │
│  ║  ★ 리뷰 게이트 3: /review-tasks ★                                 ║   │
│  ║  검증: 커버리지, TDD 준수, 의존성, 세분성                          ║   │
│  ╚═══════════════════════════════════════════════════════════════════╝   │
│         │                                                                │
│         ▼                                                                │
│  7. Analyze  ───────►  교차 산출물 일관성 확인                           │
│         │               간극, 중복, constitution 문제 감지               │
│         ▼                                                                │
│  8. Implement  ─────►  조건부 TDD 워크플로우로 실행                      │
│                          코드: 테스트 우선 | 문서/구성: 직접              │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

핵심 포인트: 각 리뷰 게이트(★)는 더 많은 시간을 투자하기 전에 AI 출력을 검증하는 인간 체크포인트입니다. 이 게이트를 건너뛰면 종종 비용이 많이 드는 재작업으로 이어집니다.

문제 해결¶

"기능 디렉토리를 찾을 수 없음"¶

명령이 기능 디렉토리를 찾을 수 없습니다.

해결책:

먼저 codexspec init을 실행하여 프로젝트 초기화
.codexspec/specs/ 디렉토리가 존재하는지 확인
올바른 프로젝트 디렉토리에 있는지 확인

"spec.md를 찾을 수 없음"¶

명세서 파일이 아직 존재하지 않습니다.

해결책:

먼저 /specify를 실행하여 요구사항 명확화
그 다음 /generate-spec을 실행하여 spec.md 생성

"Constitution을 찾을 수 없음"¶

프로젝트 constitution이 존재하지 않습니다.

해결책:

/constitution을 실행하여 생성
Constitution은 선택 사항이지만 일관된 결정을 위해 권장

"작업 파일을 찾을 수 없음"¶

작업 분해가 존재하지 않습니다.

해결책:

먼저 /spec-to-plan을 실행했는지 확인
그 다음 /plan-to-tasks를 실행하여 tasks.md 생성

"GitHub CLI가 인증되지 않음"¶

/tasks-to-issues 명령은 GitHub 인증이 필요합니다.

해결책:

GitHub CLI 설치: brew install gh (macOS) 또는 동등한 것
인증: gh auth login
확인: gh auth status

다음 단계¶

워크플로우 - 일반적인 패턴 및 각 명령을 사용하는 시기
CLI - 프로젝트 초기화를 위한 터미널 명령

명령¶

빠른 참조¶

명령 카테고리¶

핵심 워크플로우 명령¶

리뷰 명령 (품질 게이트)¶

고급 명령¶

명령 참조¶

/constitution¶

/specify¶

/generate-spec¶

/clarify¶

/spec-to-plan¶

/plan-to-tasks¶

/implement-tasks¶

/review-spec¶

/review-plan¶

/review-tasks¶

/analyze¶

/checklist¶

/tasks-to-issues¶

/codexspec:commit-staged¶

워크플로우 개요¶

문제 해결¶

"기능 디렉토리를 찾을 수 없음"¶

"spec.md를 찾을 수 없음"¶

"Constitution을 찾을 수 없음"¶

"작업 파일을 찾을 수 없음"¶

"GitHub CLI가 인증되지 않음"¶

다음 단계¶

`/constitution`¶

`/specify`¶

`/generate-spec`¶

`/clarify`¶

`/spec-to-plan`¶

`/plan-to-tasks`¶

`/implement-tasks`¶

`/review-spec`¶

`/review-plan`¶

`/review-tasks`¶

`/analyze`¶

`/checklist`¶

`/tasks-to-issues`¶

`/codexspec:commit-staged`¶