하네스 엔지니어링 2

AI Agent의 모델이 해결해 줄 것이다!?

"더 나은 모델이 나오면 해결이 될 것이다."

그렇지 않다. 모델이 문제가 아니라 구성이 문제다.

 

모델이 더 똑똑해지면 기존의 일부 오류는 사라진다. 하지만 모델이 더 똑똑해지면 우리는 더 크고 어려운 새로운 문제를 모델을 통해 해결하려고 시도할 것이며, 모델은 예상치 못한 부분에서 계속해서 실패할 것이다.

 

예상치 못한 = 비결정론적 시스템 문제

즉, 모델이 문제를 만났을 때 어떻게 해결해야 하는지 방향성을 제시하지 못하는 (환경) 구성의 문제 라는 것

 

그래서, 우리는 모델에게 새로운 프롬프트를 날리고, 이번에는 제발 잘 해결하기를 기도하는 대신에 에이전트가 우리가 의도한 방향대로 문제를 해결할 수 있도록 코딩 에이전트에게 가이드(구성)를 제시함으로서 예상치 못한 문제를 겪지 않도록 할 수 있다.

 

 

Cording agent(develop, service plan) = AI Model(s) + harness 

 

harness 의미

to control something, usually in order to use its power
무언가의 힘을 이용하기 위해 그것을 통재하다.

to collect and control something so that it can be used effectively
무언가를 효과적으로 사용할 수 있도록 수집하고 제어하다 (-Cambridge 사전)

 

 

harness = 수집 + 제어

아래 목록은 난이도가 높은 내용도 포함되어 있으니 이해가 안되는 항목이 있어도 가볍게 보고 넘기셔도 됩니다.
harness 엔지니어링을 진행하면서 점차 알게 됩니다.

수집(collect) : 에이전트가 판단하고 작업하는데 필요한 정보를 "모으는 기능"
문서, 계획, 도구 결과, UI, DOM, 스크린샷, 로그, 메트릭/트레이스

• 리포지터리 지식 맵(하)
  짧은 AGENTS.md를 맵으로 두고, 실제 지식은 구조화된 docs/에서 찾게 함.
• 버전 관리된 설계/계획 문서(하)
  설계 문서, 실행 계획, 기술 부채, 제품 스펙 등을 리포지터리 안의 기록 시스템으로 관리.
• 표준 개발 도구 결과(중)
  에이전트가 표준 개발 도구와 로컬 스크립트를 직접 실행해 컨텍스트를 수집
• 로그(중)
  워크트리별 로컬 observability stack에서 로그를 노출하고 LogQL로 조회하게 함.
• 메트릭·트레이스(중)
  PromQL 기반 메트릭 조회와 스팬 단위 성능 확인까지 포함.
• 애플리케이션 UI 상태(상)
  앱을 직접 띄우고 UI를 읽게 함.
• 브라우저 런타임 정보(상)
  Chrome DevTools Protocol을 연결해 DOM 스냅샷, 화면 상태, 탐색 결과를 수집
• 스크린샷(상)
  UI 검증과 버그 재현을 위해 시각적 결과를 직접 읽게 함

 

제어(control) : 에이전트가 "어디까지, 어떤 규칙으로, 어떤 방식으로 행동할지 제어하는 기능"
규칙/제약, 작업, 검증 ...
워크트리 격리, 검증 루프, 레이어 규칙, 종속성 제약, 맞춤형 린터, 구조적 테스트, CI, 규칙화된 피드백

• 금지 항목 : 롤백 기준, 재시도 제한, 실패 시 중단 조건
  • 구조적 테스트 : 아키텍처 불변 조건과 경계 위반을 테스트로 기계적으로 검증
  • 종속성 방향 제약 : 허용된 dependency edge만 통과하게 하고 나머지는 금지(예-Archunit)
• 품질 기준 : 린트, 테스트, 정적 분석, 코드 리뷰 규칙, 보안 검사, 정책 준수 점검
  • 맞춤형 린터 : 구조화된 로깅, 명명 규칙, 파일 크기 제한, 안정성 요구사항 등을 정적으로 강제
• 승인이 필요한 항목
• 자동 실행 가능 작업
• 워크트리 단위 격리 실행
  변경마다 별도 git worktree(브랜치)에서 앱 인스턴스를 띄워 작업 범위를 분리.
• 아키텍처 레이어 규칙(Archunit, guides.md)
• 도메인별로 Types -> Config -> Repo -> Service -> Runtime -> UI 같은 고정 레이어를 강제.
• CI와 doc-gardening
  문서 최신성, 교차 링크, 구성 품질까지 CI와 자동 에이전트로 지속 관리.
• 피드백의 규칙화
  리뷰 코멘트, 리팩터링 PR, 사용자 버그를 문서나 툴링 규칙으로 승격해 다음 실행에 반영
• 검증 루프
  버그 재현, 수정 검증, UI 동작 확인까지 에이전트가 닫힌 루프로 수행하도록 구성.

 

위의 목록보다 더 중요한 것

이전트가 실수를 저지르는 것을 발견할 때마다, 에이전트가 다시는 같은 실수를 저지르지 않도록 해결책을 마련하는 데 시간을 투자해야 한다

 

 

⚙️ 하네스 엔지니어링

하네스 엔지니어링 = 수집(정보) + 제어  ➟ 결과 산출물
- 에이전트가 실수하지 않도록 가이드

- 에이전트의 작업 품질이 기대에 미치지 못할 때 기대하는 수준을 가이드 

- 에이전트의 작업에 사람이 반복적으로 개입해야 하는 부분을 제거 하위 에이전트, Skill로 자동화 

 

👩🏼‍🔧👨🏼‍🔧 사람(엔지니어, 매니저)

- 엔지니어링 : AI Agent를 더 똑똑하게 만드는 작업  ➟ 자동화, 품질 개선

- 매니징 : 동시에 여러 AI Agent에게 업무를 할당  ➟ 생산성