Alliance — AI + Human 연합 워크플로우

Alliance는 2개의 AI(Architect + Builder)와 Human(사용자)이 연합하여 복잡한 프로젝트를 체계적으로 완성하는 문서 기반 7단계 워크플로우 시스템입니다. 각 단계마다 문서를 생성하고, 핵심 결정 포인트에서 Human이 직접 개입하여 방향을 결정합니다.

개요

3자 연합 (Alliance)

Alliance는 Architect, Builder, Human — 세 주체가 연합합니다:

참여자	기본 AI	역할	강점
Architect	Gemini	리서치, 설계, 병합, 감사, 보고서 종합	넓은 시야의 설계·분석
Builder	Claude	비평, 반박, 구현, 수정, 보고서 기여	정밀한 코드 생성·실행
Human	사용자	P0 방향 선택, P4 수정 중단 판단	전략적 판단, 최종 의사결정

두 AI의 역할은 단계에 따라 바뀝니다. 예를 들어 P0 토론에서는 Visionary와 Critic 페르소나를 교대로 맡으며, P1에서는 둘 다 설계자, P3에서는 Builder만 구현합니다. Human은 AI가 토론과 설계를 마친 뒤 핵심 결정을 내립니다.

Alliance의 특징

특징	설명
문서 중심	각 단계에서 구조화된 문서 생성
인간 체크포인트	핵심 결정 포인트에서 사용자 개입 (P0, P4)
역할 교체 토론	P0에서 Visionary ↔ Critic 역할을 교체하여 편향 방지
병렬 작업	PR, P1, P5에서 양쪽 AI가 동시에 작업 후 병합
자동 롤백	P4 감사에서 설계 오류 발견 시 P1/P2로 자동 롤백

Avalon3/Colligi와의 차이

항목	Alliance	Avalon3	Colligi
규모	대규모 프로젝트	중간 규모	분석 중심
단계 수	7단계	6단계	5단계
인간 개입	체크포인트 있음	없음	없음
문서	매 단계 문서 생성	합의 문서	분석 보고서
적합한 작업	전체 프로젝트 개발	기능/모듈 개발	리뷰/분석

7단계 파이프라인

PR → P0 (Discovery) → P1 (Design) → P2 (Task Spec) → P3 (Implementation) → P4 (Audit) → P5 (Closure)

PR — Research (병렬 리서치)

양쪽 AI가 프로젝트 관련 정보를 병렬로 조사합니다:

순서	담당	문서	설명
1	Architect + Builder	`research_gemini` + `research_claude`	양쪽 AI가 동시에 웹 리서치 수행
2	Coordinator	`research_summary`	양쪽 리서치 결과를 하나로 병합

검색 키워드 예시: "[제목] best practices", "[제목] alternatives comparison", "[제목] common pitfalls"

P0 — Discovery (3라운드 역할 교체 토론)

3라운드 토론으로 프로젝트 방향을 설정합니다. 핵심은 라운드 2에서 역할이 교체된다는 점입니다:

라운드	Architect (Gemini)	Builder (Claude)	내용
R1	🔭 Visionary	🔍 Critic	Architect가 5~10개 혁신적 아이디어 제시 → Builder가 각 아이디어의 실패 요인 3가지 비평
R2	🔍 Critic (교체)	🔭 Visionary (교체)	Builder가 3~5개 개선된 대안 제시 → Architect가 기술 타당성 검증 및 Top 3 선정
R3	종합자	—	Architect가 전체 토론을 종합하여 최종 후보 3개 + 장단점 정리

💡 역할 교체는 단일 관점의 편향을 방지합니다. Visionary만 했던 AI가 Critic이 되면서, 자신이 제안한 아이디어의 약점도 객관적으로 볼 수 있게 됩니다.

Human Checkpoint (인간 체크포인트)

P0 완료 후 사용자가 직접 방향을 선택합니다:

토론에서 나온 3개 후보 중 하나를 선택
또는 사용자가 직접 방향을 수정

💡 이것이 Alliance의 핵심입니다. AI가 아무리 잘 토론해도 최종 결정은 인간이 합니다.

P1 — Design (병렬 설계)

