20260406_하네스 엔지니어링이란

TL;DR

• 2022-2026, AI 개발 패러다임이 세 번 바뀌었습니다. Prompt Engineering → Context Engineering → Harness Engineering

• Prompt Engineering (2022-2024): "어떤 말을 해야 하나?" — 모델에게 보내는 지시문의 품질이 성패를 결정한다고 믿었습니다.

• Context Engineering (2025): "어떤 정보를 넣어야 하나?" — 프롬프트보다 컨텍스트 윈도우에 무엇을 채울지가 더 중요하다는 걸 깨달았습니다.

• Harness Engineering (2026): "어떤 시스템을 만들어야 하나?" — 컨텍스트를 소비하는 전체 시스템의 설계가 진짜 문제라는 걸 인정했습니다.

• Harness Engineering 다음 방향은 Guardian Agent, 평가 엔지니어링, 지식 엔진 입니다.

0. 엔지니어링 발전방향

1. AI 엔지니어링 4가지 축

• Prompt Engineering: 말을 잘 거는 기술
• Context Engineering: 필요한 정보를 제공하는 기술
• Harness Engineering: 규칙과 울타리를 설계하는 기술
• Agentic Engineering: 자율 에이전트를 오케스트레이션

2. Prompt 엔지니어링의 한계

• 나: 로그인 기능을 구현해줘
• 에이전트: 프로젝트의 구조? 기술스택? 제한? ???? -> 한계가 존재, 더 정교하고 정확한 정보를 줄 필요가 있음

3. 그래서 나왔습니다. Context 엔지니어링

• Context 엔지니어링 by 엔트로픽: AI가 일할 때 필요한 정보를 적절하게 골라서 제공하는 기술
• Context 엔지니어링: ai에게 프롬프트만 주는게 아니라 프로젝트의 구조, 기존 코드 예시, API 문서 디자인 규칙

4. Context 엔지니어링으로도 한계가 존재합니다.

5. 하네스 엔지니어링

5-1. 핵심요소

• 전역 규칙 (agent.md): AI가 작업을 시작할 때 무조건 읽어야 하는 헌법

• 지식 라우팅 (skills/): 특정 작업(예: DB 접근) 시에만 동적으로 꺼내 읽는 세부 법률

• 자동 검증 (Hooks): 코드 저장 전 문법과 규칙을 강제 검사하는 문지기

• 역할 분리 (Multi-Agent): 코드를 짜는 AI와 평가하는 AI의 분리 (자기 과대평가 방지)

5-2. 엔트로픽 엔지니어가 활용한 방법 - AI는 스스로를 너무 관대하게 평가한다. 깐깐한 다른 평가자가 필요함

대략 이런 느낌이랄까?

• 기획자 (Planner): 사용자의 짧은 아이디어를 받아 개발 스프린트(작업 단위)로 쪼갬.
• 생성자 (Generator): 스프린트 목표에 맞춰 코드를 실제로 작성 (skills 참조).
• 평가자 (Evaluator / QA): Playwright 등을 통해 실제 브라우저를 띄우고 버튼을 클릭하며 깐깐하게 테스트. 실패 시 Generator에게 피드백 반환.

5-3. 하네스 디렉토리 구조

/kanban-project
├── .husky/                     
│   └── pre-commit              # (1) 문지기: 코드 강제 검증 스크립트
├── agent.md                    # (2) 전역 규칙: 에이전트 헌법
├── /skills
│   └── react_best_practices.md # (3) 참조 지식: 칸반 보드 코딩 가이드
└── /harness_system             # (4) 하네스 엔진 (3중 에이전트)
    ├── 1_planner_prompt.md
    ├── 2_generator_prompt.md
    ├── 3_evaluator_prompt.md
    └── orchestrator.py         # 자동화 실행기

5-4-1. agent md

# 프로젝트 전역 규칙 (Global Rules)
이 프로젝트는 React와 Tailwind CSS를 사용하는 프론트엔드 애플리케이션입니다. 

