AI Agent-Driven Development Ecosystem

왜 만들었나

기존 AI 코드 어시스턴트의 한계

대화 세션이 끝나면 상태가 사라진다 — 브랜치, 백로그, 빌드 큐 추적 불가
개별 도구 호출 단위로 동작 — 워크플로우 전체를 아우르는 강제력이 없다
리뷰가 "찾기만"하고 끝남 — 발견한 문제를 직접 고치지 않는다
단일 에이전트가 순차 실행 — 도메인별 전문성 없이 범용적으로만 훑는다
백로그에 쌓인 기계적 작업은 사람이 직접 선별하고 착수해야 한다

에이전트 드리븐의 비전

영속 상태 관리 — Go 데몬 + SQLite가 세션을 넘어 브랜치·백로그·큐 상태를 유지
Hook 기반 강제 — 모든 도구 호출 전에 게이트 검증. 규칙 위반은 원천 차단
자율 수정 — 리뷰어가 문제를 찾으면 직접 코드를 고치고, 못 고치는 건 백로그에 등록
7개 도메인 전문 에이전트가 병렬로 리뷰 — 로직, 설계, 보안, 테스트, 시스템, 문서, 인프라
FSD(Full Self-Driving) 백로그 — 기계적 작업은 스캔부터 머지까지 완전 자율

전체 아키텍처

Claude Code Session

Hook 게이트 레이어 — 모든 도구 호출 전 강제 검증

validate-build

validate-merge

validate-handoff

enforce-rebase

handoff-probe

validate-backlog

▼ IPC (JSON over Named Pipe / Unix Socket) ▼

apex-agent 데몬 — Go + SQLite 영속 상태 관리

Backlog Module
JSON ⇄ DB 동기화

Handoff Module
브랜치 상태 머신

Queue Module
빌드/머지 FIFO 락

Hook Module
검증 패턴 매칭

HTTP Dashboard
localhost:7600 HTMX

▲ 쿼리 & 커맨드 ▲

자동화 시스템 — 데몬 API를 활용하는 상위 오케스트레이터

Auto-Review
7개 병렬 리뷰어

FSD-Backlog
자율 백로그 소탕

HTTP Dashboard API
JSON + HTML 실시간

apex-agent — Go 데몬 백엔드

이게 뭔가

Claude Code의 도구 호출을 세션을 넘어 영속적으로 관리하는 Go 데몬 프로세스. SQLite에 상태를 저장하고, Named Pipe(Windows) / Unix Socket(Linux)으로 IPC 통신한다. Hook이 밀리초 단위로 실행되는 환경에서 장기 상태 머신과 트랜잭션을 가능하게 만드는 핵심 인프라.

왜 필요했나

Claude Code의 Hook은 각 도구 호출 전/후에 실행되는 무상태 셸 스크립트다. 브랜치가 어떤 상태인지, 백로그 항목이 누구에게 할당됐는지, 빌드가 큐에 있는지 — 이런 정보를 Hook만으로는 추적할 수 없다. 데몬이 있어야 상태 기반 게이트가 가능해진다.

Backlog Module (1,928 LOC)

이중 소스 관리: JSON 파일 = git 백업(메타데이터), DB = 운영 상태(OPEN/FIXING/RESOLVED)
Import-first Export: 내보내기 전에 반드시 JSON→DB 임포트 선행 — 데이터 유실 원천 방지
트랜잭션 기반 상태 전이: OPEN → FIXING → RESOLVED
스키마 마이그레이션 v1→v3: AUTOINCREMENT + 대소문자 정규화 + DEFAULT 값
Resolve / Release 양방향 전이: 작업 실패 시 FIXING → OPEN 롤백

Handoff Module (1,131 LOC)

브랜치 상태 머신: 등록 → 설계 → 구현 → 머지까지 전체 라이프사이클 관리
N:M 관계: 하나의 브랜치가 복수 백로그, 하나의 백로그가 복수 브랜치 가능
설계 단계 보호: 소스 파일(.cpp/.hpp) 편집을 상태 기반으로 차단
Workspace ID → git branch 역참조로 fallback resolution

Queue Module (393 LOC)

