Step Code: StepFun이 Pi 코딩 에이전트에 서브에이전트와 웹 페이지 배포를 더한 터미널 코딩 에이전트

9bow · 10월 27, 2026, 2:30오전

핵심 요약

Step Code는 StepFun이 공개한 터미널 코딩 에이전트로, 오픈소스 코딩 에이전트 Pi에서 파생된 프로젝트입니다. Pi가 기본 기능에서 뺀 서브에이전트와 계획 모드를 내장하고, 목표 기반 장시간 실행과 예약 실행을 더했습니다.
기본 경로는 StepFun 계정(Step Plan 구독 또는 API 키)으로 Step 5 Preview 같은 Step 모델을 쓰는 것입니다. 문서에 따르면 Anthropic, OpenAI의 API 키나 Ollama, vLLM 같은 로컬 엔드포인트도 연결할 수 있습니다.
내장 StepPage 플러그인은 로컬에서 만든 정적 웹 페이지를 공개 URL로 배포하고 이전 버전으로 되돌립니다. Claude Code의 MCP 설정과 플러그인, Agent Skills도 대부분 그대로 읽어 들입니다.
StepFun은 같은 Step 5 Preview 모델로 다른 하네스 6종과 비교한 자체 측정을 공개했고, Step Code는 Multi-Frame에서 73.3%로 가장 높았습니다. Terminal-Bench 2.1에서는 DeepSeek Harness와 동점이었고, Codex는 토큰을 절반 정도만 썼습니다.
공식 설치본은 StepFun CDN에서 받는 바이너리이고 텔레메트리가 켜진 상태로 시작합니다. 권한 모드는 운영체제 수준의 샌드박스가 아닙니다.

Step Code 소개

코딩 에이전트의 성능은 모델만으로 정해지지 않습니다. 같은 모델이라도 어떤 도구를 쥐여 주고, 컨텍스트를 어떻게 관리하고, 작업을 어떻게 나누는지에 따라 성공률과 비용이 달라집니다. 이 소프트웨어 계층을 하네스(harness) 라고 부르며, HarnessTax 연구는 같은 모델에서 하네스만 바꿨을 때 비용이 최대 5배까지 벌어진다고 보고했습니다. 그래서 모델을 만드는 회사들이 자기 모델에 맞춘 하네스를 직접 내놓기 시작했고, Moonshot AI의 Kimi Code CLI와 DeepSeek Harness가 그 예입니다. 이번에 소개하는 Step Code는 StepFun(阶跃星辰)이 자사 플래그십 모델 Step 5 Preview의 공식 하네스로 공개한 터미널 코딩 에이전트입니다.

Step Code는 처음부터 새로 만든 프로젝트가 아니라 Mario Zechner가 만든 오픈소스 코딩 에이전트 Pi에서 파생된 프로젝트입니다. 이 사실은 README에는 나오지 않고, 저장소의 LICENSE-STATUS.md와 THIRD_PARTY_NOTICES.md에 적혀 있습니다. Pi는 현재 Earendil Works 조직 아래에서 관리되며, 예전 주소인 badlogic/pi-mono로 접속하면 이 저장소로 이동합니다. Pi가 일부러 작게 유지하는 코어 위에 StepFun은 서브에이전트, 계획 모드, 목표 기반 장시간 실행, 정적 웹 페이지 배포를 얹었습니다.

Step Code는 TypeScript로 작성된 pnpm 모노레포이며, 2026년 9월 24일 v0.1.1부터 10월 23일 v0.1.6까지 대략 1주일 간격으로 릴리스가 이어지고 있습니다. Step Code의 이전 이름은 Step Harness였던 것으로 보입니다. 저장소 내부 패키지 이름이 @step-harness/coding-agent이고, StepFun이 공개한 벤치마크 그래프의 범례에도 Step Harness로 적혀 있습니다. 이 글에서는 Step Code를 기반 프로젝트인 Pi와 비교하고, StepFun이 공개한 하네스 비교 수치를 조건과 함께 살펴본 뒤 설치 방법을 정리합니다.

