명세 기반 개발 (Spec-driven development)을 통한 자율 AI 코딩

사용 시 주의하십시오. 이 도구는 AI 에이전트에게 귀하의 코드베이스와 시스템에 대한 상당한 자율성을 부여합니다. 모든 변경 사항을 검토하고, 가능한 경우 격리된 환경에서 사용하십시오.

# Vercel의 add-skill 사용
npx add-skill fstandhartinger/ralph-wiggum
# OpenSkills 사용
...

AI 에이전트인가요? 여기서 시작하세요:

대화형 인터뷰를 통한 가이드 설치를 위해 INSTALLATION.md를 읽고 실행하십시오.

인간 개발자인가요? 여기서 시작하세요:

수동 설치 지침을 위해 INSTALL.md를 읽으십시오.

Ralph Wiggum (이 버전)은 **Geoffrey Huntley의 독창적인 반복적 bash 루프 (iterative bash loop)**와 **SpecKit 스타일의 명세 (specifications)**를 결합하여 완전히 자율적인 AI 지원 소프트웨어 개발을 구현합니다.

• 🔄 반복적 자기 수정 (Iterative Self-Correction)— 각 루프는 하나의 작업을 선택하고, 이를 구현하며, 검증하고, 커밋(commit)합니다.
• 📋 명세 기반 개발 (Spec-Driven Development)— 명확한 수락 기준 (acceptance criteria)을 포함한 전문적인 명세.
• 🎯 완료 검증 (Completion Verification)— 에이전트는 기준이 100% 충족되었을 때만 <promise>DONE</promise>를 출력합니다.
• 🧠 루프마다 새로운 컨텍스트 (Fresh Context Each Loop)— 모든 반복은 깨끗한 컨텍스트 창 (context window)에서 시작합니다.
• 📝 디스크 상의 공유 상태 (Shared State on Disk)— IMPLEMENTATION_PLAN.md가 루프 사이에 유지됩니다.

Geoffrey Huntley의 방법론을 기반으로 합니다:

┌─────────────────────────────────────────────────────────────┐
│ RALPH LOOP │
├─────────────────────────────────────────────────────────────┤
...

에이전트는 오직 다음의 경우에만 <promise>DONE</promise>를 출력합니다:

• 모든 수락 기준 (acceptance criteria)이 검증되었을 때
• 테스트가 통과했을 때
• 변경 사항이 커밋(commit)되고 푸시(push)되었을 때

셸(shell) 또는 PowerShell 루프가 이 문구를 확인합니다. 문구가 발견되지 않으면 재시도합니다.

모드	목적	명령
build (기본값)	명세/작업 선택, 구현, 테스트, 커밋	./scripts/ralph-loop.sh
plan (선택 사항)	명세로부터 상세한 작업 분할 생성	./scripts/ralph-loop.sh plan

Windows PowerShell에서는 일치하는 .ps1 스크립트를 사용하십시오. 예를 들어:
.\scripts\ralph-loop.ps1
또는
.\scripts\ralph-loop-codex.ps1 plan

대부분의 프로젝트는 명세(specs)로부터 직접 작업해도 잘 작동합니다. 에이전트는 단순히 다음 과정을 수행합니다:

• specs/ 폴더를 확인합니다.
• 우선순위가 가장 높은 미완료 명세를 선택합니다.
• 이를 완전히 구현합니다.

plan 모드는 명세를 더 작은 작업 단위로 상세하게 분해하고 싶을 때만 사용하십시오.

팁: IMPLEMENTATION_PLAN.md 파일을 삭제하면 다시 명세로부터 직접 작업하는 상태로 돌아갑니다.

AI 에이전트에게 이 저장소를 가리키며 다음과 같이 말하십시오:

"https://github.com/fstandhartinger/ralph-wiggum 을 사용하여 내 프로젝트에 Ralph Wiggum을 설정해줘"

에이전트는 INSTALLATION.md를 읽고 다음과 같은 가볍고 즐거운 설정 과정을 안내할 것입니다:

빠른 설정 (Quick Setup) (~1분) — 디렉토리 생성, 스크립트 다운로드
프로젝트 인터뷰 (Project Interview) (~3-5분) — 기술적인 세부 사항이 아닌, 당신의 비전과 목표에 집중
헌법 (Constitution) — 향후 모든 세션을 위한 가이드 문서 생성
다음 단계 (Next Steps) — 명세 생성 및 Ralph 시작에 대한 명확한 안내

인터뷰는 기술 스택의 세부 사항을 심문하기보다 당신이 무엇을 왜 만드는지를 이해하는 것을 우선시합니다. 기존 프로젝트의 경우, 에이전트가 기술 스택을 자동으로 감지할 수 있습니다.

단계별 수동 지침은 INSTALL.md를 참조하십시오.

AI에게 무엇을 만들고 싶은지 말하거나, Cursor에서 /speckit.specify를 사용하십시오:

/speckit.specify OAuth를 사용한 사용자 인증 추가

이렇게 하면 다음과 같은 내용이 포함된 specs/001-user-auth/spec.md가 생성됩니다:

• 기능 요구사항 (Feature requirements)
• 명확하고 테스트 가능한 수락 기준 (Clear, testable acceptance criteria) (매우 중요!)
• 완료 신호 섹션 (Completion signal section)

좋은 명세의 핵심: 각 명세에는 구체적이고 테스트 가능한 수락 기준이 필요합니다.