FIFO 채널 락: "build"와 "merge" 두 채널로 동시 빌드/머지 방지
Blocking Acquire: 500ms 폴링으로 대기, 선행 작업 완료 시 자동 승격
Dead Process Cleanup: 비정상 종료 PID 감지 → 자동 해제
채널 공유: 빌드와 벤치마크가 "build" 채널을 공유해 리소스 충돌 방지
PID 이관: 빌드 lock을 자식 프로세스 PID로 전이 — 고아 빌드 시 lock 유지
점유 시간 기록: finished_at 컬럼으로 빌드/머지 소요 시간 추적

Hook Module (133 LOC)

패턴 매칭 검증: cmake, ninja, build.bat 직접 호출 차단
Allowlist: apex-agent, run-hook, go build/test, 읽기 전용 명령은 허용
머지 lock 미획득 상태에서 gh pr merge 실행 차단
PreToolUse 이벤트에 바인딩 — 도구 실행 자체를 막는 선제적 방어

HTTP Dashboard (httpd 패키지)

Go html/template + HTMX 2.0.4: 외부 프레임워크 없이 net/http 표준 라이브러리만으로 구현
4개 페이지: Dashboard(전체 현황), Backlog(이슈 목록), Handoff(브랜치 상태), Queue(빌드/머지 큐)
1초 폴링으로 DB 상태 실시간 반영 — 속도 조절(Fast/Normal/Slow) 지원
JSON API 엔드포인트: 각 모듈별 /api/ 경로로 프로그래매틱 접근 가능
다크 테마 UI: 쇼케이스 페이지와 동일한 디자인 언어 적용

Handoff 상태 머신

notify start

→

started

→

notify design

→

design-notified

→

notify plan

→

implementing

→

notify merge

skip-design 경로: 설계가 불필요한 작업은 notify start --skip-design으로 바로 implementing 상태에 진입. 각 전이는 선행 상태를 검증하므로 잘못된 전환은 자동 차단된다.

HTTP 대시보드 — 실시간 모니터링

이게 뭔가

apex-agent 데몬에 내장된 브라우저 기반 실시간 대시보드. Go html/template + HTMX 2.0.4로 구현하여 외부 프레임워크 의존 없이 단일 바이너리에 내장된다. SQLite DB의 상태를 1초 간격으로 폴링하여 브라우저에 실시간 반영하며, 빌드 lock, 핸드오프 상태, 백로그 현황, 큐 점유를 한 눈에 파악할 수 있다. idle timer 연동으로 비활성 탭에서는 폴링을 자동 중단하여 리소스를 절약한다.

localhost:7600

■

Dashboard

전체 현황 요약

☰

Backlog

이슈 목록 + 필터

⇄

Handoff

브랜치 상태 머신

▶

Queue

빌드/머지 큐 상태

Go html/template + HTMX 2.0.4

외부 JS 프레임워크 없이 HTMX의 hx-get / hx-trigger로 서버 사이드 렌더링 + 부분 업데이트. 전체 페이지 새로고침 없이 실시간 갱신.

1-Second Polling + Speed Control

기본 1초 간격으로 DB 상태를 폴링. Fast(500ms) / Normal(1s) / Slow(3s) 속도 조절 가능. idle timer로 비활성 탭 자동 정지.

JSON API Endpoints

/api/dashboard, /api/backlog, /api/handoff, /api/queue — 프로그래매틱 접근을 위한 구조화된 JSON 응답.

Dark Theme + Single Binary

쇼케이스 페이지와 동일한 디자인 언어의 다크 테마. Go embed로 템플릿·CSS·JS를 바이너리에 내장 — 별도 파일 배포 불필요.

모니터링이 시스템을 개선한다: 대시보드를 통해 빌드 lock PID 버그를 발견하여 즉시 수정 — 모니터링 도구가 시스템 신뢰성을 직접 높인 사례. DB 상태를 시각화하는 것만으로도 CLI에서는 놓치기 쉬운 이상 패턴이 드러난다.

Auto-Review — 7개 병렬 리뷰 에이전트

이게 뭔가

