lee-to/aif-handoff

Autonomous Kanban board where AI agents plan, implement, and review your tasks — fully hands-off.

AIF Handoff – 자율 AI 기반 칸반 보드

정의 – 대규모 언어 모델 에이전트가 인간의 개입 없이 코드 중심 작업을 계획, 구현, 검토할 수 있게 해주는 웹 기반 칸반 보드입니다. 이 시스템은 오픈소스 AI Factory 프레임워크를 기반으로 하며 Claude, OpenAI Codex, OpenRouter 및 OpenCode용 플러그형 런타임 어댑터를 사용합니다.

핵심 아이디어 – 작업은 고정된 파이프라인(백로그 → 계획 → 구현 → 검토 → 완료)을 통해 이동합니다. 각 단계에서 전문화된 AI 하위 에이전트(또는 단일 "스킬" 함수)가 산출물을 생성하고 품질 검사를 실행하며, 수렴 조건이 충족될 때까지 자동으로 재작업을 위해 루프백할 수 있습니다. 수렴에 실패하면 작업은 수동 검토를 위해 인간에게 넘겨집니다.

주요 기능 (README에 설명된 대로)

완전 자율 파이프라인 – 작업을 생성하면 AI가 계획하고, 코드를 작성하고, 검토합니다.
칸반 UI – WebSocket을 통한 실시간 업데이트가 있는 드래그 앤 드롭 보드.
모듈식 런타임 – 오케스트레이션 로직을 변경하지 않고 프로젝트 또는 작업별로 Claude, Codex, OpenRouter 또는 OpenCode를 교체할 수 있습니다.
하위 에이전트 오케스트레이션 – 계획, 구현 및 검토를 위한 전담 코디네이터(및 보안 사이드카).
레이어 인식 실행 – 구현 단계에서 종속성 레이어를 계산하고 가능한 경우 병렬 워커를 실행합니다.
자동 복구 – 하트비트 및 감시 프로세스가 중단된 에이전트를 자동으로 복구합니다.
인간 개입 옵션 – 계획 승인, 변경 요청 또는 완전 무인 실행.
참가자 모드 – 역할 인식 작업 소유권이 있는 선택적 로컬 사용자 계정.
GitHub 통합 – 이슈 가져오기, 격리된 PR 생성, 작업당 인간 병합 PR 요구.
Model Context Protocol(MCP) 동기화 – 다른 AIF 도구와 양방향 작업 동기화.

아키텍처 개요

packages/
├─ shared/      # 유형, 상수, 로거
├─ runtime/     # 레지스트리 및 어댑터(Claude, Codex 등)
├─ data/        # SQLite 액세스(drizzle-orm)
├─ api/         # Hono REST + WebSocket 서버(포트 3009)
├─ web/         # React + Vite UI(포트 5180)
└─ agent/       # 코디네이터 + 하위 에이전트 오케스트레이션

에이전트는 30초마다 폴링하고 적절한 하위 에이전트를 디스패치하며 하트비트를 통해 작업 활성 상태를 추적합니다. 자동 검토는 두 가지 전략(full_re_review 또는 closure_first)으로 실행될 수 있으며 수렴에 실패하면 중지되고 작업에 manualReviewRequired=true가 표시됩니다.

시작하기(빠른 시작)

Docker 없이

git clone https://github.com/lee-to/aif-handoff.git
cd aif-handoff
nvm use               # Node 20.19+ 또는 22.12+
cp .env.example .env
npm install
npm run init         # 초기 DB 설정
npm run dev          # API, 웹 UI 및 백그라운드 에이전트 시작

Node 버전을 전환하는 경우 네이티브 better-sqlite3 바이너리를 다시 빌드하세요: npm rebuild better-sqlite3.

Docker 사용

git clone https://github.com/lee-to/aif-handoff.git && cd aif-handoff
cp .env.example .env
mkdir -p projects               # 생성된 프로젝트용 호스트 디렉토리
docker compose up --build      # API, UI, 에이전트(+ 선택적 MCP) 시작
# 컨테이너 내부에서 Claude 인증
docker compose exec agent claude login
docker compose restart agent

Docker는 Codex SDK/CLI 설치를 처리합니다. CODEX_VERSION을 통해 버전을 재정의할 수 있습니다.

런타임 공급자

공급자	전송 옵션
Claude (Anthropic)	SDK(직접 Agent SDK) – Anthropic 약관 위반 위험; 더 안전한 CLI 전송; `ANTHROPIC_API_KEY`를 통한 API 전송.
Codex (OpenAI)	SDK, CLI, App-Server, API
OpenRouter	API
OpenCode	API
`AIF_RUNTIME_MODULES` 환경 변수를 통해 사용자 지정 어댑터를 추가할 수 있습니다.

실행 모드

모드	`AGENT_USE_SUBAGENTS`	동작
하위 에이전트 (true)	각 파이프라인 단계는 전담 코디네이터 에이전트를 통해 실행되며 품질 기준이 충족될 때까지 반복합니다. 더 높은 토큰 사용량, 더 높은 품질.
스킬 (false – 기본값)	단계는 단일 AIF 스킬 호출(`/aif-plan`, `/aif-implement` 등)입니다. 더 빠르고 토큰 비용이 낮습니다. 선택적 `Improve`/`Verify` 단계가 추가 검사를 제공합니다.

누가 사용할 수 있나요?

보일러플레이트 오케스트레이션을 작성하지 않고 엔드투엔드 AI 생성 코드를 실험하려는 팀.
자율 소프트웨어 개발 파이프라인을 탐구하는 연구자.
LLM으로 구동되는 "설정하고 잊어버리는" 작업 보드를 찾는 개인 개발자.

라이선스 및 커뮤니티

이 저장소는 오픈소스(Lee-to 프로젝트의 일반적인 MIT/Apache 스타일)이며 오픈소스이기도 한 AI Factory 프레임워크에 의존합니다. 이슈, 기능 요청 및 기여는 GitHub를 통해 환영합니다.

결론: AIF Handoff는 여러 LLM 공급자, 모듈식 런타임 어댑터 및 칸반 UI를 결합하여 무인 소프트웨어 개발 파이프라인을 만드는 방법을 보여주는 진정한 프로덕션급 프로젝트입니다.