Duo Agent — AI skill for Claude Code

duo-agent

Claude Code와 Codex, 두 AI가 번갈아 가며 코드를 개발하고 리뷰하는 자동 협업 템플릿입니다.

---

이게 뭔가요?

보통 AI에게 코드를 짜달라고 하면 한 명한테만 물어보죠. **duo-agent**는 두 AI를 팀처럼 묶어서, 한 명이 코드를 쓰면 다른 한 명이 자동으로 검토하고 고치는 구조입니다.

• Codex → 기능 구현 담당
• Claude Code → 오류 탐지 및 수정 담당
• 사람은 중간에 개입하지 않아도 됩니다

---

시작하기 전에 필요한 것

처음 사용하는 분도 이 순서대로 따라오면 됩니다.

1. Node.js 설치

[https://nodejs.org](https://nodejs.org) 에서 **LTS 버전**을 설치하세요. 설치 후 터미널에서 확인:

node -v   # v18 이상이면 OK
npm -v

2. Claude Code CLI 설치

npm install -g @anthropic-ai/claude-code
claude --version  # 설치 확인

Claude Code를 처음 실행하면 Anthropic 계정 로그인이 필요합니다.

3. Codex CLI 설치

npm install -g @openai/codex
codex --version  # 설치 확인

OpenAI 계정과 API 키가 필요합니다. [https://platform.openai.com](https://platform.openai.com) 에서 발급받으세요.

---

설치 및 실행

1. 레포 클론

git clone https://github.com/nowah00/duo-agent.git
cd duo-agent

2. 패키지 설치

npm install

3. 환경변수 설정

cp .env.example .env

`.env` 파일을 열어서 필요하면 값을 바꿔도 됩니다. 기본값으로도 바로 실행됩니다.

4. 실행

npm run start

터미널에 아래처럼 뜨면 정상입니다:

[오전 10:00:00] AI 협업 감시 시작
[오전 10:00:00] 감시 대상: .../src
[오전 10:00:00] 최대 라운드: 8 | 재시도: 1

브라우저에서 `http://localhost:3000` 이 자동으로 열리며 모니터링 대시보드를 확인할 수 있습니다.

---

어떻게 사용하나요?

1단계 — 감시 시작

npm run start

터미널에 `AI 협업 감시 시작` 메시지가 뜨고, 브라우저에서 `http://localhost:3000` 대시보드가 열립니다.

2단계 — 작업 지시

**방법 A — 대시보드 (권장)**

브라우저 대시보드의 `Agent Control` 패널에 작업 내용을 입력하고 `▶ Kick` 버튼을 누릅니다. 터미널을 추가로 열 필요가 없습니다.

**방법 B — 터미널**

npm run kick "로그인 기능을 구현해줘"

3단계 — 자동 실행

Codex → 기능 구현 (STATUS: NEEDS_NEXT)
  ↓
Claude → 오류 검토 및 수정 (STATUS: COMPLETE)
  ↓
완료 시 TASK_DONE.md 생성 + 자동 종료

진행 상황은 대시보드에서 실시간으로 확인할 수 있습니다. 실행 중 중단하려면 `■ Stop` 버튼을 누르세요.

4단계 — 결과 확인

• 대시보드 Recent Reviews — 각 에이전트의 출력을 바로 펼쳐볼 수 있습니다
• reviews/ — 전체 출력 기록 파일
• TASK_DONE.md — 완료 여부와 라운드 정보

다음 작업 지시

이전 작업이 완료된 상태에서도 바로 다음 작업을 입력하면 됩니다. 초