코드 변경을 분석하고 7개 도메인 전문 리뷰 에이전트를 동시에 디스패치하는 자동 리뷰 시스템. 각 리뷰어는 자신의 전문 영역을 심층 분석하고, 발견한 문제를 직접 수정한다. 수정 불가능한 이슈는 등급·스코프와 함께 백로그에 자동 등록된다.

리뷰 파이프라인

변경 분석

git diff, 영향 범위

→

리뷰어 선별

변경 스코프 기반

→

7 Parallel Agents

docs-spec — 설계서↔코드 정합성

docs-records — 문서 포맷·완결성

logic — 알고리즘, 상태 전이, 에지 케이스

systems — 메모리 관리, RAII, 코루틴 안전성

test — 테스트 커버리지, 격리성

design — API 일관성, 모듈 경계, 의존성

infra-security — CMake, CI, 보안, 입력 검증

→

결과 통합

교차 분석

→

자동 수정

fix + backlog

→

빌드 검증

clang-format + build

→

PR + CI

커밋 → 푸시

핵심 성과

Zero-approval Fixing: 리뷰어가 문제를 찾으면 확인 없이 바로 수정
7개 도메인 동시 분석: 순차 리뷰 대비 시간 1/7, 커버리지 7배
자동 백로그 등록: 수정 불가 이슈도 유실 없이 추적
main 브랜치 자동 처리: main에서 실행 시 리뷰 브랜치 자동 생성→머지→삭제

리뷰어별 전문 영역

logic: 알고리즘 정확성, 에러 핸들링 경로, 상태 전이 완전성
systems: RAII 수명, 코루틴 strand 안전성, 데이터 레이스
design: CRTP 패턴, 모듈 경계, 의존성 방향, 타입 안전성
infra-security: 입력 검증, 크레덴셜 노출, CMake/vcpkg 호환성

FSD-Backlog — Full Self-Driving 백로그 소탕

이게 뭔가

백로그에 쌓인 기계적 작업을 사람의 개입 없이 스캔→선별→구현→머지까지 완전 자율로 수행하는 시스템. 설계 판단이 필요한 항목은 자동으로 건너뛰고, 확실한 항목만 골라서 처리한다. 자율주행차의 "확신이 없으면 멈춘다" 철학을 소프트웨어 개발에 적용.

FSD 파이프라인

Phase 1: 스캔

BACKLOG.md 전수 탐색

→

항목별 평가

기존 FSD 분석 태그 확인

다른 에이전트 작업 중 확인

코드 명확성 검증

기존 패턴으로 해결 가능?

→

번들링

스코프/파일 겹침 그룹화

→

Phase 2: 착수

handoff + skip-design

→

Phase 3: 구현

format→build→test

→

Phase 4: 머지

PR → squash merge

Graceful Degradation: 구현 중 예상보다 복잡한 항목이 발견되면 해당 항목의 변경만 리버트하고 [FSD 분석] 태그를 달아 백로그에 기록. 나머지 항목은 계속 진행한다.

핵심 성과

기계적 작업 완전 자동화: 오타, 포맷팅, 단순 버그 수정을 사람의 선별 없이 처리
Confidence-based Filtering: 확실한 항목만 착수, 불확실하면 멈춤
투명한 기록: 모든 판단에 [FSD 분석] 주석이 달려 추후 추적 가능
점진적 확장: 신뢰도 기준을 조정하며 자동화 범위를 점진적으로 넓힘

자율주행 비유

Level 0: 사람이 이슈 찾고, 선별하고, 수정하고, 리뷰하고, 머지
Level 2: AI가 이슈를 찾지만, 사람이 수정·리뷰·머지 (일반 AI 어시스턴트)
Level 4: AI가 스캔→선별→구현→머지. 사람은 방향 설정만 (← FSD-Backlog)
Level 5: 방향 설정까지 자율 (미래 목표)

Hook 게이트 — 안전장치

왜 Hook인가

에이전트에게 자율성을 주면서 동시에 절대 위반할 수 없는 규칙을 강제해야 한다. Hook은 Claude Code의 PreToolUse 이벤트에 바인딩되어, 도구 실행 자체를 차단한다. 에이전트가 아무리 창의적으로 우회를 시도해도 Hook이 먼저 실행되므로 물리적으로 규칙 위반이 불가능하다.

