statewright

에이전트는 제안일 뿐이지만, 상태는 법칙입니다.

AI 에이전트가 각 단계에서 어떤 도구 (tools)를 사용할 수 있는지 제어하는 상태 머신 가드레일 (State machine guardrails)입니다. 워크플로 (workflow)를 한 번 정의하면 Claude Code, Codex, Cursor, opencode, 그리고 Pi 전반에 걸쳐 적용할 수 있습니다. 전체 문서 →

Quickstart

Claude Code의 무료 티어에서 다음을 실행하여 체험해 보세요:

/plugin marketplace add statewright/statewright

/plugin install statewright
...

그 다음 start the bugfix workflow 또는 /statewright start bugfix를 실행하세요. 프롬프트가 나타나면 API 키를 붙여넣어야 합니다. 최신 버전의 Claude가 거부할 수도 있습니다. 그럴 때는 API 키를 다시 붙여넣고 정말로 실행하겠다고 말하세요. Claude가 단지 조심스럽게 행동하는 것뿐입니다.

The problem

AI 에이전트는 강력하지만 취약합니다. 모델에게 40개 이상의 도구와 개방형 문제를 주면, 시작 단계조차 간신히 벗어납니다. 일반적인 해결책은 더 큰 모델과 더 긴 프롬프트 (prompts)를 사용하는 것이지만... 이는 때때로 도움이 될 뿐입니다. 관찰 가능성 (Observability)은 사후에 무엇이 잘못되었는지 알려줄 뿐, 그것을 방지하지는 못합니다.

The approach

모델을 더 크게 만드는 대신, 문제를 더 작게 만드세요.

상태 머신 (State machines)은 도구 및 솔루션 공간을 제한하여 모델이 각 단계에서 집중된 컨텍스트 (context) 내에서 추론하도록 합니다. 계획 (planning) 상태에서는 읽기 전용 도구 (read-only tools)만 제공됩니다. 에이전트가 구현 (implementation) 단계로 전환되면, 제한된 셸 (shell) 액세스와 함께 편집 도구 (edit tools)가 잠금 해제됩니다 (Bash가 허용되더라도 write-via-redirect 및 파괴적인 작업은 차단됩니다). 테스트 (Testing) 단계에서는 지정된 테스트 명령만 허용됩니다. 현재 단계에 없는 도구를 호출하면, 무엇을 사용할 수 있는지와 어떻게 전환해야 하는지를 알려주는 메시지와 함께 거부됩니다.

이는 프런티어 모델 (frontier models) (완료까지 필요한 토큰 수 감소)과 13B 이상의 모델이 평소라면 실패했을 작업을 해결하기 시작하는 로컬 모델 (local models) 모두에서 동일하게 작동합니다.

Research results

모델 (Model)	크기 (Size)	버그 수정 (Bug Fix, 26 lines)	SWE-bench (5 tasks)
gemma3	3.3GB	FAIL	FAIL
...
*specialized edit_line tool adaptation 적용 시*
*†5개 작업 중 2개에서 테스트됨 (초기 실험 실행 후 추가됨)*

우리는 효과를 가장 명확하게 측정할 수 있는 로컬 모델 (local models)에서 검증을 진행했습니다. 우리의 5개 작업 SWE-bench 서브셋에서, 두 모델 (13.8GB 및 19.9GB)은 statewright 제약 조건을 통해 2/10에서 10/10으로 성능이 향상되었습니다. 동일한 작업, 동일한 하드웨어 환경이었습니다. 13GB 미만의 모델은 도구 호출 (tool calls)은 생성할 수 있지만, 정확한 편집을 수행할 만큼 충분한 파일 내용을 유지하지 못할 수 있습니다. 이는 statewright의 한계가 아니라 성능의 하한선입니다.

기본 시스템 프롬프트 (system prompts)를 사용하는 프론티어 모델 (Frontier models)들은 명백하고 치명적인 작업들(데이터베이스 삭제, 자격 증명 유출 등)을... 대부분의 경우 잘 처리합니다. 하지만 구조적인 이점은 더 큽니다. 모델이 파일을 수정하지 못한 채 동일한 파일을 5번 이상 반복해서 읽는 읽기 루프 데스 스파이럴 (read-loop death spirals)을 끊어내고, 모델이 허둥대는 대신 실제로 추론 (reasoning)할 수 있도록 도구 공간 (tool space)을 충분히 작게 유지하는 것입니다. 연구 요약 (Research brief) →

빠른 시작 (Quick start)

Claude Code에 설치하기:

/plugin marketplace add statewright/statewright
/plugin install statewright

브라우저가 열리면 → statewright.ai에서 가입 → 키 생성 → 붙여넣기 → 완료.

그 다음 워크플로 (workflow)를 시작하세요:

❯ start the bugfix workflow — fix the failing tests in calc.py

◆ statewright — statewright_start (workflow: bugfix)
...

슬래시 명령어를 직접 사용할 수도 있습니다: /statewright start bugfix.

작동 원리 (How it works)

