Multica (multica-ai/multica) 기반 AI 에이전트 자동화 파이프라인의 설계·배포 청사진. 목적 할당 → 계획 → Task 분해 → 리뷰어 매칭 → 자동 머지 → 충돌 해결까지 사람 개입 없이 유기적으로 돌아가는 구조를 10 계층 + 5 Phase 로 정의했다.
기존 Multica는 에이전트 실행 기반은 있지만, 자율 워크플로우(DAG, 실시간 PR 자동화, 충돌/롤백 자동화) 세 공백이 있었다. 이 공백을 유료 SaaS / OSS 셀프호스트 도구 0 도입으로 메우는 청사진이 이 레포의 전체 목표다.
- 채택: GitHub Merge Queue,
ghCLI, Claude Code hooks, 공식 MCP SDK, Multica agent/autopilot (=GPT/Claude API) - 미채택: Copilot Autofix, Sentry, CodeRabbit, Greptile, Mergify Enterprise, semgrep, trivy, LangGraph, CrewAI, Temporal, OpenHands, SWE-agent, Aider 등 — 에이전트 LLM으로 전부 대체
- 차용: OSS harness 13개의 핵심 아이디어 (Aider repo-map, SWE-agent ACI, OpenHands event stream, LangGraph checkpointer 등) — 개념만 가져와 직접 구현
multica-harness-design/
├── docs/ # 3-layer 설계 문서 (읽기 시작점)
│ ├── report.md # WHAT: 10계층 정적 아키텍처 + 스니펫
│ ├── workflow.md # HOW: 컨트롤타워 4층 + E2E 시나리오
│ └── implementation-playbook.md # DO: 즉시 배포 가능 스니펫 모음
│
├── blueprint/ # 실제 배포 템플릿 (즉시 사용 가능)
│ ├── README.md # 배포 순서 + env 변수 체크리스트
│ ├── repo/ # .github PR 템플릿 + CODEOWNERS + CI
│ ├── multica/ # workspace.context.yaml + 7 agents + 2 autopilots
│ ├── mcp/ # multica-api MCP 서버 (FastMCP, 11 tools)
│ ├── hooks/ # Claude Code hooks (settings + validate-bash + sync-status)
│ ├── daemon-patches/ # Multica daemon Go 모듈 패치 (Phase 1-3)
│ ├── operations/ # tuning/metric/discord/backup 운영 가이드
│ ├── harness-plus/ # Phase 4: versioning/eval/ab-testing/cost/replay
│ └── phase5/ # Phase 5: OSS harness 차용 31개 + operations 8개
│
├── research/ # 원조사 산출물 (sciomc 세션)
│ ├── stages/ # 4-stage 병렬 조사 원문 (~1262줄)
│ ├── findings/ # 교차검증 결과
│ └── state.json
│
└── benchmark/ # OSS harness 벤치마크 조사
├── report.md # 13개 OSS 비교 + Multica 반영안
├── stages/ # 4-stage 조사 (code-edit, agent-arch, orchestration, structured)
└── state.json
상세는 docs/report.md 참조. 요약:
| 계층 | 역할 | 주요 구성요소 |
|---|---|---|
| 1. 입력 게이트 | 목표/이슈 접수 | Multica Chat FAB, multica issue create, Discord |
| 2. 계획 DAG | 자동 분해 + 우선순위 | pm-planner (Phase 1-4 프로토콜) + plan_dag JSON |
| 3. 라우터 | 에이전트 매칭 | router 에이전트 (domain×action × 성공이력) |
| 4. 실행 허브 | Task 수행 | Multica daemon + Claude/Codex/Gemini/Opencode runtime |
| 5. 코드 게이트 | PR 리뷰 | lint-checker + code-reviewer + security-reviewer + domain-reviewer |
| 6. 머지 컨트롤 | 자동 머지 결정 | auto-merge 오토파일럿 + GitHub Merge Queue + 회로차단기 |
| 7. 포스트머지 | 이상 감지 | health-monitor (daemon 로그 tail + CI smoke LLM 판단) |
| 8. 복구 | 자동 revert | revert-bot 오토파일럿 (git revert PR) |
| 9. 학습 | 회고 + 기억 | pm-planner retrospective → long_term_memory (Phase 5) |
| 10. 안전장치 | 킬스위치·회로차단기 | workspace.context.yaml + 블랙리스트 라벨 |
각 Phase 는 외부 도구 추가 설치 0 으로 배포 가능.
- pm-planner 프롬프트에
plan_dagJSON 강제 출력 - daemon DAG 위상정렬 →
blocked_by=[]서브이슈 자동todo승격 - Discord 알림 기본 3 레벨
lint-checker/code-reviewer/security-reviewer3종 에이전트auto-merge오토파일럿 (gh pr merge --auto --squash)conflict-resolver에이전트 (3-way merge 재작성)
multica-apiMCP 서버 (Python FastMCP, 11 tools)- Claude Code hooks (settings + validate-bash + sync-status)
decomposer/router/health-monitor/revert-bot
versioning/: 에이전트 instructions git 이력eval/: LLM-as-judge 품질 측정ab-testing/: 프롬프트 변형 트래픽 분기cost-attribution/: 토큰 차원별 귀속replay/: audit.jsonl 시나리오 재현
| 서브페이즈 | 모듈 | 원형 |
|---|---|---|
| 5-1 MVP | repo-map / checkpointer / structured-output / event-stream | Aider / LangGraph / Instructor+Pydantic AI / OpenHands |
| 5-2 품질 | architect-editor / condenser / shadow-git / security-analyzer | Aider / OpenHands / Cline / OpenHands |
| 5-3 자율성 | aci / stuck-detector / memory-tiers / knowledge-sources | SWE-agent / — / CrewAI / CrewAI |
| 5-4 Polish | conventions-md / handoff-orchestrator | Aider / MAF |
- 킬 스위치:
workspace.context.yaml의AUTOMATION_MODE ∈ {full, pr-review-only, planner-only, off} - 카나리아 게이트 (자동 머지 블랙리스트 라벨):
db-migration/breaking-change/security-critical/infra-change/cost-impact - 회로 차단기: 시간당 자동 머지 5건 / 태스크당 토큰 상한 / 월간 토큰 예산 / max_retry=3 / 예산 도달 시
AUTOMATION_MODE=planner-only자동 전환 - 포스트머지 모니터: health-monitor → revert-bot 자동 트리거 (15분 window)
- LLM 할루시네이션 완화: security-critical 라벨 PR 은 security-reviewer 결과를 arch-reviewer 가 재검증
blueprint/README.md 에 상세한 배포 순서 + env 변수 체크리스트.
요약 순서:
# 0. 사전 준비
cp blueprint/multica/workspace.context.yaml ~/.multica/workspace.context.yaml
# DISCORD_WEBHOOK_URL, ANTHROPIC_API_KEY, OPENAI_API_KEY 설정
# 1. 에이전트 + 오토파일럿 임포트
for f in blueprint/multica/agents/*.md; do
multica agent create --instructions-file "$f" ...
done
for f in blueprint/multica/autopilots/*.sh; do
multica autopilot create --script "$f" ...
done
# 2. MCP 서버
cd blueprint/mcp && pip install -r requirements.txt && python server.py &
# 3. Claude Code hooks
cp -r blueprint/hooks/ ~/.claude/hooks/
# 4. 레포 템플릿 (대상 레포 각각)
cp -r blueprint/repo/.github <target-repo>/
cp -r blueprint/repo/docs/adr <target-repo>/docs/
# 5. daemon 패치 (Multica fork 빌드 필요 시)
# blueprint/daemon-patches/*.go 을 fork 에 병합 → go build이 설계를 실제 Multica (Oracle ARM + Mac Mini 하이브리드) 에 배포하여 dry-run 및 구성요소 단위 검증 한 결과:
- lint-checker 실행: drill 태스크에서 37s 내
{verdict:"changes", rules_violated:["R1","R2"]}정상 반환 - auto-merge dry-run: 30분 window / 회로차단기 / 블랙리스트 라벨 전부 정확히 판정 (실제 머지 트리거는 미수행)
- revert-bot dry-run: post-merge-smoke 실패 2건 감지 → "초기 설정 이슈, window 밖, 자동 revert 차단, 사람 확인 권장" 자동 판단 — 의도대로 작동
- 에이전트 run pickup: < 1분
- multi-account gh 격리: 20 병렬 호출 race test 전부 통과 (kim62210 ↔ DRB-DevOps 교차)
현재 상태: 2 오토파일럿 (auto-merge */30, revert-bot */15) paused. 실제 운영 데이터는 unpause 이후 축적 예정 — 운영자 판단 대기.
- docs/report.md — 10계층 전체 그림 (
[교차검증 필요]태그 포함) - docs/workflow.md — 컨트롤타워 4층 + E2E 한 태스크 추적 + ADR/commit/PR/review/merge/rollback 연쇄
- docs/implementation-playbook.md — 즉시 복붙 가능 스니펫
- blueprint/README.md — 배포 순서 체크리스트
- blueprint/operations/multi-account-gh-isolation.md — 병렬 subprocess 에서 GitHub 계정 격리 (daemon 수정 0, 필수)
- benchmark/report.md — OSS harness 근거 조사 + Multica Phase 5 반영안
- blueprint/phase5/operations/fork-integration-design.md — Phase 5 Go 모듈을 multica fork 로 포팅할 때만 참조 (선택적, YAGNI)
LLM 기반 조사 특성상 일부 내용은 공식 문서로 100% 확인되지 않았다. [교차검증 필요] 태그가 있는 항목은 배포 전 공식 문서로 재확인하라. 주요 미해결:
- CodeRabbit 설정 스키마 / Graphite 가격 / Aider 자동 충돌 / LLM-native 커밋 분류 상용 / Claude Code GitHub Action 범위 / Agent SDK retry 정책
전부 대체안 있어 차단 이슈 없음.
MIT License — 자유롭게 사용·수정·배포 가능. 근거 조사 자료는 참조한 OSS 프로젝트의 원 저자 라이선스를 존중한다.
이 레포는 개인 설계 청사진이지만, 기여 가능:
- 실사용 경험 공유: Multica 배포 후 관찰한 pain point 를 이슈로
- Phase 5 포팅 경험: multica fork 로 Go 모듈 포팅 시 발견한 이슈·개선점 (선택 사항)
- OSS harness 추가 조사: benchmark/ 에 새 프레임워크 추가
- 계정 매핑 확장:
blueprint/operations/gh-wrapper/accounts.yaml.example참고 구조 확장
Pull Request 환영.
- multica-ai/multica — Multica 본체 (Apache 2.0, upstream)
- kim62210/multica — fork. 실제 Go 포팅은 선택적 (YAGNI 원칙) — 현재 이 청사진은 fork 수정 없이도 완전 동작. 포팅이 필요해지면
blueprint/phase5/operations/fork-integration-design.md참조
유지보수: kim62210 조사 일자: 2026-04-22 근거 조사 세션: sciomc (4-stage 병렬, 13 OSS, 70KB 원문)