"에이전트를 프로덕션에서 작동하게 하는 숨겨진 아키텍처 계층." — Martin Fowler, Architecture Fitness Harness 정의

---

도입 — 3 부 시작 의 자리

2 부의 마지막 (7 장) 끝을 다시 인용한다.

"실리콘밸리 수석 개발자도 하네스 없이 코딩하지 않는다." — 알렉스

이 하네스 라는 단어가 3 부 5 장 전체의 주인공이다. 단어 자체부터 짚자.

Harness 의 어원은 말 안장의 끈 또는 낙하산 끈 이다. 자유롭게 움직이게 하면서도 떨어지지 않게 잡아 주는 도구. 비행사는 낙하산 끈이 있어 과감하게 뛰어내릴 수 있다. 끈이 없으면 — 뛰지 못한다. 즉 — *하네스는 자유의 제한이 아니라 가능 조건. *

이 책에서 AI 에이전트의 하네스 는 정확히 같은 뜻이다. *AI 가 자유롭게 과감한 코드를 짤 수 있도록 — 그 아래에서 사고를 막아 주는 시스템 *. 이 시스템이 어떻게 생겼는지 — 8 장이 그 전체 지도 를 그린다.

핵심 명제 미리.

*에이전트 시스템은 4 개 계층으로 나눠야 한다. 그중 3 계층 (하네스) 이 주인공 * 이다.

---

4 계층 아키텍처 — 한 표

먼저 표를 기록한다.

이 표를 친숙한 비유 로 다시 옮겨 본다.

운영체제 비유: 1 계층 = SDK = 컴파일러, 2 계층 = 스캐폴딩 = npm create 로 만들어지는 프로젝트 골격, 3 계층 = 하네스 = OS (Linux / macOS), 4 계층 = 에이전트 = 그 OS 위에서 도는 앱.

여러분이 Linux 위에서 앱이 어떻게 도는지 를 알고 있다면 — 4 계층 구조 가 정확히 그 모습이다. 앱 (에이전트) 은 OS (하네스) 가 없으면 못 돈다. OS 가 메모리 관리·파일 시스템·프로세스 스케줄링 을 해 주기 때문에 앱은 자기 일 (비즈니스 로직) 에만 집중한다.

이 비유의 핵심은 — *4 계층 (에이전트) 이 잘 작동하는 비결은 3 계층 (하네스) 가 잘 만들어졌기 때문 * 이라는 것. 4 장의 7 건 사고 가 왜 일어났는가 를 다시 보면 — 모두 3 계층 (하네스) 부재 로 환원된다. AI 가 약한 게 아니라 OS 가 없어서 망한 것.

---

3 계층 (하네스) 의 핵심 책임 — 전체 수명 주기 제어

하네스가 정확히 무엇을 하는가. 4 가지 책임이다.

이 4 가지가 하네스 = OS 의 4 가지 시스템 콜 같은 것. 에이전트는 이 4 가지를 자기가 직접 하지 않는다. 하네스가 대신 해 준다. 그래서 에이전트는 추론에만 집중 할 수 있다.

이게 4 장 7 건 사고에 모두 빠진 부분 이다. Lemkin Replit DB 삭제 — 인간 승인 루프 가 없었다 (Plan-Only Mode 부재). PocketOS DB + 백업 삭제 — 도구 연동 의 권한 분리 가 없었다. Anthropic 자체 사고 — 재시도 정책 이 임의 실행 으로 들어갔다.

즉 — 사고는 4 계층 (에이전트) 의 잘못 이 아니라 3 계층 (하네스) 의 부재 또는 결함 이다. AI 모델 자체는 잘 작동 했다. 하네스가 그 작동을 안전한 범위로 잡아 두지 않아서 사고가 났다.

---

가이드 vs 센서 — 하네스 통제의 두 방향

하네스가 어떻게 통제하는가 의 두 방향을 본다. 행동 전 통제와 행동 후 통제.

가이드 (Feedforward) — 행동 *전*
  ↓
설계 원칙 · 코딩 컨벤션 · 안티패턴 목록을
에이전트에 *사전 주입*
  ↓
올바른 코드를 *작성할 확률 상승*

——— 그래도 일부 잘못된 출력은 나온다 ———

센서 (Feedback) — 행동 *후*
  ↓
에이전트 출력을 *관찰*
  ↓
커스텀 린터·테스트로 *자가 오류 교정* 유도

이 두 방향이 동시에 작동 한다. 가이드 (사전 지시) 만으로는 부족하고 센서 (사후 검증) 만으로는 느리다. 둘 다 있어야 예방 + 교정 이 함께 일어난다.

여러분의 학기 팀 프로젝트 와 비유하면 — 가이드 = 시작 전 역할 분담 회의*, 센서 = 매주 코드 리뷰 회의*. 둘 다 있어야 팀 프로젝트가 굴러간다. 하나만 있으면 3 주째에 막힌다. 같은 원리가 AI 협업 에서 일어난다.

---

계획 vs 구현 분리 — 저장소 영향 지도

하네스가 가장 강력하게 작동하는 자리 한 곳을 자세히 본다. *계획과 구현을 명시적으로 분리 * 하는 패턴이다.

Phase 1: 계획 (Planning)
   ↓
1. 저장소 심볼 분석 (어떤 함수·클래스가 영향받는가?)
2. *저장소 영향 지도 (Repository Impact Map)* 생성
   ──── 보통 3 ~ 5 줄짜리 마크다운 ────
