loulanyue/spec-kit-zh

제품 시나리오와 예측 가능한 결과에 집중할 수 있게 해주는 오픈 소스(Open Source) 툴킷입니다. 모든 구현 세부 사항을 처음부터 감에 의존해 짜 맞출 필요가 없습니다.

• 🤔 명세 기반 개발(Spec-Driven Development)이란 무엇인가?
• ⚡ 빠른 시작
• 📽️ 비디오 개요
• 🚶 커뮤니티 실습 프로젝트
• 🤖 지원되는 AI 에이전트 (AI Agent)
• 🔧 specify-zh 명령어 참조
• 📚 핵심 개념
• 🌟 개발 단계
• 🎯 실험 목표
• 🔧 사전 요구 사항
• 📖 심화 읽기
• 📋 상세 프로세스
• 🔍 문제 해결 (Troubleshooting)
• 💬 지원
• 🙏 감사 인사
• ⭐ Star History
• 📄 라이선스 (License)

명세 기반 개발 (Spec-Driven Development)은 소프트웨어 개발의 시작점을 재정의합니다. 지난 수십 년 동안 코드는 개발 과정의 주인공이었고, 명세(Spec)는 종종 코딩을 시작하기 전에 임시로 세워두는 비계(Scaffolding)에 불과했습니다. 명세 기반 개발은 이 점을 변화시킵니다. 명세 자체가 실행 가능(Executable)해지며, 더 이상 구현을 가이드하는 것에 그치지 않고 계획, 작업 분해 및 최종 구현을 직접적으로 구동합니다.

요구사항부터 구현까지의 전체 프로세스를 빠르게 한 번 훑어보고 싶다면, 이 섹션을 통해 몇 분 안에 최소한의 가용 인지(Minimum Viable Cognition)를 구축할 수 있습니다.

1단계: 설치

uv tool install specify-cli-zh --from git+https://github.com/loulanyue/spec-kit-zh.git

중요 (Important)

📦 설치 패키지 명: specify-cli-zh
(pip / uv install 다운로드용)

🚀 실행 명령어: specify-zh
(터미널에서 도구 실행용)

2단계: 프로젝트 초기화

specify-zh init my-project

3단계: 검증

specify-zh check

: 이것은 이 중국어 브랜치가 Python 패키지 관리 시스템에서의 specify-cli-zh 배포 패키지 명입니다. 하지만 도구 자체를 실행할 때는 specify-cli-zh를 입력하지 마세요. : 이것은 터미널에서 실제로 실행하는 specify-zh 명령어 명입니다. 충돌을 피하기 위해 모든 명령어 접두사는 specify-zh여야 합니다. : 이것은 상위 영문 원본의 기본 명령어 명입니다. 만약 이 도구만 설치했고 환경에 충돌하는 도구가 설치되어 있지 않다면 alias를 설정할 수 있지만, 본 프로젝트의 문서와 튜토리얼에서는 항상 specify-zh라고 부를 것입니다.

시나리오	추천 명령어
장기 사용, 전역 호출 희망	uv tool install specify-cli-zh --from git+https://github.com/loulanyue/spec-kit-zh.git
임시 사용, 로컬 설치 원치 않음	uvx --from git+https://github.com/loulanyue/spec-kit-zh.git specify-zh

선호하는 설치 방식을 선택하세요:

한 번 설치하여 전역적으로 사용:

uv tool install specify-cli-zh --from git+https://github.com/loulanyue/spec-kit-zh.git

설치 완료 후 즉시 사용 가능:

# 새 프로젝트 생성
specify-zh init <PROJECT_NAME>
# 또는 기존 프로젝트에서 초기화
...

specify-cli-zh가 기본적으로 설치하는 명령어 명은 specify-zh이며, 이는 이미 설치된 다른 specify 명령어와의 충돌을 방지하기 위함입니다.

Specify 업그레이드는 업그레이드 가이드를 참조하세요. 빠른 업그레이드 명령어는 다음과 같습니다:

uv tool install specify-cli-zh --force --from git+https://github.com/loulanyue/spec-kit-zh.git

설치 없이 직접 실행:

# 새 프로젝트 생성
uvx --from git+https://github.com/loulanyue/spec-kit-zh.git specify-zh init <PROJECT_NAME>
# 또는 기존 프로젝트에서 초기화
...

