하네스 엔지니어링 - 2

이전 글

https://kyeum-d.tistory.com/45

하네스 엔지니어링 - 1

 

들어가며

지난 글에서 하네스를 이루는 중심축과 핵심 원칙에 대해서 알아봤습니다.

이제는 그 내용을 어떻게 적용할 것인가에 대한 고민이 남았습니다.

 

저 같은 일반인(?)의 경우 어떤식으로 구성했는지 그 과정을 나열하고

 

핵심 축과 원칙을 이해한채로 구성하는 것이 어떤 도움이 되는지 함께 알아보는 시간을 가지겠습니다. (대충 실패한 내용 알려준다는 뜻)

 

일단 시작해

우선 직접 구성해보고 느낀 것은

하네스의 제 8원칙(거창하네)에 따라 최종 일관성을 기대한 채로 무작정 시작을 해야 한다는 점입니다.

 

처음부터 완벽하게 구성하려고하면 시작도 못할 거 같아서

저는 무작정 시작했습니다. (사실 이 때 핵심 축이고 원칙이고 아무것도 모름) 

 

우선 제가 코드를 작성하면서 필요하다고 생각하는 에이전트들을 정의했습니다. 

 

어떻게 정의했는데?

최초에는 이렇게 총 6가지의 구성으로 에이전트들을 설계했습니다. 

• Planner
  • 기획서를 읽고 계획 작성
• Plan Reviewer
  • 세운 계획에 대해서 리뷰 진행
• Worker
  • 작업을 진행
• Builder
  • 빌드 검증
• Test Writer
  • 테스트 코드 작성 및 수행
• Code Reviewer
  • worker 가 작업한 코드에 대해서 리뷰

각 컨텍스트들은 OpenAI 의 실패사례를 토대로 세부적인 내용을 직접 담지 않고 

모델이 특정 기술이나 지식이 필요한 경우 상세한 문서를 찾아갈 수 있는 '지도' 형태로 만들었습니다.

 

이렇게 설계를 완료하니 이 에이전트들을 굴릴 수 있는 '오케스트레이터'가 필요해졌습니다.

 

오케스트레이터는 어떻게 구성하지?

*claude code 기준

마! 이게 오케스트레이터다(아님)

 

각 에이전트들을 AGENTS 로 정의하고

 

해당 AGENTS 들을 오케스트레이션 하는 SKILLS 를 생성하였습니다.

 

왜 오케스트레이터는 SKILLS 로 만드나요?

최초에 오케스트레이터도 별도 AGENTS로 구성을 할지 SKILLS로 구성을 할지 고민했는데

 

SKILLS로 구성하면 메인 세션에서 클로드와 지속적으로 커뮤니케이션이 가능합니다.

 

하네스 구성 초기 단계인 만큼 수정할 내용이 많다고 생각해서 SKILLS로 구성을 하게 됩니다.

 

(후술 하겠지만 이는 좋지 못한 결과를 발생시켰습니다.)

 

구성 끝

이제 기본적인 구성은 끝났으니 이제 바로 돌려보기 시작합니다.

 

당연하게도 돌리자마자 이것저것 문제가 발생했습니다.

 

이 중에 책임이 과한 에이전트가 있다

두루뭉술하게 에이전트를 작성했더니 

 

계획을 세우는 Planner도 기획서와 구현된 코드를 검토하고 계획을 세우고 

계획을 검토하는 Plann Reviewer 도 기획서와 구현된 코드를 검토하고 계획을 리뷰하고

작업을 진행하는 Worker 도 기획서와 구현된 코드를 확인하고 

불필요한 읽기가 너무 많이 발생했습니다. 

대충 Planner 와 형제들

 

우선은 Planner가 기획서를 읽고, 분석을 하고, 코드를 보고, 구현 상세 계획까지 세우는 것은 과다한 책임이라 생각하여

 

기획서만 읽고 해야할 작업 목록을 비즈니스 관점에서 나열하는 적립하도록 변경합니다. (구현 세부 계획 x) 

 

또한 Plan Reviewer 도 코드를 읽지 않고 오로지 기획서와 수립된 계획만을 보고

작업 목록을 명확하게 구성했는지 누락된 내용은 없는지 Plan 자체만을 검토하도록 변경합니다.

 

Worker가 고삐가 풀렸다

