Ivan 👺 — Ships Code While You Sleep

Pull request를 배포하고, 그 과정에서 팀의 교훈을 기억하는 AI 엔지니어링 팀원.

Ivan은 Claude Code를 기반으로 구축된 오픈 소스 자율 AI 코딩 에이전트로, 일반 영어 작업 지시를 실제 검토가 완료된 GitHub pull request로 변환합니다. 복사 붙여넣기 diff도 필요 없고, 채팅창을 감시할 필요도 없습니다.

Ivan에게 문장 하나만 주세요. Ivan은 그것을 PR 크기의 작업으로 분해하고, 원칙 엔지니어 페르소나와 스스로 디자인에 대해 토론하며 코드를 작성하고, 검토하고, PR을 열고, 심지어 검토 댓글까지 처리합니다.

npm downloads

license

Built with Claude

PRs welcome

npm i -g @ariso-ai/ivan && ivan "Add rate limiting to the public API"

Quick Start · Expert Mode · Institutional Memory · Commands · Contributing

왜 Ivan인가?

대부분의 AI 코딩 도구는 두 가지 문제가 있습니다. 세션 간에 모든 것을 잊어버리고, 아무도 검토하지 않은 코드를 배포한다는 것입니다. Ivan은 이 두 가지 문제를 모두 해결하기 위해 만들어졌습니다. 실제 팀원처럼 행동하는 AI 소프트웨어 엔지니어 에이전트로서, 계획하고, 스스로 논쟁하며, 구현하고, PR을 열고, 검토 댓글까지 처리합니다.

🎒 기억합니다. Ivan은 팀의 실제 PR(Pull Request)과 코딩 세션을 분석하여 이를 *기관 지식(institutional knowledge)*으로 정제한 다음, 이 어렵게 얻은 교훈들을 모든 미래 작업에 주입합니다. 팀이 많이 일할수록 Ivan은 더 똑똑해집니다.

🧌 스스로 검토합니다. Expert 모드에서는 별도의 수석 엔지니어(principal-engineer) 페르소나가 단 하나의 라인이 PR로 제출되기 전에 계획과 diff를 여러 차례에 걸쳐 비평합니다. 이는 마치 시니어 리뷰어가 구현자와 자동으로 짝을 이루어 검토하는 것과 같습니다.

🔁 순환 고리를 완성합니다. Ivan은 'PR 열기'에서 멈추지 않습니다. 인라인(inline) 리뷰 댓글을 처리하고, 수정 커밋으로 답하며, GitHub 이슈에서 @ivan-agent /build를 통해 바로 트리거될 수 있습니다.

Ivan은 Claude Code 위에서 사용자의 자격 증명(credentials)을 이용해 로컬로 실행됩니다. Anthropic API 키 또는 CLI 드라이버를 통한 Claude Max 구독을 가져오세요. OpenAI를 선호하십니까? Ivan은 대신 Codex CLI를 구동할 수 있습니다.

🍄 빠른 시작(Quick Start)

# 1. 설치
npm i -g @ariso-ai/ivan

...

이것으로 끝입니다. Ivan은 다음 작업을 수행합니다:

1. 🗺️ 요청을 관리 가능한, PR 준비가 된 작업들로 **분해(Break down)**합니다.
2. 🌿 Claude Code를 사용하여 각각의 작업을 **브랜치 및 구현(Branch & implement)**합니다.
3. 🪶 관례적 커밋 메시지(conventional commit messages)와 상세한 PR 설명을 작성합니다.
4. 🪧 컨텍스트별 리뷰 지침과 함께 PR을 열어줍니다.

Ivan이 더 깊이 생각하도록 하고 싶으신가요? 플래그 하나를 추가하세요:

ivan --mode expert "Refactor the billing module to support proration"

💬 실행 도중 생각이 바뀌었나요? Ivan이 작업하는 동안 메시지를 입력하고 Enter를 누르기만 하면 됩니다. 사용자의 컨텍스트가 실행 중인 Claude 세션(SDK executor)으로 바로 스트리밍되거나, 자동 후속 턴(Claude CLI 및 Codex executors)에 적용됩니다. 이는 마치 대화형 세션에서 끼어드는 것과 정확히 같습니다.

⠸ Executing task with Claude Code...
also add rate-limit headers to the responses ⏎
💬 Context sent to Claude — it will be incorporated into the current task

🧌 Expert Mode: 스스로 논쟁하며 당신을 대신하는 AI

Ivan은 두 가지 실행 모드를 제공합니다. --mode로 실행 시 선택하세요:

Expert 모드에서 Ivan은 두 개의 사고방식으로 분리됩니다. **구현자(Implementer)**가 코드를 작성합니다. 별도의 아키텍트(Architect) 세션 — 팀의 제도적 지식(institutional knowledge)을 보유하는 수석 엔지니어 페르소나를 채택함 — 이 이를 검토하고 도전합니다. 그들은 설계에 대해, 그리고 diff에 대해 주고받으며, 아키텍트는 작업이 배포하기에 충분히 좋다고 판단할 때 결정합니다.

            🎒 제도적 지식 (과거 PR 및 코딩 세션)
                          │  모든 라운드에 주입되어 중요하게 고려됨
                          ▼
...

• 아키텍트는 **읽기 전용(read-only)**입니다. 코드베이스를 검사하여 비판의 근거를 마련하지만, 코드를 절대 수정하지는 않습니다.
• 모든 턴은 조정된 판결로 끝납니다: APPROVE, APPROVE_WITH_NITS (추가 라운드 없이 사소한 지적 사항을 포함), 또는 REVISE (다음 패스를 요하는 차단 문제).
• 라운드는 고정되어 있지 않고 동적입니다. 아키텍트가 승인하는 순간 루프는 끝나고, 계속해서 해결되지 않은 동일한 우려를 제기하면 조기에 중단되며, 정말 어려운 작업의 경우에만 설정된 최대 횟수까지 실행됩니다. 간단한 변경 사항은 단일 라운드 내에 완료됩니다.
• 기본적으로 아키텍트는 더 강력한 추론 모델(Claude Opus)에서 실행되고, 구현자는 사용자가 구성한 모델을 사용합니다 — 수석 검토자 + 빠른 빌더입니다.

**~/.ivan/config.json**에서 조정할 수 있습니다 (라운드 횟수는 목표가 아니라 안전 상한선입니다):