## 1. 기술 스택 제한
- 상태 관리는 오직 `Zustand`만 사용합니다. Redux 신규 도입 금지.
- 스타일링은 `Tailwind CSS`만 사용하며, 별도의 `.css` 파일 생성 금지.

## 2. 코드 보호 및 안전 규칙
- 기존에 작성된 함수, 파일의 임의 삭제를 절대 금지합니다.
- 데이터 삭제 시 DB Hard Delete 대신 상태 플래그를 바꾸는 Soft Delete를 적용하십시오.

## 3. 지식 라우팅
- 코드 컴포넌트 분리 원칙은 `skills/react_best_practices.md`를 참조하십시오.

5-4-2. 스킬 라우팅

메인 프롬프트를 가볍게 유지하기 위해, 코딩할 때만 꺼내보는 세부 지침서입니다.
📄 파일명: skills/react_best_practices.md

# React 컴포넌트 작성 표준 지침

## 1. 컴포넌트 구조
- 모든 컴포넌트는 함수형 컴포넌트(Arrow Function)로 작성하십시오.
- 비즈니스 로직과 UI 렌더링 로직을 분리하는 Custom Hook 패턴을 적용하십시오.
- 상태 분리: 상태 로직은 UI 컴포넌트 내부가 아닌 `src/store/useKanbanStore.ts`로 분리하십시오.
- 컴포넌트 구조: `Board.tsx`(컨테이너), `Column.tsx`(기둥), `TaskCard.tsx`(할 일 카드)로 분리하십시오.
- 스타일링: Tailwind CSS를 사용하고, 드래그 중인 카드에는 반드시 시각적 피드백(그림자 등)을 추가하십시오.

## 2. 파일 네이밍 규칙
- 컴포넌트 파일명: PascalCase (예: `KanbanBoard.tsx`)
- 유틸리티/Hook: camelCase (예: `useKanbanState.ts`)

## 3. 에러 핸들링
- 발생하는 모든 예외는 `try-catch`로 처리하고 사용자에게 명확한 UI 에러 메시지를 노출하십시오.
  

5-4-3. Planner Agent

📄 기획자 (Planner) 프롬프트: /harness_system/1_planner_prompt.md

당신은 수석 기획자입니다. 사용자의 아이디어를 바탕으로 개발 가능한 '스프린트 목록'을 JSON 배열로 반환하십시오.

절대 제약 사항: 전체 프로젝트는 반드시 정확히 16개의 스프린트로 분해되어야 합니다. 15개도, 17개도 안 됩니다.

5-4-4. Generator Agent

📄 생성자 (Generator) 프롬프트: /harness_system/2_generator_prompt.md

당신은 시니어 개발자입니다. 할당된 칸반 보드 스프린트 목표 코드를 작성하십시오.
코딩 전 반드시 최상단의 `agent.md`와 `/skills/react_best_practices.md`를 숙지하고 제약(DnD 라이브러리, Soft Delete)을 지키십시오. 
평가자로부터 테스트 실패(FAIL) 피드백이 오면 변명 없이 즉시 수정하십시오.

5-4-5. Evaluator Agent

📄 평가자 (Evaluator) 프롬프트: /harness_system/3_evaluator_prompt.md

당신은 깐깐한 QA입니다. Generator가 작성한 칸반 보드 코드를 `npx playwright test`로 실제 브라우저에서 검증하십시오.
- 카드가 TODO에서 DONE으로 정상적으로 드래그 앤 드롭 되는지 확인하십시오.
- Soft Delete 규칙이 지켜졌는지 점검하십시오.
문제가 하나라도 있다면 구체적인 'FAIL' 리포트(예: Column.tsx 24번째 줄 에러)를 반환하십시오.

5-4-6. Hooks/Lint

#!/bin/sh
echo "🛑 [Hook] AI가 작성한 칸반 보드 코드 검사를 시작합니다..."

# 1. 문법 검사 (사용 금지된 Redux 등을 썼는지 체크)
npm run lint 

# 2. 타입 검사 (상태값이나 Soft Delete 속성 누락 검사)
npm run type-check 

# 위 명령어 중 하나라도 실패하면 저장이 거부되고 AI에게 피드백이 갑니다.