핵심은 상태 머신 (state machine) 정의인 상태 (states), 전이 (transitions), 가드 (guards), 도구 제한 (tool restrictions)을 평가하는 Rust 엔진입니다. 이는 결정론적 (deterministic)입니다. 루프 내에 LLM이 개입하지 않습니다.

그 위에는 MCP를 통해 코딩 에이전트 (coding agent)와 통합되는 플러그인 레이어가 위치합니다. 워크플로 (workflow)를 활성화하면, 훅 (hooks)이 상태별로 도구 제한 사항 (tool restrictions)을 자동으로 강제합니다. 모델은 30개가 아닌 5개의 도구만 보게 되며, 현재 단계에 대한 명확한 지침을 받고 조건이 충족되면 상태를 전환 (transition)합니다.

가드레일 (Guardrails)

가드레일	기능
상태별 도구 강제 (Per-state tool enforcement)	allowed_tools에 포함되지 않은 경우 에이전트에게 도구가 보이지 않음
...
전체 가드레일 참조는 문서에서 확인할 수 있습니다.

자신만의 워크플로 정의하기

{
  "id": "bugfix",
  "initial": "planning",
...

상태 머신 (state machines)은 DAG (Directed Acyclic Graph)가 아닙니다. 이들은 루프를 돌고 재시도하며, 이것이 에이전트 중심 작업 (agentic work)에 실제로 필요한 것입니다. 에이전트가 JSON 스키마 (JSON schema)를 참조하게 하면 statewright_create_workflow를 통해 워크플로를 생성합니다. 비주얼 에디터 (visual editor)에서 도구, 명령, 환경 블록을 미세 조정할 수 있습니다.

지원되는 에이전트

에이전트	통합 (Integration)	강제 (Enforcement)
Claude Code	Hooks + MCP	Hard (프로토콜 레이어)
...
Hard = 모델이 확인하기 전 프로토콜 레이어에서 도구 호출 (tool calls)이 차단됨. Advisory = 규칙이 컨텍스트 (context)에 주입되지만 강제되지는 않음.

가격 (Pricing)

개인 개발자에게는 무료입니다. statewright.ai의 관리형 클라우드 (managed cloud)는 워크플로 저장, 실행 이력 (run history), MCP 게이트웨이를 처리합니다.

(이 티어들은 변동될 가능성이 있습니다: 가격은 인상되지 않으며, 티어 혜택은 증가할 수만 있습니다)

플랜	워크플로	월간 전환 (Transitions/mo)	실행 이력	가격
Free	3	200	72시간	$0
...

셀프 호스팅 (Self-hosting)

엔진 (crates/engine)은 Apache 2.0 라이선스이며 런타임 의존성 없이 임베드 (embeddable)할 수 있습니다. 전체 스택의 1인 개발자 및 1개 팀 단위 셀프 호스팅은 FSL 라이선스 하에 허용됩니다.

use statewright_engine::{MachineDefinition, resolve_transition, validate_definition};

트레이드오프 (Tradeoffs)

• 에이전트의 MCP (Model Context Protocol) 지원이 필요합니다 (또는 Codex와 같은 비-MCP 에이전트를 위한 훅 (hooks)이 필요합니다).
• 워크플로 (Workflow) 정의는 수동으로 작성하지만, 에이전트가 statewright_create_workflow를 통해 생성할 수도 있습니다.
• 커서 (Cursor) 강제 적용은 권고 사항이며, 강제적이지 않습니다. MCP만으로는 Cursor의 아키텍처 내에서 도구 호출 (tool calls)을 차단할 수 없습니다.
• 연구 결과는 전체 2294개 인스턴스 벤치마크가 아닌, 5개 태스크로 구성된 SWE-bench 서브셋 (subset)을 대상으로 한 것입니다.
• 워크플로가 너무 제한적이면 에이전트가 갇힐 수 있습니다. statewright_deactivate가 탈출구 (escape hatch) 역할을 합니다.

문서 (Docs)

docs.statewright.ai — 설치 가이드, 워크플로 작성, 스키마 참조 (schema reference), MCP 도구 참조 (MCP tool reference), 그리고 에이전트 생성 워크플로 (agent-generated workflows).

기여하기 (Contributing)

워크플로 정의, 템플릿 및 버그 보고를 환영합니다. 워크플로 작성 방법은 Create Your Own을 참조하세요.

라이선스 (License)

Apache 2.0 — 일부 항목은 FSL-1.1-ALv2를 따릅니다 (2029년 5월 3일에 Apache 2.0으로 전환됨). 관리형 클라우드는 statewright.ai에서 제공됩니다.

이 프로젝트에는 특허에 기술된 기술의 독립적인 구현을 다루는 특허 서약 (patent pledge)이 포함되어 있습니다. 개인 개발자, 연구자, 오픈 소스 프로젝트 및 단일 팀 셀프 호스팅 배포는 Statewright 소프트웨어 사용 여부와 관계없이 보호 대상에 포함됩니다.

모든 것을 다스리는 하나의 훅 (One hook to rule them all).

<img src="https://statewright.ai/api/px/github" width="1" height="1" alt="" />