양쪽 AI가 동시에 설계 초안을 작성한 후 병합합니다:

순서	담당	문서	설명
1	Architect + Builder	`design_draft_architect` + `design_draft_builder`	양쪽이 동시에 설계 문서 작성 (Architect: 아키텍처 관점, Builder: 구현 관점)
2	Architect	`design_merge`	양쪽 설계를 통합하여 최종 설계 문서 생성

P4에서 PLAN_ERROR가 발생하면 P1으로 롤백하여 설계를 수정합니다.

P2 — Task Spec (상세 명세)

설계를 구현 가능한 수준의 상세 명세로 변환합니다:

순서	담당	문서	설명
1	Architect	`task_spec`	설계 기반 상세 태스크 명세 작성
2	Builder	`task_confirmed` 또는 `task_query`	명세 확인 (질문이 있으면 `task_query`)
3	Architect (선택적)	`task_spec` (수정)	질문이 있으면 명세 수정 후 재제출

P3 — Implementation (구현)

Builder(Claude)만 명세를 바탕으로 코드를 생성합니다:

다중 파일 생성
프로젝트 설정 파일 자동 생성
테스트 코드 포함
스냅샷 자동 백업 (구현 전)

Architect는 감사자이므로 구현에 참여하지 않습니다. 이는 설계자와 구현자를 분리하여 P4 감사의 객관성을 보장합니다.

P4 — Audit (감사 + 롤백)

Architect(Gemini)가 생성된 코드의 품질을 감사합니다:

감사 결과에 따른 처리:

결과	처리
PASSED	P5로 진행
CODE_ERROR (3회 미만)	Builder가 코드 수정 → Architect가 재감사
CODE_ERROR (3회 이상)	Fix Checkpoint 발동 → 사용자 판단
PLAN_ERROR (설계 오류)	P1(Design) 또는 P2(Task Spec)로 자동 롤백

Fix Checkpoint (수정 체크포인트)

코드 수정이 3회 연속 실패하면 사용자에게 확인합니다:

수정 계속 — 추가 수정 시도
P5로 진행 — 현재 상태로 마무리 (강제 종결)
프로젝트 중단 — 작업 중단

롤백 메커니즘

PLAN_ERROR 발생 시 오류 유형에 따라 자동 롤백합니다:

"design error" 또는 ROLLBACK_P1 → P1(Design)으로 롤백
"spec error" 또는 ROLLBACK_P2 → P2(Task Spec)로 롤백

P5 — Closure (병렬 보고)

양쪽 AI가 동시에 최종 보고서를 작성한 후 병합합니다:

순서	담당	문서	설명
1	Architect + Builder	`final_report_sub_architect` + `final_report_sub_builder`	Architect: 설계 관점 보고, Builder: 구현 관점 보고
2	Architect	`final_report_merged`	양쪽 보고서를 통합한 최종 보고서

완료 보고서 시트

모든 단계가 완료되면 최종 보고서가 표시됩니다:

각 단계별 소요 시간
생성된 문서 목록
생성된 코드 파일 목록
전체 프로젝트 통계

문서 명명 규칙

Alliance에서 생성되는 모든 문서는 다음 형식을 따릅니다:

SEQ-{번호}_PHASE-{페이즈}_{문서유형}_{날짜}_{시간}.md

예시:

SEQ-001_PHASE-PR_goal_input_20250214_143022.md
SEQ-005_PHASE-P0_idea_pitch_20250214_150511.md
SEQ-010_PHASE-P1_design_draft_architect_20250214_163445.md

구성 요소	설명
`SEQ-XXX`	순차 문서 번호 (자동 증가)
`PHASE-{페이즈}`	페이즈 코드 (PR, P0, P1, P2, P3, P4, P5)
`{문서유형}`	문서 종류 (idea_pitch, design_draft_architect 등)
`{날짜}_{시간}`	생성 시각 (YYYYMMDD_HHMMSS)

Alliance UI

레이아웃

영역	설명
왼쪽 패널	[프로젝트 \	히스토리] 탭 전환, 타임라인, 진행 상태, 문서 버블
오른쪽 패널	선택한 문서의 내용 뷰어

