ralplan은 무엇인가
ralplan은 oh-my-claudecode(줄여서 OMC)라는 오픈소스 하네스에 들어 있는 계획 워크플로다. 하네스란 모델 자체가 아니라 그 모델을 어떤 순서로, 어떤 역할로, 어떤 검증을 거쳐 일하게 할지 정해 둔 규칙 묶음이다. 같은 모델이라도 하네스가 다르면 결과가 달라진다.
쓰는 법은 한 줄이다. Claude Code 터미널에서 /oh-my-claudecode:ralplan "결제 실패 재시도 로직 추가"처럼 작업을 적으면 된다. 이름 그대로 /oh-my-claudecode:plan --consensus의 짧은 별칭이고, consensus는 합의라는 뜻이다.
여기서 벌어지는 일이 보통의 코딩 에이전트와 다르다. 대개는 요청을 받으면 곧장 파일을 열고 코드를 쓴다. ralplan은 코드를 쓰지 않는다. 대신 Planner·Architect·Critic 세 에이전트가 순서대로 붙어 계획 문서 하나를 놓고 합의에 이를 때까지 돈다. 합의가 끝나야 사람에게 승인을 묻고, 승인이 떨어져야 비로소 실행 단계로 넘어간다.
왜 한 에이전트가 다 하면 안 되나
같은 모델에게 "계획 세워줘" 다음에 "이 계획 검토해줘"라고 세 번 물어도 될 것 같지만, 실제로는 세 번 다 같은 사각지대에 빠진다. 방금 자기가 쓴 글을 스스로 반박하는 일은 사람에게도 어렵다.
그래서 ralplan은 역할마다 권한과 의무를 다르게 준다. 초안을 쓰는 쪽에는 형식을 강제하고, 반박하는 쪽에서는 고칠 권한을 빼앗고, 판정하는 쪽에는 반려 의무를 준다. 세 에이전트는 서로 다른 프롬프트와 서로 다른 도구 권한으로 뜬다 — 이름만 다른 같은 호출이 아니다.
아래 세 절이 각 역할이 무엇을 내놓아야 하는지다.
Planner — 선택지를 최소 두 개 낸다
Planner는 계획 초안을 쓴다. 다만 자유롭게 쓰지 못하고 RALPLAN-DR이라는 형식을 채워야 한다. 필수 항목이 셋이다 — 이 계획이 지킬 원칙 3~5개, 선택을 가르는 결정 요인 상위 3개, 그리고 실행 가능한 선택지 최소 두 개다. 선택지마다 장단점을 함께 적는다.
가장 중요한 조항은 마지막이다. 살아남은 안이 하나뿐이라면 나머지를 왜 버렸는지 무효화 근거를 적어야 한다. 이 한 줄이 "처음 떠오른 방법"이 자동으로 정답이 되는 흐름을 끊는다. 비교 대상이 문서에 남기 때문에, 몇 주 뒤 "왜 이렇게 만들었지?"라는 질문에도 답이 남는다.
결과물은 대화 속에 흩어지지 않고 .omc/plans/ 아래 마크다운 파일로 저장된다. 계획은 3~6개의 실행 가능한 단계로 쓰고, 단계마다 실행자가 확인할 수 있는 완료 기준을 붙인다. 30개짜리 잔가지 목록도, 두 줄짜리 선언도 아니다.
높은 위험 작업에서 --deliberate를 붙이면 여기에 프리모템 세 시나리오(무엇이 어떻게 실패할 수 있는가)와 확장 테스트 계획(단위·통합·e2e·관측)이 더 붙는다.
Architect — 고칠 수 없어야 반론이 산다
Architect는 Planner가 쓴 계획을 읽고 설계 관점에서 반박한다. 이 에이전트의 정의에는 disallowedTools: Write, Edit이 박혀 있다 — 파일을 쓰거나 고치는 도구가 아예 차단된 읽기 전용 에이전트다.
권한을 뺀 것이 핵심이다. 고칠 수 있는 사람은 반론 대신 손을 먼저 댄다. 고칠 수 없으면 할 수 있는 일이 하나뿐이다. Architect에게 요구되는 산출물은 선호안에 대한 가장 강한 반론(steelman antithesis)과 최소 하나의 실제 트레이드오프 긴장, 그리고 가능하면 둘을 잇는 종합안이다.
판단의 근거도 강제된다. 모든 지적은 file:line 참조를 달아야 하고, 증상이 아니라 근본 원인을 짚어야 하며, "리팩터링을 고려해 보라" 같은 모호한 권고는 허용되지 않는다. deliberate 모드에서는 Planner가 세운 원칙을 계획이 스스로 어기고 있는 지점을 명시적으로 표시한다.
반론자를 아예 다른 모델로 바꾸고 싶으면 --architect codex를 준다. Codex CLI가 깔려 있으면 그 단계만 Codex가 맡고, 없으면 기본 Architect로 조용히 되돌아간다. 같은 모델 셋이 공유하는 사각지대까지 빼고 싶을 때 쓰는 스위치다.
Critic — 통과가 아니라 반려를 맡는다
Critic의 정의에 적힌 전제가 이 워크플로 전체의 성격을 정한다. 잘못된 승인은 잘못된 반려보다 10~100배 비싸다. 그래서 Critic은 도움을 주는 리뷰어가 아니라 최종 품질 게이트로 설계됐고, 저자는 승인을 받으러 온 사람으로 취급된다.
보는 각도도 다르다. 보통의 리뷰는 적혀 있는 것을 평가하지만 Critic은 적혀 있지 않은 것을 함께 본다. 실행자·이해관계자·회의론자 세 관점을 번갈아 쓰면서 빠진 항목을 찾는다. 확인 항목은 원칙과 선택지가 서로 맞는지, 대안을 공정하게 검토했는지, 리스크 완화가 구체적인지, 완료 기준이 실제로 테스트 가능한지, 검증 절차가 적혀 있는지다.
그리고 반려 의무가 있다. 얕은 대안, 결정 요인끼리의 모순, 두루뭉술한 리스크, 약한 검증은 명시적으로 거부해야 한다. deliberate 모드에서는 프리모템이나 확장 테스트 계획이 빠져 있으면 그것만으로 반려 사유가 된다. 판정은 APPROVE·ITERATE·REJECT 셋 중 하나다.
세 역할이 모여야 생기는 이점 셋
첫째, 순차가 강제된다. Architect가 끝나기 전에는 Critic을 부르지 않는다. 문서에 대문자로 박혀 있는 규칙이고, 두 호출을 같은 병렬 묶음에 넣지 말라고까지 적혀 있다. 동시에 부르면 서로의 지적을 못 읽으므로 합의가 아니라 독백 두 개가 나온다.
둘째, 재작업이 폐루프다. Critic이 ITERATE나 REJECT를 내면 Architect와 Critic의 지적을 모아 Planner가 계획을 고치고, 다시 Architect부터 검토가 시작된다. 고친 부분만 다시 보는 것이 아니다. 이 루프는 최대 다섯 번 돌고, 다섯 번 안에 승인이 나지 않으면 합의에 이르지 못했다는 사실과 함께 최선안을 사람에게 넘긴다.
셋째, 승인 전에는 코드가 잠긴다. 계획 산출물은 pending approval로 표시되고, 그 전까지 ralplan은 파일을 고치거나 커밋하거나 PR을 열거나 실행 스킬에 일을 넘길 수 없다. 계획 단계가 코드를 만지기 시작하면 계획은 이미 저지른 일의 사후 정당화가 된다.
승인 이후의 실행도 이 워크플로가 직접 하지 않는다. --interactive로 돌렸다면 마지막에 실행 방식을 고르는 질문이 뜨고, 선택에 따라 team(병렬 실행)이나 ralph(순차 실행 + 검증)로 넘긴다. 계획하는 자와 만드는 자를 분리하는 원칙이 끝까지 유지된다.
어떻게 시작하나
먼저 Claude Code가 설치돼 있어야 한다. 그다음 OMC를 넣는다. 플러그인으로 /plugin install oh-my-claudecode를 치거나, 터미널에서 npm i -g oh-my-claude-sisyphus@latest를 실행한다. 둘 중 어느 쪽이든 뒤이어 /oh-my-claudecode:omc-setup을 한 번 돌리면 준비가 끝난다.
기본 사용은 /oh-my-claudecode:ralplan "작업 설명"이다. 아무 플래그도 없으면 Planner → Architect → Critic 루프가 자동으로 돌고, 완성된 계획을 pending approval로 표시한 뒤 출력하고 멈춘다. 중간에 묻지 않고, 아무것도 실행하지 않는다.
자주 쓰는 플래그는 넷이다. --interactive는 초안 검토와 최종 승인 두 지점에서 사람에게 묻는다. --deliberate는 프리모템 세 시나리오와 확장 테스트 계획을 추가하는데, 인증·보안·마이그레이션·운영 장애·개인정보처럼 위험 신호가 뚜렷한 요청에서는 붙이지 않아도 자동으로 켜진다. --architect codex와 --critic codex는 각각 반론자와 심판만 Codex로 바꾼다.
결과물은 .omc/plans/ 아래 마크다운으로 남고, 마지막에는 ADR 형식(결정, 결정 요인, 검토한 대안, 선택 이유, 결과, 후속 과제)이 붙는다. 이 파일이 곧 실행 지시서이자 나중에 결정을 되짚는 기록이다.
언제 쓰고, 언제 안 쓰나
ralplan이 가장 크게 값을 하는 자리는 실행을 바로 시키려는 순간이다. OMC에는 "ralph로 앱 좀 개선해줘" 같은 모호한 실행 요청을 가로채 ralplan으로 돌리는 게이트가 있다. 범위가 불분명한 채로 여러 에이전트를 띄우면 그들이 계획 단계에서 해야 할 범위 탐색을 실행하면서 하게 되고, 결과는 대개 부분 구현이나 방향이 어긋난 결과물이다.
반대로 오타 수정, 함수 하나 이름 바꾸기, 한 줄 설정 변경처럼 되돌리기 쉽고 판단할 것이 없는 작업에는 과하다. 합의 루프는 공짜가 아니라 시간과 토큰을 쓴다.
기준을 하나로 줄이면 이렇다. 되돌리는 비용이 계획하는 비용보다 큰 작업이면 ralplan을 쓴다. 데이터 마이그레이션, 인증 구조 변경, 공개 API 수정, 결제 흐름 손대기가 여기에 들어간다. 잘못된 승인이 잘못된 반려보다 10~100배 비싸다는 Critic의 전제는 사실 사람이 일할 때도 그대로 성립한다.