5-4-7. Orchestrator

📄 파일명: /harness_system/orchestrator.py

import argparse
import sys
import time

# (가상) 에이전트 및 시스템 명령어 래퍼 (실무에선 Anthropic API 및 subprocess 사용)
class HarnessSystem:
    def call_planner(self, prompt, sprints_needed):
        print(f"  [Planner] {sprints_needed}개의 칸반 보드 스프린트 생성 완료.")
        return [{"title": f"Sprint {i}"} for i in range(1, sprints_needed + 1)]
    
    def call_generator(self, sprint):
        print("  [Generator] DnD 및 Zustand 로직 작성 중... (문지기 Hook 자동 검사 포함)")
        time.sleep(1) # 코드 작성 및 .husky/pre-commit 검사 시뮬레이션
        return "code_diff"

    def call_evaluator(self, code, attempt):
        print("  [Evaluator] Playwright 브라우저 E2E 테스트 실행 중...")
        time.sleep(1)
        if attempt < 1: # 첫 시도는 무조건 실패한다고 가정 (자가 교정 테스트)
            return False, "FAIL: 드래그 시 카드가 겹치는 버그 발생 및 Soft Delete 미적용."
        return True, "PASS"

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--prompt", type=str, default="칸반 보드 앱 만들어줘")
    parser.add_argument("--sprints", type=int, default=16)
    args = parser.parse_args()

    print("🚀 [칸반 보드 하네스 시스템] 가동 시작...")
    system = HarnessSystem()

    # 1. 16개 스프린트 강제 검증 루프
    sprints = []
    while len(sprints) != args.sprints:
        sprints = system.call_planner(args.prompt, args.sprints)
        if len(sprints) != args.sprints:
            print("❌ 기획자 에러: 16개가 아닙니다. 다시 생성합니다.")

    # 2. Generator ↔ Evaluator 무한 교정 루프
    print("\n⚙️ 본격적인 칸반 보드 개발을 시작합니다.")
    for i, sprint in enumerate(sprints, 1):
        print(f"\n▶ 스프린트 {i}/{args.sprints} 진행 중...")
        
        passed = False
        retries = 0
        
        while not passed and retries < 5:
            code = system.call_generator(sprint)
            is_valid, feedback = system.call_evaluator(code, retries)
            
            if is_valid:
                print("  ✅ [Evaluator] 테스트 통과! 코드 병합 완료.")
                passed = True
            else:
                print(f"  ❌ [Evaluator] 반려: {feedback}")
                print("  🔄 에러 피드백을 Generator에게 보내 코드를 자동 수정합니다.")
                retries += 1
                
        if not passed:
            print(f"\n🚨 치명적 오류: 스프린트 {i} 실패. 사람의 확인이 필요합니다.")
            sys.exit(1)

    print("\n🎉 모든 스프린트 완료! 완벽하게 작동하는 칸반 보드 앱이 완성되었습니다.")

if __name__ == "__main__":
    main()

5-4-8. 실행

python harness_system/orchestrator.py --prompt "칸반 보드 앱 만들어줘" --sprints 16

6. 결론

• 프롬프트를 고치지 말고, 하네스(시스템)를 고치는 방향으로 진화

• 이제 개발자와 실무자의 역할은 '명령어를 입력하는 사람'이나 '코더'가 아니라 하네스 설계를 어떻게 하느냐로 바뀌고 있음 -> AI가 완벽하게 일할 수 있는 튼튼한 환경(레일)을 깔아주는 시스템 설계자이자 감독관으로 진화해야 함

7. 개인 테스트

Feature Flag 테스트를 위해 아래와 같이 프롬프트 입력

 datadog feature flag를 테스트할 예정입니다.
  harness 구조를 먼저 설계하고 싶습니다.
  https://www.anthropic.com/engineering/harness-desi
  gn-long-running-apps 링크를 참고해서
          
  /kanban-project
  ├── .husky/
  │   └── pre-commit              # (1) 문지기: 코드
   강제 검증 스크립트                        
  ├── agent.md                    # (2) 전역 규칙:
  에이전트 헌법                                
  ├── /skills
  │   └── react_best_practices.md # (3) 참조 지식:
  칸반 보드 코딩 가이드                     
  └── /harness_system             # (4) 하네스 엔진
  (3중 에이전트)                                
      ├── 1_planner_prompt.md
      ├── 2_generator_prompt.md
      ├── 3_evaluator_prompt.md
      └── orchestrator.py  
      
