20260406_하네스 엔지니어링이란
1. AI 엔지니어링 4가지 축
- Prompt Engineering: 말을 잘 거는 기술
- Context Engineering: 필요한 정보를 제공하는 기술
- Harness Engineering: 규칙과 울타리를 설계하는 기술
- Agentic Engineering: 자율 에이전트를 오케스트레이션
2. Prompt 엔지니어링의 한계
- 나: 로그인 기능을 구현해줘
- 에이전트: 프로젝트의 구조? 기술스택? 제한? ???? -> 한계가 존재, 더 정교하고 정확한 정보를 줄 필요가 있음
3. 그래서 나왔습니다. Context 엔지니어링
- [1] 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회 반복 시 전략 │
│ 개입 │ 변경 강제 지시 │
├───────────────┼──────────────────────────────┤
│ 가장 단순한 │ 모델 성능이 좋아지면 │
│ 것부터 │ 스프린트 구조를 제거할 수 │
│ │ 있도록 설계 │
└───────────────┴──────────────────────────────┘
터미널에 나오는 출력
