개발 하네스 — 폐쇄루프 운영 및 하네스 엔지니어링 지침

이 저장소에서 AI 코딩 에이전트(Antigravity, Claude Code, DeepSeek, Cursor 등)가 자율 루프로 저가형 모델(Flash, DeepSeek, Haiku)까지 완벽히 통제하여 고성능 극한 개발을 수행하도록 구성한 하네스 엔지니어링(Harness Engineering) 설계와 운영법이다.

1. 패러다임의 진화: Prompting → Context → Harness

시대	패러다임	핵심 질문	한계
2022 ~ 2024	Prompt Engineering	"어떻게 말해야(프롬프트) 잘 알아들을까?"	단일 턴 한계, 복잡한 프로젝트에서 망각 및 환각
2024 ~ 2025	Context Engineering (안드레 카파시)	"모델의 컨텍스트 창에 무엇을 넣고 뺄 것인가?"	컨텍스트가 길어지면 집중도 감쇠, 실행 검증 부재
2025 ~ 2026	Harness Engineering (`Agent = Model + Harness`)	"어떤 제약과 피드백 루프로 모델을 가둘 것인가?"	해결: 비결정적 모델을 결정적 시스템으로 완성

안드레 카파시(Andrej Karpathy)와 업계 리더들이 정립한 핵심 공식은 다음과 같다:

\text{Agent} = \text{Model} + \text{Harness}

Model (커널/CPU): 비결정적(Stochastic) 추론 엔진. 아무리 좋은 프런티어 모델이라도 하네스가 없으면 "다 됐습니다"라고 거짓 보고(Vibe Coding)를 하거나 테스트를 무력화한다.
Harness (운영체제/제약계층): 도구 세트, 컨텍스트 스케줄러, 결정적 테스트 게이트, 린터, 상태 저장소. 모델의 출력을 기계적으로 검증하고 실패 시 에러를 피드백하여 자가수정(Self-Correction)을 강제한다.

2. 안드레 카파시의 에이전틱 코딩 4대 원칙

카파시가 제시한 에이전트의 실패 방지 원칙:

Think Before Coding (생각 먼저, 코딩 나중): 추측으로 코드를 작성하지 않는다. 요구사항이 모호하면 먼저 조사하거나 명확히 질문하고, 파일 3개 이상 변경 시 플랜을 수립한다.
Simplicity First (최소 구현 원칙): 미래를 위한 오버엔지니어링, 불필요한 추상화 계층을 금지한다. 실패한 테스트(RED)를 통과(GREEN)시키는 가장 단순한 코드를 작성한다.
Surgical Changes (외과수술식 정밀 변경): 요청과 무관한 주변 코드, 주석, 포맷을 임의로 건드리지 않는다. Blast Radius(폭발 반경)을 극도로 제한한다.
Goal-Driven Closed Loop (목표 주도 폐쇄 루프): 모호한 "수정"이 아니라, 기계적으로 검증 가능한 테스트(Exit Code 0)가 달성될 때까지 자율 루프를 돈다.

3. 저가형 모델(Flash, DeepSeek, Haiku)로 극한 개발을 하는 하네스 기법

프런티어 모델(Opus/GPT-4o) 대신 Gemini Flash, DeepSeek-V3/R1, Claude Haiku 등 1/10~1/50 비용의 저가형 모델로 최고 효율을 내기 위한 4가지 하네스 기법:

① Token Diet (컨텍스트 오염 차단)

저가형 모델은 컨텍스트가 20k~50k 토큰 이상 누적되면 지침 준수율(Instruction Following)이 급격히 저하된다.
규칙: MainWindow.xaml.cs(86KB) 같은 대형 소스는 절대로 통째로 읽지 않는다. grep_search로 함수 라인을 파악하고 30~50줄 단위로 슬라이스 조회(view_file)한다.
전역 지침 압축: AGENTS.md를 150줄 이내로 유지하고, 세부 규칙은 파일 열람 시 동적 주입(Path-Scoped Rules)한다.

② Anti-Cheating Guard (치팅 원천 차단)

저가형 모델이 자율 루프에서 막히면 흔히 시도하는 3대 꼼수:
1. 실패하는 테스트 코드를 삭제하거나 단정(Assert)을 완화
2. [Fact(Skip = "...")] 또는 [Ignore] 속성 추가
3. 실패하는 예외를 빈 catch { } 블록으로 삼킴
방어: 정적 메타 테스트(MetaTestQualityAndPruningTests) 및 Stop 훅으로 테스트 수 감소 및 Skip 속성을 검출하여 즉시 실패 처리.

③ Error-Driven Hill Climbing (결정적 에러 피드백)

저가형 모델은 막연한 에러 설명보다 정확한 컴파일러 진단 코드(CS0246, CS8602)와 파일:라인:컬럼, xUnit Expected/Actual 차이를 주입받았을 때 1~2턴 만에 완벽히 교정한다.
하네스는 실패 시 빌드/테스트 출력의 핵심 30~50줄을 모델 컨텍스트에 즉시 주입한다.