Hook	이벤트	역할	타입
`validate-build`	Bash	cmake, ninja, build.bat 직접 호출 차단 — `apex-agent queue build`만 허용	BLOCK
`validate-merge`	Bash	머지 lock 미획득 상태에서 `gh pr merge` 실행 차단	BLOCK
`validate-handoff`	Bash / Write	핸드오프 미등록 브랜치에서 Edit/Write/커밋 차단	GATE
`enforce-rebase`	Bash (push)	push 전 자동 rebase 실행 — 충돌 시 차단+안내	AUTO
`handoff-probe`	Edit / Write	설계 단계에서 소스 파일(.cpp/.hpp) 편집 차단, 문서는 허용	PROBE
`validate-backlog`	Edit / Write / Read	`docs/BACKLOG.json` 직접 접근 차단 — CLI(`backlog list/show/add/...`) 경유 필수	BLOCK

설계 원칙 — "자유와 안전의 공존": 에이전트에게 최대한의 자율성을 부여하되, 되돌리기 어려운 작업(빌드, 머지, 소스 변경)에만 게이트를 설치한다. 파일 읽기, 분석, 계획 수립에는 제약이 없다. 이렇게 하면 창의성을 해치지 않으면서도 치명적 실수를 원천 차단할 수 있다.

Feature Branch 라이프사이클

하나의 기능이 착수부터 머지까지 거치는 전체 흐름. 각 단계에서 데몬과 Hook이 어떻게 개입하는지 보여준다.

① 착수 — 브랜치 등록

Handoff 데몬에 브랜치를 등록하고, 연결된 백로그 항목을 FIXING 상태로 전환

apex-agent handoff notify start --backlog 126 --summary "..."

② 설계 — 소스 편집 차단

handoff-probe가 .cpp/.hpp 편집을 차단. 문서와 설계서만 작성 가능. 설계 완료 시 상태 전환

apex-agent handoff notify design --summary "..."

③ 구현 — 자유로운 코딩

상태가 implementing이면 모든 파일 편집 허용. clang-format 후 빌드

apex-agent queue build debug

④ 리뷰 — Auto-Review 실행

7개 리뷰어가 병렬로 코드 분석 → 자동 수정 → 백로그 등록 → 재빌드

/auto-review

⑤ 머지 준비 — Lock 획득

validate-merge가 lock 없는 머지를 차단. enforce-rebase가 자동 rebase

apex-agent queue merge acquire

⑥ 머지 게이트 검증

Handoff가 최종 검증: FIXING 백로그 없음? 통과 시 머지 허용

gh pr merge --squash --admin

⑦ 완료 — 정리

lock 해제, 백로그 상태를 RESOLVED로 전환, 브랜치 정리

apex-agent handoff notify merge && apex-agent queue merge release

⑧ 대시보드 — 실시간 모니터링

HTTP 대시보드에서 전체 라이프사이클을 실시간으로 시각화. 브랜치 상태, 큐 점유, 백로그 현황이 1초 간격으로 갱신되어 병목과 이상 패턴을 즉시 파악

http://localhost:7600

핵심 혁신

JSON + SQLite 분리

JSON 파일 = git 백업 (메타데이터: 제목, 등급, 스코프)
SQLite DB = 운영적 진실 (상태, 타임스탬프)

Git 추적 가능한 메타데이터와 빠른 상태 쿼리를 동시에 달성. Import-first Export로 두 소스 간 데이터 불일치를 원천 방지한다.

자율 수정 리뷰

기존: 리뷰어가 "여기 문제있음"이라고 코멘트 → 개발자가 수정
혁신: 리뷰어가 문제를 찾으면 직접 코드를 고친다

7개 도메인 전문 에이전트가 병렬로 분석하므로 사람 리뷰어 1명이 순차로 훑는 것보다 빠르고 빈틈이 없다.

Confidence 기반 자동화

