AI DEV DIRECTOR

세 개의 AI 코딩 CLI를 한 회사처럼 돌려, 목표 한 줄을 검증된 코드로 바꾸는 로컬 개발 감독관. A local orchestrator that runs three subscription AI CLIs (Claude Code, OpenAI Codex, Google Antigravity) as HEAD / BUILDER / REVIEWER, and turns a one-line goal into tested, independently reviewed code — without a single pay-per-use API call.

상태: 개인 운영 환경에서 매일 쓰고 있는 코드를 그대로 공개한 것입니다. 윈도우 우선, 한국어 UI. macOS / Linux: 코드는 준비돼 있지만 미검증입니다 (v3.1.8, 아래 참고). 맥에서 돌려 보신 분은 이슈로 알려 주시면 고맙겠습니다. Status: the code we run daily, published as-is. Windows-first, Korean UI, English comments. macOS / Linux: supported in code since v3.1.8 but not yet verified on a real Mac — reports welcome.

---

macOS 전용 앱 (HanginIs fork)

이 포크에는 Swift/AppKit + WKWebView 전용 앱과 macOS 실행 관련 수정이 포함됩니다. 기존 CLI 로그인과 프로젝트 설정을 사용하며, 서버를 자동 실행하고 콘솔을 앱 창에 표시합니다.

python3 -m venv .venv
./.venv/bin/python -m pip install -r requirements.txt
./script/build_and_run.sh

Xcode/Swift 5.9 이상, macOS 13 이상이 필요합니다. 결과는 dist/AI-Dev-Director.app입니다. 앱은 빌드 시 저장소의 절대 경로를 기억하므로 저장소를 이동했다면 다시 빌드하세요. 앱 자체는 응용 프로그램 폴더로 복사할 수 있습니다. --build-only 옵션은 앱을 실행하지 않고 빌드만 합니다.

• 앱 안의 프로젝트 선택 버튼은 macOS 기본 폴더 선택 창을 엽니다.
• 종료 시 서버를 백그라운드로 유지하거나 작업과 서버를 중지할 수 있습니다. 콘솔의 시스템 중지로 서버가 이미 꺼졌다면 작업 중지 후 종료는 바로 앱을 닫습니다.
• 실행 오류는 data/desktop-server.log에 기록됩니다.
• 아이콘: AI-assisted artwork, 이 포크를 위해 생성. 원본은 macos/Assets/AppIcon.png.
• 맥에서 앱 실행·콘솔 표시·폴더 선택 및 취소·서버 자동 시작을 수동 확인했습니다. AI 개발 미션 전체의 성공을 보증하는 검증은 아니며, 공급자 오류는 별도로 확인해야 합니다.

무엇을 하나 (What it does)

   goal ──▶ HEAD (plans an ORDER) ──▶ BUILDER (proposes whole files as JSON)
                 ▲                              │
                 │                              ▼
          HEAD decision ◀── REVIEWER ◀── Verifier (build / tests in an isolated worktree)

• NORMAL 파이프라인 — HEAD가 목표를 ORDER(허용 경로·파일 수·diff 상한이 명시된 작업 명세)로 만들고, BUILDER가 파일 전체를 JSON으로 제출하면 Director가 Scope Guard로 검사한 뒤 격리 작업본(git worktree) 에 반영하고 테스트를 돌립니다. REVIEWER가 독립 검토하고 HEAD가 PASS/FAIL/수정 지시를 내립니다. 원본 프로젝트는 절대 직접 수정되지 않습니다.
• 미션(Mission) — 채팅 한 줄이 미션이 됩니다. HEAD가 마일스톤 ORDER를 하나씩 계획하고, 각 단계는 직전 PASS 작업본의 스냅샷에서 시작하며, 실제 증거(테스트·리뷰)를 보고 다시 계획합니다. 완료된 산출물은 설정에 따라 자동 반영되되 사람이 그 사이 고친 파일은 덮어쓰지 않습니다.
• HEAD 프록시 자율 모드 — 결제·실계좌 주문·실제 자격증명·되돌릴 수 없는 외부 행동만 사람에게 묻고, 나머지 마찰(빌더 JSON 깨짐, 토큰 한도, 경로 범위, 리뷰 지적, 한도 초과)은 재시도·공급자 교체·재계획으로 스스로 풉니다.
• TRIAD 연구 모드 — 세 AI가 독립 연구 → 상호 비판 → 종합 가설 → NORMAL 파이프라인으로 실험 구현 → 세 갈래 해석 → 연구 메모리. 설계와 구현은 docs/V3_TRIAD_RESEARCH_PLAN.md.
• TRINITY 콘솔(8081) — 세 AI의 역할·호출·토큰·현재 단계를 보여주는 무대형 대시보드, 채팅, 미션 다시보기, 역할 교환, 작업 정지 / 시스템 중지 버튼. /classic은 표 중심의 작업실 화면입니다.

