에이전트 작업, 상태기계로 강제하는 '어하니스'

오래 도는 코딩 에이전트가 정해진 절차를 멋대로 건너뛰는 문제를 막기 위해, 작업 과정을 '상태기계(state machine)'로 강제하는 오픈소스 도구 '어하니스(aharness)'가 공개됐다. '이 절차를 지켜달라'고 부탁하는 것만으로는 부족하다는 문제의식에서 출발한다.

무슨 일인가

제작자의 가설은 이렇다. 이제 에이전트는 길고 여러 단계로 이뤄진 작업을 해낼 만큼 똑똑해졌지만, 실패의 양상이 '능력 부족'에서 '절차 이탈'로 옮겨갔다는 것이다. 승인을 건너뛰거나, 복구 규칙을 잊거나, 만들지도 않은 결과물을 만들었다고 주장하거나, 낡은 맥락에서 계속 작업을 이어가는 식이다. 프롬프트와 스킬은 절차를 '설명'할 수는 있어도 '강제'하지는 못한다. 어하니스는 절차를 아예 실행 규칙(runtime)으로 바꾼다. 각 상태가 코덱스(Codex)가 다음에 할 수 있는 행동을 규정하고, 정해진 형식의 제출물로 무슨 일이 있었는지를 증명하며, 검증된 출구를 통해서만 다음 상태로 넘어간다.

핵심 짚어보기

유한상태기계(FSM)는 이름이 붙은 상태들과 허용된 전이로 이뤄진 그래프다. 어하니스는 이 FSM을 타입스크립트(TypeScript)로 정의한다는 점이 특징이다. 그냥 코드로 짜면 유연하지만 통제가 어렵고, YAML이나 JSON으로 짜면 검증은 쉽지만 실제 업무에 쓰기엔 너무 뻣뻣하다. 그 사이에서 타입스크립트는 검증 가능하면서도 타입·가드·npm 생태계까지 끌어쓸 수 있는 절충점을 제공한다는 설명이다. 핵심 베팅은 '쓸 만한 워크플로는 재사용 가능한 소프트웨어'라는 것이다. 프롬프트로 복사해 돌려쓰는 대신, 작성·리뷰·버전관리하고 더 작은 FSM을 조합해 npm 패키지로 배포하자는 발상이다. 어하니스는 기존 코덱스 환경(AGENTS.md·스킬·MCP 서버·권한·로컬 도구)에 그대로 얹힌다.

1인기업 실전 적용 포인트

• 혼자 에이전트에게 긴 작업을 맡길 때, '테스트 통과 전에는 배포 금지' 같은 규칙을 부탁이 아니라 통과 못 하면 다음 단계로 못 넘어가는 게이트로 박아둘 수 있다.
• 에이전트가 '끝냈다'고 보고만 하고 실제로는 안 한 경우를 막으려면, 결과물 제출을 타입으로 검증하게 만들어 거짓 완료 보고를 차단한다.
• 실패 시 재시도 횟수와 복구 경로를 정의해, 1인 운영자가 자리를 비운 사이 에이전트가 무한 루프에 빠지는 사고를 예방한다.
• 자주 쓰는 작업 흐름은 작은 FSM으로 만들어 재사용·버전관리하면, 매번 긴 프롬프트를 새로 쓰는 수고를 던다.

전망 / 주의점

모델이 더 오래, 더 자율적으로 일할수록 '능력'보다 '신뢰성'이 병목이 된다. 어하니스 같은 절차 강제 계층은 장시간 자동화를 실무에 쓰려는 사람에게 점점 중요해질 것이다. 다만 현재는 별 9개 수준의 초기 프로젝트이고 코덱스 중심으로 설계돼 있어, 다른 에이전트 환경에 그대로 적용되진 않는다. 또 워크플로를 타입스크립트로 직접 짜야 하므로 비개발자에게는 진입장벽이 있다는 점은 감안해야 한다.

출처: GitHub (https://github.com/Alfredvc/aharness)