구현 세부사항에 대한 계획들을 제거했더니 이제 Worker에게 너무 큰 자유가 주어졌습니다. 

 

이 큰 자유는 하네스라는 마구가 무색해질 정도로 Worker 가 마음대로 작업을 하게 내버려둡니다.

내가 Worker여

패키지 구조와 작업 공간을 정확히 파악하지 못하고 필요하다고 생각하는 곳에 즉각적으로 코드를 추가했으며

 

이미 존재하는 검증된 코드를 재사용하지 않은 채 전체적인 구조를 무시하고 작업을 진행하였습니다. 

 

이런 문제들로 인해 저는 구성 에이전트로 Spec Writer 를 추가하게 됩니다.

 

Worker로 진입하기 전에 현재 아키텍처의 구성이나 도메인을 이루고 있는 레이어들 기본적인 규칙들을

Spec Writer가 조금 더 코드 레벨에서 큰 그림을 그리도록 했습니다. 

 

이렇게 Worker 까지의 구성은 어느 정도 완성되었는데..

 

Builder? 너 하는 게 뭐야

Builder의 역할이 굉장히 애매합니다.

→ 아무리 모델을 haiku로 돌린다고 하지만 빌더가 굳이 별도 에이전트로 있을 필요는 없음

Worker 에서 작업이 끝나면 빌드를 해서 검증하도록 변경합니다.

 

이렇게 구성을 변경해 가면서 최종적으로 다음과 같이 구성이 됩니다.

 

• Planner
  • 기획서를 확인하고 코드를 확인하지 않고 기획서 내용에 대해서만 정리하여 “무엇을” 만들어야 하는지 계획을 세움
• Plan Reviewer
  • 기획서에 명시된 “무엇을” 만들어야 하는지에 대한 내용이 전부 계획에 들어가 있는지 검토
• Spec Writer
  • “무엇을” 만들지에 대한 내용을 확인 후 우리 시스템에 맞춰 “어떻게” 만들어야 하는지 큰 그림 제시
• Worker
  • 실제로 코드 작성 작업
• Test Writer
  • 단위 테스트에 대한 전통적인 방법론을 주입
  • 코드 동작에 대한 검증이 아닌, 추상화된 수준의 비즈니스 동작 단위 검증
• Code Reviewer (claude 의 /simplify 기능에서 착안하여 구성)
  
  • simplify 의 3가지 검토 축 
    • 재사용성 검토
    • 코드 품질
    • 효율성
  • 재구성 한 3가지 검토 축
    • 아키텍처 : 모듈 구조, 계층 분리, 의존성 방향
    • 유지보수성 : 가독성, 네이밍, 복잡도, 에러 처리, 효율성
    • 재사용성 : DRY 원칙, 공통 컴포넌트 활용, 중복 코드 검출

이렇게 각 각 분리된 md 파일로 규약과 명세를 세분화하여

 

하네스 구성을 완료했습니다! 

 

.

.

. 

 

?

 

 

네 이렇게 구성하면

나약한 개발자여

이 친구 다시 봐야 합니다.

 

지금까지 구성한 것이 하네스를 이루는 3가지 축 중

 

첫 번째 축인 컨텍스트 엔지니어링을 완료했다고 볼 수 있습니다. 

 

그럼 이제 두 번째 축 구성을 하는구나!

맞습니다(?). 첫 번째 축은 다들 이미 잘하고 계실 것 같고

 

하네스를 구성함에 있어 가장 핵심적인 두 번째 축인

 

아키텍처 제약에 대해서 작업을 해야 합니다.

 

• Planner, Plan Reviewer
  • 특정 경로(피그마에서 추출한 기획서가 있는 폴더)만 읽을 수 있도록 강제
  • 특정 경로에만 파일을 Write 할 수 있도록 강제 (계획 작성)
  • Bash 명령어 차단 등등...
• Worker
  • 커스텀 린터 / 정적 분석 추가하여 검증
    ex) 안티패턴 감지 → !! 같은 단언 연산자를 쓰거나 Transaction 안에서 외부 API 를 호출하거나 순환 의존성, 패키지 네이밍 규칙, 등등
    
  • 작업 완료되면 hook 으로 build 명령어 실행
  • 의존성이 추가된 경우 의존성에 대한 검증
• Test Writer
  • 작업 완료 후 hook 을 통해 테스트 커버리지를 검사한다던지 @Disabled 가 없는지 검사 등
  • 작업이 가능한 폴더는 test 폴더로 제한