지속적 설치(Persistent Installation)의 장점:

• 도구가 PATH에 유지되어 언제든 사용 가능
• 별도의 쉘(Shell) 별칭(Alias) 관리가 필요 없음
• uv tool list, uv tool upgrade, uv tool uninstall을 사용하여 더 완전한 도구 관리가 가능하며 쉘 설정이 더 간결해짐

설치 완료 후, 다음 명령어를 실행하여 CLI가 정상적으로 작동하는지 확인하세요:

specify-zh --help # 명령어 도움말을 표시하며, 브랜드명은 specify-cli-zh입니다
specify-zh version # 버전 번호와 환경 정보를 표시합니다
specify-zh check # 로컬 도구 체인(git, AI agent 등)을 점검합니다

Tip

설치 패키지명 vs 실행 명령어명

용도	명칭
pip/uv 설치 시 사용	specify-cli-zh
터미널 실행 시 사용	specify-zh

이미 존재하는 저장소(Repository)에 Spec Kit을 도입하는 경우, specify-zh init . 또는 specify-zh init --here를 우선적으로 사용하는 것을 권장합니다. 이렇게 하면 현재 디렉토리에서 즉시 초기화를 완료할 수 있습니다.

프로젝트 디렉토리에서 AI 어시스턴트를 시작하세요. 초기화가 완료되면 어시스턴트가 Spec Kit 명령어를 제공합니다.

Tip

Codex CLI의 경우, 사용자 정의 명령어는 /prompts: 네임스페이스를 사용합니다.
올바른 호출 방식은 /prompts:speckit-constitution, /prompts:speckit-specify 등입니다.
/speckit.constitution 또는 /prompts:speckit:constitution과 같이 입력하지 마세요. Codex는 해당 형식을 지원하지 않습니다.

** /speckit.constitution**을 사용하여 프로젝트의 거버넌스 원칙(Governance Principles)과 개발 가이드라인을 생성합니다. Codex CLI를 사용하는 경우, **/prompts:speckit-constitution**을 입력하세요. 이 원칙들은 이후의 모든 사양(Specification), 계획(Plan), 구현(Implementation) 단계에 관통하여 적용됩니다.

/prompts:speckit-constitution

# Claude / Gemini / 기타 agent
/speckit.constitution 코드 품질, 테스트 표준, 사용자 경험(UX) 일관성 및 성능 요구사항을 강조하는 프로젝트 원칙 생성
# Codex CLI
...

** /speckit.specify**를 사용하여 무엇을 구축할지 기술합니다. Codex CLI에 대응하는 명령어는 **/prompts:speckit-specify**입니다. 이 단계에서는 기술 스택(Tech Stack)보다는 무엇을(What) 그리고 왜(Why) 하는지에 중점을 두어야 합니다.

/prompts:speckit-specify 사진 앨범 관리를 도와주는 애플리케이션을 구축합니다. 앨범은 날짜별로 그룹화되며 홈 화면에서 드래그 앤 드롭으로 순서를 변경할 수 있습니다. 앨범 간의 중첩은 허용되지 않으며, 각 앨범 내의 사진은 타일형 미리보기 방식으로 표시됩니다.

** /speckit.plan**을 사용하여 기술 스택과 아키텍처 선택 사항을 보완합니다. Codex CLI에 대응하는 명령어는 **/prompts:speckit-plan**입니다.

/prompts:speckit-plan 애플리케이션은 Vite를 사용하며 외부 의존성을 최소화합니다. 네이티브 HTML, CSS, JavaScript를 우선적으로 사용합니다. 이미지는 원격으로 업로드하지 않으며, 메타데이터는 로컬 SQLite 데이터베이스에 저장합니다.

** /speckit.tasks**를 사용하여 실행 계획을 실행 가능한 작업 목록(Task List)으로 변환합니다. Codex CLI에 대응하는 명령어는 **/prompts:speckit-tasks**입니다.

/prompts:speckit-tasks
/speckit.tasks

** /speckit.implement**를 사용하여 계획에 따라 작업을 수행하고 기능 구현을 완료합니다. Codex CLI에 대응하는 명령어는 **/prompts:speckit-implement**입니다.

/prompts:speckit-implement
/speckit.implement

