tzachbon/smart-ralph

해결하는 문제

Smart Ralph는 AI 코드 에이전트(특히 Claude Code 및 Codex)를 위한 사양 기반 개발 프레임워크입니다. 개발자가 계획 없이 바로 코딩을 시작하는 것을 방지하고, 구현을 시작하기 전에 연구, 요구사항 수집, 기술 설계의 구조화된 프로세스를 강제합니다. 이로써 복잡한 기능이 충분히 고려되며, 여러 세션에 걸쳐 중단 후 재개하거나 감사할 수 있습니다.

작동 방식

이 프로젝트는 개발의 각 단계를 담당하는 전문 에이전트들이 협력하는 다중 에이전트 워크플로우를 구현합니다:

1. 트라이지(Triage): 큰 목표를 의존성 인식 가능한 작은 사양(에픽)으로 분할합니다.
2. 연구(Research): 기존 코드베이스를 분석하고 웹에서 실현 가능성 여부를 조사합니다.
3. 요구사항(Requirements): 사용자 스토리와 수용 기준을 정의합니다.
4. 프로토타입(Prototype): (옵션) 특정 설계 질문을 일시적인 환경에서 테스트합니다.
5. 설계(Design): 아키텍처와 기술적 트레이드오프를 정의합니다.
6. 작업(Tasks): 설계를 실행 가능한 작업 시퀀스로 나눕니다.
7. 실행(Execution): 각 작업을 하나씩 구현하며, 각 작업마다 새로운 컨텍스트를 사용하고 품질 게이트(POC, 리팩터링, 테스트, 린팅)를 적용합니다.

또한 코드베이스 인덱싱 기능도 포함되어 있으며, 프로젝트를 스캔하여 검색 가능한 컴포넌트 사양을 생성하여 연구 에이전트가 기존 코드를 더 효율적으로 찾을 수 있도록 도와줍니다.

대상 사용자

Claude Code 또는 OpenAI Codex를 사용하여 단순한 프롬프트 기반 코드 생성이 아닌, 더 체계적이고 아키텍처 중심의 AI 보조 기능 개발을 원하는 개발자에게 적합합니다.

주요 특징

• 사양 기반 워크플로우: 연구 → 요구사항 → 설계 → 작업 → 구현의 순서를 강제합니다.
• 상태 지속성: 진행 상황을 .progress.md 및 tasks.md에 기록하여 세션 중단 후 작업을 재개할 수 있습니다.
• 코드베이스 인덱싱: 컨트롤러, 서비스, 모델을 자동 스캔하여 AI가 검색 가능한 인덱스를 생성합니다.
• 다중 에이전트 전문화: 각 단계에 대해 triage-analyst, product-manager, architect-reviewer와 같은 별도의 역할을 사용합니다.
• 유연한 실행: 승인 체크포인트를 포함한 상세한 '정상' 모드와 빠른 반복을 위한 '빠른' 모드를 모두 지원합니다.