와 유사한 형태로 harness 구조를 잡아주세요                          

완성된 하네스 구성

완성된 하네스 구조입니다:

  ff-by-harness/
  ├── .husky/
  │   └── pre-commit                          # (1)
  문지기: 5개 Quality Gate 강제 검증
  ├── agent.md                                # (2)
  전역 규칙: 에이전트 헌법
  ├── skills/
  │   └── datadog_feature_flag_guide.md       # (3)
  참조 지식: DD FF + RUM 코딩 가이드
  ├── harness_system/                         # (4)
  하네스 엔진 (3중 에이전트)
  │   ├── 1_planner_prompt.md                 #
  제품 사양 확장
  │   ├── 2_generator_prompt.md               #
  스프린트 기반 코드 생성
  │   ├── 3_evaluator_prompt.md               #
  4기준 평가 (분리된 QA)
  │   └── orchestrator.py                     #
  파일 기반 조율 엔진
  ├── contracts/                              #
  스프린트 계약 아카이브 (자동 생성)
  └── workspace/                              #
  에이전트 간 통신 채널 (런타임 생성)
      ├── plan.md                             #
  Planner → Generator
      ├── sprint_contract.md                  #
  Generator ↔ Evaluator
      ├── eval_report.md                      #
  Evaluator → Generator
      ├── iteration_log.md                    #
  전체 반복 이력
      └── final_verdict.md                    #
  최종 판정

  핵심 설계 결정 (Anthropic 블로그 원칙 반영)

  ┌───────────────┬──────────────────────────────┐
  │     원칙      │             적용             │
  ├───────────────┼──────────────────────────────┤
  │ 생성-평가     │ Generator와 Evaluator를 별도 │
  │ 분리          │  에이전트로 분리하여         │
  │               │ 자기평가 편향 방지           │
  ├───────────────┼──────────────────────────────┤
  │ 파일 기반     │ workspace/ 내 .md 파일로     │
  │ 통신          │ 에이전트 간 상태 전달        │
  ├───────────────┼──────────────────────────────┤
  │               │ 구현 전                      │
  │ 스프린트 계약 │ Generator↔Evaluator가        │
  │               │ Acceptance Criteria 합의     │
  ├───────────────┼──────────────────────────────┤
  │ 피드백 루프   │ 최대 5회 반복, 4기준 모두    │
  │               │ 8/10 이상 시 조기 종료       │
  ├───────────────┼──────────────────────────────┤
  │ Orchestrator  │ 동일 이슈 3회 반복 시 전략   │
  │ 개입          │ 변경 강제 지시               │
  ├───────────────┼──────────────────────────────┤
  │ 가장 단순한   │ 모델 성능이 좋아지면         │
  │ 것부터        │ 스프린트 구조를 제거할 수    │
  │               │ 있도록 설계                  │
  └───────────────┴──────────────────────────────┘

터미널에 나오는 출력

8. Feature Flag

그래서 하네스로 만든 데모앱은?

• Kill Switch / Progressive Rollout (배포) / User Targeting / AB Test 4가지 시나리오를 테스트해 볼 수 있음

참고 자료

• 프롬프트에서 하네스까지 - AI 에이전틱 패턴 4년의 기록 ← 꼭 읽어보세요!
• Youtube: 프롬프트 엔지니어링은 끝났습니다: 이제 '하네스'의 시대입니다
• Notion: 🐴 하네스 엔지니어링 완벽 가이드 — AI 에이전트를 진짜로 통제하는 기술 | Notion
• Harness design for long-running application development
• 테스트 코드 Repo: GitHub - gblee87/harness-datadog-feature-flag: harness test for datadog feature flag (RUM)