전체 단계별 설명을 확인하려면 Spec-Driven Development(사양 주도 개발) 전체 프로세스 가이드를 읽어보시기 바랍니다.

처음 접하는 경우, constitution -> specify -> plan -> tasks -> implement 순서로 진행하는 것을 권장합니다. 요구사항이 여전히 모호하다면 먼저 /speckit.clarify를 실행할 수 있으며, Codex CLI의 경우 /prompts:speckit-clarify를 사용한 후 계획 단계로 진입하면 됩니다.

Spec Kit의 작동 방식을 빠르게 이해하고 싶으신가요? 먼저 이 비디오 개요를 확인해 보세요:

다음의 커뮤니티 프로젝트들은 다양한 시나리오에서 사양 주도 개발(Specification-Driven Development)이 실제로 어떻게 사용되는지 보여줍니다:

• Greenfield .NET CLI 도구: 빈 디렉토리에서 시작하여, constitution(헌법), specify(사양 정의), plan(계획), tasks(작업) 및 다회차 implement(구현) 프로세스를 완전히 아우르는 .NET 단일 파일 시간대 도구 CLI를 구축합니다.
• Greenfield Spring Boot + React 플랫폼: REST API, 차트, 반복 추적을 포함하는 LLM 성능 분석 플랫폼을 처음부터 구축하며, clarify(명확화) 및 문서 간 일관성 분석 프로세스를 시연합니다.
• Brownfield ASP.NET CMS 확장: 기존 ASP.NET CMS 프로젝트에 두 가지 기능을 추가하여, 프로젝트 시작 시점에 기존 사양이나 constitution이 없더라도 spec-kit이 어떻게 기존 코드베이스에 적응하는지 보여줍니다.

에이전트 (Agent)	지원 여부	설명
Qoder CLI	✅
...

Tip

중국 내 주요 AI 코딩 도구(Tongyi Lingma, DeepSeek Coder, Baidu Comamate, MarsCode 등)는 모두 --ai generic 모드를 통해 접속할 수 있습니다.
자세한 내용은 '중국 대규모 언어 모델(LLM) 접속 가이드'를 참조하세요.
팀 내부에 커스텀 프롬프트 템플릿이나 명령 디렉토리가 있는 경우, --ai-commands-dir을 사용하여 기존 워크플로우에 통합할 수 있습니다.

specify-zh 명령은 다음 기능과 파라미터를 지원합니다:

명령	설명
init	최신 템플릿을 사용하여 새로운 Specify 프로젝트를 초기화합니다
version	현재 CLI 버전 및 실행 환경 정보를 표시합니다
check	로컬 머신에 필요한 도구(예: git, claude, gemini, cursor-agent, codex, kiro-cli, qodercli, vibe 등)가 설치되어 있는지 확인합니다
codex-sync	Codex 프롬프트를 다시 동기화하고, Codex에서 직접 실행 가능한 /prompts:speckit-* 명령을 표시합니다

파라미터/옵션	타입	설명
<project-name>	파라미터	새 프로젝트 디렉토리 이름 (--here 사용 시 생략 가능하며, .을 사용하여 현재 디렉토리를 나타낼 수 있음)
--ai	옵션	접속할 AI 어시스턴트: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, roo, codebuddy, amp, shai, kiro-cli (별칭 kiro), agy, bob, qodercli, tabnine, vibe 또는 generic
--ai-commands-dir	옵션	에이전트 명령 파일 디렉토리 (--ai generic과 함께 사용, 예: .myagent/commands/)
--script	옵션	사용할 스크립트 타입: sh (bash/zsh) 또는 ps (PowerShell)
--ignore-agent-tools	플래그	Claude Code와 같은 AI 도구에 대한 검사를 건너뜁니다
--no-git	플래그	git 저장소 초기화를 건너뜁니다
--here	플래그	새 디렉토리를 생성하는 대신 현재 디렉토리에서 직접 초기화합니다
--force	플래그	현재 디렉토리가 비어 있지 않을 때 확인 절차를 건너뛰고 강제로 병합/덮어씁니다
--skip-tls	플래그	SSL/TLS 검증을 건너뜁니다 (권장하지 않음)
--debug	플래그	상세 디버그 출력을 활성화하여 문제 해결을 용이하게 합니다
--github-token	옵션	GitHub API 요청에 사용할 토큰 (또는 GH_TOKEN / GITHUB_TOKEN 환경 변수를 통해 전달 가능)
--ai-skills	플래그	Prompt.MD 템플릿을 에이전트 전용 skills/ 디렉토리에 설치합니다 (--ai와 함께 사용 필요)