지키는 것 (Hard rules, enforced in code)

규칙	구현
종량제 API 금지 — 로그인된 구독 CLI만 사용	core/env_utils.py 가 모든 *_API_KEY 를 환경에서 제거하고 CLI를 호출
원본 프로젝트 무수정	모든 빌드는 .director_worktrees/ 안의 git worktree에서만
Scope Guard	ORDER의 허용 경로·보호 경로·파일 수·diff 상한을 Director가 검사, 빌더는 완화 불가 (core/safety.py)
리뷰어 fail-closed	리뷰 응답이 없거나 깨지면 PASS가 아니라 FAIL
돈·자격증명은 사람이	core/autopilot.py 의 정지 조건 — 결제, 실계좌 주문 코드(OrderSend 등), 계정 생성, 외부 비가역 행동
프로세스 트리 타임아웃	멈춘 CLI는 자식까지 함께 종료 (core/process_runner.py)
정지는 정지	채팅의 "중단/멈춰/stop", 콘솔의 작업 정지 버튼 → 돌던 CLI 즉시 종료, 미션 STOPPED 고정, 재시작해도 재개 안 됨

요구 사항 (Requirements)

• Windows 10/11 (매일 쓰는 환경). macOS / Linux는 미검증: 프로세스 트리 종료(psutil), 작업본 폴더 열기(open / xdg-open), CLI 탐색(~/.local/bin, /opt/homebrew/bin, /usr/local/bin), 셸 런처(start-companion.sh)까지 코드는 갖춰져 있으나 실제 맥에서 돌려 보지 못했습니다. 폴더 선택 창은 tkinter라 Homebrew 파이썬은 brew install python-tk가 필요하고, 없으면 콘솔에 경로를 직접 입력하면 됩니다.
• Python 3.9+ 와 pip install -r requirements.txt
• Git
• 로그인된 CLI 중 최소 두 개: Claude Code(claude), OpenAI Codex(codex), Google Antigravity(agy). 구독 로그인 세션을 그대로 씁니다. API 키는 필요 없고, 있어도 무시됩니다.

빠른 시작 (Quick start)

pip install -r requirements.txt
python -m pytest -q            # 604개 테스트, CLI 없이 스텁으로 돕니다 (약 25분)

2026-11-04 기준 593/596 통과, 3개 실패 (v3.1.8에서 플랫폼 분기 테스트 8개 추가, 윈도우에서 통과). 실패 3개는 알려진 드리프트입니다: 두 개는 "저장소가 아닌 폴더는 거부"를 기대하는 옛 UI 테스트인데 v3.0부터 빈 폴더도 자동 준비(greenfield)하도록 바뀌었고, 하나는 스냅샷 제외 목록 픽스처 드리프트입니다. 안전 게이트·정책·미션 테스트는 모두 통과합니다.

콘솔 켜기 (윈도우):

.\start-companion.ps1          # http://127.0.0.1:8081  (TRINITY 무대)  ·  /classic (작업실)
.\stop-companion.ps1

콘솔 켜기 (macOS / Linux, 미검증):

chmod +x start-companion.sh stop-companion.sh
./start-companion.sh           # python3 companion_server.py 를 백그라운드로, PID는 data/companion.pid
./stop-companion.sh

Antigravity CLI(agy)가 그 플랫폼에 없으면 config.yaml에서 BUILDER를 codex 또는 claude로 바꾸면 됩니다. CLI 두 개로도 동작합니다.

CLI로 바로 한 번 돌리기:

python director.py run -p D:/work/my_project -g "src/calc.py에 add(a, b)를 만들고 테스트를 추가해"
python director.py mission -p D:/work/my_project -g "회원가입 흐름을 끝까지 구현"
python director.py do -g "로그인 버그 고쳐" --profile quick     # 미션 + 자동 반영을 한 번에
python director.py status
python director.py clean-worktrees -p D:/work/my_project --dry-run

