odyth/red-queen

The Hive를 운영했던 AI의 이름을 따왔습니다. 당신의 것은 당신의 SDLC(Software Development Life Cycle, 소프트웨어 개발 생명 주기)를 운영합니다.

Red Queen은 Claude Code에 대한 Jenkins와 같습니다.

Jira 또는 GitHub 티켓을 설정 가능한 AI 코딩 파이프라인 — 명세(spec), 계획 검토(plan review), 코드 작성(code), 검토(review), 테스트(test), 사람의 검토(human review) — 을 통해 전달하고 마지막에 병합된 PR(Pull Request)을 생성하는 결정론적 상태 머신(deterministic state machine)입니다. 오케스트레이터(orchestrator) 자체는 AI 토큰을 전혀 소비하지 않습니다. 단지 단계 사이에서 Claude Code 워커(worker)를 배정하고 당신이 설정한 게이트(gate)에서 멈출 뿐입니다.

당신은 티켓을 할당합니다. Claude가 명세(spec)를 작성합니다. 자동화된 계획 검토(plan-review)가 차단 요소와 모호성을 점수화합니다(점수가 낮으면 재작업을 위해 루프를 돕니다). 당신은 사람의 검토 게이트(human gate)에서 승인합니다. Claude가 코드를 작성하고 PR을 생성합니다. 또 다른 Claude가 이를 검토합니다. 또 다른 Claude가 테스트를 수행합니다. 당신은 최종 PR을 검토하고 병합합니다. 어떤 게이트에서든 개입하거나, 게이트를 완전히 제거할 수도 있습니다.

단계(Phases), 기술(skills), 게이트(gates)는 모두 redqueen.yaml에 선언됩니다.

— security-review 단계를 추가하거나,
계획 검토(plan-review) 점수가 깨끗할(clean) 때 사람의 명세 검토(human spec-review)를 건너뛰거나,
.redqueen/skills/ 디렉토리에 파일을 넣어 기술 프롬프트(skill prompt)를 덮어쓸 수 있습니다.

그래프는 당신이 원하는 대로 형성할 수 있습니다.

npm install -g redqueen

요구 사항:

• Node.js >= 24
• Claude Code CLI 설치 및 인증 완료 (claude --version이 셸에서 작동해야 함)
• 이슈 트래커(issue tracker): Jira Cloud 또는 GitHub Issues
• GitHub에 원격 저장소가 있는 git 저장소

이것이 기본 경로입니다 — Red Queen은 이미 Jira 기반의 SDLC를 운영 중인 팀을 위해 구축되었습니다.

git 저장소의 루트에서:

redqueen init

프롬프트에 답하세요. 이슈 트래커로는 jira를, 소스 제어(source control)로는 github를 선택하세요. init은 redqueen.yaml, gitignore 처리된 .env, 코드베이스 맵(codebase map), 그리고 .redqueen/references/ 아래의 참조 템플릿(reference templates)을 작성합니다.

.env를 열고 다음을 설정하세요:

JIRA_TOKEN=... # Atlassian API 토큰 (id.atlassian.com → Security)
GITHUB_PAT=... # 저장소 범위로 제한된 세분화된 PAT (fine-grained PAT)

사용자 정의 필드 ID(Custom field IDs)와 단계 옵션 ID(phase option IDs)는 테넌트(tenant)마다 다릅니다. Red Queen이 이를 가져오도록 하세요:

redqueen jira discover

이 명령은 Jira 프로젝트를 쿼리하여 phase(단계) 및 spec(사양) 커스텀 필드를 선택하고, 각 Red Queen phase를 Jira 옵션 값과 매칭한 뒤, 확인된 ID들로 redqueen.yaml을 패치(patch)합니다. 매칭되지 않은 phase는 <CHANGE ME> 상태로 유지되므로, 수동으로 수정해야 합니다. 미리 보기를 위해 --dry-run을 사용하고, 확인 프롬프트를 건너뛰려면 --yes를 사용하세요.

redqueen service install
redqueen service start

macOS에서는 ~/Library/LaunchAgents/ 아래에 LaunchAgent를 생성하며, Linux에서는 ~/.config/systemd/user/ 아래에 --user systemd 유닛을 생성합니다. 설치 프로그램은 PATH에서 claude를 자동으로 감지하여 그 절대 경로를 pipeline.claudeBin에 기록하므로, 서비스의 제한된 PATH로 인해 실행이 막히는 일을 방지합니다.

http://127.0.0.1:4400을 여세요. 다섯 개의 탭이 있습니다:

Status(상태)— 현재 단계, 큐 깊이(queue depth), 마지막 폴링(poll), SSE 이벤트 스트림.
Service(서비스)— 데몬(daemon) 시작 / 중지 / 재시작, 로그 경로.
Config(설정)— 브라우저 내에서 redqueen.yaml 편집; 저장 시 핫 리로드(hot reload)가 트리거되며 어떤 섹션이 적용되었는지 또는 재시작이 필요한지 보여줌.
Skills(스킬)— 번들 및 사용자 재정의 프롬프트(prompts) 목록; skills.disabled를 통해 모든 스킬 비활성화 가능.
Workflow(워크플로우)— 실시간 검증과 함께 단계(phase) 추가, 제거, 순서 변경; 작업이 진행 중인 동안에는 저장을 거부함.

Jira에서 티켓의 AI Phase 필드를 Spec Writing으로 설정하고 AI 봇 계정에 할당하세요. 오케스트레이터(orchestrator)는 30초마다 폴링하거나(설정된 경우 웹후크(webhook)에 반응) 작동합니다. 다음과 같이 단계가 이동하는 것을 볼 수 있습니다:
Spec Writing → Plan Review → Spec Review (사람의 승인 단계) → Coding → Code Review → Testing → Human Review → merged(병합).

