michaelshimeles/ralphy

Discord 참여하기 - 질문이 있으신가요? 기여하고 싶으신가요? 커뮤니티에 참여하세요!

자율적인 AI 코딩 루프 (Autonomous AI coding loop). 작업이 완료될 때까지 AI 에이전트 (AI agents)를 실행합니다.

옵션 A: npm (권장)

npm install -g ralphy-cli
# 그 후 어디에서든 사용 가능
ralphy "add login button"
...

옵션 B: 클론 (Clone)

git clone https://github.com/michaelshimeles/ralphy.git
cd ralphy && chmod +x ralphy.sh
./ralphy.sh "add login button"
...

두 버전은 동일한 기능을 제공합니다. 아래 예시는 ralphy를 사용합니다.

(npm) - bash 스크립트를 사용하는 경우 ./ralphy.sh를 대체하여 사용하세요.

단일 작업 (Single task) - 무엇을 할지 말하기만 하면 됩니다:

ralphy "add dark mode"
ralphy "fix the auth bug"

작업 목록 (Task list) - PRD (제품 요구 사항 문서)를 통해 작업을 진행합니다:

ralphy # PRD.md를 사용함
ralphy --prd tasks.md

선택 사항. AI가 따라야 할 규칙을 저장합니다.

ralphy --init # 프로젝트 설정을 자동 감지함
ralphy --config # 설정 보기
ralphy --add-rule "use TypeScript strict mode"

.ralphy/config.yaml을 생성합니다:

project:
name: "my-app"
language: "TypeScript"
...

규칙은 모든 작업(단일 작업 또는 PRD)에 적용됩니다.

ralphy # Claude Code (기본값)
ralphy --opencode # OpenCode
ralphy --cursor # Cursor
...

모든 엔진에 대해 기본 모델을 재정의할 수 있습니다:

ralphy --model sonnet "add feature" # Claude와 함께 sonnet 사용
ralphy --sonnet "add feature" # 위 명령의 단축키
ralphy --opencode --model opencode/glm-4.7-free "task" # 커스텀 OpenCode 모델
...

-- 구분자를 사용하여 하위 엔진 CLI에 추가 인자를 전달할 수 있습니다:

# copilot 전용 인자 전달
ralphy --copilot --model "claude-opus-4.5" --prd PRD.md -- --allow-all-tools --allow-all-urls --stream on
# claude 전용 인자 전달
...

-- 이후의 모든 내용은 해석 없이 엔진 CLI로 직접 전달됩니다.

마크다운 파일 (Markdown file) (기본값):

ralphy --prd PRD.md

## Tasks
- [ ] create auth
- [ ] add dashboard
...

마크다운 폴더 (Markdown folder) (대규모 프로젝트용):

ralphy --prd ./prd/

폴더를 지정하면, Ralphy는 모든 .md 파일을 읽고 작업을 통합합니다.

prd/
backend.md # - [ ] create user API
frontend.md # - [ ] add login page
...

작업(Tasks)은 파일별로 추적되므로, 완료 시 해당 파일이 올바르게 업데이트됩니다.

YAML:

ralphy --yaml tasks.yaml

tasks:
- title: create auth
  completed: false
...

JSON:

ralphy --json PRD.json