Step Code vs. Pi

Pi의 저자는 Pi를 "a minimal, extensible agent harness" 라고 소개하며, 서브에이전트와 계획 모드 같은 기능은 기본으로 넣지 않고 사용자가 확장으로 직접 만들게 하는 쪽을 택했습니다. Step Code는 같은 코어를 가져다 그 기능들을 내장하고, 기본 모델 연결을 StepFun 계정으로 맞췄습니다. 두 프로젝트의 공식 문서에서 확인한 차이는 다음과 같습니다:

항목	Pi	Step Code
개발 주체	Mario Zechner, Earendil Works	StepFun
기본 모델 연결	`/login`으로 내장 공급자의 구독이나 API 키를 연결	`/login`의 기본 공급자는 Step 계정(구독 또는 API 키), 다른 공급자는 환경 변수나 `models.json`
서브에이전트, 계획 모드	기본 기능에서 제외, 확장으로 구현	내장 (`explore`, `review`, `planner`, `general` 역할, `/plan`)
장시간 작업	코딩 에이전트에는 내장 명령 없음, 실험적 런타임 Pi Durable을 별도 패키지로 제공	`/goal`(목표 달성까지 반복), `/cron`(예약 실행)
실행 전 권한 확인	내장 권한 시스템 없음, 컨테이너나 샌드박스 사용 권장	Ask, Approve for Me, Full Access 3단계 권한 모드 (운영체제 샌드박스는 아님)
확장 배포	npm, Git으로 공유하는 Pi 패키지	같은 방식의 패키지(`step install`) + Claude Code 플러그인 형식의 마켓플레이스(`/plugin`)
공식 설치본	`pi.dev` 설치 스크립트 또는 npm	StepFun CDN의 바이너리 설치 스크립트

Pi Durable은 코딩 에이전트의 명령이 아니라 장시간 실행 에이전트 애플리케이션을 만들기 위한 프레임워크이므로, Step Code의 /goal과 같은 층위의 기능은 아닙니다. PyTorchKR에서도 Gemma 4와 Pi로 로컬 코딩 에이전트를 구성하는 글과 턴마다 사고 여부를 고르는 Pi 포크 Jeff-Code를 소개한 적이 있습니다. Step Code는 모델 회사가 Pi를 자사 하네스의 기반으로 삼았다는 점에서 이들과 다릅니다.

Step Code를 사용하면 좋을 사용자

Step Code는 Step 5 Preview를 코딩 작업에 쓰려는 개발자, 특히 Step Plan 구독으로 비용을 고정하려는 개발자에게 가장 맞습니다. Claude Code를 쓰던 개발자라면 MCP 설정, CLAUDE.md, 스킬, 플러그인 대부분을 그대로 가져올 수 있어 옮기는 비용이 작습니다. 데모나 프로토타입을 바로 공유 링크로 내보내야 한다면 StepPage가 별도 배포 도구를 대신합니다.

반대로 Step 모델을 쓸 계획이 없다면 Step Code를 고를 이유가 약합니다. 다른 공급자를 연결할 수는 있지만, StepFun이 공개한 최적화와 벤치마크는 모두 Step 5 Preview 기준이고 같은 코어의 Pi를 직접 쓰는 선택지가 있습니다. 외부 전송 범위를 엄격하게 통제해야 하는 조직에게는, 텔레메트리 설정과 배포 바이너리 출처를 확인하기 전까지 Step Code가 적절한 선택지가 아닙니다. 프로젝트가 아직 0.1.x 버전이고 Windows PowerShell 설치는 베타라는 점도 함께 고려해야 합니다.

Step Code의 서브에이전트와 멀티 에이전트 워크플로우

Step Code는 작업을 서브에이전트에게 나눠 맡기는 기능을 기본으로 제공합니다. 서브에이전트마다 독립된 컨텍스트를 쓰고 메인 에이전트는 요약만 받습니다. StepFun이 내세우는 토큰 효율의 근거도 여기에 있습니다. 긴 작업을 서브에이전트로 쪼개면 중간 탐색 결과가 메인 대화의 컨텍스트에 쌓이지 않기 때문입니다. 내장 역할 4가지는 다음과 같습니다:

역할	맡는 일	쓸 수 있는 도구
`general`	일반 구현 작업	모든 도구
`explore`	읽기 전용 저장소 탐색	`read_file`, `find_files`, `search_files`, `list_directory`
`review`	정확성과 회귀(regression) 검토	읽기 전용 도구와 명령 실행
`planner`	조사와 구현 계획 수립	읽기 전용 도구와 명령 실행

서브에이전트는 단일, 병렬, 체인(앞 결과를 {previous}로 받아 순차 실행) 3가지 방식으로 부를 수 있고, v0.1.6에서는 서브에이전트 도구에 run_in_background 옵션이 추가되어, 결과를 기다리지 않고 작업을 맡긴 뒤 끝나면 알림을 받습니다. 백그라운드 작업은 동시에 8개까지 돌며, 10분 동안 유휴 상태이면 멈춥니다. 마크다운 파일에 이름, 설명, 도구 목록을 적어 .stepcode/agents/에 두면 직접 만든 역할도 추가할 수 있습니다.

더 큰 작업에는 Ultracode 워크플로우를 씁니다. 모델은 phase(), parallel(), pipeline(), agent() 같은 함수로 여러 에이전트의 실행 순서를 정하는 JavaScript 스크립트를 씁니다. Step Code는 이 스크립트를 네트워크와 파일 시스템 접근이 없는 샌드박스 VM에서 실행합니다. 실행 기록은 .stepcode/workflows/runs/에 남아 중간에 끊겨도 이어서 실행할 수 있습니다. 워크플로우는 사용자가 /ultracode on으로 세션 단위로 켜거나 메시지 앞에 ultracode:를 붙여야만 실행됩니다. 다만 문서에 따르면 이 동의 요건은 모델 지시문으로 강제되며, 동의 없는 호출은 실행 단계에서 막히지 않고 기록만 남습니다.

장시간 작업에는 /goal을 씁니다. 목표를 주면 Step Code가 그 목표를 달성하거나 사용자가 멈출 때까지 여러 턴을 스스로 이어 가고, 상태 표시줄에 활성 시간이 표시됩니다. /cron은 5필드 크론(cron) 표현식으로 작업을 예약합니다. 두 기능 모두 Step Code 프로세스가 계속 실행 중이어야 동작합니다.

Step Code의 StepPage 정적 웹 페이지 배포

StepPage는 로컬 디렉터리나 ZIP 파일을 StepFun의 정적 호스팅에 올려 공유 가능한 URL을 받는 기능입니다. v0.1.1부터 첫 실행 때 플러그인이 자동으로 설치되며, 내부적으로는 steppage-mcp MCP 서버를 통해 배포, 버전 목록 조회, 특정 버전 승격(promote), 롤백을 처리합니다. 사용자는 "./dist를 웹사이트로 배포하고 미리보기 링크를 만들어 줘" 처럼 자연어로 요청하면 됩니다. 정적 파일만 올릴 수 있고 백엔드나 데이터베이스는 호스팅하지 않으며, 자동 준비에는 별도로 설치된 Node.js 20 이상이 필요합니다.

아래 두 화면은 StepFun이 Step Code 페이지에 공개한 데모 영상의 일부입니다. 왼쪽은 펠리컨이 자전거를 타는 SVG를 만들어 배포한 뒤 Step Code가 출력한 결과로, 공개 URL, 미리보기 URL, 사이트 ID, 버전, 관리 링크가 표시됩니다. 오른쪽은 그 공개 URL을 브라우저로 연 화면입니다.

배포 결과는 누구나 접근할 수 있는 공개 링크이므로, StepFun 문서도 배포 전에 빌드 결과물에 키, 비공개 설정, 사용자 데이터가 섞여 있지 않은지 확인하라고 경고합니다. 호스팅 용량과 제한은 Step Plan 모델 사용량과 별도로 계정의 정적 호스팅 정책을 따릅니다.