왼쪽 패널 상단에는 세그먼트 탭이 있습니다:

프로젝트 탭: 현재 실행 중인 프로젝트의 진행 상태, 타임라인, 문서 버블
히스토리 탭: 과거 실행 기록 목록 및 설정 복원/다시 실행 기능

타임라인 패널

표시 요소:

진행 바 — 7단계 시각적 표시
현재 상태 — 실행 중인 단계 이름
데몬 상태 — 실행중/정지/오류 표시
문서 버블 — 채팅 형태의 문서 타임라인

문서 버블 정보:

요소	설명
에이전트 이름	문서를 생성한 AI/역할
타임스탬프	생성 시간
페이즈 배지	어떤 단계의 문서인지
내용 미리보기	문서의 첫 몇 줄

문서 뷰어 패널

선택한 문서의 전체 내용을 마크다운으로 렌더링
문서가 선택되지 않으면 안내 플레이스홀더 표시

액션 버튼

상태	사용 가능한 액션
미시작	새 프로젝트 시작, 삭제
실행중	데몬 정지, 프로젝트 취소, 강제 리셋
완료	새 프로젝트 시작, 프로젝트 삭제
오류	재시도, 강제 리셋, 삭제

히스토리

Alliance는 실행이 완료(또는 실패)될 때마다 히스토리를 자동으로 기록합니다. 좌측 패널 상단의 [프로젝트 | 히스토리] 탭으로 전환하여 과거 실행 기록을 확인할 수 있습니다.

히스토리 탭

히스토리 목록에는 각 실행의 다음 정보가 표시됩니다:

제목 및 성공/실패 상태 아이콘
도달 단계 (예: P5), 소요 시간, 문서 수
설명 미리보기 (항목 선택 시)
출력 디렉토리 경로 (선택 시)

히스토리 액션 버튼

히스토리 항목을 선택하면 하단에 액션 버튼이 표시됩니다:

버튼	동작
설정 복원	선택한 항목의 제목, 설명, 첨부 파일을 프로젝트 탭으로 복원 (시트를 열지 않음)
다시 실행	설정을 복원하고 새 프로젝트 시트를 열어 바로 재실행 (스냅샷 기본 ON)
열기	출력 디렉토리를 Finder에서 열기
선택 해제	현재 선택을 해제
히스토리 삭제	전체 히스토리를 삭제

설정 복원은 환경만 복원합니다. 이후 "새 프로젝트 시작" 버튼을 눌러 시트를 열면 복원된 값이 자동으로 채워집니다. 다시 실행은 시트를 즉시 열어 빠르게 재시작할 수 있습니다.

스냅샷 연동

새 Alliance 프로젝트 시작 시 자동으로 스냅샷을 생성할 수 있습니다:

프로젝트 시작 시트에 "시작 전 스냅샷 생성" 체크박스가 있습니다 (기본: ON)
체크하면 Alliance가 시작되기 전에 프로젝트 전체의 스냅샷이 자동으로 생성됩니다
스냅샷 메시지에는 Alliance 프로젝트 제목이 포함됩니다

추천: Alliance를 여러 번 실행하거나 대규모 변경이 예상되는 경우, 스냅샷을 활성화해 두면 언제든 이전 상태로 복원할 수 있습니다.

재실행 시 파일 처리

새 프로젝트를 시작하면 이전 실행의 파일이 자동으로 정리됩니다:

항목	동작
`state.json`	새 프로젝트 정보로 덮어쓰기
`docs/` 폴더	이전 문서 파일 자동 삭제 후 새 문서 생성
`daemon.log`	이어쓰기
`history.json`	이전 실행 기록 보존 (삭제되지 않음)

Fast 모드

단순한 작업(버그 수정, 리팩토링, 테스트 등)에서는 PR과 P0 단계를 건너뛰고 P1부터 바로 시작합니다:

모드	시작 단계	적합한 작업
Creative (기본)	PR (Research)	새 프로젝트, 대규모 기능
Fast	P1 (Design)	버그 수정, 리팩토링, 테스트

자동 감지 키워드: bug, fix, refactoring, test

Colligi 분석 문서 연계