# 기본 프로젝트 초기화
specify-zh init my-project
# 지정된 AI 어시스턴트로 초기화
...

기본적으로 specify-zh init을 실행한 후, 귀하의 AI 코드 에이전트는 구조화된 개발을 위한 다음과 같은 슬래시(/) 명령어를 얻게 됩니다.

Important

--ai-skills를 사용한 경우, 설치 결과는 /speckit.* 형태가 아닌 skills 형태로 나타납니다.

슬래시 명령(Slash command) 형태입니다.
특히 Codex의 경우: 이때는 보통 .codex/prompts/ 대신 .agents/skills/speckit-* 형태를 보게 됩니다.

Codex CLI의 사용자 정의 명령 실행 형식은 /speckit.constitution이 아니라 /prompts:speckit-constitution (/prompts: + 파일명)입니다.

명세 기반 개발 (Spec-Driven Development) 프로세스를 위한 필수 명령:

권장 순서: 먼저 /speckit.constitution을 사용하여 거버넌스 원칙을 명확히 정의한 다음, 단계적으로 /speckit.specify, /speckit.plan, /speckit.tasks 및 /speckit.implement로 진행하세요. 만약 Codex CLI를 사용 중이라면, 각각을 /prompts:speckit-constitution, /prompts:speckit-specify, /prompts:speckit-plan, /prompts:speckit-tasks, /prompts:speckit-implement로 대체하여 사용하십시오.

명령	설명
/speckit.constitution	프로젝트 거버넌스 원칙 및 개발 가이드라인 생성 또는 업데이트
/speckit.specify	무엇을 구축할 것인지 정의 (요구사항 및 사용자 스토리)
/speckit.plan	선택된 기술 스택을 포함하는 기술 구현 계획 생성
/speckit.tasks	실행 가능한 작업 목록 생성
/speckit.implement	모든 작업을 실행하여 계획에 따라 기능 구축

품질 향상 및 검증을 위한 추가 명령:

명령	설명
/speckit.clarify	설명이 부족한 부분을 명확히 함 (/speckit.plan 이전에 사용 권장; 기존 /quizme 명령)
/speckit.analyze	아티팩트(Artifact) 간의 일관성 및 커버리지 분석 (/speckit.tasks 이후, /speckit.implement 이전에 실행)
/speckit.checklist	요구사항의 완전성, 명확성 및 일관성을 검증하기 위한 사용자 정의 품질 체크리스트 생성 ("자연어 버전의 단위 테스트"와 유사)

Tip

위 표는 일반적인 슬래시 명령 (slash command) 작성법을 사용합니다. Codex CLI에서 실행할 경우, /speckit.<name>을 /prompts:speckit-<name>으로 바꾸십시오.

변수	설명
SPECIFY_FEATURE	Git 저장소가 아닌 경우, 기능(feature) 브랜치 감지를 덮어씁니다. Git 브랜치를 사용하지 않고 특정 기능을 개발할 수 있도록 이를 기능 디렉토리 이름(예: 001-photo-albums)으로 설정하십시오. 반드시 /speckit.plan (Codex CLI에서는 /prompts:speckit-plan) 또는 후속 명령을 사용하기 전, 에이전트(Agent)와 상호작용하는 컨텍스트 내에서 이 변수를 설정해야 합니다.

명세 기반 개발 (Spec-Driven Development)은 다음 사항을 강조하는 구조화된 프로세스입니다:

의도 기반 개발 (Intent-driven development): 명세(Specification)가 구현(Implementation)보다 우선하며, 먼저 "무엇을 할 것인가"(what)를 정의한 다음 "어떻게 할 것인가"(how)를 정의합니다.
풍부한 명세 생성: 가드레일(Guardrails)과 조직 원칙을 사용하여 제약 조건을 설정합니다.
다단계 반복 정교화: 프롬프트(Prompt)를 통해 한 번에 코드를 생성하기를 기대하는 대신 단계를 거쳐 발전시킵니다.
고급 AI 모델에 대한 높은 의존도: 명세를 해석하는 고급 AI 모델의 능력을 활용합니다.

