하네스 프레임워크란?

<aside> 💡

**하네스(Harness)**는 AI 코딩 도구가 내 프로젝트 규칙을 따르도록 제어하는 구조화된 프레임워크입니다. Claude Code 위에 "한 층"을 올려서 바이브 코딩의 품질을 높여줍니다.

</aside>

AI 코딩 도구(Claude Code, Cursor, Codex 등)에는 이미 내장 하네스가 있습니다 — 위험한 git 명령 차단, 권한 체크, 도구 경계 설정 등. 하지만 이것은 범용이라 내 프로젝트만의 아키텍처, 기술 스택, 코딩 규칙은 모릅니다.

이 프레임워크는 그 위에 프로젝트 전용 하네스를 올려줍니다:

graph TB
    A["내 프로젝트 하네스 (한 층 올리기)"] --> B["내장 하네스 (이미 있음)"]
    A --- C["CLAUDE.md, docs/, hooks"]
    B --- D["시스템 프롬프트, 권한 체크"]

GitHub 레포지토리

<aside> 📦

GitHub: github.com/jha0313/harness_framework

</aside>

프레임워크 구조 (4개 레이어)

project/
├── CLAUDE.md                    ← 프로젝트 헌법
├── docs/
│   ├── PRD.md                   ← 뭘 만드는지
│   ├── ARCHITECTURE.md          ← 어떻게 만드는지
│   ├── ADR.md                   ← 왜 이렇게 만드는지
│   └── UI_GUIDE.md              ← 어떻게 보여야 하는지 (선택)
├── .claude/
│   ├── commands/
│   │   ├── harness.md           ← /harness — 원스톱 실행
│   │   └── review.md            ← /review — 규칙 기반 리뷰
│   └── settings.json            ← hooks 설정
├── scripts/
│   ├── execute.py               ← Phase 순차 실행 + 상태 관리
│   └── hooks/
│       ├── tdd-guard.sh         ← 테스트 없으면 구현 차단
│       ├── dangerous-cmd-guard.sh ← 위험 명령어 차단
│       └── circuit-breaker.sh   ← 반복 에러 감지
└── phases/                      ← Phase 파일 + 실행 상태

Layer 1: docs/ — 프로젝트의 뇌

<aside> 🧠

프레임워크의 핵심입니다. 마크다운 3~4개 파일만 채우면 됩니다.

</aside>

PRD.md — 뭘 만드는지

Product Requirements Document. 핵심 기능과 MVP 제외 사항을 정의합니다.

• PRD.md 템플릿

<aside> ⚠️

MVP 제외 사항이 매우 중요합니다. 이걸 안 써놓으면 AI가 "이 기능도 추가할까요?" 하면서 scope가 끝없이 늘어납니다. "이건 안 만든다"를 명시하는 게 "이건 만든다"보다 더 중요할 때가 많습니다.

</aside>