AI · 방법론· 2025 — 2026

AI Harness Boilerplate (HDD 프레임워크)

Harness-Driven Development — AI를 가상 IT 조직처럼 운용하는 OS

역할: 기획 · 설계 · 개발

Next.js 14Firebase Data ConnectElasticsearchts-morphClaude CodeCursor

Headline

"AI의 출력 품질은 프롬프트 길이가 아니라 시스템이 가하는 제약(Harness)의 강도에 비례한다"

1인 개발자가 AI를 단순 코드 어시스턴트가 아닌 완벽하게 통제된 가상 IT 조직(Virtual Org)으로 운용하기 위한 Vibe Coding 운영체제 + HDD(Harness-Driven Development) 방법론의 공식 보일러플레이트. Benchlink PMS 마이그레이션에서 실전 검증.

Problem

· "기존 컨벤션 지켜줘" — AI는 새 컨텍스트 창에서 모든 약속을 망각
· AI 자유도가 높을수록 환각·에이전트 표류 발생, 멀쩡한 코드까지 손상
· 1인 개발자는 PM/디자이너/백엔드/프론트/QA를 동시 고용 불가

Action

· Persona Isolation — 6개 페르소나(PM/Designer/Backend/Frontend/QA/Marketing) 권한 격리, 허가된 경로 외 접근 불가
· Dependency Blinding — depcruise + ast-grep으로 영향 파일만 컨텍스트 주입, 코드베이스 무분별 탐색 차단
· AST 강제 — 텍스트 편집 금지, ts-morph 스크립트로만 리팩토링/Props 변경/리네이밍
· State Machine — 모든 작업을 10~15개 파일 단위 원자적 배치로 분절, batch_N.md로 영속화
· Circuit Breaker — 동일 에러 3회 실패 시 자동 중단 + 구조화된 핸드오버 보고서 출력
· 외주 파이프라인 — 크몽/위시켓 공고 → PRD → UI 명세 → 배치 개발 → QA/PR → 납품 자동화

Result

· Benchlink PMS 마이그레이션 3개월 → 1개월 단축 (3배 가속)
· $600 / 12개 도메인 / 30건 배치 — ROI 약 300%
· 10개 정책 문서 + 5종 템플릿 + .cursorrules 헌법 파일로 구성
· DB/프레임워크 교체 시 파일 3개만 수정하면 전이 가능 (확장성)

10개 하네스 정책 문서 (harness/)

00_PERSONA_COWORK

페르소나 격리 매트릭스

01_INITIATION_PROTOCOL

신규 서비스 부트스트래핑

02_CORE_HARNESS_POLICY

9가지 핵심 통제 정책

03_STATE_MACHINE

배치 상태 + 핸드오버

04_GITOPS

PR 자동화 파이프라인

05_TOOL_MANIFEST

툴체인 명세 (Firebase DC · ES)

06_TESTING_STRATEGY

테스트 + 서킷 브레이커

07_COLLABORATION_SETUP

Slack · Jira 완전 설정

08_SERVICE_DISCOVERY

서비스 발굴 (Mode A/B)

09_AUTOMATION_PIPELINE

n8n + Claude API 자동화

Core Code

핵심 코드 스니펫

Dependency Blinding — 영향 파일만 컨텍스트 주입

# 단일 파일 변경 시 영향 파악
npx depcruise src --focus "src/components/Portfolio/Card.tsx" \
  --output-type json | jq -r '.modules[].source'

# 스키마 변경 시 영향 파악
npx depcruise src --include-only "^src/(components|hooks|app)" \
  --focus "src/generated/graphql.ts" \
  --output-type json | jq -r '.modules[] | select(.dependents | length > 0) | .source'

# 특정 심볼(타입, 함수) 사용처 탐색
ast-grep --pattern 'PortfolioCardProps' --lang tsx

AI가 전체 코드베이스를 자유 탐색하지 못하도록 물리적으로 차단. depcruise가 추출한 파일 외에는 열지 않음.

Circuit Breaker — 무한 루프 차단 + 핸드오버

[🚨 CIRCUIT BREAKER TRIGGERED — HUMAN HANDOVER REQUIRED]
시도 횟수      : 3/3
실패 단계      : [build/lint/test/e2e]
에러 메시지    : [full error text]
영향 파일      : [list]
근본 원인 추정 : [analysis]
권장 조치      : [next steps for human]

# Do not retry without explicit human instruction.

동일 에러 3회 실패 시 작업 즉시 중단, 구조화된 보고서로 인간에게 제어권 반환.

다른 프로젝트 보기