단계	중점 사항	주요 활동
0에서 1 개발 ("Greenfield")	무에서 유 생성	창의적 탐색
병렬 구현
반복적 강화 ("Brownfield")	기존 시스템 현대화

우리의 연구와 실험은 주로 다음 측면에 집중되어 있습니다:

• 다양한 기술 스택을 사용하여 애플리케이션 생성

• "명세 기반 개발은 특정 기술, 프로그래밍 언어 또는 프레임워크에 종속되지 않는 프로세스이다"라는 가설 검증

• 핵심 비즈니스 애플리케이션의 개발 시연

• 조직 구조적 제약(클라우드 제공업체, 기술 스택, 엔지니어링 관행) 결합

• 기업 디자인 시스템 및 컴플라이언스 요구사항 지원

• 다양한 사용자 그룹과 선호도에 맞는 애플리케이션 구축

• 다양한 개발 방식 지원 (Vibe-coding부터 AI 네이티브 개발까지)

• 병렬 실험 및 대비 구현 개념의 타당성 검증

• 견고한 반복적 기능 개발 워크플로우 제공

• 업그레이드 및 현대화 리팩토링 작업을 처리할 수 있도록 프로세스 확장

Linux / macOS / Windows

• 지원되는 AI 코딩 에이전트
• 패키지 관리를 위한 uv
• Python 3.11+
• Git

네트워크 환경이 제한적인 경우, 초기화 및 업그레이드 시 대기 시간을 줄이기 위해 GitHub 접속 프록시(Proxy)를 미리 준비하거나 설치 단계에서 미러 서버(Mirror source)를 구성하는 것을 권장합니다.

Agent 도구 통합 과정에서 문제가 발생하면 Issue를 제출해 주세요. 통합 경험을 지속적으로 최적화할 수 있도록 노력하겠습니다.

완전한 규격 기반 개발 (Specification-Driven Development) 방법론

• 전체 워크플로우(Workflow)에 대한 심층 이해
  상세 실습 프로세스
• 단계별 조작 가이드
  이전 버전에서 마이그레이션
• 기존 spec-kit 등으로부터의 마이그레이션 가이드
  업그레이드 가이드
• 버전 업그레이드 권장 사항 및 일반적인 변경 사항 처리 방식 확인

클릭하여 단계별 상세 실습 프로세스 펼치기

specify-cli-zh 툴킷을 사용하여 specify-zh 명령어로 프로젝트를 가이드할 수 있습니다. 다음을 실행하세요:

specify-zh init <project_name>

또는 현재 디렉토리에서 초기화하려면:

specify-zh init .
# 또는 --here 플래그 사용
specify-zh init --here
...

사용 중인 AI 에이전트(Agent)를 선택하라는 메시지가 표시됩니다. 터미널에서 직접 지정할 수도 있습니다:

specify-zh init <project_name> --ai claude
specify-zh init <project_name> --ai gemini
specify-zh init <project_name> --ai copilot
...

specify-zh 명령은 대응하는 CLI 도구(예: Claude Code, Gemini CLI, Cursor 등)가 설치되어 있는지 확인합니다. 해당 도구가 없거나 도구 검사를 원하지 않는 경우, 명령에 --ignore-agent-tools 플래그를 추가하여 검사를 강제로 건너뛸 수 있습니다:

specify-zh init <project_name> --ai claude --ignore-agent-tools

프로젝트 폴더로 이동하여 AI 에이전트 프로그램을 실행하세요. 예시에서는 claude를 사용합니다.

Codex CLI에서 /prompts:speckit-constitution, /prompts:speckit-specify, /prompts:speckit-plan, /prompts:speckit-tasks 및 /prompts:speckit-implement 등의 명령어가 나타나면 설정이 올바르게 완료된 것입니다.

[!IMPORTANT] Codex CLI의 커스텀 명령어 형식은 /prompts:<파일명>이 아니라 /speckit.xxx 또는 /speckit:xxx입니다. 예를 들어 ~/.codex/prompts/speckit-constitution.md에 대응하는 명령어는 /prompts:speckit-constitution입니다.

Codex의 경우, 전역 프롬프트(Global prompts) 디렉토리에 다음 파일들이 존재하는지 우선적으로 확인하십시오:

