AI Agent Engineering
my-harness
전문 에이전트 팀이 협업하는 AI 네이티브 개발 환경
Overview
프로젝트 배경
Claude Code는 강력한 AI 코딩 에이전트지만, 기본 상태에서는 단일 에이전트로 동작합니다. 복잡한 프로젝트에서는 프론트엔드, 백엔드, QA, 디자인 등 도메인마다 고유한 설계 원칙과 판단 기준이 필요한데, 하나의 에이전트가 모든 영역을 동일한 깊이로 다루기 어렵습니다.
my-harness는 이 문제를 해결하기 위해 oh-my-opencode의 에이전트 시스템을 도입하고, 개인 개발 환경에 맞게 커스터마이징한 Claude Code 하네스입니다. 18개의 전문 에이전트와 15개의 스킬(7개 도메인 지식 베이스 + 8개 범용 스킬), 10개의 플러그인을 도입한 뒤, 스킬 시스템 마이그레이션, 팀 구성 자동화, PR 프로세스 설계 등을 통해 나만의 하네스로 발전시켰습니다.
오케스트레이터가 작업을 분석하고, 적절한 전문 에이전트에게 위임하며, 결과를 검증하는 탐색→위임→검증 루프를 자동으로 수행합니다. 이를 통해 AI 에이전트 팀이 실제 개발팀처럼 협업하는 환경을 갖추게 되었습니다.
Problem
무엇이 문제였나
“단일 AI 에이전트의 한계를 넘어, 전문 에이전트 팀이 협업하는 개발 환경 구축”
Claude Code를 실제 프로젝트 개발에 활용하면서 다음과 같은 구조적 한계를 경험했습니다.
첫째, 전문성의 부재입니다. 단일 에이전트가 프론트엔드, 백엔드, QA, 디자인 등 모든 도메인을 동일한 깊이로 다루기 어렵습니다. 각 도메인에는 고유한 설계 원칙, 안티패턴, 기술 스택이 존재합니다.
둘째, 지식의 휘발성입니다. 세션이 끝나면 맥락이 사라집니다. 프로젝트 컨벤션, 아키텍처 결정, 검증된 패턴을 매번 다시 설명해야 했습니다.
셋째, 협업 구조의 부재입니다. 실제 개발팀처럼 PO가 기획하고, 디자이너가 설계하고, 개발자가 구현하고, QA가 검증하는 파이프라인이 없습니다. 모든 역할을 하나의 에이전트가 순차적으로 수행합니다.
넷째, 품질 검증의 공백입니다. 코드 리뷰, 테스트 전략, 보안 검토 등 품질 게이트 없이 구현만 빠르게 진행됩니다.
AS-IS
작업 계획
도구: 단일 에이전트
한계: 계획과 구현의 분리 없음, 즉흥적 실행
프론트엔드 구현
도구: 단일 에이전트
한계: React/Next.js 고유 패턴·컨벤션 미반영
백엔드 구현
도구: 단일 에이전트
한계: API 설계 원칙·보안·성능 패턴 미적용
코드 리뷰·QA
도구: 수동 검토
한계: 구현자가 곧 검증자, 자기 검증의 한계
도메인 지식 참조
도구: 매 세션 재설명
한계: 컨벤션·패턴 휘발, 일관성 유지 불가
Process
어떻게 해결했나
단일 에이전트의 한계를 극복하기 위해, oh-my-opencode의 에이전트 시스템을 도입하고 개인 환경에 맞게 커스터마이징했습니다. 구체적으로 다음 세 단계로 나만의 하네스를 구축했습니다.
01
에이전트 시스템 도입
oh-my-opencode의 에이전트 아키텍처를 도입했습니다. 코어 에이전트(Orchestrator, Planner, Oracle 등 11개)가 탐색→계획→실행→검증 루프를 담당하고, 도메인 전문가 에이전트(FE, BE, Designer, PO, QA, Ops, DA 7개)가 각 영역의 구현과 판단을 맡는 2계층 구조입니다.
02
스킬 시스템 마이그레이션
도입된 도메인 지식 시스템(177개 이상의 참조 파일)을 Claude Code의 스킬 시스템으로 마이그레이션했습니다. 기존 knowledge/ 디렉토리에서 에이전트가 파일 경로를 직접 참조하는 방식을, SKILL.md의 frontmatter 기반으로 자동 트리거되는 구조로 전환했습니다. 태스크-지식 매핑 테이블을 통해 작업 맥락에 따라 관련 스킬이 자동 활성화됩니다.
03
에이전트 팀 구축
claude-team 쉘 스크립트 래퍼를 작성하여 도메인 전문가 에이전트들을 팀으로 즉시 구성할 수 있도록 했습니다. claude 명령어에 --append-system-prompt와 구조화된 프롬프트를 조합하여, full(7명), prod(5명), dev(5명) 세 가지 팀 프리셋을 하나의 명령어로 실행합니다. PO가 PRD를 작성하고, Designer가 디자인 스펙을 정의하고, FE/BE가 구현하고, QA가 검증하는 프로세스를 따르며, 각 단계에서 필요에 따라 사용자가 개입하여 방향을 컨펌합니다.
Development Process
어떻게 만들었나
oh-my-opencode의 에이전트 시스템을 도입한 뒤, 스킬 마이그레이션·팀 자동화·PR 프로세스 설계 등을 통해 나만의 하네스로 커스터마이징했습니다. 코어 에이전트가 오케스트레이션 인프라를 제공하고, 도메인 전문가 에이전트가 각 영역의 구현과 판단을 수행합니다.
Orchestrator
탐색 > 위임 > 검증 루프 조율
Planner
전략적 작업 계획 수립
Oracle
아키텍처 설계, 디버깅 컨설팅
Analyzer
코드베이스 분석 (read-only)
Librarian
외부 문서/OSS 검색
Frontend Engineer
React/Next.js 구현
Backend Engineer
API 설계, DB, 서버
Product Designer
UI/UX 설계, 디자인 스펙
Product Owner
제품 전략, PRD 작성
QA Engineer
테스트 전략, 코드 검증
Orchestrator (claude --agent orchestrator)
Agent Team (claude-team prod)
시스템 구성
코어 에이전트 (11개)
orchestrator.md
모델: opus
설명: 메인 진입점. 탐색→위임→검증 루프 조율
planner.md
모델: opus
설명: 전략적 작업 계획 수립 (구현 없음)
pre-planner.md
모델: opus
설명: 사전 요구사항 분석, 모호성 식별
plan-reviewer.md
모델: opus
설명: 계획 검토 및 검증
oracle.md
모델: opus
설명: 아키텍처 설계, 고난이도 디버깅 컨설팅
analyzer.md
모델: opus
설명: 코드베이스 분석 (read-only)
deep-worker.md
모델: opus
설명: 자율 심층 작업, 목표 지향 실행
librarian.md
모델: opus
설명: 외부 문서/OSS 검색, 공식 문서 참조
delegator.md
모델: sonnet
설명: 범용 작업 위임 및 조율
search.md
모델: haiku
설명: 빠른 팩트 조회, 파일/경로 검색
media-reader.md
모델: sonnet
설명: PDF, 이미지 등 미디어 파일 해석
도메인 전문가 에이전트 (7개)
fe-dev.md
모델: opus
설명: 시니어 프론트엔드 엔지니어 (React/Next.js, TypeScript)
be-dev.md
모델: opus
설명: 시니어 백엔드 엔지니어 (Node.js, PostgreSQL, API 설계)
designer.md
모델: sonnet
설명: 시니어 프로덕트 디자이너 (UI/UX, 디자인 시스템)
po.md
모델: sonnet
설명: 시니어 프로덕트 오너 (제품 전략, PRD, 로드맵)
qa.md
모델: sonnet
설명: 시니어 QA 엔지니어 (테스트 전략, 자동화, 보안)
ops-lead.md
모델: opus
설명: 클라이언트 운영 총괄 (프로젝트 관리, CI/CD)
data-analyst.md
모델: opus
설명: 시니어 데이터 애널리스트 (SQL, 퍼널/코호트 분석)
도메인 스킬 (7개, 177+ 참조 파일)
각 전문가 에이전트의 지식 베이스. SKILL.md(진입점 + 태스크-지식 매핑 테이블)와 도메인별 참조 파일로 구성된다. 작업 맥락에 따라 자동 활성화.
be
역할: 백엔드 — API 설계, DB, 보안, 캐싱, 분산 시스템, 성능
참조 파일: 25개
fe
역할: 프론트엔드 — React/Next.js, 상태 관리, 테스트, 성능, 접근성
참조 파일: 32개
designer
역할: 디자인 — UI/UX, 디자인 시스템, 토큰, 접근성, 리서치
참조 파일: 25개
po
역할: 프로덕트 — 전략, PRD, 우선순위, 로드맵, 사용자 리서치
참조 파일: 25개
qa
역할: QA — 테스트 전략, 자동화, 성능/보안 테스트, 정적 분석
참조 파일: 25개
ops-lead
역할: 운영 — 프로젝트 관리, 클라이언트, SLA, 프로세스 최적화
참조 파일: 25개
data-analyst
역할: 데이터 — SQL, 퍼널/코호트 분석, A/B 테스트, 대시보드
참조 파일: 25개
범용 스킬 (8개)
commit-convention
역할: Conventional Commits + Tim Pope + Chris Beams 기반 Git 커밋 컨벤션
find-skills
역할: npx skills CLI로 오픈 스킬 생태계 검색 및 설치 지원
mcp-builder
역할: MCP(Model Context Protocol) 서버 설계 및 구축 가이드 (Python/Node)
역할: PDF 읽기·병합·분할·워터마크·폼 작성·OCR 등 전방위 PDF 처리
pptx
역할: PPTX 읽기·생성·편집·템플릿 작업 (markitdown + pptxgenjs 기반)
remotion-best-practices
역할: Remotion(React 비디오) 개발 베스트 프랙티스 (30개+ 규칙)
vercel-react-best-practices
역할: Vercel 엔지니어링 기반 React/Next.js 성능 최적화 64개 규칙
web-design-guidelines
역할: Vercel Web Interface Guidelines 기반 UI 접근성·UX 가이드
플러그인 (10개)
settings.json의 enabledPlugins에 선언. Claude Code가 자동으로 설치/업데이트한다.
superpowers
용도: 스킬 시스템 자동 평가/활성화
context7
용도: 라이브러리 공식 문서 실시간 검색
code-review
용도: 멀티 에이전트 기반 PR 코드 리뷰
feature-dev
용도: 탐색→설계→구현→리뷰 기능 개발 워크플로우
frontend-design
용도: 고품질 프론트엔드 UI/UX 디자인
skill-creator
용도: 스킬 생성·테스트·평가·개선 루프
typescript-lsp
용도: TypeScript LSP 연동 (타입 진단, 자동 완성)
playwright
용도: Playwright 브라우저 자동화 테스트
github
용도: GitHub MCP 서버 (이슈·PR·레포 관리)
vercel
용도: Vercel 플랫폼 연동 (배포, 로그, 환경 변수)
claude-team (쉘 스크립트 래퍼)
claude 명령어에 --append-system-prompt와 구조화된 프롬프트를 조합하여 에이전트 팀을 즉시 생성하는 쉘 스크립트.
full
구성: 전체팀 (7명: PO + Designer + FE + BE + QA + OPS + DA)
prod
구성: 프로덕션팀 (5명: PO + Designer + FE + BE + QA)
dev
구성: 개발팀 (5명: FE + BE + QA + OPS + DA)
커맨드 (2개)
/init-deep
설명: 계층적 CLAUDE.md 자동 생성. 프로젝트 구조를 분석하여 최적화된 지침 파일을 자동으로 구성한다.
/ulw-loop
설명: Oracle 검증 기반 자기 참조 개발 루프. 구현→Oracle 리뷰→수정을 반복하여 코드 품질을 높인다.
이벤트 훅 (4개)
claude-remote-notification.sh
이벤트: Notification
역할: 원격 알림 전송
claude-remote-session-start.sh
이벤트: SessionStart
역할: 세션 시작 알림
claude-remote-stop.sh
이벤트: Stop
역할: 세션 종료 알림
notify.sh
이벤트: Notification, Stop
역할: macOS 로컬 알림
사용법
claude --agent orchestrator
설명: 탐색→위임→검증 루프를 자동으로 수행하는 메인 에이전트. 대부분의 작업에 이걸 쓰면 된다. (권장)
claude --agent planner
설명: 구현 없이 작업 계획만 수립한다. 복잡한 태스크의 설계/분석 단계에서 사용.
claude-team dev
설명: 도메인 전문가 에이전트들을 팀으로 구성하여 협업.
Retrospective
회고
기존 에이전트 시스템을 평가하고 도입한 뒤, 자신의 개발 환경에 맞게 발전시키는 경험이었습니다. 단순히 도구를 사용하는 것이 아니라, 도구의 구조를 이해하고 커스터마이징하는 과정에서 AI 에이전트 시스템의 설계 원리를 체득했습니다.
가장 큰 수확은 스킬 시스템 마이그레이션과 팀 워크플로우 설계입니다. knowledge/ 디렉토리 기반의 수동 참조 방식을 SKILL.md 기반 자동 트리거로 전환하고, PR 프로세스 6단계와 구현 지시 규칙을 CLAUDE.md에 설계하여 에이전트 팀이 일관된 품질로 협업할 수 있는 구조를 만들었습니다.
missionary 프로젝트에서 이 하네스를 실전 투입했습니다. PO가 PRD를 작성하고, Designer가 디자인 스펙을 정의하고, FE/BE가 구현하고, QA가 검증하는 파이프라인이 실제로 동작하는 것을 확인했습니다. 남이 만든 시스템을 가져다 쓴 것이 아니라, 평가하고 선택하고 자기 환경에 맞게 발전시킨 경험입니다.
다음 프로젝트
⛪ missionary →