구조화된 프롬프트 기반 개발 (Structured Prompt-Driven Development) — AI 코딩 프롬프트를 실행 가능한 설계 계약으로 변환하기

OpenSPDD는 AI 코딩 시대를 위한 방법론이자 크로스 플랫폼 CLI (Command Line Interface) 도구입니다. 이는 설계와 구현 사이의 양방향 동기화를 통해 AI 코딩 프롬프트를 "일회성 입력값"에서 "실행 가능한 설계 계약 (executable design contracts)"으로 업그레이드합니다.

기존의 AI 코딩 도구들은 계획 문서 (plan documents)를 생성하지만, 이러한 문서들은 근본적인 한계를 가지고 있습니다:

문제점	일반적인 계획 문서 (Typical Plan Documents)	REASONS Canvas
성격 (Nature)	작업 목록 (Task list)	설계 계약 (Design contract)
제약 사항 (Constraints)	없음 — AI가 자유롭게 임의로 수행	명시적 — 규범 (Norms)이 "방법"을 정의하고, 안전장치 (Safeguards)가 "하지 말아야 할 것"을 정의
상세 수준 (Detail Level)	상위 수준: "BillingService 생성"	정밀함: 메서드 시그니처 (method signatures), 파라미터 (parameters), 에러 핸들링 (error handling), DI (Dependency Injection) 패턴
추적 가능성 (Traceability)	없음 — 문서가 코드와 함께 업데이트되지 않음	있음 — /spdd-sync를 통해 역방향 동기화 가능
검증 (Validation)	모호함 — "완료되면 끝"	명시적 — 안전장치 (Safeguards) 내의 정확한 에러 메시지, HTTP 상태 코드
의존성 (Dependencies)	암시적 — AI가 추론함	명시적 — 작업 (Operations)이 엄격한 실행 순서를 정의

핵심 통찰 (The core insight): 계획은 "제안"이지만, REASONS Canvas는 "계약"입니다.

REASONS Canvas는 7차원 구조화 설계 프레임워크입니다:

┌─────────────────────────────────────────────────────────────────────┐
│ REASONS Canvas │
├─────────────────────────────────────────────────────────────────────┤
...

왜 7차원인가?

R+E+A = 설계 결정 ("왜" 그리고 "무엇을")
S+O = 구현 경로 ("어떻게")
N+S = 품질 가드레일 (Quality guardrails)

이 세 가지 모두 필수적입니다. N+S가 없으면 AI가 임의로 수행하고, S+O가 없으면 AI가 마음대로 구조를 재편하며, R+E+A가 없으면 AI에게 맥락 (context)이 부족해집니다.

┌─────────────────────────────────────────────────────────────────────┐
│ SPDD Workflow │
├─────────────────────────────────────────────────────────────────────┤
...

핵심 원칙: "현실이 (설계와) 달라질 때는, 코드를 업데이트하기 전에 프롬프트를 먼저 수정하라."

교차 플랫폼 (Cross-platform): Cursor, Claude Code, GitHub Copilot, Antigravity, OpenCode, Codex 지원
자동 감지 (Auto-detection): 사용자의 AI 코딩 환경을 자동으로 감지
단일 바이너리 (Single Binary): Go의 embed 지시어를 통해 모든 템플릿을 내장
양방향 동기화 (Bidirectional Sync): 설계 문서와 코드를 동기화된 상태로 유지
대화형 UI (Interactive UI): 명령 선택을 위한 현대적인 터미널 UI 제공

brew install gszhangwei/tools/openspdd

또는:

brew tap gszhangwei/tools
brew install openspdd

go install github.com/gszhangwei/open-spdd/cmd/openspdd@latest

바이너리는 $(go env GOPATH)/bin/openspdd에 설치됩니다.

(일반적으로 ~/go/bin/openspdd입니다.) 해당 디렉토리가 $PATH에 포함되어 있는지 확인하십시오.

# zsh
echo 'export PATH="$(go env GOPATH)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
# bash
...