부실한 계획은 에스컬레이션(escalation)되기 전까지 Spec Feedback을 통해 최대 3번 루프를 돕니다. 깨끗한 계획을 즉시 Coding 단계로 자동 승격시키고 사람의 승인 단계를 건너뛰려면 pipeline.skipSpecReviewIfReady: true를 설정하세요.

GitHub Issues에서 파이프라인을 제어하고 싶다면, redqueen init 시 github-issues를 선택하세요. 라벨(rq:phase:spec-writing 등)이 Jira 커스텀 필드를 대신합니다. 전체 라벨 컨벤션(convention) 및 웹후크 설정에 대해서는 GitHub Issues 어댑터 README를 참조하세요.

redqueen service install # plist/unit + wrapper 작성, 활성화, 시작
redqueen service status # 설치/실행 상태 + 로그 경로 표시
redqueen service start # 시작 (로드되지 않은 경우 부트스트랩 수행)
...

래퍼 스크립트(.redqueen/run-redqueen.sh)는 node redqueen start를 실행(exec)하기 전에 .env를 소싱(source)하므로, 여러분의 plist/unit에는 비밀 값(secret values)이 포함되지 않습니다. 로그 경로(Log paths)는 프로젝트 디렉토리 하위의 .redqueen/redqueen.{out,err}.log로 기본 설정됩니다.

모든 런타임 설정(runtime config)은 redqueen.yaml에 저장됩니다. redqueen init은 합리적인 기본값을 작성하며, 스키마(schema)는 src/core/config.ts 내에 인라인으로 문서화되어 있습니다. 또한 examples/ 하위에 두 개의 전체 참조 설정(reference configs)이 있습니다. 하나는 GitHub Issues용이고, 다른 하나는 Jira용입니다.

YAML 내의 ${ENV_VAR} 참조는 로드 시점에 process.env(및 인접한 .env 파일)로부터 보간(interpolated)됩니다. 비밀 값(secrets)에는 ${JIRA_TOKEN} 및 ${GITHUB_PAT}를 사용하세요. 리터럴 값(literal values)을 직접 붙여넣지 마십시오. 대시보드 검증기(validator)가 이를 거부할 것입니다.

redqueen service start 실행 후:

• redqueen status는 PID와 함께 Red Queen — running을 출력합니다.
• http://127.0.0.1:4400 의 대시보드가 로드되며, Service 탭의 상태 필(state pill)이 running으로 표시됩니다.
• 할당된 티켓(ticket)은 한 번의 폴링 간격(poll interval) 내에 진입 단계(entry phase)에서 첫 번째 자동화 단계(automated phase)로 이동합니다.
• .redqueen/audit.log는 단계 전환(phase transitions)이 발생하는 대로 보여줍니다.
• redqueen service stop 실행 후 redqueen service start를 수행하면 서비스가 계속 실행 상태로 유지됩니다.

증상	예상 원인	해결 방법
command not found: redqueen	글로벌 설치(Global install) 실패 또는 PATH에 없음	npm install -g redqueen을 다시 실행하고, which redqueen으로 확인
서비스는 시작되지만 워커(workers)가 claude: command not found로 실패함	서비스의 런타임 PATH에 claude가 없음	redqueen service install을 다시 실행하여 재감지하거나, pipeline.claudeBin을 명시적으로 설정
대시보드(Dashboard)의 Stop 클릭 시 UI에서 재시작할 방법이 없음	예상된 동작 — 대시보드는 방금 종료시킨 서비스에 의해 제공됨	터미널에서 redqueen service start 실행
Jira 이슈가 수집되지 않음	웹훅(Webhook) 전달 실패 또는 customFields 설정 오류	.redqueen/audit.log를 확인하고, redqueen jira discover --dry-run을 실행하며, Jira 웹훅이 publicBaseUrl에 도달하는지 확인
GitHub에서 401 Unauthorized 발생	PAT(Personal Access Token)에 권한 범위(scope) 누락	Contents / Issues / PRs / Workflows / Metadata 권한을 포함하여 세분화된(fine-grained) PAT를 재발급
워커가 단계 중간에 멈춤	Claude Code 프롬프트가 예기치 않은 상태에 도달함	.redqueen/audit.log 확인; 단계 재시도(phase retries)는 최대 3회까지 수행되며, 이후 blocked 상태로 격상됨

어댑터별(Per-adapter) 트러블슈팅은 각 어댑터의 README에 있습니다.

flowchart LR
subgraph cli["CLI (src/cli/)"]
init[init]
...

어댑터 패턴(Adapter pattern) — 모든 이슈 트래커(issue trackers)는 IssueTracker를 구현하며, 모든 소스 제어(source control)는 SourceControl을 구현합니다. Linear나 Bitbucket을 추가하는 것은 코어(core) 변경이 아닌 새로운 어댑터를 추가하는 것입니다.

이 저장소(repo) 내부에서 작업 중이신가요? AGENTS.md부터 시작하세요 — 빌드 명령, 코드 스타일, 인터페이스가 포함되어 있습니다. 사용자의 프로젝트에 Red Queen을 설치하시나요? 에이전트(agent)에게 다음을 전달하세요:

"redqueen을 설치하고, jira + github를 위해 redqueen init을 실행한 뒤, .env에 토큰을 채우세요. 그 다음 redqueen jira discover를 실행하고, redqueen service install && redqueen service start를 실행하세요."

LLM 크롤러 인덱스: llms.txt.

• CHANGELOG.md — 릴리스 노트 (release notes)
• CONTRIBUTING.md — 개발 루프 (dev loop), 코드 스타일, 어댑터 추가
• LICENSE — MIT
• Examples — 복사하여 붙여넣을 수 있는 참조 설정 (reference configs)
• Website
• Issue tracker