Claude Code 및 Codex를 위한 Spec 기반 개발 (Spec-driven development)

Claude Code 및 Codex를 위한 Spec 기반 개발.

Smart Ralph는 기능 요청을 구조화된 스펙(spec)으로 변환한 다음, 새로운 컨텍스트와 함께 한 번에 하나의 작업으로 실행합니다. 이 실행 루프는 자체적으로 완결되며 외부 플러그인 의존성이 없습니다.

작동 방식 | 설치 | 빠른 시작 | 명령어 | 문제 해결

Smart Ralph는 구현 전에 리서치(research), 요구사항(requirements), 디자인(design), 작업 파일(task files)을 생성합니다. 대규모 목표는 트리아지(triage)로 시작할 수 있으며, 이는 작업을 의존성을 고려한 스펙으로 분할합니다.

스펙 파일은 프로젝트 내에 유지되므로 실행 전에 각 단계를 검토하거나 편집할 수 있습니다. Smart Ralph는 작업 간의 진행 상황을 기록하고 중단된 세션 후 재개할 수 있습니다.

선택적인 프로토타입 기능을 통해 일회성 소스 코드를 프로덕션 코드로 전환하지 않고도 하나의 집중된 디자인 질문을 테스트할 수 있습니다.

flowchart TD
A["기능이 필요해요!"] --> B{"/start가 범위를 감지합니다"}
B -->|단일 스펙| C[리서치]
...

/plugin marketplace add tzachbon/smart-ralph
/plugin install ralph-specum@smart-ralph

설치 후 Claude Code를 재시작하세요.

codex plugin marketplace add tzachbon/smart-ralph \
--sparse .agents/plugins \
--sparse plugins/ralph-specum-codex
...

설치 후 새로운 Codex 작업을 시작합니다. /hooks를 실행하세요.

배치된 Stop hook을 검토하고, 자동 작업 실행을 원한다면 신뢰하십시오. 그렇지 않은 경우, 작업당 한 번 $ralph-specum-implement를 실행하세요.

Codex 설치 가이드에는 업데이트, codex plugin marketplace add .를 사용한 로컬 개발, 그리고 이전의 platforms/codex/ 스킬로부터의 마이그레이션이 포함되어 있습니다.

로컬 Claude Code 개발을 위해서는 이 저장소를 클론하고 claude --plugin-dir ./plugins/ralph-specum을 실행하세요.

$ralph-specum-start user-auth "JWT 인증 추가"

Smart Ralph가 다음 작업을 선택하기를 원할 때 $ralph-specum을 사용하세요. Codex는 명령에 정확한 --quick 플래그가 포함되어 있지 않은 한 각 스펙 아티팩트 후에 승인을 요청합니다. 여러 기능이나 시스템에 걸쳐 목표가 있는 경우 $ralph-specum-triage로 시작하세요.

/ralph-specum:start user-auth "JWT 인증 추가"

--quick

이 옵션을 사용하면 단계별로 중단하지 않고 스펙을 생성하고 실행할 수 있습니다. 인자 없이 /ralph-specum:start를 실행하여 활성화된 스펙을 재개합니다.

Claude Code는 /ralph-specum:<이름>을 사용하고, Codex는 $ralph-specum-<이름>을 사용하며, new는 $ralph-specum-start에 통합됩니다.

| 명령어 | 기능 | |
|---|---|
|/ralph-specum:start [이름] [목표] | 스펙 재개 또는 생성 |
|/ralph-specum:start [목표] --quick | 모든 스펙 단계를 생성하고 실행합니다. |
|/ralph-specum:new <이름> [목표] | 스펙을 생성하고 리서치 전에 승인을 기다립니다. |
|/ralph-specum:triage [이름] [목표] | 큰 목표를 에픽으로 분할합니다. |
|/ralph-specum:research | 리서치를 실행하거나 반복합니다. |
|/ralph-specum:requirements | 리서치로부터 요구사항을 생성합니다. |
|/ralph-specum:prototype | 선택적 프로토타입을 실행하거나 재개합니다. |
|/ralph-specum:design | 기술 설계를 생성합니다. |
|/ralph-specum:tasks | 설계를 실행 가능한 작업으로 분할합니다. |
|/ralph-specum:implement | 작업을 하나씩 실행합니다. |
|/ralph-specum:index | 검색 가능한 코드베이스 스펙을 생성합니다. |
|/ralph-specum:refactor | 요구사항, 설계 또는 작업을 업데이트합니다. |
|/ralph-specum:status | 스펙과 진행 상황을 표시합니다. |
|/ralph-specum:switch <이름> | 활성화된 스펙을 변경합니다. |
|/ralph-specum:cancel | 실행을 취소하고 루프 상태를 제거합니다. |
|/ralph-specum:feedback [메시지] | 피드백을 제출하거나 문제를 보고합니다. |
|/ralph-specum:help | 명령어 및 워크플로우 도움말을 표시합니다. |

Smart Ralph는 각 단계에 집중된 에이전트를 할당합니다.

작업은 네 가지 단계를 따릅니다:

• 작동하게 만들기 (Make it work): POC로 접근 방식을 검증합니다.
• 리팩토링 (Refactoring): 작동하는 구현을 정리합니다.
• 테스트 (Testing): 단위(unit), 통합(integration), 엔드투엔드 커버리지를 추가합니다.
• 품질 게이트 (Quality gates): 린트(lint), 타입, CI 검사를 실행합니다.

계획 제어에는 다음이 포함됩니다:

--tasks-size fine|coarse: 작업 세분성(task granularity)을 조정합니다. [P]
[VERIFY]: 낮은 충돌의 병렬 작업을 위한 플래그입니다. [VERIFY]
그리고 빠른 모드(quick mode) 외부에서 Spec 단계 간 명시적인 검증 승인 체크포인트가 필요한 VE 작업이 있습니다.

• 일반 모드(normal mode)에서는 Smart Ralph가 연구 또는 요구사항 이후에 프로토타입을 제안할 수 있습니다. 안전한 단계 경계에서 /ralph-specum:prototype 또는 $ralph-specum-prototype를 실행할 수도 있습니다. - 빠른 모드(quick mode)에서는 Smart Ralph가 프로토타입 질문을 하지 않으며, 결정을 스스로 내리고 항상 프로토타입 결과 이후에 디자인을 계속합니다.
• 프로토타입 소스는 형제 작업트리(sibling worktree) 또는 적격 스크래치 디렉터리에 유지됩니다. 빠른 모드는 현재 체크아웃으로 어떠한 소스도 전송하지 않으며, 일반 모드에서는 승인한 경로만 전송합니다.
• 검토된 터미널 기록은 불변(immutable)입니다. 로컬 증거는 푸시(push), 원격 브랜치, PR 업데이트, 이슈 작성 또는 기록 삭제를 승인하지 않습니다.

Smart Ralph는 .progress.md에 진행 상황을 저장하고 tasks.md에서 완료된 작업을 표시합니다. 각 구현 작업은 새로운 컨텍스트로 시작됩니다.

/ralph-specum:index
기존 프로젝트를 스캔하여 specs/.index/ 아래에 검색 가능한 컴포넌트 Spec을 작성합니다.

. 연구 에이전트는 해당 인덱스를 사용하여 프로젝트가 이미 가지고 있는 코드를 찾습니다.

/ralph-specum:index
/ralph-specum:index --quick
/ralph-specum:index --dry-run
...

스캐너는 컨트롤러(controllers), 서비스(services), 모델(models), 헬퍼(helpers), 마이그레이션(migrations)을 감지합니다. 또한 외부 URL, MCP 서버, 설치된 기술도 기록할 수 있습니다. Smart Ralph가 한 번도 보지 못한 코드베이스에서 기능을 시작하기 전에 인덱스를 실행하십시오.

생성된 인덱스는 요약 대시보드, 컴포넌트 Spec, 그리고 외부 리소스 Spec을 가지고 있습니다. 연구(Research)는 컨텍스트를 수집할 때 기능 Spec과 색인된 Spec 둘 다 검색합니다.

플러그인 소스 코드는 plugins/ralph-specum/에 위치하며,
Claude Code의 경우 plugins/ralph-specum-codex/에, 그리고 Codex의 경우 plugins/ralph-speckit/에 Spec-Kit 워크플로우를 위해 있습니다.

Smart Ralph는 사용자가 실행하는 프로젝트 내부에 기능 Spec을 작성합니다:

specs/
|-- .current-spec
`-- my-feature/
...

실행이 완료되면 Smart Ralph는 .ralph-state.json 파일을 삭제하지만, 나중에 작업할 수 있도록 결정과 학습 내용을 담은 .progress.md 파일은 유지합니다.

에픽(Epic) 계획은 specs/_epics/<name>/ 아래에 위치합니다. 여기의 상태 파일들은 어떤 Spec이 준비되었는지, 차단되었는지, 아니면 완료되었는지를 추적합니다.

ralph-speckit은 GitHub의 Spec-Kit 방법론을 위한 대안 플러그인입니다. 이는 프로젝트 헌법(project constitution)과 요구사항-작업 추적성(requirement-to-task traceability)을 추가합니다.

플러그인은 또한 /speckit:status, /speckit:switch, /speckit:cancel, /speckit:clarify, 그리고 /speckit:analyze를 포함합니다. 파일 레이아웃 및 명령어 세부 정보는 Ralph Speckit 가이드를 참조하십시오.

• 반복되는 작업 실패: .progress.md를 읽고, 보고된 문제를 수정한 다음, /ralph-specum:implement를 실행합니다.
• 처음부터 다시 시작: /ralph-specum:cancel를 실행한 다음, 새로운 스펙을 시작합니다. - 작업 재개: /ralph-specum:start를 실행합니다. Ralph는 활성 스펙을 찾습니다.

설치, 상태, 훅(hook), 복구 문제에 대한 내용은 문제 해결 가이드를 참조하십시오.

Smart Ralph v3.0.0은 실행을 플러그인의 Stop hook으로 이동했습니다. v2.x를 사용했던 프로젝트는 더 이상 별도의 Ralph Loop 플러그인이 필요하지 않습니다.

Smart Ralph를 업데이트하고, Claude Code를 재시작한 다음, 작업을 재개하십시오. 기존 스펙 파일은 마이그레이션할 필요가 없습니다. 다른 워크플로우에서 사용하지 않는 경우 Ralph Loop를 제거할 수 있습니다. 이후 변경 사항은 GitHub 릴리스를 확인하십시오.

PR(Pull Request)도 환영합니다. 설정, 테스트 및 풀 리퀘스트 지침은 CONTRIBUTING.md를 읽어보십시오.

Smart Ralph는 Ralph 에이전틱 루프 패턴과 Springfield의 가장 열정적인 학생에서 이름을 따왔습니다. Ralph가 다음 작업을 수행합니다. Ralph처럼 행동하십시오.

• Claude Code 및 OpenAI Codex용으로 구축됨
• 코딩 에이전트가 전체 기능을 처리하기를 원했던 개발자들에게 영감을 받음