{

Ivan의 강점은 모든 작업을 처음부터 시작하지 않는다는 점입니다. `ivan learn` 명령어는 팀의 엔지니어링 지혜를 담는 영구적이고 검색 가능한 저장소를 구축하며, Expert 모드는 이 저장소에서 모든 작업에 활용합니다.

```bash
# 리포지토리에서 학습 저장소 초기화
ivan learn init --repo /path/to/repo

...

작동 방식:

• 💰 ingest-pr / ingest-repo — GitHub의 PR 리뷰 피드백을 가져와 재사용 가능한 엔지니어링 교훈과 리포지토리 컨벤션으로 정제합니다.
• 🧬 coding-sessions — 로컬 Claude Code 기록(transcript)을 분석하여 사고 패턴(아키텍처, 제품, 품질에 대해 추론하는 방식)과 예시 상호작용(선임 엔지니어가 어떻게 생각하는지를 보여주는 질문과 수정 사항)을 추출합니다.
• 📦 표준화되고 커밋 가능 — 학습 내용은 .ivan/ 아래의 일반 JSONL 형식으로 저장되므로, git에 존재하고 리포지토리와 함께 이동하며 다른 아티팩트처럼 검토할 수 있습니다. 파생된 로컬 .ivan/db.sqlite가 빠른 의미론적 검색(semantic retrieval)을 담당하며, 쿼리는 절대 네트워크를 사용하지 않습니다.
• 🪝 install-hooks — Ivan의 검색 기능을 Claude Code 자체(UserPromptSubmit 및 PostToolUse(Edit|Write|MultiEdit))에 연결하여 적절한 순간에 적절한 교훈이 나타나도록 합니다.

ivan learn install-hooks --repo /path/to/repo   # 학습 내용이 실시간으로, 편집 중간에 표시됨
ivan learn rebuild --repo /path/to/repo          # 파생된 인덱스 재구축

🦆 리뷰 코멘트 처리 — 자동화

Ivan은 리뷰 피드백과 실패한 CI를 사후 처리가 아닌, 일급(first-class) 워크플로우로 취급합니다.

ivan address                       # 해결되지 않은 코멘트나 실패한 체크가 있는 모든 열린 PR을 스캔
ivan address 123                   # PR #123만 처리
ivan address --from-user alice     # 특정 리뷰어의 코멘트만 처리
...

각 해결되지 않은 인라인 댓글에 대해 Ivan은 수정 사항을 구현하고, 공동 작성자(co-author)를 명시하여 커밋하며, 수정하는 커밋과 함께 스레드에 답글을 달아 댓글 처리 상태를 추적합니다. 이때 GitHub GraphQL API를 사용하여 중복으로 댓글 처리를 하는 일이 없도록 합니다. 또한 PR에서 **실패한 체크(failing checks)**도 가져와서 이를 위한 수정 사항을 푸시할 수 있습니다.

🪤 GitHub Actions: 이슈에서 Ivan 트리거하기

모든 이슈를 PR로 전환합니다. 한 번 실행하세요:

ivan add-action

이 명령어는 워크플로우를 설치하여, 누군가 이슈에 @ivan-agent /build라고 댓글을 달면 Ivan이 해당 이슈를 읽고 PR을 열고, 검토(review)를 위해 약 15분간 기다린 후 ivan address를 실행하여 모든 댓글 처리를 완료합니다. 이 과정은 완전히 자동화됩니다.

필수 저장소 비밀값 (Required repository secrets) (설정 → 비밀 및 변수 → Actions):

🗝️ 드라이버: 원하는 방식으로 실행하기

Ivan은 코딩 에이전트와 GitHub에 접근하는 방식에 대해 의도적으로 유연합니다.

코딩 에이전트 실행(Coding agent execution) — ivan configure-executor로 언제든지 전환할 수 있습니다:

• SDK 모드 (SDK mode) (기본값) — Claude Code SDK를 통해 Anthropic API를 직접 사용합니다. 신뢰성이 높고 CI/CD에 적합합니다. sk-ant-... 키가 필요합니다.

GitHub 인증(GitHub auth) — 설정 시 선택합니다:

• GitHub CLI (기본값) — gh auth login을 사용하여 로컬 사용에 쉽고 안전합니다.
• 개인 접근 토큰 (Personal Access Token, PAT) — CI, Actions 및 비대화형 환경용입니다.

⚒️ 설정(Configuration)

Ivan은 첫 실행 시 필요한 모든 것을 사용자에게 요청합니다. 설정은 ~/.ivan/config.json에 저장되며, 로컬 데이터베이스는 ~/.ivan/db.sqlite에 있습니다.

ivan reconfigure              # 전체 설정을 다시 실행
ivan configure-executor       # Claude SDK (API) vs Claude CLI (Max) vs Codex CLI
ivan choose-model             # 구현 모델 선택 (Claude 또는 Codex)
...

모델(Models) (ivan choose-model):

• Claude Sonnet 4.6 — 권장 기본값, 속도와 품질의 균형이 뛰어남
• Claude Haiku 4.5 — 더 빠름, 간단한 작업에 이상적
• Claude Opus 4.8 — 가장 강력함, 느림 (전문가 모드(Expert mode)의 기본 아키텍트)

저장소별 설정(Per-repository settings):

ivan edit-repo-instructions   # 이 저장소의 모든 작업에 적용되는 코딩 가이드라인
ivan config-tools             # Claude Code가 사용할 수 있는 허용 목록 도구(allow-list tools)
ivan config-blocked-tools     # 특정 도구를 차단 (저장소별 최소 권한 원칙(least-privilege by repo))

📜 CLI 참조

ivan                          # 대화형: Ivan이 무엇을 만들지 질문합니다
ivan "작업 설명"       # 비대화형: 작업을 직접 실행합니다
ivan --mode expert "작업"     # 협업 아키텍트 ↔ 구현자 루프
...

ivan reconfigure
ivan configure-executor       # Claude SDK vs Claude CLI vs Codex CLI
ivan choose-model             # Sonnet / Haiku / Opus (또는 Codex 모델)
...

ivan learn init --repo <경로>
ivan learn ingest-pr --repo <경로> --pr <번호>
ivan learn ingest-repo --repo <경로> [--state merged|open|closed|all] [--limit N]
...

ivan web [--port <포트>]      # 브라우저에서 작업, 태스크, 로그 및 PR 링크 모니터링
ivan web-stop [--port <포트>]

http://localhost:3000에 접속하여 작업, 태스크 진행 상황, 실행 로그 및 PR 링크를 실시간으로 확인하세요.

🕯️ 작동 방식(How It Works)

빌드 워크플로우(Build workflow)

request ─▶ task breakdown ─▶ branch ─▶ implement ─▶ smart commit ─▶ PR
                                  │                                    │
                          (전문가 모드: 설계 + 검토 라운드)  (선택 사항: 대기 및 자동 수정)

Address workflow — GitHub GraphQL API를 통해 해결되지 않은 인라인 댓글을 찾아내고, 각 수정 사항을 구현하며, 수정 커밋과 함께 응답하고, 상황별 리뷰 지침을 추가합니다.

Everything is tracked — 로컬 SQLite 데이터베이스가 모든 작업(job), 태스크(task), 상태 전환(status transition), 브랜치(branch), PR 링크, 그리고 Claude Code 도구 호출 기록을 저장하며, 이는 ivan web을 통해 확인할 수 있습니다.

🕸️ 아키텍처 (Architecture)

ivan/
├── src/
│   ├── services/
...

☕ 기여하기 (Contributing)

Ivan은 오픈 소스이며, 버그 수정, 새로운 드라이버 추가, 더 나은 학습 추출 방법, 또는 문서화(docs) 등 어떤 형태의 기여든 진심으로 환영합니다.

git clone https://github.com/ariso-ai/ivan.git
cd ivan
npm install
...