하네스 엔지니어링

하네스 엔지니어링

AI가 통제 불능 상태가 되지 않도록 제약과 규칙을 걸어, 결과물의 품질을 일관되게 통제하는 설계 기법

도입 배경

AI 코딩 에이전트는 같은 요청에도 다른 결과를 만들 수 있고, 작업이 길어질수록 요구사항 누락, 컨텍스트 오염, 검증 부족, 잘못된 코드 변경 같은 문제가 발생할 수 있다.

특히 코딩이나 소프트웨어 개발처럼 정교한 작업에서는 결과물의 퀄리티를 예측하고 통제하기 어렵다는 문제가 있다.

하네스 엔지니어링의 목적

AI가 예상 밖의 코드를 짜거나 에러를 발생시키는 것을 최소화하고, 인간 기획자나 개발자가 원하는 방향대로 안전하고 정확하게 결과물을 도출하도록 유도하는 것

하네스 엔지니어링

Codex 생태계에서는 Superpowers 같은 플러그인을 사용할 수 있으며, gstack, oh-my-codex 같은 외부 워크플로우 도구들도 Codex 또는 다른 AI 코딩 에이전트와 함께 활용된다.

본편에서는 하네스 엔지니어링 툴 중 superpowers을 기반으로 이야기를 하겠다.

Superpowers 기본 워크플로우

Superpowers 기본 워크플로우는 아래와 같다.

1. 브레인스토밍

- 코드를 작성하기 전에 활성화된다.

- 질문을 통해 초기 아이디어를 다듬고, 대안을 탐색하며, 검증을 위해 설계를 부분별로 제시한다. 설계 문서를 저장한다.

2. using-git-worktrees

- 설계 승인 후 활성화된다.

- 브랜치에 격리된 작업 공간을 생성하고, 프로젝트 설정을 실행하며, 테스트 기준선이 제대로 설정되었는지 확인한다.

3. 작성 계획

- 승인된 디자인으로 활성화한다.

- 작업을 2~5분 정도의 짧은 작업으로 나누어준다.

- 모든 작업에는 정확한 파일 경로, 전체 코드, 검증 단계가 포함되어 있다.

4. 서브에이전트 기반 개발 또는 계획 실행

- 계획에 따라 활성화된다.

- 2단계 검토(사양 준수, 코드 품질)를 거쳐 작업별로 새로운 서브에이전트를 배포하거나, 사람의 검토를 거쳐 일괄적으로 실행한다.

5. 테스트 주도 개발(TDD)

- 구현 중에 활성화된다.

- 레드-그린 리팩토링(RED-GREEN-REFACTOR) 방식을 적용한다.

- 즉, 실패하는 테스트를 작성하고, 실패하는 것을 확인한 후, 최소한의 코드만 작성하고, 테스트 통과를 확인한 다음 커밋한다.

테스트 전에 작성된 코드는 삭제된다.

6. 코드 검토 요청

- 작업 사이에 활성화된다.

- 계획 대비 검토를 수행하고 심각도별로 문제를 보고한다.

- 심각한 문제는 진행을 차단한다.

7. 개발 브랜치 완료

- 작업이 완료되면 활성화된다.

- 테스트를 검증하고, 옵션(병합/PR/유지/폐기)을 제시하며, 작업 트리를 정리한다.

이 과정에서 설계 문서, 작업 계획, 테스트 결과, 코드 리뷰 이슈를 기록하고 검증 루프로 연결한다. 즉, 하네스의 핵심은 AI가 임의로 코드를 작성하지 않도록 작업 단계를 구조화하고, 각 단계마다 검증 가능한 기준을 두는 데 있다.

하네스 엔지니어링 장점

장점	설명
일관된 AI 결과물	AI가 코드를 바로 작성하지 않고, 브레인스토밍, 설계, 작업 계획, 구현, 테스트, 리뷰 순서를 따르도록 만든다.
요구사항 누락 최소화	AI는 작업을 거치며 컨텍스트를 압축한다. 그 과정에서 요구사항이 누락되는 경우가 많은데, 하네스는 요구사항을 기반으로 설계 문서와 작업 계획을 만들고, 변경사항을 추적한다.
검증 가능한 개발 프로세스	코드 생성, 테스트, 코드리뷰를 포함한 검증 루프를 만든다.
작업 범위를 나누어 관리	복잡한 기능 작업을 작은 단위로 분리하고, 각 작업마다 파일 경로, 구현 내용, 검증 방법을 명확히 정의한다.
협업과 인수인계에 유리	하네스 기반 작업은 설계 문서, 작업 계획, 테스트 결과, 코드 리뷰 이슈가 기록된다.

하네스 엔지니어링 단점

단점	설명
초기 설정과 학습 비용	superpowers 같은 도구를 사용한다면 skill 구조나 각 단계의 동작 방식을 이해해야 하므로 진입 장벽이 높을 수 있다.
작은 작업에 비효율적	규모가 작은 작업에는 오버 엔지니어링으로 작용될 수 있다.
검증 기준에 따른 효과 제한	부족한 테스트 코드, 모호한 리뷰 기준, 불명확한 요구사항 등은 여전히 잘못된 결과를 만들 수 있다. 결국 하네스의 품질은 사람이 정의한 규칙, 테스트, 검증 기준의 품질에 의존한다.
AI의 자율성 하락	AI가 정해진 절차를 따르도록 하기 때문에, 빠르게 아이디어를 실험하거나 자유롭게 대안을 탐색하는 상황에서는 제약적일 수 있다.
토큰 발생 증가	브레인스토밍, 설계, 작업 계획, 구현, 테스트, 리뷰 등의 과정을 거치고, 리뷰에서 reject 시 다시 구현 과정을 반복하다보니 토큰이 많이 소모된다.

정리

하네스 엔지니어링은 AI 코딩 에이전트를 더 안전하고 일관되게 활용하기 위한 개발 방식이다.

AI가 설계, 계획, 구현, 테스트, 리뷰, 정리의 프로세스를 따르기 때문에 결과물을 더 예측 가능하게 만든다.

다만 모든 작업에 적용하기 보다는, 요구사항이 복잡하거나 코드 품질이 중요한 작업, 또는 팀 단위로 AI를 활용하는 작업에서 효과적이다.

결국 하네스 엔지니어링의 핵심은 AI가 좋은 결과를 낼 수밖에 없는 작업 환경과 검증 구조를 사람이 설계하는 데에 있다.