• Code Reviewer
  • 리뷰어 폴더만 쓰기 권한 부여
  • 각 에이전트는 본인의 작업 결과물에 대해서 파일로 상태를 남겨 전달

 

이런 식으로 제약을 걸어서 에이전트가 올바른 방향으로 목적지에 도달할 수 있도록 제어할 수 있습니다. 

 

+ 추가로 구성하다 보니 

커스텀 린터에는 이것저것 추가할 내용들이 많았습니다.

(대표적으로 자꾸 data class 를 계속 필요한 비즈니스 로직이 있는 코드 내부에 추가한다던지 등)

모델이 작성한 코드를 검토하면서 보일 때마다 기록을 해두고

주기적으로 정리하면서 하나씩 적용해 나가면 될 것 같습니다.

 

이제 아키텍처 제약 축을 완성했습니다.

 

뭔가 빼먹은 게 있는 거 같아요

지금 생각해 보면 에이전트들에게 제약을 열심히 걸었는데 

 

간과한 사실이 한 가지 있었습니다. 

 

오케스트레이터를 SKILLS 로 작성했고 오케스트레이터에게 별도의 제약을 걸지 않았다는 점입니다.

 

오케스트레이터를 SKILLS 로 작성했을 때의 제가 생각한 장/단점은 

 

장점

• 중간에 사용자가 개입할 수 있음
• 오케스트레이션을 함께 관리하여 실패에 대한 컨텍스트를 모두 가지고 있어 빠른 피드백으로 수정 할 수 있음
• 수정 대상이 많지 않음

단점

• 컨텍스트 고갈 현상 심함
• 세션이 끊기면 재개 불가능 (resume 같은 게 있으니 끊길 일이 없긴 하지만)
• 결정론 부족 → 각 에이전트의 응답을 직접 보고 LLM 이 판단하기 때문에 기계적인 구분이 어려움
• 규칙 위반 → 각 에이전트들이 일을 제대로 못하면 자꾸 직접 개입하려고 하는 현상이 발견됨

여기서 단점 중에 '직접 개입하려는 현상'이 가장 심했고 고쳐지지 않았습니다.

 

방법이 없을지 다른 고수들의 레퍼런스를 찾아봤더니 별도의 py 코드로 오케스트레이션을 구성하는 것을 발견했습니다.

 

이렇게 구성하면 개입현상을 원천차단 할 수 있겠다고 생각이 들어 해당 형태를 차용하기로 결정합니다.

 

처음에는 이 '사용자 개입'이 장점이라고 생각했지만 

에이전트 간의 파일 핸드오프와 피드백 루프가 제대로 구축된다면,

애초에 개입 자체가 불필요하겠다는 생각이 들었습니다.

 

이런 식으로 2번째 축인 아키텍처 제약을 구성을 완료했습니다.

마지막 엔트로피 관리만 남았나요?

3번째 원칙인 엔트로피 관리에는

 

크게 3가지 요소가 있을 수 있는데

 

1. 데드 코드 및 AI Slop 제거

• 더 이상 사용하지 않는 코드 혹은 지정한 규칙을 어기는 코드를 찾아서 제거

2. 중복 코드 제거

지속적으로 코드베이스를 탐색하며 중복되는 유틸리티 함수들이나 퍼져있는 관리 포인트들을 한 곳으로 모음

3. 컨텍스트 문서의 부패 관리

• 예외 사항이나 지속적으로 컨텍스트를 추가하기 시작하면 정리가 안된채로 비대해집니다.
  비대해진 컨텍스트 문서는 부패하게 되고 결국 AI 에게 노이즈를 주는 상황이 생길 수 있습니다.

이런 3가지 요소에 대한 관리를 하는 '가비지 컬렉터' 를 별도의 생명주기로 실행하도록 구성하여

감지된 코드를 수정 후 PR을 생성하는 등으로 활용해 볼 수 있습니다.

 

엔트로피 관리는 하네스 엔지니어링에서 '엔지니어링' 관점으로 봤을 때
지속 가능한 하네스를 구성하기 위한 가장 중요한 요소라고 생각하는데

그와 동시에 가장 어렵고 까다로운 내용이기도 하여 저도 아직 구성 단계에 있습니다.

 

하네스 한 번만 구성해놓으면 잘 되겠죠?