Colligi의 분석 보고서를 Alliance에 첨부 파일로 전달하면, 보고서에 포함된 키워드(fix, test, refactor 등)에 의해 Fast 모드가 자동 활성화되어 PR과 P0을 건너뛸 수 있습니다.

일반 입력:    PR → P0 → P1 → P2 → P3 → P4 → P5  (7단계)
Colligi:        ──────→ P1 → P2 → P3 → P4 → P5  (5단계)

💡 추천 워크플로우: 대규모 프로젝트에서는 Colligi로 먼저 분석 → 분석 결과를 Alliance에 첨부 → 설계부터 구현까지 자동 진행하는 2단계 워크플로우가 가장 효과적입니다.

파일 첨부

새 프로젝트 시트에서 .txt 또는 .md 파일을 첨부 파일로 추가할 수 있습니다:

첨부 파일 영역의 + 버튼으로 파일을 추가합니다
.txt, .md 형식만 지원됩니다
여러 개의 파일을 동시에 첨부할 수 있습니다
첨부된 파일의 내용은 프로젝트 설명에 자동으로 병합되어 AI에게 전달됩니다

Colligi 분석 보고서를 설명란에 복사/붙여넣기하는 대신, 첨부 파일로 추가하면 더 편리합니다.

자율 모드

자율 모드가 활성화되면 Human Checkpoint와 Fix Checkpoint를 자동으로 처리합니다:

P0에서 첫 번째 선택지를 자동 선택
P4에서 자동 재시도

⚠️ 자율 모드에서는 사용자 개입 없이 전체 파이프라인이 실행됩니다. 중요한 프로젝트에서는 비활성화하는 것을 권장합니다.

자율 모드 설정: 설정 → Intelligence → 자율 모드 토글

안전 장치

장치	값	설명
최대 반복	20	전체 문서 처리 사이클 최대 횟수
페이즈당 최대 문서	10	한 페이즈에서 생성할 수 있는 최대 문서 수
CLI 타임아웃	5분	AI CLI 실행당 최대 시간
재시도	3회	연결 오류 시 재시도 (10초 간격)

무한 루프 감지 시 자동으로 중단하고 사용자 개입을 요청합니다.

결과 저장 위치

{프로젝트}/
└── .projecthub/
    └── alliance/
        ├── state.json                                     # 워크플로우 상태
        ├── history.json                                   # 실행 히스토리
        ├── daemon.log                                     # 데몬 로그
        ├── daemon.pid                                     # 데몬 프로세스 ID
        └── docs/
            ├── SEQ-001_PHASE-PR_goal_input_*.md          # 목표 입력
            ├── SEQ-002_PHASE-PR_research_gemini_*.md     # Architect 리서치
            ├── SEQ-003_PHASE-PR_research_claude_*.md     # Builder 리서치
            ├── SEQ-004_PHASE-PR_research_summary_*.md    # 리서치 병합
            ├── SEQ-005_PHASE-P0_idea_pitch_*.md          # 아이디어 제시
            ├── SEQ-006_PHASE-P0_critical_review_*.md     # 비평
            ├── ...                                        # (이하 순차적 문서)
            └── SEQ-XXX_PHASE-P5_final_report_merged_*.md # 최종 보고서

활용 시나리오

전체 프로젝트 개발

Todo 앱을 만들어줘.
React + TypeScript + Supabase 스택으로,
사용자 인증, CRUD, 실시간 동기화 기능이 필요해.

Alliance는 리서치부터 구현, 감사까지 전체 개발 사이클을 관리합니다.

대규모 리팩토링

현재 프로젝트를 마이크로서비스 아키텍처로 전환해줘.
기존 모노리스 코드를 분석하고 서비스 분리 계획을 세워줘.

기술 마이그레이션

이 프로젝트의 JavaScript를 TypeScript로 마이그레이션해줘.
점진적으로 변환하되, 기존 기능이 깨지지 않도록 해줘.

다음 단계

Avalon3 — 중간 규모 작업에 적합한 토론 시스템
Colligi — 분석 중심 작업에 적합한 집단지성
AI 에이전트 — 간단한 코드 생성
설정 — AI 프로바이더 및 자율 모드 설정