Show GN: Act Operator – "실제 프로덕션용" LangGraph 1.0+ 프로젝트 제어 하네스 오픈소스
(github.com/Proact0)같은 AI 모델, 사람인데 왜 결과가 다를까.
매번 베이스를 새로 파서 다시 만들고, 팀마다 다른 방식으로 Agent를 사용해서 코드 충돌이 일어나고, 운영은 안 되는 프로토타입만 쌓이는…
여기엔 항상 AI 도구 활용 인력 간 협업 시 발생하는 고질적인 이상 현상이 발생합니다.
기술에 익숙한 개발자가 Claude Code에게 워크플로우 구현을 시키면 뛰어난 코드가 나옵니다. 그런데 처음 접한 개발자가 같은 Claude Code에게 같은 요청을 하면 일반적이고, 일관성 없고, 미묘하게 잘못된 코드가 나옵니다. 같은 모델입니다. 왜 그랬을까요?
문제는 모델이 아닌 컨텍스트 격차(Context Gap) 였습니다 — 그리고 이건 사람과 AI 에이전트 모두에게 동일하게 적용됩니다.
온보딩 없이 투입된 새 팀원이 같은 코드베이스에서 헤매는 이유도 같습니다: 컨벤션은 암묵적이고, 아키텍처는 누군가의 머릿속에만 있고, 가이드해줄 구조화된 환경이 없습니다. AI 에이전트도 다르지 않습니다.
숙련자도 이 벽에 부딪힙니다. 세션이 바뀌면 에이전트가 지난 설계를 잊습니다. 어제 정한 아키텍처를 오늘의 에이전트는 모릅니다. 지식은 사람 머릿속에만 있고, 코드베이스 안에는 없으니까요. 사람이 컨벤션을 찾을 수 없으면 에이전트도 찾을 수 없습니다.
이걸 해결하기 위해서 프롬프트 개선이나 더 좋은 모델이 필요한 게 아닙니다. 사람과 에이전트가 함께 동작하는 환경 자체를 설계해야 합니다.
[ 하네스는 원래부터 있었다. ]
하네스(harness)라는 단어는 고대 프랑스어 'harnois'에서 왔습니다. 원래 의미는 "군대 장비, 통제 도구"입니다.
1690년대부터 비유적 의미가 확립됩니다: "통제되지 않은 힘을 올바른 방향으로 제어해서 사용하다(to control for use as power)".
바람을 에너지로 바꾸는 풍력 발전소가 "바람을 하네싱(harnessing)한다"고 하는 것과 같은 맥락입니다.
공학에서 이 원칙은 형태만 바꿔 반복해서 등장했습니다.
- 전기 배선 하네스(Wiring Harness): 복잡하게 얽힌 전선을 하나의 번들로 묶어 제어 가능한 단위로 만드는 장치. 자동차 산업에서 수십 년째 표준입니다.
- 테스트 하네스(Test Harness): 전체 인프라 없이 특정 컴포넌트를 격리해서 실행할 수 있도록 스텁과 드라이버로 구성한 실행 환경. 소프트웨어 테스팅의 핵심 개념입니다.
- CI/CD 파이프라인: 코드가 직접 프로덕션으로 가지 않고 빌드·테스트·검증 레이어를 통과하도록 구조화한 통제 환경. 이것도 하나의 하네스입니다.
공통점은 하나입니다.
통제되지 않는 대상(전선, 코드 컴포넌트, 배포 흐름)을 올바른 방향으로 제어하기 위한 외부 환경 설계.
그래서 2026년 초 OpenAI가 Codex 에이전트로 5개월간 수동 코드 한 줄 없이 100만 줄 규모의 시스템을 만들었을 때, 이 오래된 원칙을 AI 에이전트에 적용한 것을 하네스 엔지니어링(Harness Engineering) 이라고 명명한 것은 자연스러운 귀결이었습니다. Martin Fowler도, Anthropic 엔지니어링 팀도 같은 시기에 같은 단어를 쓴 건 우연이 아닙니다.
또 LangChain도 하네스만 개선해서 Terminal Bench 2.0 순위를 30위에서 5위로 올렸죠.
그래서 act-operator는 실제 프로덕트에서 사용될 수 있는 LangGraph 1.0+ 구조 제어용 하네스로서 만들어졌습니다.
[ Ultra-Quick Start ]}
uv가 설치된 환경에서 아래 한 줄이면 실제 프로덕션용 LangGraph 1.0+ 프로젝트 하네스 셋팅이 완료됩니다.
uvx --from act-operator act new
[ Act Operator의 3단 레이어 ]
AI 기반 개발에서 하네스는 누가 작업하든 상관없이 사람과 AI 에이전트 모두가 올바른 출력을 안정적으로 생성할 수 있도록 감싸는 스캐폴딩, 실행 가능한 지식, 피드백 루프의 시스템입니다.
Act Operator는 이를 세 가지 레이어로 구현합니다:
- 스캐폴딩: 첫 번째 에이전트 프롬프트 이전에 조립되는 최소 저결합도와 최소 고응집도가 보장된 모듈 컨벤션과 베이스 클래스가 내장된 완전한 프로젝트 스켈레톤
- 실행 가능한 SSOT: 에이전트와 사람이 런타임에 읽는 동작 가능한 파일로 인코딩된 지식
- 피드백 루프: 세션 간 에이전트를 정렬 상태로 유지하는 명세
[ 실행 가능한 SSOT ]
일반적인 팀은 개발, 설계 지식을 위키, 아키텍처 문서, 구전 지식으로 공유, 심지어 안 할 때도 있죠. 문제는 문서가 낡아가고, 위키가 오래되고, 구전 지식이 팀 변화에서 살아남지 못한다는 점입니다.
하네스는 이 지식들을 동작하는 파일로 인코딩합니다 — 정적 문서가 아닌, 에이전트와 사람이 직접 읽는 실행 가능한 참조입니다. Act Operator는 결합도와 응집도를 고려하여 세 가지 상호보완적 SSOT 구성요소 레이어로 관리합니다:
- Act Template (scaffold): 프로젝트 스켈레톤 자체 — 기본 CI 워크플로우, 베이스 클래스, 테스트 구조, 모노레포 설정, 환경변수 관리, 사용 가이드
- Agent Skills: 총 5개의 스킬, 50개 이상 참조 패턴, 결정 트리, 아키텍처 템플릿
- Drawkit: draw.io용 Act 아키텍처 사전 정의 쉐이프 — 사람 간 커뮤니케이션을 위한 공유 시각 어휘
각 구성요소는 서로 다른 대상을 겨냥하면서 동일한 기저 컨벤션을 참조합니다. Act Template은 에이전트와 개발자 모두가 작업하는 구조적 기반을 확립합니다. 스킬은 그 구조 안에서 에이전트가 올바르게 구축하는 방법을, Drawkit은 팀에게 아키텍처 시각화 방법을 알려줍니다.
[ 오픈소스 기타 정보 ]
- Claude Code 외에 OpenCode, Cursor, Gemini CLI 등 스킬 디렉터리를 지원하는 도구라면 모두 동작합니다.
- 한국어/영어 문서 모두 지원
- Apache 2.0 License – PIPY에서 200% 무료 배포중
사랑하는 모든 분들의 피드백 및 컨트리뷰션을 환영합니다(그리고 깃스타★..!). 감사합니다 :)