Statewright – AI 에이전트를 안정적으로 만드는 Visual State Machine | AI Paper Digest

TL;DR Highlight

AI 에이전트에게 40개 이상의 도구를 주면 오히려 성능이 떨어지는 문제를 State Machine으로 각 단계별 사용 가능한 도구를 제한해 해결하는 오픈소스 프로젝트다. 더 큰 모델 대신 더 작은 문제 공간을 만들어 신뢰성을 높이는 접근이 핵심이다.

Who Should Read

AI 에이전트가 중간에 엉뚱한 도구를 쓰거나 예측 불가능하게 동작해서 골머리를 앓고 있는 백엔드/풀스택 개발자. Claude Code, Cursor 같은 AI 코딩 도구를 워크플로우에 통합하려는 개발자에게 특히 유용하다.

Core Mechanics

AI 에이전트에 40개 이상의 도구를 한꺼번에 주면 모델이 어디서부터 시작해야 할지 몰라 거의 아무것도 못 하는 문제가 있다. 이 문제의 기존 해결책은 더 큰 모델이나 더 긴 프롬프트였는데, 효과가 제한적이다.
Statewright의 핵심 아이디어는 '모델을 크게 만드는 대신 문제를 작게 만들자'는 것이다. State Machine(상태 기계)으로 워크플로우를 단계별로 나누고, 각 단계에서 쓸 수 있는 도구를 명시적으로 제한한다.
예를 들어 Planning 단계에서는 읽기 전용 도구만 쓸 수 있고, Implementation 단계로 넘어가면 편집 도구가 열리지만 파괴적 명령이나 write-via-redirect는 여전히 차단된다. Testing 단계에서는 지정된 테스트 명령만 허용한다.
현재 단계에 없는 도구를 호출하면 거절 메시지와 함께 '지금 사용 가능한 도구가 무엇인지', '다음 단계로 어떻게 전환하는지'를 알려준다. 이게 단순한 차단이 아니라 모델이 맥락을 유지하도록 돕는 역할을 한다.
프론티어 모델(GPT, Claude 등)에서는 completion까지 필요한 토큰 수가 줄어드는 효과가 있고, 13B+ 로컬 모델에서는 원래 실패하던 태스크를 성공시키는 효과가 있다고 주장한다.
공개된 리서치 결과에 따르면 gemma3(3.3GB)는 버그픽스와 SWE-bench 모두 실패, gemma4:e2b(7.2GB)는 버그픽스는 통과, SWE-bench는 실패였다. 다만 이 실험 코드는 공개되지 않아 재현 검증이 불가능한 상태다.
Claude Code, Codex, Cursor, opencode, Pi 등 주요 AI 코딩 도구에서 동작하며, Claude Code에서는 `/plugin marketplace add statewright/statewright` 한 줄로 설치 가능하다. Rust로 작성됐고 Apache 2.0 라이선스다.
연구 페이지에 특허 출원(#64/054,240, 2026년 4월 30일)이 명시되어 있으며 35개 청구항이 state machine guardrail 관련 내용을 커버한다. 오픈소스 코어 엔진과 특허 대상의 경계가 불명확해 커뮤니티의 우려를 낳고 있다.

Evidence

리서치 결과를 로컬에서 재현해보려 했지만 실험 코드가 공개되지 않았다는 지적이 있었다. 연구 페이지에는 특허 언급과 'core engine'이 나오는데, 특허 대상인 'state machine guardrail runtime'과 오픈소스 'core engine'의 차이가 무엇인지 불명확하다는 혼란도 제기됐다.
특허 존재 자체가 이 프로젝트를 깊이 살펴보고 싶지 않게 만든다는 의견이 있었다. 아이디어 자체는 흥미롭고 납득이 가는데 특허 때문에 관심을 접게 된다는 반응이 대표적이다.
비슷한 접근(티켓팅 시스템 기반 단계별 워크플로우)을 직접 구현해본 개발자가 댓글을 달았는데, Claude Code가 파일 검색에 grep을 쓰는 것이 너무 느리다며 ripgrep 사용을 권고했다. 로컬 도구 속도 문제가 LLM 대기 시간보다 더 체감되는 병목이라는 실사용 경험이었다.
MCP(Model Context Protocol, 외부 도구를 LLM에 연결하는 프로토콜) 방식으로 API를 제공하는 것이 더 나을 수 있다는 의견이 있었다. MCP 자체가 컨텍스트 사용 최적화에 최선이 아닌데 이를 권장하는 것이 일관성 있냐는 의문이 제기됐다.
스마트 모델이 테스트 가능한 단계별 계획을 짜고, 더 저렴한 모델이 구현하고, 또 다른 모델이 각 단계를 리뷰하는 파이프라인을 이미 쓰고 있다는 개발자가 'Rust state engine이 무슨 가치를 추가하냐'고 반문했다. 알고리즘으로 검증 가능한 건 테스트로 충분하고, 애매한 패턴 준수 같은 건 어차피 LLM이 판단해야 하는데 state engine이 그 간극을 메워주는지 모르겠다는 의문이었다.

How to Apply

Claude Code를 쓰다가 에이전트가 중간에 엉뚱한 파일을 수정하거나 예상 밖의 명령을 실행하는 문제를 겪고 있다면, `/plugin marketplace add statewright/statewright` 후 `/statewright start bugfix`로 bugfix 워크플로우를 실행해 각 단계별 도구 제한이 실제로 에이전트 동작을 얼마나 안정화시키는지 테스트해볼 수 있다.
13B 이하 로컬 모델로 코드 수정 태스크를 시도했는데 계속 실패하는 경우, Statewright로 Planning/Implementation/Testing 단계를 분리해 각 단계의 컨텍스트를 줄이면 원래 실패하던 태스크를 성공시킬 수 있다고 주장하므로 시도해볼 가치가 있다.
프로덕션 AI 에이전트 파이프라인을 설계 중이라면 Statewright의 state machine 정의 방식을 참고해, 각 단계에서 허용/차단할 도구 목록을 명시적으로 정의하는 아키텍처 패턴을 채택할 수 있다. 특허 이슈가 우려된다면 코드를 직접 참조용으로만 살펴보고 자체 구현하는 방향도 고려할 것.
Cursor나 Windsurf 같은 AI 코딩 도구를 팀 전체가 사용 중이라면, Statewright가 지원하는 플러그인 방식으로 동일한 워크플로우 정의를 팀 전체에 배포해 에이전트 동작의 일관성을 높이는 용도로 활용할 수 있다.

Code Example

snippet

# Claude Code에서 Statewright 설치 및 실행
/plugin marketplace add statewright/statewright
/plugin install statewright
/reload-plugins

# bugfix 워크플로우 시작
/statewright start bugfix

# 각 단계별 동작 예시:
# - Planning 단계: read-only 도구만 허용 (파일 읽기, 검색 등)
# - Implementation 단계: 편집 도구 허용, 단 write-via-redirect 및 파괴적 shell 명령 차단
# - Testing 단계: 지정된 테스트 명령만 허용
#
# 허용되지 않은 도구 호출 시 응답 예시:
# "Tool 'bash' is not available in the current 'planning' state.
#  Available tools: [read_file, search_files, list_dir]
#  To use bash, transition to 'implementation' state."

Terminology

State Machine프로그램이 가질 수 있는 '상태'(예: planning, implementation, testing)와 상태 간 전환 규칙을 명시적으로 정의하는 설계 패턴. 신호등처럼 빨강→초록→노랑 순서만 허용하고 임의 전환은 막는 것과 같은 개념이다.

GuardrailAI 모델이 특정 범위를 벗어난 행동을 하지 못하도록 막는 제약 장치. 차도의 가드레일처럼 벗어나는 순간 즉시 막는 구조다.

SWE-bench실제 GitHub 이슈를 AI가 자동으로 수정하는 능력을 평가하는 벤치마크(성능 측정 기준). AI 코딩 에이전트 성능 비교에 널리 쓰인다.

MCPModel Context Protocol의 약자로, 외부 도구(파일 시스템, API, DB 등)를 LLM에 표준화된 방식으로 연결하는 Anthropic이 만든 프로토콜. USB 포트처럼 다양한 도구를 꽂아 쓸 수 있게 해준다.

write-via-redirectShell에서 `echo 'text' > file` 처럼 리다이렉션(`>`)을 이용해 파일을 덮어쓰는 방식. 의도치 않게 파일을 날릴 수 있어 Statewright가 Implementation 단계에서도 차단하는 위험 명령 유형이다.

frontier model현재 공개된 AI 모델 중 가장 성능이 높은 최신 대형 모델을 통칭하는 말. GPT-4o, Claude 3.5 Sonnet 같은 모델들이 해당한다.

Statewright – AI 에이전트를 안정적으로 만드는 Visual State Machine