• 가장 우선순위가 높은 작업을 선택합니다.
• 해당 작업을 완전히 구현합니다.
• 수락 기준 (acceptance criteria)을 검증합니다.
• 출력값:
  <promise>DONE</promise>

기준을 통과한 경우에만 출력됩니다 - Bash 루프가 해당 문구를 확인합니다.

• 컨텍스트 (context)가 초기화되고, 다음 반복 (iteration)이 시작됩니다.

매 루프 실행 시 모든 출력값은 logs/ 디렉토리 내 로그 파일에 기록됩니다.

세션 로그 (Session log): logs/ralph_*_session_YYYYMMDD_HHMMSS.log (CLI 출력을 포함한 전체 실행 기록)
반복 로그 (Iteration logs): logs/ralph_*_iter_N_YYYYMMDD_HHMMSS.log (반복당 CLI 출력)
Codex 마지막 메시지 (Codex last message): logs/ralph_codex_output_iter_N_*.txt

문제가 발생하여 멈춘 경우, 이 로그들에 상세한 추적 정보 (verbose trace)가 포함되어 있습니다.

각 명세 (spec)는 몇 번의 시도가 있었는지 추적합니다. 완료되지 않은 상태로 10번의 시도가 지나면, 해당 명세는 "stuck" 상태로 표시되며 더 작은 명세들로 분할되어야 합니다.

# stuck 상태인 명세 확인
source scripts/lib/nr_of_tries.sh
print_stuck_specs_summary

카운터는 명세 파일 내의 주석으로 저장됩니다:

<!-- NR_OF_TRIES: 5 -->

Telegram을 통해 진행 상황 업데이트를 받으세요! 설정 방법은 TELEGRAM_SETUP.md를 참조하세요.

# telegram 활성화 (TG_BOT_TOKEN 및 TG_CHAT_ID 필요)
./scripts/ralph-loop.sh
# 오디오 알림 활성화 (CHUTES_API_KEY 필요)
...

받게 될 내용:

• 🚀 루프 시작 알림
• ✅ mermaid 다이어그램이 포함된 명세 완료 알림
• ⚠️ 연속된 실패 또는 stuck 상태인 명세에 대한 경고
• 🏁 루프 종료 시 요약

각 명세가 완료될 때마다 completion_log/에 항목이 생성됩니다.

YYYY-MM-DD--HH-MM-SS--spec-name.md — 요약 및 mermaid 코드
YYYY-MM-DD--HH-MM-SS--spec-name.png — 렌더링된 mermaid 다이어그램

이 파일들은 무엇이 구축되었는지에 대한 시각적 이력을 제공합니다.

./scripts/ralph-loop-codex.sh plan
./scripts/ralph-loop-codex.sh

PowerShell:

.\scripts\ralph-loop-codex.ps1 plan
.\scripts\ralph-loop-codex.ps1

project/
├── .specify/
│ └── memory/
...

**헌법 (constitution)**은 단일 진실 공급원 (single source of truth)입니다. 선택적 기능들 (Telegram, GitHub Issues, 완료 로그)은 스크립트에 내장되는 것이 아니라 그곳에서 구성됩니다.

각 반복(iteration)은 깨끗한 컨텍스트 윈도우 (context window)를 할당받습니다. 에이전트 (agent)는 매번 디스크에서 파일을 읽습니다.

IMPLEMENTATION_PLAN.md는 루프 (loop) 사이에도 유지됩니다. 에이전트는 이를 읽어 작업을 선택하고, 진행 상황을 반영하여 업데이트합니다.

테스트 (tests), 린트 (lints), 빌드 (builds)는 유효하지 않은 작업들을 거부합니다. 에이전트는 마법의 문구 (magic phrase)를 사용하기 전에 반드시 문제를 해결해야 합니다.

에이전트는 수락 기준 (acceptance criteria)이 100% 검증되었을 때만 <promise>DONE</promise>를 출력합니다. Bash 루프 (bash loop)가 이를 강제합니다.

AI가 스스로를 식별하고, 스스로 수정하며, 스스로 개선하도록 신뢰하십시오. 패턴을 관찰하고 프롬프트 (prompts)를 조정하십시오.

설치 중에 다음 중 하나를 선택할 수 있습니다:

SpecKit Specs (기본값) — specs/ 디렉토리 내의 Markdown 파일
GitHub Issues — 리포지토리 (repository)에서 가져오기
Custom Source — 사용자 정의 메커니즘

헌법 (constitution)과 프롬프트 (prompts)는 그에 따라 적응합니다.

Ralph Wiggum은 에이전트 기술 (Agent Skills) 명세를 따르며 다음 항목들과 호환됩니다:

설치 도구 (Installer)	명령어 (Command)
Vercel add-skill	npx add-skill fstandhartinger/ralph-wiggum
...

다음과 함께 작동합니다: Claude Code, Cursor, Codex, Windsurf, Amp, OpenCode 등.

이 접근 방식은 다음을 기반으로 구축되었습니다:

• Geoffrey Huntley의 how-to-ralph-wiggum — 독창적인 방법론
• Original Ralph Wiggum technique — Claude 커뮤니티 제작
• Claude Code Ralph Wiggum 플러그인 (plugin)
• GitHub의 SpecKit — 명세 기반 개발 (Spec-driven development)

우리의 기여: Bash 루프 (bash loop) 접근 방식과 SpecKit 스타일의 명세, 그리고 매끄러운 AI 기반 설치 프로세스를 결합했습니다.

MIT License — 자세한 내용은 LICENSE를 참조하십시오.

웹사이트: ralph-wiggum-web.onrender.com