AI 협업 인프라의 진화
-단순 컨텍스트 주입에서 팀 전체 AI 개발 운영 플랫폼으로-
오늘날 Claude, Codex, Cursor 같은 AI 에이전트는 코드를 작성하고 리뷰하고 테스트를 짭니다. 기술적 능력 자체는 뛰어납니다. 하지만 대규모 플랫폼에서 AI와 함께 일해보면 금세 한계가 드러납니다. AI는 매 세션마다 아무것도 모르는 상태로 시작합니다.
이 문제를 해결하기 위해 Vizend 팀이 만든 것이 vizend-agent-hub입니다. v0.4.0 기준으로 17개 Skill · 8개 Agent · 9개 Hook 스크립트를 갖춘 Claude Code 플러그인으로, Meta-Harness 독립화와 팀 품질 피드백 루프 등 4단계 고도화 로드맵을 설계하고 있습니다.
1. 문제 — AI와 함께 일한다는 것의 현실
|
AI 에이전트는 매 세션마다 아무것도 모르는 상태로 시작한다. |
단일 서비스·소규모 프로젝트에서는 프롬프트로 설명하면 됩니다. 하지만 수십 개 서비스가 얽힌 대규모 플랫폼에서는 이야기가 달라집니다.
|
① |
AI가 일반적인 단일 앱 패턴(src/components, src/pages)으로 수렴합니다. Vizend는 episodes/dramas/libraries 기반 workspace 구조가 핵심인데, |
|
② |
구조를 택한 근거와 참고 문서가 남지 않습니다. 결과물은 만들어지지만 '설명 가능한 개발 과정'이 없습니다. |
|
③ |
작업 중단·재개·승인 요청 같은 운영 흐름을 단발성 AI 호출로는 처리할 수 없습니다. 장기 작업에서 계획→구현→평가→승인 지점이 필요했습니다. |
이 문제를 프롬프트 개인기로 풀 수 없습니다. 구조적으로 해결해야 합니다.
▌ "Claude/Codex 자체가 하네스 아닌가?"
맞습니다. Claude Code와 Codex는 이미 강력한 하네스 기능을 갖추고 있습니다. 하지만 없는 것이 있습니다.
|
기능 |
Claude Code / Codex |
+ vizend-agent-hub |
|---|---|---|
|
에이전트 루프 · 파일 읽기/쓰기 |
✅ |
✅ |
|
세션 상태 관리 |
△ 제한적 |
✅ 자동 저장·복구 |
|
Vizend 도메인 지식 (레이어·서비스·컨벤션) |
❌ |
✅ 17 Skills |
|
서비스 간 연동 패턴 |
❌ |
✅ cross-service-context |
|
팀 공용 검증 기준 |
❌ |
✅ vsr-check |
도구는 있지만, 우리 코드를 아는 도구가 아닙니다. vizend-agent-hub는 Claude/Codex 위에 Vizend 전용 설정 레이어를 얹는 것입니다. Skill 파일 하나만 고치면 전 팀에 즉시 적용됩니다.
2. 현재 vizend-agent-hub — v0.4.0
초기에는 단순히 Vizend 구조 문서를 AI에게 읽히는 용도였습니다. 지금은 Claude Code 플러그인 시스템 위에서 자동으로 실행되는 Skill·Agent·Hook의 집합체로 성장했습니다.
▌ Skills — 17개
세션에서 /vizend-agent-hub:skill-name 으로 직접 호출하거나, Hook이 키워드를 감지해 자동으로 라우팅합니다.
|
카테고리 |
Skill |
역할 |
|---|---|---|
|
도메인 컨텍스트 |
service-catalog |
서비스 목록·책임·의존 관계 요약 |
|
architecture |
레이어 구조(Facade→Feature→Store→Boot) + 의존 방향 규칙 |
|
|
conventions |
CDO/VO/SDO/RDO 네이밍, 패키지 컨벤션 |
|
|
coding-standards |
Java 21/Spring Boot 코딩 표준 |
|
|
glossary |
도메인 용어 사전 빠른 조회 |
|
|
개발 워크플로우 |
hub-index |
스킬 라우팅 메타 허브 — 어느 스킬을 써야 할지 안내 |
|
dev-loop |
계획→구현→검증 자율 반복 루프 |
|
|
git-workflow |
브랜치 전략·Conventional Commits·MR 규칙 |
|
|
cross-service-context |
멀티 서비스 시나리오 컨텍스트 로딩 |
|
|
품질 / 검증 |
vsr-check ★ |
8카테고리 위반 자동 탐지 — 코드 근거만, 추론 보고 금지 |
|
security-review |
JWT·인증·보안 취약점 탐지 |
|
|
verification-loop |
빌드·테스트·린트·보안·레이어링 6단계 전체 루프 |
|
|
create-integration-test |
Flow/Seek/Action @SpringBootTest 기반 테스트 생성 |
|
|
자동화 / 생성 |
sync-domain-docs |
도메인 코드 ↔ 문서 동기화 |
|
flyway-script |
Flyway 마이그레이션 스크립트 작성 가이드 |
▌ Agents — 8개
메인 컨텍스트와 격리된 전문화 인스턴스. 코드를 수정하면 code-reviewer가 자동으로 호출되는 식으로 능동적으로 동작하며, 독립 분석 후 결과만 반환합니다.
|
Agent |
역할 |
자동 트리거 |
|---|---|---|
|
planner |
TASK.md 생성 · Pre-flight 진단 · 범위(Scope) 분류 |
멀티스텝·멀티서비스 작업 |
|
code-reviewer |
레이어링·네이밍·테스트 정합성 검토 |
코드 작성·수정 후 자동 |
|
security-reviewer |
JWT·StageContext·인증 취약점 탐지 |
인증 코드, 새 API 엔드포인트 |
|
violation-detector |
8카테고리 코드 근거 기반 위반 탐지 |
vsr-check 내부 실행 |
|
tdd-guide |
Red-Green-Refactor 사이클 안내 |
새 기능, 버그 픽스 |
|
integration-test |
@SpringBootTest 기반 테스트 스캐폴딩 |
Flow/Seek/Action 테스트 작성 |
|
architect |
시스템 설계·기술 트레이드오프 분석 |
의존 구조 변경, 신규 서비스 |
|
refactor-cleaner |
Dead code 제거·복잡도 축소 |
대규모 정리, 릴리스 전 |
▌ Hook — 자동 실행되는 보이지 않는 손
Skill·Agent와 달리 Hook은 사용자가 호출하지 않아도 세션 이벤트마다 자동 실행됩니다. AI 판단 없이 하네스가 직접 스크립트를 실행합니다.
|
이벤트 |
동작 |
|---|---|
|
SessionStart |
Vizend 컨텍스트 자동 주입 · 이전 세션 상태 복원 · 허브 버전 확인 · 워크스페이스 헬스 체크 |
|
UserPromptSubmit |
서비스명 키워드 감지 → 관련 Skill 라우팅 제안 |
|
PostToolUse |
파일 수정 시 TASK.md 스냅샷 저장 (세션 중단 대비) |
|
PreCompact |
컨텍스트 압축 전 핵심 진행 상태 보존 |
|
Stop |
TASK.md 체크박스 드리프트 감지 · 미완료 리마인드 · 세션 상태 저장 |
세션이 시작되면 Vizend 컨텍스트가 자동으로 주입되고 이전 작업 상태가 복원됩니다. 세션이 갑자기 종료되어도 마지막 스냅샷 시점의 TASK.md가 다음 세션에서 자동 복구됩니다.
3. 사용 전후 비교 — 실제 개발 시나리오
시나리오: "gallery에 새 구독(subscribe) API 추가해줘"
|
❌ 하네스 없이 |
✅ 하네스 사용 시 |
|---|---|
|
• AI: 일반 Spring Boot 패턴으로 생성 • "Facade-Feature 레이어 써야 해" • "@AuthorizedRole 빠졌어" • "StageContext로 pavilionId 꺼내야 해" • "qra-backend로 이벤트 넘겨야 해" • … 수정 반복 → 재지시 5~6회 · 세션 1시간+ |
• [Hook] 컨텍스트 자동 주입 + 'gallery' 감지 → Skill 추천 • AI: "SubscriptionPvsFlow + @AuthorizedRole + EventProxy로 qra-backend 연동까지 처리할까요?" • 개발자: "OK" • Command·Resource·Flow·Logic·이벤트 전부 생성 • [Hook] vsr-check 자동 실행 → 위반 0건 → 재지시 0~1회 · 세션 15~20분 |
▸ 하네스 없이 생성된 첫 코드의 위반 항목
동일 시나리오에서 하네스 없이 생성된 코드를 vsr-check로 스캔한 결과입니다. 하네스 사용 시 동일 조건에서 위반 0건.
|
# |
위반 항목 |
카테고리 |
|---|---|---|
|
1 |
Facade 내 레이어 분리 없이 Repository 직접 호출 |
Architecture CRITICAL |
|
2 |
@AuthorizedRole 누락 — 열린 API |
Security CRITICAL |
|
3 |
Request/Response DTO 사용 (CDO/CommandRequest 아님) |
Product |
|
4 |
도메인 Entity new 직접 생성 — Logic 경유 없음 |
Architecture |
|
5 |
cross-service 이벤트 발행 누락 → qra-backend 연동 단절 |
Product CRITICAL |
핵심: 하네스가 먼저 맥락을 주입하고, Skill이 규칙을 적용하고, vsr-check가 결과를 검증합니다. '어떻게 해달라'를 매번 설명하지 않아도 됩니다.
▸ 세 가지 관점 비교
|
❌ 하네스 없이 |
✅ 하네스 사용 시 |
|
|---|---|---|
|
생산성 |
||
|
세션 시작 비용 |
서비스 구조 매번 설명 (10~15분) |
Hook 자동 주입 (0분) |
|
첫 코드 품질 |
일반 Spring → 수정 반복 |
처음부터 Vizend 패턴 |
|
재지시 횟수 |
5~6회 |
0~1회 |
|
팀 유지보수성 |
||
|
레이어 일관성 |
개발자마다 다름 |
Facade→Feature→Domain 고정 |
|
네이밍 일관성 |
DTO/Request 혼재 |
CDO/VO/CommandRequest 일관 |
|
역할 접미사 |
임의 (Service/Handler) |
PvsFlow/DvpFlow/PeerFlow 고정 |
|
발전 가능성 |
||
|
새 서비스 추가 |
규칙 재설명 필요 |
AGENTS.md 한 장으로 즉시 |
|
AI 도구 전환 |
규칙 재입력 필요 |
AGENTS.md 공유 — 제로 비용 |
|
규칙 업데이트 |
프롬프트 개인기 의존 |
Skill 파일 1개 수정 → 전 팀 적용 |
▸ 수치로 확인된 변화
|
항목 |
이전 |
이후 |
|---|---|---|
|
서비스 가이드 문서 수 |
3개 |
82개 (전 서비스 커버) |
|
공용 Skill |
0개 |
17개 |
|
전문화 Agent |
0개 |
8개 |
|
자동 Hook 스크립트 |
0개 |
9개 |
|
PR 전 위반 탐지 |
사람이 직접 확인 |
vsr-check 8카테고리 자동 |
|
세션 중단 복구 |
수작업 재설명 |
TASK.md 스냅샷 자동 복구 |
|
AI 도구 전환 비용 |
규칙 재입력 필요 |
AGENTS.md 공유 — 제로 비용 |
|
첫 코드 레이어 위반 건수 |
평균 5~7건 |
0건 |
4. 앞으로 — 고도화 로드맵
현재 Phase 1은 완료됐습니다. 남은 3가지 핵심 한계를 Phase 2~4에서 해결합니다.
|
단계 |
목표 |
내용 |
|---|---|---|
|
Phase 1 ✅ 완료 |
지식·역할·검증·상태 레이어 |
Skill 17개 · Agent 8개 · Hook 9개 · 문서 82개 "AI가 맥락을 갖추고, 이전 작업을 기억한다" |
|
Phase 2 🔨 단기 |
품질 강화 + 피드백 루프 |
Hook 프로필(minimal / standard / strict) + 교정 이벤트 자동 감지 → Hub 레포지토리 MR 자동 제출 "교정이 팀 허브 품질 개선으로 이어진다" |
|
Phase 3 📐 중기 |
분리 + CI 연동 레이어 |
Meta-Harness 독립 플러그인 추출 + CI 문서 자동화 + MCP(GitLab·Jira·빌드 결과) "AI가 시스템을 직접 본다" |
|
Phase 4 🚀 장기 |
오케스트레이션 레이어 |
병렬 에이전트 실행 + 패턴 자동 추출 + 팀 공용 하네스 서버 "AI가 팀의 인프라가 된다" |
▌ 핵심 설계 방향: Meta-Harness
Phase 3의 가장 중요한 목표는 현재 혼재된 구조를 두 레이어로 완전히 분리하는 것이다. Meta-Harness가 독립 플러그인이 되면 다른 팀은 자신의 도메인 지식 허브만 추가하면 된다.
|
Meta-Harness — 범용 AI 협업 인프라 Session 관리 · TASK 관리 · Hub 품질 피드백 · Memory · Skill Router | 프로젝트 무관 |
|---|
|
↑ depends on ↑ |
|
vizend-agent-hub — Vizend 도메인 컨텍스트 service-catalog · architecture · conventions · vsr-check 등 17 Skills + 8 Agents |
▌ 팀 품질 피드백 루프
현재 세션 내 교정은 휘발됩니다. Phase 2에서 교정 이벤트를 자동 감지해 팀 전체 품질 개선으로 이어지는 3단계 루프를 도입합니다.
|
A. 감지 Stop Hook이 교정 시그널 자동 스캔 |
→ |
B. 로컬 아카이빙 proposals/ 저장 개발자 확인 → confirmed |
→ |
C. 기여 제출 /hub-feedback submit Hub ㅈ MR 자동 생성 |
교정 시그널('아니', '그게 아니라')을 Stop Hook이 감지 → 로컬에 저장 → 개발자 확인 후 Hub 레포 MR 자동 생성. 팀원 누구의 세션에서 발생한 교정이든 허브 품질 개선의 입력이 됩니다.
▌ 토큰 절약 — Vista Rule-Base 코드 오프로드
Claude는 Vista(코드 생성 도구)가 자동 생성한 boilerplate 코드까지 전부 읽고 분석합니다. 이미 알고 있는 패턴(JPA Repository, setter/getter, Vista 표준)에 불필요한 토큰을 소모하는 셈입니다.
|
방향 |
내용 |
|---|---|
|
단기 조치 |
.claude-ignore 또는 Skill 내 skip_paths로 generated 디렉토리 제외 conventions Skill에 "Vista 생성 파일은 분석 불필요" 가이드 추가 |
|
옵션 A 스크립트 분리 |
Vista/CRUD 패턴을 Python 스크립트로 분리 → Claude는 실행 결과만 수신 생성 파일에 .generated 마킹 → read skip 적용 |
|
옵션 B Vista 직접 연계 |
Vista API 호출로 코드 생성 → Claude는 diff만 검토 bootstrap Skill에 Vista 생성 파일 목록 명시 → violation-detector 검사 제외 |
rule-base 도구가 처리할 수 있는 영역을 Claude에게 맡기지 않는 것. 이것이 AI 협업 비용을 실질적으로 줄이는 설계 원칙이다.
5. 결론
|
vizend-agent-hub는 'AI에게 좋은 결과물을 만들게 하는 도구'가 아닙니다. 반복 가능하고 설명 가능한 개발 프로세스를 만드는 운영 인프라입니다. 하네스 없이는 AI가 코드를 빠르게 씁니다. 하네스 있으면 AI가 처음부터 Vizend 코드를 씁니다. AI는 단순 생성 도구가 아니라, 적절한 컨텍스트와 컨트롤 플레인(control plane)이 결합될 때 훨씬 강력한 팀 전체의 개발 플랫폼이 됩니다. |
참고
github.com/garrytan/gstack · agents-community · vizend-agent-hub · todo-projects · oh-my-claudecode · everything-claude-code
James