{
"tasks": [
{
...

제목(Titles)은 고유해야 합니다.

GitHub Issues:

ralphy --github owner/repo
ralphy --github owner/repo --github-label "ready"

ralphy --parallel # 기본값 3개의 에이전트 (agents)
ralphy --parallel --max-parallel 5 # 5개의 에이전트 (agents)

각 에이전트는 격리된 워크트리 (worktree) + 브랜치 (branch)를 할당받습니다:

Agent 1 → /tmp/xxx/agent-1 → ralphy/agent-1-create-auth
Agent 2 → /tmp/xxx/agent-2 → ralphy/agent-2-add-dashboard
Agent 3 → /tmp/xxx/agent-3 → ralphy/agent-3-build-api

--create-pr 옵션이 없는 경우:

: 베이스 브랜치 (base branch)로 자동 병합 (auto-merge)되며, AI가 충돌 (conflicts)을 해결합니다.

--create-pr 옵션이 있는 경우:

: 브랜치를 유지하고 풀 리퀘스트 (PRs)를 생성합니다.

--no-merge 옵션이 있는 경우:

: 병합하거나 PR을 생성하지 않고 브랜치를 유지합니다.

YAML 병렬 그룹 (parallel groups) - 실행 순서를 제어합니다:

tasks:
- title: Create User model
  parallel_group: 1
...

ralphy --branch-per-task # 작업당 브랜치 생성
ralphy --branch-per-task --create-pr # + PR 생성
ralphy --branch-per-task --draft-pr # + 초안(draft) PR 생성
...

브랜치 명명 규칙: ralphy/<task-slug>

Ralphy는 작업 중에 브라우저 상호작용을 자동화하기 위해 agent-browser를 사용할 수 있습니다.

ralphy "test the login flow" --browser # 강제 활성화
ralphy "add checkout" --no-browser # 강제 비활성화
ralphy "build feature" # 자동 감지 (기본값)

활성화되면 AI는 다음과 같은 브라우저 명령어를 받습니다:

agent-browser open <url>

• URL로 이동
  agent-browser snapshot

• 요소 참조 (element refs) 가져오기 (@e1, @e2)
  agent-browser click @e1

• 요소 클릭
  agent-browser type @e1 "text"

• 입력창에 텍스트 입력
  agent-browser screenshot <file>

• 스크린샷 캡처

사용 사례 (Use cases):

• 기능 구현 후 UI 테스트
• 배포 (deployments) 확인
• 양식 채우기 (Form filling) 및 워크플로우 테스트

설정 (Config) (.ralphy/config.yaml):

capabilities:
  browser: "auto" # "auto", "true", 또는 "false"

Discord, Slack 또는 커스텀 웹훅 (webhooks)을 통해 세션이 완료되었을 때 알림을 받으세요.

설정 (Config) (.ralphy/config.yaml):

notifications:
  discord_webhook: "https://discord.com/api/webhooks/..."
  slack_webhook: "https://hooks.slack.com/services/..."
  ...

알림에는 작업 완료 횟수 및 상태 (완료/실패)가 포함됩니다.

의존성 디렉토리가 큰 대규모 리포지토리 (repos)의 경우, 샌드박스 (sandbox) 모드가 git 워크트리 (worktrees)보다 빠릅니다:

ralphy --parallel --sandbox

작동 방식:

심볼릭 링크 (Symlinks): 읽기 전용 의존성 (node_modules, .git, vendor, .venv, .pnpm-store, .yarn, .cache)

복사 (Copies): 에이전트 (agents)가 수정할 수 있는 소스 파일 (src/, app/, lib/, 설정 파일 등)

사용 이유:

• 워크트리 (worktrees) 전반에 걸쳐 기가바이트 단위의 node_modules를 중복 생성하는 것을 방지
• 대규모 모노레포 (monorepos)에서 훨씬 빠른 샌드박스 (sandbox) 생성
• 각 작업 후 변경 사항이 원래 디렉토리로 동기화됨

대신 워크트리 (worktrees)를 사용해야 하는 경우 (기본값):

• 각 샌드박스 (sandbox)에서 전체 git 히스토리 (history) 접근이 필요한 경우
• 실제 리포지토리가 필요한 git 명령어를 실행하는 경우
• 워크트리 (worktree) 오버헤드가 최소한인 작은 리포지토리 (repos)

병렬 실행 신뢰성:

• 워크트리 (worktree) 작업이 실패하는 경우 (예: 중첩된 워크트리 리포지토리), ralphy는 자동으로 샌드박스 (sandbox) 모드로 전환합니다.
• 재시도 가능한 속도 제한 (rate-limit) 또는 할당량 (quota) 오류를 감지하고 나중에 재시도하도록 보류합니다.
• 로컬 변경 사항은 병합 (merge) 단계 전에 스태시 (stashed)되고 이후에 복구됩니다.
• 에이전트 (agents)는 PRD 파일, .ralphy/progress.txt, .ralphy-worktrees 또는 .ralphy-sandboxes를 수정해서는 안 됩니다.

플래그 (Flag)	기능
--prd PATH	작업 파일 또는 폴더 (자동 감지, 기본값: PRD.md)
--yaml FILE	YAML 작업 파일
--json FILE	JSON 작업 파일
--github REPO	GitHub 이슈 (Issues) 사용
--github-label TAG	라벨 (Label)로 이슈 필터링
--sync-issue N	PRD 진행 상황을 GitHub 이슈 #N에 동기화
--model NAME	모든 엔진에 대해 모델 (Model) 재정의
--sonnet	--claude --model sonnet의 단축키
--parallel	병렬 실행
--max-parallel N	최대 에이전트 (Agents) 수 (기본값: 3)
--sandbox	Git 워크트리 (Worktrees) 대신 경량 샌드박스 (Sandboxes) 사용
--no-merge	병렬 모드에서 자동 병합 (Auto-merge) 건너뛰기
--branch-per-task	작업당 브랜치 (Branch) 생성
--base-branch NAME	베이스 브랜치 (Base branch)
--create-pr	PR (Pull Requests) 생성
--draft-pr	초안(Draft) PR 생성
--no-tests	테스트 (Tests) 건너뛰기
--no-lint	린트 (Lint) 건너뛰기
--fast	테스트 및 린트 건너뛰기
--no-commit	자동 커밋 (Auto-commit) 하지 않음
--max-iterations N	N개 작업 후 중단
--max-retries N	작업당 재시도 (Retries) 횟수 (기본값: 3)
--retry-delay N	재시도 사이의 간격 (초)
--dry-run	미리보기만 수행
--browser	브라우저 자동화 (Browser automation) 활성화
--no-browser	브라우저 자동화 비활성화
-v, --verbose	디버그 출력 (Debug output)
--init	.ralphy/ 설정 구성
--config	설정 표시
--add-rule "rule"	설정에 규칙 (Rule) 추가

필수 사항 (Required):

• AI CLI: Claude Code, OpenCode, Cursor, Codex, Qwen-Code, Factory Droid, GitHub Copilot 또는 Gemini CLI

npm 버전 (ralphy-cli):

• Node.js 18+ 또는 Bun

Bash 버전 (ralphy.sh):

jq

yq (YAML 작업용, 선택 사항)

bc (비용 계산용, 선택 사항)

두 버전 공통:

gh (GitHub 이슈 / --create-pr 사용 시, 선택 사항)

agent-browser (--browser 사용 시, 선택 사항)

엔진	CLI	권한(Permissions)	출력
Claude	claude	--dangerously-skip-permissions	토큰 + 비용
OpenCode	opencode	full-auto	토큰 + 비용
Codex	codex	N/A	토큰
Cursor	agent	--force	지속 시간(duration)
Qwen	qwen	--approval-mode yolo	토큰
Droid	droid exec	--auto medium	지속 시간(duration)
Copilot	copilot	--yolo	토큰
Gemini	gemini	--yolo	토큰 + 비용

엔진이 0이 아닌 값으로 종료되면, ralphy는 디버깅을 용이하게 하기 위해 CLI 출력의 마지막 줄을 오류 메시지에 포함합니다.

개선된 인증 오류 감지: extractAuthenticationError 단순화 기능이 추가되었습니다.

함수에 더 나은 엣지 케이스 처리(예: 로그인 중 JSON dumps)가 추가되었습니다.프로젝트 표준 추가: 일관된 AI 지원 개발을 위해 .CLAUDE.md, .cursorrules, CONTRIBUTING.md가 추가되었습니다.향상된 기본 프롬프트: 간결하고 집중된 코드 변경 사항을 강제합니다.

Copilot 엔진 개선: 비대화형 모드(--yolo), 인증/속도 제한/네트워크 오류에 대한 적절한 오류 감지, 토큰 사용량 파싱, 마크다운 보존을 위한 임시 파일 기반 프롬프트가 추가되었습니다.무한 재시도 루프 수정: 작업이 치명적인 구성/인증 오류 발생 시 이제 제대로 중단됩니다.프로젝트 표준: 일관된 코딩 스타일을 위해 .editorconfig와 .gitattributes가 추가되었습니다.

JSON PRD 지원: 병렬 그룹 및 작업 설명을 지원하는 JSON 파일을 작업 소스로 사용하기 위한 새로운 --json 플래그가 추가되었습니다.

Gemini CLI 지원: Google Gemini CLI를 위한 새로운 --gemini 엔진 옵션이 추가되었습니다.GitHub 이슈 동기화: 각 작업 후 PRD 진행 상황을 GitHub 이슈에 동기화하는 --sync-issue <번호> 기능이 추가되었습니다.성능 개선: 중복 파일 읽기 감소, 재시도 시 지수 백오프(exponential backoff) 적용, 비차단 로깅, 작업 시간 가시성이 향상되었습니다.버전 수정: CLI 버전이 이제 package.json에서 동적으로 읽어옵니다.

• 병렬 신뢰성 (parallel reliability): 워크트리 (worktree) 오류 발생 시 샌드박스 (sandbox) 모드로 폴백 (fallback)
• 에러 출력 (error output): 실패한 엔진 명령에 대한 CLI 출력 스니펫 (snippet) 포함
• 재시도 처리 (retry handling): 속도 제한 (rate-limit) / 할당량 (quota) 오류를 감지하여 조기 중단
• 병합 안전성 (merge safety): 병합 단계 전에 로컬 변경 사항을 스태시 (stash)하고 이후 복구
• 프롬프트 (prompts): PRD 및 .ralphy progress/sandbox/worktree edits를 명시적으로 피함

샌드박스 모드 (sandbox mode): 종속성을 위해 심볼릭 링크 (symlinks)를 사용하는 경량 격리 (worktrees보다 빠름)
성능 향상 (performance improvements): 작업 캐싱 (task caching), 병렬 병합 분석 (parallel merge analysis), 스마트 브랜치 순서 지정 (smart branch ordering)
웹훅 알림 (webhook notifications): 세션 완료 시 Discord, Slack 및 커스텀 웹훅 지원 (.ralphy/config.yaml에서 설정)

엔진 전용 인자 (engine-specific arguments): --를 통해 하위 CLI로 인자 전달

Windows 개선 사항 (Windows improvements): .cmd 래퍼 (wrappers)에 대한 향상된 에러 처리

• Windows 줄 바꿈 (line ending) 처리 수정

• Windows Bun 명령 해석 수정

• GitHub Copilot CLI 지원 (--copilot)

• 모델 오버라이드 (model override): 모든 엔진에 대해 모델을 오버라이드하는 --model <name> 플래그

• --sonnet: --claude --model sonnet의 단축어

• --no-merge: 병렬 모드에서 자동 병합을 건너뛰는 플래그

• 병렬 자동 병합 중 AI 지원 병합 충돌 해결 (AI-assisted merge conflict resolution)

• 루트 사용자 감지 (root user detection): Claude/Cursor의 경우 에러, 기타 엔진의 경우 경고

• OpenCode 에러 처리 및 모델 오버라이드 지원 개선

• 브라우저 자동화 (browser automation): --browser / --no-browser 지원, agent-browser 사용 시 자동 감지

• 설정 옵션 (config option): .ralphy/config.yaml 내 capabilities.browser

• TypeScript CLI: npm install -g ralphy-cli

• 크로스 플랫폼 바이너리 (macOS, Linux, Windows)

• npm 버전의 경우 jq/yq/bc에 대한 의존성 없음

• 단일 작업 모드 (single-task mode): PRD 없이 ralphy "task" 실행

• 프로젝트 설정 (project config): --init을 통해 .ralphy/ 생성 (규칙 + 자동 감지 포함)

• 신규 옵션: --config, --add-rule, --no-commit

• Factory Droid 지원 (--droid)

• Qwen-Code 지원 (--qwen)

• Cursor 지원 (--cursor) - 향상된 작업 검증 (task verification)

• worktrees를 이용한 병렬 실행 (parallel execution)

• 작업당 브랜치 생성 (branch-per-task) + 자동 PR (auto-PR)

• YAML + GitHub Issues 소스 지원

• 병렬 그룹 (parallel groups)

• OpenCode 지원

• 재시도 로직 (retry logic)
  --max-iterations

--dry-run

• 초기 출시 (initial release)

개발 가이드라인은 CONTRIBUTING.md를 참조하세요.

핵심 원칙 (Key principles):

• 변경 사항을 작고 집중되게 유지할 것 - 커밋당 하나의 논리적 변경 (one logical change per commit)
• 큰 작업은 마이크로 태스크 (micro-tasks)로 분할할 것
• 속도보다 품질 (Quality over speed)
• 죽은 코드 (dead code)를 남기지 말 것
• 엔트로피 (entropy)와 싸울 것 - 코드베이스를 발견했을 때보다 더 나은 상태로 남겨둘 것

AI 코딩 어시스턴트 (AI coding assistants)가 참조할 수 있는 파일:

• CLAUDE.md - Claude Code 지침
• .cursorrules - Cursor IDE 규칙

MIT