openspdd를 처음 실행할 때, 시스템이 이를 감지하여 사용자의 쉘에 맞는 정확한 명령어가 포함된 일회성 힌트를 출력합니다.

만약 리포지토리(repo)를 클론(clone)했다면, scripts/install.sh 스크립트가 go install을 실행하고 PATH 안내를 자동으로 출력합니다:

./scripts/install.sh # @latest 버전을 설치합니다
./scripts/install.sh v1.2.3 # 특정 태그(tag) 버전을 설치합니다

GitHub Releases에서 다운로드할 수 있습니다.

openspdd uninstall은 바이너리가 어떻게 설치되었는지(Homebrew 또는 go install)를 감지하여 그에 맞는 정리 작업을 수행합니다. 모든 변경 사항은 실행 전 계획(plan)이 출력되며, 기본적으로 확인 절차가 필요합니다.

# 아무것도 변경하지 않고 미리보기
openspdd uninstall --dry-run
# 대화형 (기본값): 계획을 출력하고 확인을 요청합니다
...

Homebrew로 설치한 경우, 이는 brew uninstall gszhangwei/tools/openspdd를 실행하는 것과 더불어 첫 실행 마커(first-run-marker)를 정리하는 작업과 동일합니다. go install로 설치한 경우, 해결된 경로(resolved path)에 있는 바이너리를 제거합니다. 만약 설치 방법을 분류할 수 없는 경우(예: 수동으로 복사한 바이너리), uninstall은 동작을 거부하고 사용자가 수동으로 제거할 수 있도록 해결된 경로를 출력합니다.

범위: openspdd 바이너리와 openspdd 자체의 첫 실행 마커(first-run marker)만 제거됩니다. 프로젝트 내부에 생성된 SPDD 명령 템플릿(.cursor/commands/spdd-*.md, .claude/commands/spdd-*.md 등)은 사용자 파일이므로 그대로 유지됩니다. Homebrew tap인 gszhangwei/tools 또한 그대로 유지됩니다.

# 설치된 버전 출력
openspdd -v
# 프로젝트로 이동
...

그 다음, 사용 중인 AI 코딩 도구에서 전체 SPDD 워크플로우(workflow)를 따르세요:

# 1단계: 전략적 분석 (복잡한 기능 구현 시 권장)
/spdd-analysis @requirements/user-registration.md
# 2단계: 분석 결과로부터 REASONS Canvas 생성
...

더 간단한 기능의 경우, 1단계를 건너뛰고 요구사항을 직접 제공할 수 있습니다:

/spdd-reasons-canvas 이메일 인증을 포함한 사용자 등록 구현

# 자동 감지 및 초기화
openspdd init
# 도구를 수동으로 지정
...

# 사용 가능한 명령 목록 표시 (코어 + 도구별 명령)
openspdd list
# 선택적 명령 목록 표시
...

# 모든 기본 명령 생성
openspdd generate --all
# 대화형 선택
...

openspdd --tool cursor <command>
openspdd --tool claude-code <command>
openspdd --tool antigravity <command>
...

도구 (Tool)	감지 (Detection)	설정 디렉토리 (Config Directory)
Cursor	.cursor/ , .cursorrules	.cursor/commands/
Claude Code	.claude/ , CLAUDE.md	.claude/commands/
Antigravity	.antigravity/	.antigravity/commands/
GitHub Copilot	.github/copilot-instructions.md , .github/copilot-prompts/	.github/copilot-prompts/
OpenCode	.opencode/ , opencode.json	.opencode/commands/
Codex	.codex/ , .codex/config.toml	.agents/skills/

OpenCode 명령 명명 규칙은 마크다운 파일 이름을 따릅니다 (예를 들어, spdd-analysis.md는 /spdd-analysis로 매핑됩니다). OpenCode에서 명령 별칭(alias) 충돌을 방지하기 위해, 생성된 OpenCode 명령 파일은 의도적으로 프론트매터(frontmatter)의 name을 생략합니다.

Codex는 .agents/skills/<id>/SKILL.md 아래에 프로젝트 범위의 스킬 번들(skill bundles)을 생성합니다.

