최근에 Claude Code 소스코드가 유출되는 일이 발생했다.
유출된지 1시간 때, 해당 깃허브를 들어가봤는데 당시에는 8000스타였던 것이 4시간 뒤에는 3만 이상의 스타를 기록하고 있었다 .
이를 통해 많은 커뮤니티에서 하네스 엔지니어링이라는 단어를 사용하고, 해당 소스코드들을 통해 코덱스에 하네스를 적용했다길래, 이게 뭔가 싶어 알아보고 이를 일부 적용해보았다.
하네스 엔지니어링
AI 에이전트가 안정적으로 코딩, 작업, 테스트를 수행할 수 있도록 감싸는 환경(스캐폴딩, 프레임워크, 도구, 가드레일)을 설계하고 제어하는 기술
뜻은 위와 같지만, 정작 풀어보면 이것은 그냥 에이전트에게 필요한 것을 강제화하는 기능이라고 보면 된다.
쉽게 예로 들자면 우리가 AGENT 를 사용할 때, 이 에이전트가 진행해야하는 규칙이 존재한다면 AGENT.md 에 규칙을 명시하고 사용한다.
만약 이러한 AGENTS.md 가 없다면, 에이전트는 우리가 설정한 제약에 맞춰 진행하지 않으므로 매 실행마다 서로 다른 실행 방식을 가지거나, 잘못된 방식을 사용하여 결과를 도출해낼 수도 있다.
이러한 상황을 방지하기 위해 하네스 엔지니어링이 필요하다.
내가 적용한 런타임 하네스 훅
내가 적용한 런타임 하네스 훅은 다음과 같다.
- 실행 진입점 래퍼 :
README.md, AGENTS.md 등 기본 파일 존재 확인- 런타임 훅 :
임계치 및 종목에 따라 지식을 저장/후처리/회수하여 사용- 주기적 실행 :
일정 시간마다 스크립트 틱을 돌려, 특정 json 파일에 예약된 작업을 실행
훅 설정 과정에서 문제 발생 ...!!
이 중에서 훅을 설정하는데 분명 공식대로 따라한 것이 분명해보였음에도 이상하게 작동이 안되었다... !!
직접 스크립트 파일을 실행할때는 잘 작동하는데, 이상하게 hooks.json 에 설정한 hooks 들이 정상작동하지 않더라.
여러 세션을 바꾸어가며 물어봐도, Codex 가 맞는 방식으로 구현했다고 해서 더 헷갈렸다...
결국 알아낸 바로는 나의 실수가 맞았고, Codex 도 그 내용을 몰라 그런 것이었다.
해결 방법
https://developers.openai.com/codex/hooks
위의 홈페이지를 살펴보면 hooks.json 의 경우 .codex/hooks.json 이나 <repo>/.codex/hooks.json 에 놓으라고 되어있다.
나의 경우에는 이처럼 진행하였지만 실질적인 문제는 다음과 같았다.
내가 등록한 hook 의 실행 파일은 .codex/scripts/폴더 에 존재하였다.
위처럼 다양한 폴더들이 존재하는 내부에 해당 파일을 두었으나, 계속 안되어 다시 한 번 홈페이지를 살펴보니 뭔가 공통되는 경로들을 발견할 수 있었다.
모두가 실행 파일을 .codex/hooks/... 에 놓는 것이었다.
이후 나도 이 예시와 같이 실행 파일 경로를 hooks 하위에 두니 훅 실행이 정상적으로 작동하였다.
근데 현재 SessionStart 훅이 세션 시작때가 아닌 세션 시작 후 첫 프롬프트 실행 시 실행되는 문제가 있다.
codex github issue 를 보니 이미 올라온 문제라, 곧 해결될 것이니 그냥 기다리면 해결될 것이라고 생각된다 !