3. 3 줄짜리 영향 지도에서 *잘못된 참조* 즉시 발견
   ↓
[★ 인간 검토 체크포인트 ★] ← 필수
   ↓
Phase 2: 구현 (Implementation)
   ↓
4. 실제 파일 경로 · 심볼 기반 코드 생성
5. *환각 (hallucination) 없는* 구조적 출력 보장

이 패턴이 강력한 이유는 비용 비대칭 에 있다.

같은 오류 라도 어느 단계에서 발견하느냐 에 따라 비용이 수백 배 차이 난다. 하네스가 Phase 1 → Phase 2 사이에 인간 검토 체크포인트 를 강제 함으로써 — 이 비용 비대칭을 *항상 왼쪽으로 이동 * 시킨다.

이게 왜 Plan Mode 가 거의 모든 도구의 기본값이 되었는가 의 답이다 (2 장 참조). Plan Mode = 계획 vs 구현 분리 = 비용 왼쪽 이동.

---

구조화 입출력 — Vague in → Vague out

하네스의 또 한 가지 핵심 원칙. 한 줄로 기록된다.

Vague in → Vague out. Structure in → Structure out.

모호한 입력 → 모호한 출력. 구조적 입력 → 구조적 출력.

이게 작동하는 이유 — AI 는 입력의 구조 에 민감 하다. "이것 좀 고쳐줘" 같은 모호한 요청을 받으면 모호한 결과 를 낸다. "src/auth/middleware.ts 의 verifyToken 함수에서 expired token 케이스 를 처리하도록 try-catch 추가하되 기존 에러 형식 유지" 같은 구조적 요청을 받으면 — 구조적 결과 가 나온다.

하네스가 제공해야 할 3 가지 구조 는 다음이다.

• 파일 경로 — 정확
• 심볼 이름 — 실제 존재하는 함수·클래스
• 기존 코드 패턴 — 컨벤션 명시

이게 왜 CLAUDE.md 가 작동하는가 의 답이다 (14 장에서 깊이). CLAUDE.md 가 *3 가지 구조 (경로 + 심볼 + 패턴) 를 매 세션 처음에 AI 에 자동 주입 * 한다. 그래서 AI 의 첫 응답이 모호하지 않다.

---

Architecture Fitness Harness — Martin Fowler 의 명명

이 하네스 개념 자체는 Martin Fowler 가 정리했다. Refactoring 과 Patterns of Enterprise Application Architecture 의 저자다 — 소프트웨어 아키텍처에서 거의 교과서급 권위.

Fowler 의 정의를 옮긴다.

"Architecture Fitness Harness — 성능 요구사항, 로깅 표준 등 구조적 특성을 위반하지 않도록 지속적 압력."

이걸 AI 시대 에 옮기면 — AI 가 우리 팀의 코드 컨벤션을 위반하지 않도록 지속적으로 압력 을 가하는 시스템. 그 압력이 가이드 + 센서 (앞에서 봤던 두 방향) 다.

Fowler 의 다른 표현으로 — "인간 개발자의 경험을 시스템에 외재화." 시니어 개발자가 몸으로 알고 있던 것 — "이런 코드는 짜지 마라", "이 함수는 건드리지 마라", "이 패턴이 우리 팀 컨벤션이다" — 을 시스템 (CLAUDE.md, 린터, 훅) 에 박아 두는 것. 그래서 *시니어가 그 자리에 없어도 AI 가 시니어의 판단 을 흉내 * 낸다.

이게 11 장 경험 = 하네스의 검증자 의 핵심이다. 이 책에서 가장 깊은 한 줄 이라고 미리 표시해 둔다 — "하네스 = 시니어 경험의 외재화."

---

7 건 사고를 다시 본다 — 하네스 부재의 4 사례

4 장의 7 건을 4 계층 아키텍처 시각 으로 다시 본다. 어느 사고가 어느 계층의 부재 였는지 표로.

4 사례 모두 3 계층 (하네스) 부재. AI 모델 (4 계층) 은 잘 작동 했다. SDK (1 계층) 도 잘 작동 했다. 3 계층이 빠져 있어서 사고가 났다.

이게 3 부 전체의 출발점이다. 3 계층 (하네스) 이 무엇으로 만들어지는가 가 9 ~ 11 장의 주제다.

• 9 장 — Superpowers (3 계층 도구 패키지)
• 10 장 — 검증 루프 (3 계층의 센서 측면, Boris Cherny)
• 11 장 — 경험 외재화 (3 계층의 가이드 측면, CLAUDE.md)
• 12 장 — SDD 실증 벤치마크 (3 계층 도입의 수치적 효과)

---

8 장 정리 — 지도를 펴 둔다

3 부의 첫 장인 8 장은 지도 다. 어디로 가는지 를 그려 둔 그림. 5 장의 규모별 곡선 이 어디에서 우리가 서 있는가 의 그림이라면 — 8 장의 4 계층 아키텍처 는 어떻게 우리가 일을 분배하는가 의 그림.

표어로 닫는다.

AI-Native Vibe Coding: No Design, No Code. — No Design 이 의미하는 설계의 부재 는 — 정확히 3 계층 (하네스) 의 부재 다.

다음 9 장에서는 3 계층 하네스를 실제로 만드는 도구 들 을 본다. Superpowers 프레임워크 — 시각적 컴패니언 / 서브에이전트 / 2 단계 리뷰. 추상적 표가 손에 잡히는 도구 로 바뀌는 자리다.

"이 4 계층을 실제 코드 로 어떻게 만드는가? 다음 페이지에서."