코딩 에이전트가 파일을 일부 바꾼 뒤 멈췄다면, 가장 먼저 할 일은 재실행이 아니라 마지막으로 안전하게 끝난 단계와 이미 일어난 변경을 분리하는 일입니다. 복구의 단위는 프롬프트가 아니라 확인 가능한 단계 기록입니다. 이 글은 Smithers 0.35.0이라는 요청 맥락에서, 실패한 작업을 로컬에서 다시 이어 가기 위한 작은 워크플로를 데모로 정리합니다.
다만 공개 저장소 smithersai/flows를 2026년 9월 22일 확인했을 때 0.35.0 릴리스 노트는 찾지 못했습니다. 아래 코드는 특정 버전 API를 실행한 후기가 아니라, 공식 README가 설명하는 저널·재개·소유권 보호 개념을 바탕으로 만든 문서 기반 설계 예시입니다.
30초 요약
- 실패 로그와 작업 산출물을 먼저 보존합니다.
- 단계마다 입력 해시·출력 경로·완료 상태를 남깁니다.
- 재개할 때는 마지막 완료 단계 다음만 실행합니다.
- 같은 작업을 둘이 재개하지 않도록 잠금 소유자를 확인합니다.
Smithers가 여기서 맡는 일은 무엇일까?
공식 README에서 Smithers Flows는 Effect 기반의 typed workflow SDK이자 지속 실행 런타임으로 소개됩니다. 외부에 영향을 주는 동작을 journal에 기록하고, 끊긴 실행을 재개하는 방향이 핵심입니다.
에이전트 작업에 대입하면 모델의 답변 전체를 외우는 도구가 아니라, 파일 읽기 → 패치 생성 → 테스트 → 커밋 후보 작성처럼 되돌아볼 수 있는 경계를 만드는 도구에 가깝습니다. 택배 상자마다 송장을 붙이는 것처럼, 어느 상자가 문 앞에서 멈췄는지를 찾아 그 다음 상자만 다시 보내는 방식입니다.
README는 동시에 실행되는 상태를 fenced ownership으로 보호하고 각 단계를 content-addressed identity로 구분한다고 설명합니다. 같은 작업 ID를 잡은 프로세스가 둘이면, 복구보다 먼저 소유권 충돌을 멈춰야 합니다.
처음부터 재실행하면 왜 더 꼬일까?
실패한 에이전트 작업에는 보통 세 종류의 상태가 섞여 있습니다. 파일에는 패치가 남았지만 테스트는 돌지 않았을 수 있고, 테스트는 통과했지만 결과를 기록하는 단계가 끊겼을 수도 있습니다.
| 구간 | 재실행 중심 방식 | 단계 기록 중심 방식 |
|---|---|---|
| 실패 직후 | 전체 프롬프트를 다시 보냄 | 마지막 완료 단계와 워크트리를 확인 |
| 파일 변경 | 덮어쓸 가능성이 큼 | 기존 diff를 입력 산출물로 고정 |
| 테스트 | 중복 실행 여부가 불명확 | 테스트 명령·exit code를 단계 결과로 기록 |
| 동시 복구 | 충돌 가능성을 나중에 발견 | 소유권 잠금부터 확인 |
특히 테스트나 배포처럼 부수 효과가 있는 단계는 다시 실행할수록 비용과 혼란이 늘 수 있습니다. 재실행 범위를 줄이는 기준은 ‘모델이 기억하는 맥락’이 아니라 로컬에 남은 증거여야 합니다.
로컬 복구 폴더는 이렇게 나눠 보세요
아래 예시는 특정 Smithers API 호출이 아닙니다. 어떤 워크플로 엔진을 쓰든 적용할 수 있도록, 작업 디렉터리에 최소한의 상태 파일을 두는 구조로 적었습니다.
agent-recovery/
├── task.json # 요청, 브랜치, 시작 커밋
├── journal.ndjson # 단계별 append-only 기록
├── artifacts/ # patch, test-output, agent-response
├── lock.json # 현재 복구 소유자와 만료 시각
└── resume.ts # 다음 실행 대상을 계산하는 작은 스크립트
journal.ndjson은 한 줄이 한 사건인 append-only 로그로 두면, 중간에 프로세스가 죽어도 앞선 줄을 해석하기 쉽습니다. 완료 표시를 파일 변경보다 나중에 쓰고, 산출물 경로와 입력 해시를 함께 남기면 엉뚱한 작업을 이어 붙일 위험도 낮아집니다.
{"step":"patch","status":"completed","input":"a3f…","artifact":"artifacts/001.patch"}
{"step":"test","status":"failed","command":"pnpm test","exitCode":1,"artifact":"artifacts/002-test.txt"}
이 기록이라면 복구 프로그램의 입력은 단순합니다. patch는 이미 끝났으므로 보존하고, test의 실패 원인과 워크트리를 확인한 뒤 테스트 단계부터 새 시도로 기록합니다. 실패한 단계의 결과도 지우지 말고 새 시도 번호로 남기세요.
최소 데모: 다음 실행 대상을 계산하기
다음 TypeScript는 journal을 읽어 첫 번째 미완료 단계를 찾는 문서 기반 예시입니다. 실제 운영에서는 파일 잠금, 원자적 쓰기, 예외 처리와 실행 엔진의 재개 API를 추가해야 합니다.
type Entry = { step: string; status: "completed" | "failed" | "running" };
const order = ["inspect", "patch", "test", "review"];
function nextStep(entries: Entry[]) {
const done = new Set(entries.filter(e => e.status === "completed").map(e => e.step));
return order.find(step => !done.has(step)) ?? null;
}
console.log(nextStep([
{ step: "inspect", status: "completed" },
{ step: "patch", status: "completed" },
{ step: "test", status: "failed" }
]));
// 예상 출력: "test"
여기서 failed를 completed로 취급하지 않는 것이 포인트입니다. 실패 로그를 읽고도 같은 테스트를 다시 돌릴지, 패치를 되돌릴지, 사람 검토로 넘길지는 별도의 정책이어야 합니다.
공식 README의 ‘side effect를 journal에 기록하고 interrupted execution을 resume한다’는 설명은 이 경계와 잘 맞습니다. 다만 README만으로 Smithers가 위 파일 형식이나 이 함수의 정책을 제공한다고 말할 수는 없습니다.
Smithers를 붙이기 전의 복구 순서
git status와 diff를 별도 artifact로 저장합니다. GitHub 문서가 설명하는 브랜치·커밋 흐름은 변경을 분리해 검토하는 기본 안전망이 됩니다.- 에이전트에게 새 지시를 주기 전에 실패한 명령, exit code, 마지막 완료 step을 task 파일에 고정합니다.
- 하나의 복구 실행자만 lock을 획득하게 하고, 만료된 lock은 사람 확인 뒤에만 넘깁니다.
- 다음 step을 실행한 뒤에는 산출물 저장 → journal 완료 기록 순서를 지킵니다.
- 테스트가 다시 실패하면 전체 작업을 재생성하지 말고, 실패 artifact와 diff를 검토 큐로 보냅니다.
이 순서의 목적은 자동화량을 늘리는 것이 아니라, 실패한 한 번의 실행이 다음 시도를 오염시키지 않게 하는 데 있습니다. 에이전트가 코드를 바꾸는 속도보다, 사람이 재개 지점을 판별하는 속도가 중요할 때가 있습니다.
바이브코딩으로 확장할 때 쓸 프롬프트
작업을 다시 맡길 때는 ‘고쳐줘’보다 허용 범위를 좁히는 편이 낫습니다. 아래처럼 artifact를 입력으로 지정하면 새 에이전트가 이미 끝난 작업을 다시 만들 가능성을 낮출 수 있습니다.
현재 브랜치와 artifacts/001.patch는 변경하지 말고 읽어라.
journal.ndjson에서 completed가 아닌 첫 step만 대상으로 삼아라.
실행 전에는 예상 명령과 수정 예정 파일을 제시하고, 테스트 실패 시 새 패치를 만들지 말고
artifacts/에 실패 로그를 저장한 뒤 원인 후보 3개만 보고하라.
프롬프트도 권한 경계입니다. 재개 작업에는 ‘무엇을 할지’보다 ‘무엇을 다시 하지 않을지’를 먼저 적는 편이 안전합니다.
잘 맞는 경우와 아직 이른 경우
여러 단계가 있고 테스트·파일 생성·외부 호출처럼 재실행 비용이 다른 작업이라면, 저널 기반 복구가 특히 유용합니다. CI에서 긴 작업을 돌리거나, 사람이 검토를 끼워 넣는 에이전트 파이프라인도 후보입니다.
반대로 한 파일을 고치고 바로 끝나는 일회성 작업이라면 git diff와 테스트 명령만으로도 충분할 수 있습니다. Smithers 저장소는 현재 pre-1.0 패키지와 특정 Effect release candidate 의존성을 안내하므로, 도입 전에는 Node.js 22.19 이상 조건과 의존성 호환성을 별도 검증해야 합니다.
제품화한다면 작업 ID, artifact 보존 기간, 잠금 만료 정책, 사람 승인 지점을 먼저 정의하세요. 작업 재개 버튼 하나만 만들면 편해 보이지만, 어떤 산출물을 재사용하는지 보이지 않으면 결국 재실행 버튼과 다르지 않습니다.
작업 환경을 함께 정리한다면
로컬 복구는 여러 로그와 diff를 나란히 비교하는 일이 많습니다. 아래 카드는 실제 반환된 쿠팡 파트너스 카드만 배치하며, 특정 모델·가격·호환성은 카드에서 확인하세요.
로그·diff·테스트 출력을 옆에 두고 비교할 보조 화면이 필요할 때 고른 카드입니다. 정확한 사양과 호환 조건은 카드에서 확인하세요.
여러 창을 오가며 journal과 artifact를 검토하는 입력 도구가 필요할 때 고른 별도 역할의 카드입니다. 손 크기·연결 방식 등 개인 조건은 카드에서 확인하세요.
이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
출처
- Smithers Flows 공식 README: https://github.com/smithersai/flows
- Smithers Flows 공개 Releases 화면: https://github.com/smithersai/flows/tags
- Smithers Flows 루트 package.json: https://raw.githubusercontent.com/smithersai/flows/main/package.json
- GitHub Docs, Hello World: https://docs.github.com/en/get-started/using-github/hello-world
핵심 정리: 다섯 가지 질문과 답
Q. 실패한 에이전트 작업을 바로 재실행해도 되나요?
아니요. 먼저 마지막 완료 단계, 남은 diff, 실패 artifact를 분리해 확인하는 편이 안전합니다.
Q. 복구 로그에는 무엇을 남겨야 하나요?
단계 이름, 상태, 입력 식별값, 산출물 경로, 실행 명령과 실패 exit code가 최소 단위입니다.
Q. 실패한 단계는 로그에서 지워야 하나요?
아니요. 새 시도로 남겨 원인과 재시도 범위를 추적할 수 있게 합니다.
Q. Smithers 0.35.0의 동작을 이 글에서 검증했나요?
아니요. 공개 릴리스 근거를 확인하지 못했으므로, 공식 README의 일반 개념만 근거로 사용했습니다.
Q. 언제 워크플로 엔진 도입을 미뤄도 되나요?
부수 효과가 거의 없는 짧은 단발 작업이라면 Git diff와 테스트 기록만으로도 충분할 수 있습니다.
'AI > 오픈 소스 소개' 카테고리의 다른 글
| ConnectOnion 함수 도구 연결, 에이전트가 무엇을 했는지 기록까지 남기는 법 (0) | 2026.09.26 |
|---|---|
| Orca Git worktree 데모, 에이전트 답이 섞일 때 비교부터 분리하는 법 (0) | 2026.09.25 |
| VeloxQuant-MLX로 긴 대화를 붙잡을 때, 압축률보다 먼저 볼 것 (0) | 2026.09.21 |
| SandBase Harness, 도구 실행이 멈췄을 때 승인 흐름을 확인하는 법 (0) | 2026.09.20 |
| Obsidian 노트 검색 AI, 하루 MVP는 어디까지 만들까 (0) | 2026.09.14 |
댓글