Step Code의 컨텍스트 관리와 다른 도구 호환

Step Code는 v0.1.4에서 CLM(Context Language Models) 이라는 컨텍스트 관리 방식을 추가했습니다. 대화가 컨텍스트 한도에 가까워지면 모델이 앞부분을 선택적으로 압축하되 원본 세션 로그는 덮어쓰지 않으며, 압축에 실패하면 기존의 요약 방식으로 돌아갑니다. v0.1.6 릴리스 노트에는 프롬프트 캐시(prompt cache) 적중률을 높이는 수정도 여럿 들어 있습니다. 예를 들어 예전에는 계획 모드에 들어갈 때 도구 목록 순서가 바뀌어 대화 전체의 캐시가 무효화되었습니다. StepFun은 수정 전 측정에서 233k 토큰을 읽고 1.6k 토큰만 돌려받았다고 적었습니다.

다른 코딩 에이전트에서 옮겨 오는 경로도 준비되어 있습니다. 첫 실행 때 ~/.claude.json과 ~/.codex/config.toml의 MCP 서버 설정을 감지해 가져올지 묻고, 원본 파일은 수정하지 않습니다. .claude-plugin/plugin.json 형식의 Claude Code 플러그인과 ~/.claude/skills의 스킬을 읽으며, 기존 CLAUDE.md도 프로젝트 지침으로 그대로 씁니다. 다만 SSE와 WebSocket 방식의 MCP 서버, 각 공급자의 로그인 정보는 옮겨지지 않습니다. 실험 기능으로는 터미널 세션을 Lark에 연결해 도구 실행 승인을 메신저 카드로 처리하는 /connect lark가 있습니다.

Step Code의 권한 모드와 데이터 전송

Step Code의 권한 모드는 Ask, Approve for Me, Full Access 3가지이며 Shift+Tab으로 바꿉니다. 새 대화형 세션의 기본값은 Approve for Me로, 일상적인 작업은 묻지 않고 실행하고 위험하거나 분석할 수 없다고 판단한 명령만 확인을 받습니다. Full Access는 위험 확인을 거친 뒤 그런 명령도 바로 실행합니다. StepFun 문서는 이 규칙 검사가 임의의 스크립트를 모두 걸러내지 못하며 운영체제 수준의 샌드박스가 아니라고 명시하고, 신뢰할 수 없는 코드는 컨테이너나 가상 머신에서 실행하라고 안내합니다. 익숙하지 않은 프로젝트에서는 /permissions로 Ask 모드를 고르고 시작하는 편이 안전합니다.

텔레메트리는 따로 확인해야 합니다. Step Code의 시작 코드(apps/cli/src/main.ts) 주석에 따르면 사용자가 설정에서 끄지 않는 한 사용 보고가 켜진 상태로 시작합니다. 그런데 공개 저장소의 observability.ts는 아무 일도 하지 않는 구현(no-op)으로 채워져 있습니다. StepFun은 docs/open-source-status.md에서 비공개 관측(observability) 구현과 릴리스 배포 과정을 저장소 밖에 둔다고 밝혔습니다. 공식 설치 스크립트가 받는 바이너리는 StepFun CDN에서 내려오고 GitHub에는 릴리스나 태그가 없으므로, 설치본이 무엇을 보내는지는 공개 소스만으로 확인할 수 없습니다. 텔레메트리를 끄려면 전역 설정 파일 ~/.stepcode/config.toml에 다음을 추가합니다:

[telemetry]
enabled = false

이 설정은 텔레메트리만 끄며, 모델 요청에는 작업과 관련된 파일 내용과 도구 결과가 그대로 포함됩니다. StepFun FAQ도 로컬 에이전트라고 해서 코드가 밖으로 나가지 않는 것은 아니라고 답합니다.

Step Code 벤치마크