(벤더 간 개방형 표준 디렉토리; agentskills.io 참조) — 단순한 평면형 명령 파일이 아닙니다. Codex CLI / IDE 확장 프로그램 내에서 $spdd-analysis 명령으로 SPDD 명령을 호출하십시오.

(등등) 생성된 스킬은 기본적으로 명시적 호출(explicit-only invocation)만 가능하도록 구성됩니다 (agents/openai.yaml에서 allow_implicit_invocation: false로 설정됨).

Codex의 자동 호출(auto-invocation) 동작을 사용하려면 --allow-implicit을 전달하십시오. 신뢰 모델(Trust-model) 참고 사항: 일부 Codex 버전에서는 신뢰할 수 없는 프로젝트의 스킬이 조용히 무시됩니다. 스킬을 생성한 후에도 스킬이 나타나지 않는다면, ~/.codex/config.toml에서 해당 프로젝트가 신뢰할 수 있는 것으로 표시되어 있는지 확인하십시오 (openai/codex#9752 참조). 생성 실행 후에도 스킬이 여전히 나타나지 않으면 (공식 문서에 따라) Codex를 재시작하십시오.

.github/
├── copilot-instructions.md # 메인 지침 파일 (마커와 함께 자동 병합됨)
└── copilot-prompts/
...

명령 (Command)	설명 (Description)
spdd-analysis	요구사항에 대한 전략적 분석
spdd-reasons-canvas	REASONS-Canvas 구조화된 프롬프트 생성
spdd-generate	구조화된 SPDD 프롬프트 파일로부터 코드 생성
spdd-prompt-update	새로운 요구사항으로 기존 SPDD 프롬프트 업데이트
spdd-sync	코드 변경 사항을 SPDD 프롬프트 파일로 다시 동기화

도구 (Tool)	명령 (Command)	설명 (Description)
GitHub Copilot	copilot-instructions	Copilot을 위한 메인 지침 파일

다음 명령들은 베타(beta) 버전으로 제공됩니다 — 기본적으로 설치되어 있지는 않지만, 수동으로 설치할 수 있습니다:

명령 (Command)	설명 (Description)
spdd-story	기능 요구사항을 수용 기준(acceptance criteria)을 포함한 INVEST 준수 스토리로 분해
spdd-code-review	REASONS-Canvas를 기준으로 코드를 검토하여 의도 이탈(intent drift) 및 위반 사항 탐지
spdd-api-test	API 테스트를 위한 cURL 명령이 포함된 독립형 쉘 스크립트 생성
spdd-reverse	레거시 온보딩을 위해 기존 코드를 REASONS-Canvas 프롬프트로 역공학(Reverse-engineer)

# 모든 선택적 명령 목록 표시
openspdd list --optional
# 특정 선택적 명령 설치
...

시나리오 (Scenario): 사용자 등록 구현

일반적인 계획 (Typical Plan):

1. UserRegistrationController 생성
2. UserRegistrationService 생성
3. UserRegistrationRequest DTO 생성
...

REASONS Canvas (작업 발췌):

### Create UserRegistrationService - `UserRegistrationServiceImpl`
1. **책임 (Responsibility)**: 사용자 등록 비즈니스 로직 처리
2. **패키지 (Package)**: `com.example.user.service.impl`
...

차이점: 계획(Plan)은 "무엇을 할 것인가"를 말하지만, REASONS Canvas는 "정확히 어떻게 할 것인가"를 명시합니다.

시나리오 (Scenario)	권장 사항 (Recommendation)	이유 (Reason)
엔터프라이즈 기능 개발 (Enterprise feature development)	강력 권장 (Highly recommended)	설계-구현 추적성 (Design-implementation traceability), 장기적 유지보수성 (long-term maintainability)
...

`git clone https://github.com/gszhangwei/open-spdd.git`
`cd open-spdd`
`go build -o openspdd ./cmd/openspdd`
...

# 모든 테스트 실행
go test ./tests/...
# 상세 출력과 함께 실행
...