ls -la ~/.codex/prompts/

정상적인 경우 다음과 같은 파일들이 보일 것입니다:

speckit-constitution.md
speckit-specify.md
speckit-plan.md
...

specify-zh는 이제 Codex 프로젝트를 초기화할 때 이러한 프롬프트들을 ~/.codex/prompts/로 동기화합니다. 프로젝트 내의 .codex/prompts/는 호환성을 위한 복사본으로만 유지됩니다.

만약 Codex에서 여전히 명령어를 인식하지 못한다고 표시되면, 프로젝트 디렉토리에서 다음을 실행하십시오:

specify-zh codex-sync --project .

이 명령은 프로젝트 내부와 전역 프롬프트를 다시 동기화하며, Codex에서 사용해야 할 /prompts:speckit-* 명령어 목록을 나열합니다.

초기화 시 --ai-skills를 사용했다면, Codex의 경우 다음을 확인하는 것이 더 중요합니다:

ls -la .agents/skills/

정상적인 경우 다음과 같이 보일 것입니다:

speckit-constitution/
speckit-specify/
speckit-plan/
...

이 경우 더 이상 /prompts:speckit-constitution을 사용하지 마십시오. 대신 대화 중에 직접 스킬(Skill)의 이름을 언급하는 것이 더 적절합니다. 예:

speckit-constitution 스킬을 사용하여 코드 품질, 테스트 표준, 사용자 경험 일관성 및 성능 요구 사항을 강조하는 프로젝트 원칙을 생성해줘.

개발의 첫 단계는 해당 프로젝트의 헌장(Constitution)을 수립하는 것입니다. Codex CLI에서는 /prompts:speckit-constitution을 사용하고, 다른 에이전트에서는 /speckit.constitution을 사용하십시오.

이는 이후의 모든 단계에서 기술적 결정과 성능이 일관성을 유지하도록 보장합니다.

# Codex CLI
/prompts:speckit-constitution 코드 품질, 테스트 표준, 사용자 경험(UX) 일관성 및 성능 요구 사항에 집중하는 프로젝트 헌장(Project Charter)을 수립합니다.
# Claude / Gemini / 기타 agent
...

이 단계는 .specify/memory/constitution.md 파일에 기초 헌장을 생성합니다. AI 에이전트는 이후의 사양 정의(Specification Definition), 구현 계획(Implementation Planning) 및 구체적인 실행 단계에서 이 파일을 반복적으로 참조하게 됩니다.

프로젝트 원칙을 확립했다면, 기능 요구 사항의 개요를 구상하기 시작할 수 있습니다. 일반적인 작성 방식은 /speckit.specify이며, Codex CLI를 사용 중이라면 /prompts:speckit-specify를 사용하십시오.

[!IMPORTANT] 당신이 무엇을 구축하려고 하는지, 그리고 왜 그것을 구축해야 하는지를 가능한 한 명확하게 설명하십시오. 이때 기술 스택(Tech Stack)에 집중하지 마십시오.

프롬프트(Prompt) 입력 예시:

팀 생산성 플랫폼인 Taskify를 개발합니다. 사용자가 프로젝트를 생성하고, 팀원을 추가하며, 작업을 할당하고, 칸반(Kanban) 보드를 가로질러 댓글을 남기거나 작업을 드래그 앤 드롭(Drag-and-drop)할 수 있도록 합니다. 이 기능의 초기 개발 단계(이 단계를 "Taskify 생성"이라고 부릅시다)에서는 먼저 5명의 고정 사용자를 사전 설정합니다: 제품 관리자(PM) 1명과 엔지니어 4명입니다. 3개의 샘플 프로젝트를 생성합니다. "할 일(To Do)", "진행 중(In Progress)", "검토 중(In Review)", "완료(Done)"와 같은 표준 칸반 상태 열을 포함해야 합니다. 첫 번째 버전에서는 로그인 모듈을 만들지 않습니다. 작업 카드 UI에서는 상태를 변경할 수 있어야 합니다(다른 열로 드래그하거나 전환). 임의의 카드에 무제한의 댓글을 남길 수 있고 사용자를 할당할 수 있어야 합니다...