설정 (Configuration)

config.yaml 한 파일입니다. 역할별 공급자(head/builder/reviewer), 타임아웃, 안전 상한, 검증 명령, 자율 모드(autonomy)와 프로필(quick / standard / deep), 프로젝트별 검증 명령(projects)을 둡니다. 프로젝트별 검증 명령을 프로젝트 안이 아니라 여기에 두는 이유는 빌더가 그것을 약화시킬 수 없게 하기 위해서입니다.

프로젝트별 명령이 없으면 프로젝트가 실제로 지원하는 테스트를 고릅니다. 파이썬 tests/가 있으면 pytest(프로젝트에 자체 pytest 설정이 없으면 상위 폴더의 pytest.ini를 쓰지 않도록 -c /dev/null --rootdir .), Package.swift에 테스트 대상이 있으면 swift test, package.json에 test 스크립트가 있으면 npm test입니다. 기본값 python -m pytest tests/가 Swift·JS 프로젝트를 종료 코드 4로 매번 실패시키던 문제를 막습니다. swift test 결과의 XCTest·Swift Testing 통과 수도 집계해 회귀를 판단합니다. verification.timeout(기본 120초)은 검증 명령 하나에 주는 시간입니다.

절대 경로처럼 한 컴퓨터에만 맞는 설정은 깃에 올라가지 않는 config.local.yaml에 둡니다. config.yaml과 같은 구조이며 그 위에 병합됩니다. 예: 테스트 대상이 없는 SwiftPM 앱의 점검 실행 파일, NumPy가 필요한 앱의 전용 가상환경 Python.

companion.json 은 콘솔 포트와(선택) 허용 프로젝트 목록입니다. 콘솔은 항상 127.0.0.1 에만 바인딩되며, 상태를 바꾸는 요청은 로컬 출처 검사와 브리지 토큰(data/solomon-bridge.token, 첫 실행 때 생성)을 요구합니다.

구조 (Layout)

director.py            CLI 진입점 (run / mission / do / status / resume / clean-worktrees)
companion_server.py    8081 콘솔 서버 (정적 파일 허용 목록 + /ops/* API)
dashboard_server.py    작업실(/classic)·채팅·미션 정지·상태 요약
agents/                HEAD / BUILDER / REVIEWER 어댑터 (claude, codex, antigravity, google 역할, mock)
core/                  orchestrator, mission, autopilot(정책), safety(Scope Guard), verifier, git_manager,
                       process_runner, provider_manager(장애 조치), research_*(TRIAD), usage(토큰 집계)
schemas/               ORDER / BuilderResult / ReviewResult / Decision / Provenance (pydantic)
console/               TRINITY 무대와 작업실 프런트엔드 (의존성 없는 정적 파일)
scripts/               폴더 선택 도우미, CLI 진단, 실패 run 재시도, 역할 smoke
tests/                 604 tests (스텁 CLI로 격리, 로컬 설정 파일에 의존하지 않음; 실제 CLI 통합은 -m integration_cli 로 opt-in)
docs/                  설계·마일스톤 기록

알려진 한계 (Known limits)

• 큰 변경도 "파일 전체 JSON 제안" 방식이라 CLI 출력 한도에 걸릴 수 있습니다. 한 번은 압축 재시도, 그 다음은 공급자 교체.
• 각 CLI의 구독 한도(쿼터)에 그대로 종속됩니다. 한도가 끝나면 장애 조치 순서대로 다른 CLI로 넘어갑니다.
• 리뷰어와 HEAD가 같은 공급자로 몰리면 REDUCED_INDEPENDENCE 표시와 함께 통과시킵니다(숨기지 않음).
• 테스트는 로컬 스텁 CLI로 돕니다. 실제 세 CLI를 끝까지 태우는 E2E는 opt-in 마커로만 돌아갑니다.
• macOS / Linux는 미검증입니다. 일부 테스트는 윈도우 드라이브 문자 경로(C:/...)를 전제로 해서 그 플랫폼에서는 실패할 수 있으며, 제품 동작과는 무관합니다.

라이선스 (License)

MIT License — LICENSE 파일을 보세요. 자유롭게 쓰고, 고치고, 재배포할 수 있습니다. 저작권 표시와 라이선스 문구만 남겨 주세요.