117 lines
7.9 KiB
Markdown
117 lines
7.9 KiB
Markdown
# 개발 하네스 — 폐쇄루프 운영 및 하네스 엔지니어링 지침
|
|
|
|
> 이 저장소에서 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대 원칙
|
|
|
|
카파시가 제시한 에이전트의 실패 방지 원칙:
|
|
|
|
1. **Think Before Coding (생각 먼저, 코딩 나중)**:
|
|
추측으로 코드를 작성하지 않는다. 요구사항이 모호하면 먼저 조사하거나 명확히 질문하고, 파일 3개 이상 변경 시 플랜을 수립한다.
|
|
2. **Simplicity First (최소 구현 원칙)**:
|
|
미래를 위한 오버엔지니어링, 불필요한 추상화 계층을 금지한다. 실패한 테스트(RED)를 통과(GREEN)시키는 가장 단순한 코드를 작성한다.
|
|
3. **Surgical Changes (외과수술식 정밀 변경)**:
|
|
요청과 무관한 주변 코드, 주석, 포맷을 임의로 건드리지 않는다. Blast Radius(폭발 반경)을 극도로 제한한다.
|
|
4. **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 ← 마지막 검증 성공 시각 타임스탬프 (자동 관리)
|
|
```
|
|
|
|
### 왜 이렇게 분리하는가?
|
|
1. **전역 MD(`AGENTS.md`)는 항상 컨텍스트를 차지한다.** 여기에 수천 줄의 세부 룰을 넣으면 모든 대화 턴마다 토큰 비용이 발생하고 모델의 주의력이 흐려진다.
|
|
2. **경로별 룰(`rules/`)은 필요할 때만 들어온다.** WPF 창을 고칠 때만 WPF 룰이 들어오고, 백엔드 코어 엔진을 만질 때는 로드되지 않는다.
|
|
3. **절차서(`skills/`)는 트리거될 때만 들어온다.** 평소 대화에서는 토큰을 0바이트 소모한다.
|
|
4. **강제는 프롬프트가 아니라 훅과 게이트로 한다.** 프롬프트의 "반드시 테스트하세요"는 모델이 무시할 수 있지만, 훅의 `exit 2`는 물리적으로 턴 종료를 차단한다.
|
|
|
|
---
|
|
|
|
## 6. 결론: 하네스 기반 자율 개발 체크리스트
|
|
|
|
1. [ ] 세션 시작 시 상태 브리핑 확인
|
|
2. [ ] 변경 전 실패하는 테스트(RED) 확인
|
|
3. [ ] 최소한의 코드 수정(GREEN) 진행
|
|
4. [ ] 대용량 파일은 Grep/Slice로 토큰 절약
|
|
5. [ ] `dotnet test` 성공 후 턴 종료 (0 실패, 0 에러)
|
|
6. [ ] `docs/BACKLOG.md` 상태 동기화
|
|
|