이 프롬프트를 보내면 AI가 사양 초안(Specification Draft) 작성을 시작하는 것을 볼 수 있습니다. 이 기능을 제공하는 CLI의 경우, 자동으로 Git 브랜치를 생성하는 것과 같이 내장된 새로운 기능 생성 쉘 스크립트(Shell Script)를 실행할 수도 있습니다.

이 작업이 완료되면 새로운 코드 브랜치(예: 001-create-taskify)가 생성되고, specs/001-create-taskify 아래에 템플릿으로 정의된 다양한 사용자 스토리(User Story)와 수락 기준(Acceptance Criteria)을 포함한 완전한 요구 사항 사양 세트가 생성된 것을 확인할 수 있습니다.

이 시점의 프로젝트 디렉토리 구조는 대략 다음과 같습니다:

└── .specify
├── memory
│ └── constitution.md
...

기초 사양 설명이 생성되면, 첫 번째 요청에서 정확하게 포착되지 않은 요구 사항들을 단계적으로 명확히 하기 시작할 수 있습니다.

이후 발생할 수 있는 재작업(Rework)을 최소화하기 위해, 구현 계획을 수립하기 전에 명확화 워크플로우(Clarification Workflow)를 실행해야 합니다.

권장되는 단계별 방법론은 다음과 같습니다:

• /speckit.clarify (Codex CLI에서는 /prompts:speckit-clarify에 해당)를 사용하십시오. 이는 세부 사항을 정리하기 위해 커버리지를 보완하는 질문을 점진적으로 제공하며, 답변은 "Clarifications" 섹션에 기록됩니다. - (선택 사항) 자유로운 대화를 통해 임의의 세부 사항을 보충하는 것도 여전히 허용됩니다.

만약 프로토타입 탐색이나 가벼운 요구 사항 때문에 이 단계를 의도적으로 건너뛰고 싶다면, 명시적으로 명확화가 필요 없다고 선언할 수도 있습니다.

모든 보충 세부 사항을 완료한 후에는, AI에게 본 사양을 바탕으로 생성된 **Review & Acceptance Checklist (검토 및 수락 체크리스트)**를 하나씩 확인하며 체크해 달라고 요청할 수 있습니다.

프롬프트 예시:

수락 기준(Acceptance Criteria) 체크리스트를 읽고 항목별로 점검하십시오. 현재 사양 문서가 해당 체크 항목의 판정 요구 사항을 충분히 충족하면 체크 표시를 하십시오. 충족하지 못하면 빈칸으로 두십시오.

AI와 함께 구축하는 과정을 요구 사항을 명확히 하고 역질문을 던지는 기회로 간주하십시오. AI가 출력한 초안을 최종본으로 간주해서는 절대 안 됩니다.

요구 사항 정리가 완료되었으므로, 이제 기술 스택 및 기타 기술 요구 사항을 구체적으로 논의할 수 있습니다. /speckit.plan 명령을 사용하십시오. Codex CLI를 사용 중이라면 해당 명령은 /prompts:speckit-plan입니다. 여기에 당신의 기술적 선호도를 담은 프롬프트를 추가하십시오:

.NET Aspire와 Postgres 데이터베이스를 사용하여 이 프로젝트를 구축하기를 희망합니다. 프론트엔드 애플리케이션은 Blazor Server를 사용하며, 드래그 앤 드롭 컴포넌트를 활용하여 작업 칸반 상호작용을 구현하고 실시간 렌더링 업데이트를 달성합니다. projects/tasks/notifications를 지원하는 REST API 백엔드 서비스를 구축하십시오.

이때의 출력물은 단순한 구현 계획뿐만 아니라 구현 세부 사항 파일(Implementation Details Files) 세트를 동반합니다. 이때의 파일 트리는 다음과 같습니다:

.
├── CLAUDE.md
├── memory
...

생성된 research.md 문서를 검토하여, AI가 당신의 지침에 따라 올바른 기술 스택을 선택했는지 확인하십시오. 만약 일부 세부 사항이 적절하지 않아 보인다면, AI에게 다시 생각하도록 요청하거나 로컬에 설치된 프레임워크 버전의 자료(Documentation)를 읽도록 지시할 수 있습니다.

또한, 빈번하게 변경되는 기술 스택(예: 최신 버전의 .NET 또는 최신 프론트엔드 프레임워크)의 경우, AI에게 계획과 병행하여 능동적으로 연구 검색(Research Search)을 수행하도록 요청할 수 있습니다. 예시 프롬프트:

