Show HN: Statewright – Visual state machines that make AI agents reliable
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
# 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
Related Papers
Show HN: Needle: We Distilled Gemini Tool Calling into a 26M Model
Gemini의 함수 호출(tool calling) 능력만 뽑아서 26M(2600만) 파라미터짜리 초경량 모델로 만든 프로젝트로, 폰/워치/스마트글라스 같은 엣지 디바이스에서 직접 실행 가능하다.
Show HN: adamsreview – better multi-agent PR reviews for Claude Code
Claude Code에서 최대 7개의 병렬 서브 에이전트가 각각 다른 관점으로 PR을 리뷰하고, 자동 수정까지 해주는 오픈소스 플러그인이다. 기존 /review나 CodeRabbit보다 실제 버그를 더 많이 잡는다고 주장하지만 커뮤니티에서는 복잡도와 실효성에 대한 회의론도 나왔다.
How Fast Does Claude, Acting as a User Space IP Stack, Respond to Pings?
Claude Code에게 IP 패킷을 직접 파싱하고 ICMP echo reply를 구성하도록 시켜서 실제로 ping에 응답하게 만든 실험으로, 'Markdown이 곧 코드이고 LLM이 프로세서'라는 아이디어를 네트워크 스택 수준까지 밀어붙인 재미있는 사례다.
Show HN: Git for AI Agents
AI 코딩 에이전트(Claude Code 등)가 수행한 모든 툴 호출을 자동으로 추적하고, 어떤 프롬프트가 어느 코드 줄을 작성했는지 blame까지 가능한 버전 관리 도구다.
Principles for agent-native CLIs
AI 에이전트가 CLI 도구를 더 잘 사용할 수 있도록 설계하는 원칙들을 정리한 글로, 에이전트가 CLI를 도구로 활용하는 빈도가 높아지면서 이 설계 방식이 실용적으로 중요해지고 있다.
Agent-harness-kit scaffolding for multi-agent workflows (MCP, provider-agnostic)
여러 AI 에이전트가 서로 역할을 나눠 협업할 수 있도록 조율하는 scaffolding 도구로, Vite처럼 설정 없이 빠르게 멀티 에이전트 파이프라인을 구성할 수 있다.