StepFun은 Step Code 페이지에서 같은 Step 5 Preview 모델을 Step Code와 다른 하네스들에 연결해 비교한 결과를 영상으로 공개했습니다. 영상 속 비교 표의 수치는 다음과 같으며, 행 순서는 원문을 따랐습니다:

하네스	Terminal-Bench 2.1 (89개 과제)	Multi-Frame (150개 과제)	실행(rollout)당 토큰 (Terminal-Bench, Multi-Frame)
Step Code	80.9% (72/89)	73.3% (110/150)	3.23M, 5.09M
DeepSeek Harness	80.9% (72/89)	71.3% (107/150)	3.67M, 7.46M
Codex	78.7% (70/89)	70.7% (106/150)	1.57M, 5.59M
Claude Code	77.5% (69/89)	67.3% (101/150)	3.23M, 8.48M
OpenCode	avg@8 74.9% (직접 비교 불가)	같은 과제 세트 값 없음 (다른 세트 57.0, 77.2)	입력 4.94M, 출력 0.034M
Kimi Code	74.2% (66/89)	70.7% (106/150)	2.36M, 5.60M
Z Code	71.9% (64/89)	72.7% (109/150)	1.53M, 7.90M

이 표는 StepFun이 자체적으로 정리해 공개한 값입니다. 각주에 따르면 OpenCode 행은 8회 평균(avg@8)으로 잰 외부 기준의 값이라 다른 행과 직접 비교할 수 없고, 같은 영상의 Multi-Frame 그래프에는 OpenCode가 69.3%로 따로 찍혀 있습니다. 표에는 일부 값이 추정값이라는 표시(估算值)도 있지만, 어느 칸에 해당하는지는 영상 해상도로는 확인되지 않습니다.

Multi-Frame에서 Step Code는 점수가 가장 높고 토큰 사용량이 가장 적어, StepFun이 내세운 완료율 1위와 최저 토큰 사용량 주장은 이 벤치마크에서 성립합니다. 다만 2위 Z Code와의 차이는 150개 과제 중 1개입니다. Multi-Frame이 어떤 과제로 구성되었는지는 Step Code 페이지에 설명이 없습니다.

Terminal-Bench 2.1에서는 결과가 다릅니다. Step Code는 DeepSeek Harness와 72/89로 동점이고, Codex는 과제 2개를 덜 풀었지만 토큰은 1.57M으로 Step Code(3.23M)의 절반 정도만 썼습니다. 표에는 반복 실행 횟수가 적혀 있지 않습니다. 과제 수 분모로 보아 단일 실행 기준으로 보이며, 그렇다면 과제 1~2개 차이를 하네스의 우열로 단정하기는 어렵습니다. 하네스 사이의 점수 차보다 토큰 사용량 차이가 더 크다는 점은 앞서 언급한 HarnessTax 연구의 결론과 같은 방향입니다.

StepFun의 Step 5 Preview 발표 페이지는 같은 Terminal-Bench v2.1에서 Step 5 Preview(High)가 85.0%를 기록했다고 보고했습니다. 이 값을 어떤 하네스와 몇 회 반복으로 쟀는지는 적혀 있지 않습니다. 85.0%는 89개 과제의 단일 실행으로는 나올 수 없는 값(75/89는 84.3%, 76/89는 85.4%)이고 위 표의 최고점(80.9%)보다도 높으므로, 두 페이지의 수치는 같은 조건의 값으로 비교하지 않는 편이 맞습니다.

Step Code 설치와 사용

Step Code를 쓰려면 Step Plan 계정 또는 StepFun API 키가 필요합니다. macOS, Linux, WSL에서는 다음 명령으로 설치합니다. 설치 스크립트는 최신 릴리스를 내려받아 체크섬을 확인하고, ~/.stepcode/bin에 step 실행 파일을 설치한 뒤 셸 설정에 PATH를 추가합니다:

curl -fsSL https://static-openapi.stepfun.com/stepcode/install.sh | bash

Windows PowerShell 설치는 베타이며, StepFun은 WSL에서 설치하기를 권장합니다:

irm https://static-openapi.stepfun.com/stepcode/install.ps1 | iex

설치 스크립트를 직접 읽어 보면 체크섬은 바이너리와 같은 서버의 매니페스트에서 가져오므로 전송 중 손상은 걸러내지만, 서버 자체를 검증하는 서명 검사는 아닙니다. 시스템에 sha256 도구가 없으면 경고만 내고 검증을 건너뜁니다. 검색 도구 fd와 ripgrep이 릴리스 묶음에 없으면 GitHub 릴리스에서 체크섬 검증 없이 받아 옵니다. 설치가 끝나면 새 터미널을 열고, 작업할 프로젝트 디렉터리에서 step을 실행합니다. 처음 실행하면 로그인과 테마 선택 안내가 나옵니다:

cd /path/to/your/project
step

대화형 화면에서 /login으로 Step 계정에 로그인하고 /model로 모델을 고릅니다. 구독 계정은 중국판(platform.stepfun.com)과 해외판(platform.stepfun.ai)을 구분해서 골라야 합니다. SSH나 컨테이너 안에서는 step login --no-browser로 받은 인증 링크를 다른 기기의 브라우저에서 열면 됩니다. 대화형 화면 없이 한 번만 실행하려면 -p 옵션을 씁니다:

step -p "What is the tech stack of this project? What is each directory responsible for? How do I run it locally?"

-p 실행에는 승인 대화상자가 없으므로, 스크립트나 CI에서는 --approval-mode와 --non-interactive-approval로 승인 정책을 정하고 쓸 도구를 지정합니다. 승인이 필요한 작업이 거부되면 기본값(--non-interactive-denial terminate)은 실행을 끝내고, continue는 거부 이유를 모델에게 돌려줘 다른 방법을 찾게 합니다. --completion-check git-committed는 작업이 커밋되었는지와 최종 답변이 있는지 확인합니다. 조건을 채우지 못하면 Step Code가 같은 세션에서 최대 2번(기본값) 더 작업을 이어 갑니다. 대화형으로 돌아와서는 step -c로 가장 최근 세션을 이어 가고 step -r로 지난 세션을 골라 다시 열며, /init은 프로젝트를 읽어 AGENTS.md 지침 파일을 만듭니다.

다른 공급자의 모델을 쓰려면 해당 API 키를 환경 변수로 지정하고 --provider로 고릅니다. StepFun 문서에 실린 Anthropic 예시는 다음과 같습니다:

export ANTHROPIC_API_KEY="YOUR_ANTHROPIC_API_KEY"
step --provider anthropic

로컬의 Ollama, vLLM, LM Studio 같은 OpenAI 호환 서버는 ~/.stepcode/models.json에 baseUrl, api 형식, 모델 ID를 적어 연결합니다. 인증이 없는 로컬 서버라도 apiKey에는 비어 있지 않은 자리표시 값을 넣어야 /model 목록에 나타납니다. 문서는 Ollama, vLLM, SGLang에서 compat 항목의 supportsDeveloperRole과 supportsReasoningEffort를 false로 두어야 하는 경우가 많다고 안내합니다. Step Plan 구독료는 Step Code 페이지 기준 월 결제로 Mini $6.99, Plus $9.99, Pro $29, Max $99이며, 등급마다 월 크레딧 사용량이 다릅니다.

소스에서 직접 빌드하려면 Git, Node.js, pnpm이 필요합니다. 저장소의 package.json은 Node.js 22.19.0 이상을 요구합니다:

git clone https://github.com/stepfun-ai/Step-Code.git
cd Step-Code
pnpm install --ignore-scripts
pnpm run build
pnpm step

Step Code의 라이선스

Step Code 공식 페이지 (StepFun 개발자 플랫폼)

Step Code 공식 문서

Step Code 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임에서 이런 글들을 계속 정리하고 있습니다. 회원 가입으로 주요 글들을 이메일로, 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로 새 글 알림을 받아보세요!

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~