"plan.md(실행 계획)와 각 구현 세부 사항 문서를 통독하여, 외부 검색 연구를 통해 이득을 얻을 수 있는 기술적 세부 사항을 찾아내길 바랍니다. .NET Aspire의 라이브러리 변경은 매우 빠르게 이루어지는 경우가 많기 때문입니다. 심층 조사가 필요한 이러한 세부 작업들을 찾아낸 후, 연구 문서(research.md)를 업데이트하여 이번 애플리케이션에 채택될 정확한 프레임워크 버전을 조사하고 확인하십시오. 이를 바탕으로 그에 상응하는 연구 세부 작업을 생성하고 연구 작업을 시작하십시오."

이 과정에서 AI가 쓸모없는 지식을 연구하고 있다는 사실을 발견할 수 있습니다. 이럴 때 다음과 같은 프롬프트를 사용하여 AI의 범위를 좁히고 올바른 방향으로 유도할 수 있습니다:

"단계를 몇 가지로 나누어야 할 것 같습니다. 우선, 개발 예정이지만 아직 명확하지 않아 추가 조사가 필요한 하위 작업 목록을 작성하십시오(예: 조사해야 할 API만 작성). 그런 다음 목록의 내용에 따라 각각 독립적인 연구 작업을 시작하십시오. 요컨대, 우리는 각각의 특정한 불확실한 지점들을 개별적으로 확인하기만 하면 됩니다. 방금 당신이 한참 동안 늘어놓은 일반론적인 이야기들은 갈팡질팡하는 쓸모없는 정보일 뿐입니다. 조사는 개발 과정에서의 매우 구체적인 의문점을 해결해 주어야 하며, 포괄적인 개요를 나열하는 것이 아니어야 합니다."

[!NOTE] AI는 당신이 생각지도 못한 새로운 컨트롤(Control)을 멋대로 추가할 수도 있습니다. 즉시 이를 지적하고, 독단적인 변경 사항에 대해 합리적인 설명을 요구하십시오.

계획이 생성된 후에는 단절되거나 구현이 누락된 항목이 없도록 즉시 AI가 논리를 여러 번 다시 검토하게 해야 합니다. 다음과 같은 프롬프트를 사용할 수 있습니다:

"이제 앞뒤 실행 계획과 모든 부속 문서 자료를 한 차례 감사(Audit)하십시오. 당연해 보이는 암묵적인 작업들이 실제로는 단절될 위험이 있는지 판단하기 위해 주의 깊게 읽으십시오(이 계획이 절차대로 실행될 수 있을지 확신할 수 없기 때문입니다). 예를 들어, 핵심 계층(Core layer)에 특정 기능이 명시되어 있는데, 대응하는 문서에서 구현과 관련된 조항을 전혀 찾을 수 없다면 문제가 될 것입니다. 감사를 수행하십시오."

이 동작은 AI가 자기 계획의 폐쇄 루프 안에서 '장님 코끼리 만지기'식으로 발생하는 고질적인 문제를 매우 효과적으로 방지해 줍니다. 기초 검토가 완료되면, 반드시 해당 체크리스트(Checklist)에서 다시 한번 확인하도록 하여 안심하고 코딩 단계로 넘어갈 수 있도록 하십시오.

[!NOTE] 이는 AI가 '과잉 엔지니어링 (Over-engineering)'을 하거나 황당한 리팩토링(Refactoring) 방안을 지어내는 것을 막는 훌륭한 방어선입니다 (이 모델들이 모두 과시하기를 좋아한다는 점을 잊지 마세요). constitution.md(헌장 내에 약속된 프로젝트 핵심 원칙)에 명시된 규율 조항을 주의 깊게 살펴보라고 반복해서 강조하고, 작업을 중단하도록 명령할 수 있습니다.

기술 계획이 검증되고 확정되면, 프로젝트의 방대한 청사진을 명확한 순서가 있고 구체적이며 실제로 실행 가능한 일정 목록으로 압축할 수 있습니다. /speckit.tasks를 사용하십시오. 만약 Codex CLI를 사용 중이라면, 해당 명령은 /prompts:speckit-tasks입니다.

/speckit.tasks