/harnessArchitecture-as-constraint — 구조가 에이전트를 제약한다.
/harness Claude Code CLI 또는 연결된 에이전트에서 호출합니다.
> **에이전트가 실패하면 에이전트를 고치지 마라. 구조를 고쳐라.** > — Bockeler, "Architecture as Harness" > 출처: `apt-docs/theories/05_harness_theory.md` (MinIO) ---
Harness = 말에 씌우는 고삐. 말(에이전트)의 능력을 제거하지 않으면서 **방향을 제한**한다. 전통적 접근: 프롬프트 엔지니어링, 파인튜닝 → "에이전트를 더 똑똑하게" 하네스 접근: 구조적 제약, 자동 검증, 피드백 루프 → **"구조를 더 단단하게"** **패러다임 전환**: Instruction-driven → **Architecture-driven reliability** ---
하네스의 4개 축. APT의 모든 설계는 이 4축 중 하나 이상에 해당한다.
```
Inform (정보 제공)
↓
에이전트에게 충분한 맥락
↓
┌─────────┼─────────┐
│ │ │
Constrain [Agent] Verify
(경계 제한) (작업) (검증)
│ │ │
└─────────┼─────────┘
↓
Correct (교정)
↓
피드백으로 개선
```
| 축 | 역할 | APT 구현체 | 없으면 |
|---|---|---|---|
| **Inform** | 에이전트에게 맥락 제공 | KG, docs, Progressive Disclosure | 맥락 없이 코딩 = Vibe Coding |
| **Constrain** | 해 공간의 경계 설정 | Span 분해, Contract 7필드, complexity_threshold | 무한 자유 = 무한 오류 |
| | v24: Gate Check Hook = Constrain축 물질화 | | |
| **Verify** | 결과물 자동 검증 | Taliban 9-lens, Ground Truth, TDD | 고무도장 승인 |
| **Correct** | 피드백으로 개선 | Fractal Feedback, AptFeedback, 프로메테우스 | 같은 실수 반복 |
--- 에이전트가 실패했을 때, 4축 중 어디가 약한지 진단한다.
### Step 1: 증상 분류
| 증상 | 약한 축 | 처방 |
|------|---------|------|
| 엉뚱한 방향으로 구현 | **Inform** | KG 보강, docs 추가, 프로메테우스 발동 |
| 범위 초과 / Gold Plating | **Constrain** | Contract 경계 강화, Span 재분해 |
| 틀린 코드가 통과됨 | **Verify** | Taliban lens 추가, 테스트 강화 |
| 같은 버그 재발 | **Correct** | Feedback loop 점검, Lesson 기록 |
### Step 2: KG 조회 — 현재 4축 상태
```cypher
// 프로젝트의 4축 건강도 파악
MATCH (anchor:SemanticAnchor {name: $project})
// Inform: KG 노드 밀도
OPTIONAL MATCH (anchor)-[:HAS_SPAN*]->(s)
WITH anchor, count(s) as span_count
// Constrain: Contract 완성도
OPTIONAL MATCH (ct:AptContract) WHERE ct.name STARTS WITH 'CT_' + $project
WITH anchor, span_count, count(ct) as contract_count,
sum(CASE WHEN ct.status = 'fulfilled' THEN 1 ELSE 0 END) as fulfilled
// Verify: Taliban 결과
OPTIO > 하네스 시대의 병목은 **코드 품질이 아니라 명세 품질**이다. ``` 전통: 코드 작성 능력이 병목 → 더 잘 코딩하려 노력 하네스: 명세 작성 능력이 병목 → Contract를 더 정확하게 ``` - 에이전트는 이미 코드를 잘 짠다 (LLM 능력) - 문제는 **뭘 짜야 하는지 모르는 것** (명세 부재) - 따라서 Contract의 7필드를 정밀하게 쓰는 것이 최우선 ---
에이전트 실패 시 아래 질문을 순서대로: 1. **구조가 이 실패를 방지할 수 있었나?** → YES면 구조를 고쳐라 2. **에이전트에게 충분한 정보가 있었나?** → NO면 Inform 축 보강 3. **해 공간이 충분히 좁았나?** → NO면 Constrain 축 강화 4. **검증이 이 오류를 잡았어야 했나?** → YES면 Verify 축 추가 5. **이전에 같은 문제가 있었나?** → YES면 Correct 축 실패 **절대 하지 말 것**: "에이전트 프롬프트를 더 길게 써보자" — 이건 하네스가 아니라 기도. ---
``` 하네스 (설계 철학) ← APT 전체 구조의 이유 ├── Inform 축 ← 프로메테우스가 담당 (지식 획득) ├── Constrain 축 ← Span + Contract (SP/ST) ├── Verify 축 ← 탈레반이 담당 (적대적 검증) ├── Correct 축 ← Fractal Feedback + Lesson └── 연결 보장 ← 롱기누스가 담당 (KG↔Code 관통) ``` ---
| 금지 | 이유 | 대안 | |------|------|------| | 프롬프트만 수정해서 해결 시도 | 구조 문제를 지시문으로 해결 불가 | 4축 진단 후 구조 개선 | | 에이전트 탓만 하기 | "바보 에이전트" = 구조 실패 고백 | Bockeler 체크리스트 | | 4축 중 하나만 강화 | 밸런스 깨짐 | 4축 균형 진단 | | 검증 없이 신뢰 | 고무도장 = 구조 부재 | Taliban + Ground Truth | --- *고삐 없는 말은 빠르지만 방향을 모른다. 하네스는 속도를 줄이지 않으면서 방향을 잡는다.*