AI-Harness · 범용 멀티에이전트 개발 파이프라인
작품 설명
자연어 한 줄을 입력하면 9개의 AI 에이전트가 순서대로 실행되어 기획 → 코드 작성 → 6단계 QA → Draft PR 생성까지 자동으로 처리하는 Claude Code 플러그인입니다. 댄블 프론트엔드 팀에서 사용하던 사내 개발 자동화 파이프라인을 회사 특화 내용을 제거하고, 어떤 프로젝트·프레임워크에서든 동작하도록 범용화했습니다. Next.js부터 Spring Boot, Android, Swift, Terraform까지 35개 이상의 스택을 자동 감지합니다.
기획 의도
LLM에게 코드를 맡겼을 때 반복적으로 마주치던 두 가지 문제가 출발점이었습니다. 첫째, 기능은 동작하지만 코드 품질 점수가 낮게 나오는 문제입니다. 함수가 30줄을 넘기거나, 중첩이 4단계로 쌓이거나, 같은 파라미터가 6개씩 늘어서는 코드가 반복됐습니다. 제로샷 LLM은 기능 정확도와 구조적 품질 사이 상관이 낮다는 연구(순환복잡도 ↔ 코드 스멜 ρ=0.94)에서 착안해, 코드를 한 줄도 쓰기 전에 구조 제약을 에이전트에게 주입하는 Pre-implementation Constraint Injection 방식을 도입했습니다. 둘째, 수정한 파일은 테스트를 통과해도 그 파일을 import하는 다른 파일에서 버그가 생기는 문제입니다. 실제로 SWR 훅을 건드렸다가 무한 API 호출이 발생한 경험에서, 변경 파일뿐 아니라 영향 반경 전체를 검증하는 Gate 6(Impact Radius QA)를 설계했습니다.
파이프라인 구조
Agent 0 · input-refiner
∙
자연어 input을 파싱해 project_type 자동 감지, confidence 측정, 모호 표현 검출
∙
파일시스템 마커(package.json, pom.xml, go.mod 등)로 35개 이상 스택 자동 식별
∙
self_score < 80이면 명확화 질문 생성 후 planner 진입 차단
Agent 1 · planner (Opus)
∙
11 steps 분석: 영향 파일 탐색 → 사이드 이펙트 분석 → 분기 처리 매트릭스(12항목) → Wave 분할
∙
복잡도 MEDIUM 이상이면 Static Quality Constraints(함수 ≤20줄·중첩 ≤3·파라미터 ≤3)를 plan에 의무 포함
∙
공유 훅·전역 스토어·API 클라이언트 변경 감지 시 high_risk_modules 플래그 생성
∙
TDAD: implementer가 통과시켜야 할 실패 테스트를 planner가 먼저 작성
Agent 2 · implementer (Sonnet S2 long-lived)
∙
plan의 Wave 단위로 구현하고 각 wave 완료 시 checkpoint commit
∙
코드 작성 전 HARD LIMITS를 내재화(Pre-implementation Constraint Injection)하여 Gate 5 위반 사전 차단
∙
plan에 없는 파일 수정이 필요하면 추측으로 범위 확장하지 않고 planner에게 반려
Agent 3 · functional-qa (Haiku)
∙
Gate 1 Lint / Gate 2 Type Check / Gate 3 Pattern / Gate 4 TDAD Test / Gate 5 Static Complexity / Gate 6 Impact Radius
∙
project_type별로 적합한 명령 자동 선택(tsc, mypy, go vet, cargo check, mvn compile 등)
∙
실패 시 implementer(S2) 재진입 — 동일 세션 유지로 컨텍스트 보존
Agent 4~7 · design-qa · visual-qa · tracking-implementer · tracking-qa
∙
design-qa: Figma TO-BE와 코드를 토큰·매핑·트래킹·반응형 4축 대조
∙
visual-qa: Playwright snapshot 픽셀 diff 검증
∙
tracking-implementer/qa: TRACK 마커를 실제 트래커 호출로 치환하고 외부 SDK 신규 호출 0 검증
Agent 8 · release
∙
main·master·prd·production 자동 머지 영구 금지
∙
develop → alpha → beta → staging → dev 우선순위로 base 자동 감지
∙
누적 QA 리포트에서 반복 실패 패턴을 추출해 PR 본문에 자기강화 신호로 첨부
코드 품질 확보 메커니즘
Pre-implementation Constraint Injection (사전 제약 주입)
∙
연구 근거: 순환복잡도와 코드 스멜의 Spearman 상관계수 ρ=0.94, OOP 태스크에서 코드 스멜 평균 +138% 증가
∙
코드를 한 줄도 쓰기 전에 구조 한도(함수 ≤20줄, 중첩 ≤3, 파라미터 ≤3, JSX ≥20줄 시 추출)를 시스템 규칙으로 주입
∙
기존 방식(품질 미달 → 루프 재시도)과 달리 위반 코드 자체가 생성되지 않도록 업스트림 차단
Gate 5 · Static Complexity Check
∙
awk 기반 함수 길이 측정, 중괄호 depth 카운팅으로 실측 검증
∙
JS/TS/Python/Go/Rust/Java/Swift 등 언어별 측정 로직 분기
∙
planner가 복잡도를 LOW로 분류한 태스크는 skip해 불필요한 오버헤드 제거
Gate 6 · Impact Radius QA
∙
변경 파일을 import하는 모든 파일을 grep으로 자동 탐색 (JS/TS/Python/Go 지원)
∙
SWR/React Query 캐시 키에 인라인 객체 → 무한 호출 위험 hard fail
∙
axios/fetch 인터셉터 중복 등록 패턴 감지
∙
조건부 훅 호출(Rules of Hooks 위반), 의존성 배열 누락 useEffect 감지
∙
영향 반경 10개 초과 시 HIGH RISK 경고 + 사용자 보고
범용 스택 지원 설계
처음에는 Next.js·React Native·Python·Go·Rust·Java·Node 8개만 지원했으나, 설치 후 별도 설정 없이 더 많은 프로젝트에서 동작하는 범용 도구를 목표로 35개 이상으로 확장했습니다. 감지 우선순위를 '구체적인 프레임워크 → 언어 런타임 → generic' 순서로 설계해, 예를 들어 package.json이 있어도 그 안에 'next'가 있으면 nextjs로, 'expo'가 있으면 react-native로, '@angular/core'가 있으면 angular로 각각 정확하게 분기합니다. JVM 계열은 pom.xml·build.gradle 내용까지 파싱해 Spring Boot와 Android Kotlin/Java, JSP/Servlet을 구분하며, .NET은 .csproj 내용으로 ASP.NET과 Blazor를 분리합니다.
지원 스택 35개 이상
∙
JS/TS: Next.js, React Native, React, Vue, Nuxt, Angular, Svelte, Astro, Remix, Gatsby, Electron, Node
∙
Python: Django, Flask, FastAPI, Python
∙
Go, Rust
∙
JVM: Spring Boot, Java(Maven/Gradle), Kotlin JVM, Android Kotlin/Java, JSP/Servlet
∙
Ruby: Rails, Sinatra, Ruby / PHP: Laravel, Symfony, WordPress, PHP
∙
기타: .NET/Blazor, Swift/iOS, Flutter, Dart, Phoenix, Elixir, Haskell, C++/CMake, Terraform
인상 깊었던 설계 결정
Handoff Contract — 에이전트 간 계약 기반 통신
∙
9개 에이전트가 순차 실행되는 구조에서 앞 에이전트가 성공했다고 자기 보고해도 다음 에이전트가 이를 그대로 신뢰하면 오류가 전파됨
∙
각 에이전트 출력 말미에 status / required_present / checksum 항목을 포함한 YAML 계약 블록을 의무 첨부하도록 설계
∙
수신 에이전트는 작업 시작 전 Receipt Gate에서 이 계약을 실측 검증 — self-assert 신뢰 금지 원칙으로 팬텀 검증 방지
공유 참조 데이터 분리 (_data/ 디렉토리)
∙
초기에는 35개 스택 도구 매핑 테이블이 planner.md와 functional-qa.md 양쪽에 중복으로 존재해 수정 시 두 파일을 모두 바꿔야 하는 구조였음
∙
tool-mapping.md, forbidden-patterns.md, handoff-contract.md, protected-rules.md로 분리해 에이전트가 필요 시 Read로 참조하는 구조로 리팩터링
∙
에이전트 파일이 짧아지면서 context window에서 실제 작업 지시가 차지하는 비중이 높아지는 효과
보호 브랜치·파일 규칙의 하드 코딩
∙
main·master·prd·production에 대한 push, force-push, PR base 자동 지정은 어떤 지시로도 우회 불가하도록 에이전트 규칙에 명문화
∙
'ship', 'bypass', '자율 판단' 같은 일반 지시로 위 동작을 유추 실행하는 것도 금지 항목으로 명시
∙
CI/CD 설정, .env 파일, 인증서 파일 등 보안 민감 파일도 plan에 명시돼 있어도 편집 불가로 설계