"확신이 없으면 멈춘다"
FSD-Backlog는 명확한 해법이 있는 항목만 처리하고, 설계 판단이 필요한 건 태그를 달고 건너뛴다.

자동화의 범위를 점진적으로 넓히면서도 사고를 일으키지 않는 안전한 확장이 가능하다.

실시간 대시보드

Go 템플릿 + HTMX로 구현한 브라우저 대시보드. DB 상태를 1초 폴링으로 시각화. 외부 프레임워크 없이 net/http 표준 라이브러리만으로 단일 바이너리에 내장.

대시보드를 통해 빌드 lock PID 버그를 발견하여 즉시 수정 — 모니터링 도구가 시스템 신뢰성을 직접 높인 사례.

PreToolUse 강제

에이전트에게 "이것은 절대 하지 마"라고 프롬프트에 쓰는 것만으로는 부족하다. Hook이 도구 실행 레벨에서 물리적으로 차단하므로 에이전트의 hallucination이나 창의적 우회가 불가능하다.

IPC 데몬 아키텍처

Hook은 ~100ms 안에 실행되어야 하므로 장기 상태를 자체적으로 관리할 수 없다. Go 데몬이 세션 전체에 걸쳐 상태를 유지하고, 모든 Hook과 자동화 시스템이 IPC로 상태를 조회·변경한다.

크로스 플랫폼

Windows(Named Pipe)와 Linux(Unix Socket) 모두 지원. run-hook 스크립트가 플랫폼을 감지하고 적절한 바이너리를 실행한다. Go의 크로스 컴파일로 단일 코드베이스, 이중 배포.

엔지니어링 지표

컴포넌트	지표	상세
apex-agent	8,000+ LOC (Go)	Backlog 1,928 + Handoff 1,131 + Queue 393 + Hook 133 + httpd + IPC/daemon + CLI
Auto-Review	7 parallel agents	docs-spec, docs-records, logic, systems, test, design, infra-security
FSD-Backlog	4-phase pipeline	Scan → Select → Implement → Merge (confidence-gated)
Hook Gates	6 enforcement points	build, merge, handoff, rebase, edit-probe, backlog
HTTP Dashboard	4 pages	Dashboard, Backlog, Handoff, Queue — HTMX 1s polling, JSON API
DB Migrations	v1 → v3	AUTOINCREMENT, case normalization, junction table, git_branch fallback
State Machines	3개	Handoff (7-state), Backlog (3-state), Queue (FIFO)
IPC	JSON over pipe/socket	Windows Named Pipe + Linux Unix Socket, 자동 플랫폼 감지
테스트	~2,000 LOC	유닛 + E2E (in-process daemon), -race flag on CI

데이터 흐름 — 시스템 간 상호작용

Source of Truth

BACKLOG.json

git 백업 (메타데이터)

제목 · 등급 · 스코프 · 타입

↕ Import / Export

SQLite DB

운영 상태

OPEN → FIXING → RESOLVED

⇔

Daemon (IPC)

apex-agent

Backlog Handoff Queue Hook httpd

⇔

Consumers

6 Hooks

PreToolUse 게이트

Auto-Review

7개 병렬 리뷰어

FSD-Backlog

자율 백로그 소탕

Dashboard

localhost:7600

결론: 에이전트가 에이전트를 관리하는 시대

이 생태계의 핵심은 단순한 "AI 도구"가 아니라 자기 규율을 갖춘 자율 시스템이라는 점이다.

apex-agent는 영속 상태를 관리하는 뇌이고, 6개의 Hook은 규칙을 물리적으로 강제하는 울타리이며, Auto-Review는 품질을 보장하는 눈이고, FSD-Backlog는 기계적 작업을 소화하는 손이며, Dashboard는 전체를 조망하는 시야다.

이 다섯 가지가 유기적으로 결합되어, 사람이 "무엇을 만들 것인가"에만 집중할 수 있는 환경을 만든다. 브랜치 생성부터 코드 리뷰, 백로그 정리, 실시간 모니터링, 머지까지 — 개발의 모든 기계적 단계를 에이전트가 자율적으로 수행한다. 이것이 AI Agent-Driven Development의 현재이자, 소프트웨어 개발의 미래다.