하네스는 현재 모델이 제대로 할 수 없는 것에 대한 가정이 들어가 있습니다.

 

하지만 모델이 발전하면 이 가정 또한 부패하기 시작합니다. 

 

그래서 이제 제약 없이도 잘할 수 있는 부분들은 제거를 해야 합니다. 

 

근데.. 이거 말이 쉽지 여러 요소들 중에 어떤 것을 이제 잘하게 되었는지 어떻게 알 수 있을까요?

 

1. 하네스 변경에 대해 기록한다 

하네스를 추가할 때, 코드를 짜듯 "왜 이 제약을 걸었는지" 명시적으로 기록하고 태깅하는 방법입니다. 

ADR(Architecture Decision Record) 처럼 기록해 두면 모델이 업데이트되면서 더 잘하게 되었다고 발표하는 내용과

 

하네스에 추가한 가정에 대한 기록을 찾아 대조하며 빠르게 검증해 볼 수 있습니다.

 

2. 하네스 없이 테스팅 해본다

하네스가 없이도 모델이 잘 해낼 수 있는지 아는 유일한 방법은, 하네스를 벗긴 상태로 시험을 치르게 하는 것입니다.

 

한계 돌파 테스트셋 (Limit-break Testset)

• 일반적인 기능 테스트(Unit Test)와 별개로, 과거 모델이 실패했던 까다로운 엣지 케이스나 컨텍스트 한계 상황만을 모아둔 전용 평가 데이터셋을 구축

같은 테스트 셋을 구성해 놓으면 발전한 모델에 대한 평가가 가능합니다. 

 

3. 피처 플래그를 활용한 모듈형 하네스

하네스를 시스템과 강하게 결합해 두면 떼어내기가 매우 힘듭니다.

토글(Toggle) 아키텍처

• 하네스의 각 축(예: 자가 검증 루프, 컨텍스트 요약기, 강제 JSON 파서 등)을 언제든 껐다 켤 수 있는 플러그인 형태로 설계

같은 방법으로 구성을 해놓는 방법이 있을 수 있습니다. 

 

 

마치며

오늘은 하네스 구성에 대한 실전 가이드와 요소들에 대해 이야기를 나누어 봤습니다.

모든 것은 구성하는 사람에 따라 추가/제거되겠지만 큰 틀은 비슷할 것이라 생각됩니다.

 

모델이 점점 발전함에 따라 엔지니어링 기법 또한 발전했습니다. 

 

하지만 컨텍스트 엔지니어링으로 발전했다고 프롬프트 엔지니어링이 사라졌을까요?

 

하네스 엔지니어링 기법이 나와서 컨텍스트 엔지니어링이 필요 없어졌을까요?

 

모든 엔지니어링 기법은 기존에 존재하던 엔지니어링 기법 위에 설계되고 만들어졌습니다. 

 

하네스 엔지니어링 이후에는 어떤 엔지니어링 기법이 각광받을지, 어떤 형태로 모델이 진화할지는

아무도 모릅니다. 

 

하지만 다음 엔지니어링 기법도 하네스 엔지니어링 기법을 기반으로 만들어질 것입니다. 

 

코더에서 개발자로 개발자에서 엔지니어로

우리는 주어진 요구사항에 대한 기능을 개발하여 동작시키는 코더에서

 

단순히 코드를 만드는 것을 넘어 '비즈니스 문제'와 '시스템의 지속 가능성'을 고민하는 개발자로 한 단계 진화해 왔습니다.

 

이제는 코드를 직접 생산하는 실무자를 넘어, '코드를 생산하는 시스템'을 설계하는 엔지니어로 진화하는 과도기에 있다고 생각합니다.

 

저를 포함한 많은 분들이 AI의 발전에 대한 FOMO를 느끼고 미래에 대한 걱정을 하실 것이라 생각됩니다.

 

이제 슬슬 옥석 가리기가 시작된 현 상황에서

AI의 변화를 받아들이고 발 빠르게 AI를 다루는 기법들을 적용하고 부딪혀보며 성장해 나가는 것도 좋지 않을까 생각됩니다.

 

긴 글 읽어주셔서 감사드립니다!  

 

+ 발표 자료로 사용했던 내용 첨부합니다! 무단 배포 및 재사용 환영

하네스엔지니어링_main (1).pptx

12.14MB