④ Subagent Hierarchy (계층형 서브에이전트)

넓은 범위의 코드 검색, 문서 리서치 등 컨텍스트를 많이 소비하는 작업은 초경량 서브에이전트(invoke_subagent, flash/flash_lite)에 위임한다.
메인 에이전트의 컨텍스트는 순수한 아키텍처/코드 수정 상태로 깨끗하게 유지된다.

4. 5계층 하네스 아키텍처

계층	역할	이 저장소의 구현
① 하네스 환경	에이전트 런타임 & 도구	Antigravity(AGY) · Claude Code (`.claude/settings.json`)
② 루프 계약 (SSOT)	도구 중립 작업 헌법	`AGENTS.md` (AAIF 표준, <150줄)
③ 상태층 (External State)	세션 리셋에도 유지되는 상태	`docs/BACKLOG.md` · `docs/IMPLEMENTATION_AUDIT.md` · `.verify-stamp`
④ 결정적 체커	에이전트가 건너뛸 수 없는 게이트	Stop 훅 / 검증 게이트 → `dotnet test Paca.Tests`
⑤ 사람 관문	되돌릴 수 없는 결정	커밋·푸시·릴리스 승인 (`/release` 스킬)

5. 멀티 MD 파일 관리 표준

AGENTS.md                     ← 도구 중립 최상위 작업 계약 (AAIF 표준, 전역 상주, 150줄 이내)
CLAUDE.md                     ← @AGENTS.md 임포트 + 도구별 훅 바인딩
.claude/
  settings.json               ← 훅 등록 + 권한 설정
  hooks/
    session-brief.sh          ← SessionStart: 브랜치/변경파일/미완료 백로그 자동 브리핑
    verify-on-stop.sh         ← Stop: 턴 종료 시 소스 변경 감지 → dotnet test 강제 게이트
  rules/                      ← [Path-Scoped] 해당 파일을 열 때만 로드되는 영역별 규칙
    desktop-wpf.md            ← Paca.App/**, Paca.Browser/**
    engine-core.md            ← Paca.Core/**, Paca.Server/**
    mobile-maui.md            ← Paca.Mobile/**, Paca.Mobile.Core/**
    tests.md                  ← Paca.Tests/**
  skills/                     ← [On-Demand] 호출 시에만 컨텍스트에 들어오는 절차서
    tdd/SKILL.md              ← /tdd    RED→GREEN→증거 사이클
    verify/SKILL.md           ← /verify 완료 기준 전수 점검
    release/SKILL.md          ← /release 배포 파이프라인
  .verify-stamp               ← 마지막 검증 성공 시각 타임스탬프 (자동 관리)

왜 이렇게 분리하는가?

전역 MD(AGENTS.md)는 항상 컨텍스트를 차지한다. 여기에 수천 줄의 세부 룰을 넣으면 모든 대화 턴마다 토큰 비용이 발생하고 모델의 주의력이 흐려진다.
경로별 룰(rules/)은 필요할 때만 들어온다. WPF 창을 고칠 때만 WPF 룰이 들어오고, 백엔드 코어 엔진을 만질 때는 로드되지 않는다.
절차서(skills/)는 트리거될 때만 들어온다. 평소 대화에서는 토큰을 0바이트 소모한다.
강제는 프롬프트가 아니라 훅과 게이트로 한다. 프롬프트의 "반드시 테스트하세요"는 모델이 무시할 수 있지만, 훅의 exit 2는 물리적으로 턴 종료를 차단한다.

6. 결론: 하네스 기반 자율 개발 체크리스트

세션 시작 시 상태 브리핑 확인
변경 전 실패하는 테스트(RED) 확인
최소한의 코드 수정(GREEN) 진행
대용량 파일은 Grep/Slice로 토큰 절약
dotnet test 성공 후 턴 종료 (0 실패, 0 에러)
docs/BACKLOG.md 상태 동기화

7.9 KiB Raw Blame History

개발 하네스 — 폐쇄루프 운영 및 하네스 엔지니어링 지침

1. 패러다임의 진화: Prompting → Context → Harness

2. 안드레 카파시의 에이전틱 코딩 4대 원칙

3. 저가형 모델(Flash, DeepSeek, Haiku)로 극한 개발을 하는 하네스 기법

① Token Diet (컨텍스트 오염 차단)

② Anti-Cheating Guard (치팅 원천 차단)

③ Error-Driven Hill Climbing (결정적 에러 피드백)

④ Subagent Hierarchy (계층형 서브에이전트)

4. 5계층 하네스 아키텍처

5. 멀티 MD 파일 관리 표준

왜 이렇게 분리하는가?

6. 결론: 하네스 기반 자율 개발 체크리스트

7.9 KiB

Raw Blame History