용어집
《상태 관리와 지속화: 긴 작업이 중단을 견디게 만들기》의 용어 60개. 레슨 본문에서 처음 등장하는 용어에 마우스를 올리면 정의를 볼 수 있습니다.
| 용어 | 정의 | 출처 |
|---|---|---|
| 메모리 | 모델에게 주는 컨텍스트. '모델은 무엇을 보았는가?'에 답하며, `NOTES.md`처럼 이미 디스크에 쓰여 있을 수도 있고 아직 프로세스 메모리에만 있을 수도 있다. | How we built our multi-agent research system — Anthropic Engineering |
| 실행 상태 | 하네스 프로세스 자신이 붙들고 있는 실행 중인 장면. `messages` 배열, 턴과 사용량 카운터, 아직 기록되지 않은 도구 호출이며, 기본적으로 프로세스 메모리에만 살다가 프로세스가 끝나는 순간 회수된다. | How we built our multi-agent research system — Anthropic Engineering |
| messages | 하네스가 메모리에 붙들고 있는 완전한 대화 이력 배열. 모델에게 컨텍스트를 복원할 유일한 출처이자 체크포인트에서 가장 큰 덩어리다. | How we built our multi-agent research system — Anthropic Engineering |
| turns | 이미 몇 턴을 돌았는지 세는 카운터. 최대 턴 상한 같은 정지 조건을 판단하는 데 쓰이며, 재개할 때는 0부터 다시 세지 않고 체크포인트의 값에서 이어 가야 한다. | How we built our multi-agent research system — Anthropic Engineering |
| tokensUsed | 누적 토큰 사용량 카운터. 재개할 때는 다시 추정하지 않고 체크포인트에서 그대로 이어받아, 컨텍스트 압축 임계값 판단이 계속 맞물리게 한다. | How we built our multi-agent research system — Anthropic Engineering |
| pendingToolUse | 허공에 뜬 도구 호출(모델이 지명했지만 결과가 아직 기록되지 않은 것)을 표시하는 체크포인트 필드. `null`이거나 `{ id, name, input }` 모양의 기록이다. | How we built our multi-agent research system — Anthropic Engineering |
| 허공에 뜬 호출 | 모델이 지명했지만 그 결과가 `messages`에 밀려 들어가기 전에 프로세스가 죽어, 짝이 되는 `tool_result`가 없는 채로 남은 `tool_use` 블록. | How we built our multi-agent research system — Anthropic Engineering |
| 체크포인트 | 실행 상태(`messages`, `turns`, `tokensUsed`, `pendingToolUse`)를 디스크에 직렬화해 크래시 뒤에도 프로세스가 이어 갈 수 있게 하는 것. 모델의 적응력과 짝지어지는 결정론적 안전장치 중 하나다. | How we built our multi-agent research system — Anthropic Engineering |
| checkpoint.json | `version`, `task`, `turns`, `tokensUsed`, `messages`, `pendingToolUse`를 담는 체크포인트 파일. 실행 장면의 완전한 스냅숏이다. | How we built our multi-agent research system — Anthropic Engineering |
| version | `checkpoint.json`의 프로토콜 버전 번호. `loadCheckpoint`가 포맷을 알아보는지 먼저 확인하고, 맞지 않는 버전은 로드를 거부할 수 있게 해 준다. | How we built our multi-agent research system — Anthropic Engineering |
| task | 사용자의 원래 작업을 말로 적어 `checkpoint.json`에 담아 두는 필드. 다시 띄운 하네스가 이 장면이 어느 작업의 것인지 알고 진척을 보고할 수 있게 한다. | How we built our multi-agent research system — Anthropic Engineering |
| saveCheckpoint | 현재 상태를 디스크에 쓰는 함수. 올바른 구현은 임시 파일에 먼저 쓰고 원자적으로 이름을 바꿔, 반쯤 쓰인 파일이 남지 않게 한다. | How we built our multi-agent research system — Anthropic Engineering |
| 저장 지점 A | 한 턴 안의 첫 번째 체크포인트. 모델이 도구를 지명한 뒤 그 도구가 실행되기 전에 쓰며, 이번 턴의 `tool_use` 블록을 `pendingToolUse`에 기록한다. | How we built our multi-agent research system — Anthropic Engineering |
| 저장 지점 B | 한 턴 안의 두 번째 체크포인트. 도구 결과가 `messages`에 밀려 들어간 뒤에 쓰며, `pendingToolUse`를 다시 `null`로 지운다. | How we built our multi-agent research system — Anthropic Engineering |
| 임시 파일 | 원자적 체크포인트 쓰기에서 먼저 쓰는 중간 파일(`checkpoint.json.tmp` 같은 것). 온전히 다 쓰인 뒤에야 이름을 바꿔 진짜 파일 자리에 얹는다. | How we built our multi-agent research system — Anthropic Engineering |
| fs.renameSync | 같은 파일 시스템 안에서의 원자적 이름 바꾸기. 디렉터리 엔트리는 새 파일을 통째로 가리키거나 옛 파일을 가리킨 채로 남을 뿐, 반쯤 이름이 바뀐 중간 상태는 존재하지 않는다. | How we built our multi-agent research system — Anthropic Engineering |
| 제자리 덮어쓰기 | `fs.writeFileSync`로 체크포인트 파일 위에 곧장 쓰는 방식. 원자적이지 않아서 쓰기 도중에 프로세스가 죽으면 잘려 나간 JSON이 남을 수 있다. | How we built our multi-agent research system — Anthropic Engineering |
| 재개 | 크래시 뒤 체크포인트에서 루프를 다시 일으키는 것. 상태를 읽어 내고 `messages`를 다시 세워, 1턴째부터 다시 시작하는 대신 에러가 난 자리에서 이어 간다. | How we built our multi-agent research system — Anthropic Engineering |
| loadCheckpoint | 체크포인트 파일을 읽고 파싱하는 함수. `version` 필드를 검사하고, 버전이 맞지 않거나 파싱에 실패하면 조용히 빈 상태로 되돌아가는 대신 큰 소리로 던져야 한다. | How we built our multi-agent research system — Anthropic Engineering |
| reconcile | 재개 시 허공에 뜬 `pendingToolUse`를 처리하는 함수. 도구의 성질(읽기 전용인가 영향이 큰가)과 원장의 상태를 보고 다시 실행할지, 저장된 결과를 재사용할지, `is_error`를 돌려줄지 정한다. | Handle tool calls — Claude API |
| READ_ONLY_TOOLS | 부수 효과가 없다고 판정한 도구 이름의 집합(`read_file`, `grep`, `list_dir`, `web_search`). 재개 시 `reconcile`은 이 집합에 든 도구만 마음 놓고 다시 실행한다. | Handle tool calls — Claude API |
| 읽기 전용 도구 | 부수 효과가 0인 도구(파일 읽기, 검색 같은 것). 몇 번을 다시 실행해도 바깥 세계가 그대로이므로 안전하다. | Handle tool calls — Claude API |
| 영향이 큰 도구 | 바깥 상태를 바꾸는 도구(`send_email`, `create_ticket`, `delete_file`). 중복된 부수 효과를 피하려면 다시 실행하기 전에 이미 실행되었는지부터 확인해야 한다. | Handle tool calls — Claude API |
| is_error | `tool_result`의 선택적 필드. `true`로 두면 도구 실행이 실패했거나 상태를 알 수 없다는 뜻이 되어, 모델이 성공을 전제하는 대신 사실을 알고 다시 판단하게 된다. | Handle tool calls — Claude API |
| tool_result | 각 `tool_use`에 대해 모델에게 돌려주는 콘텐츠 블록. 프로토콜은 모든 `tool_use`가 짝이 되는 `tool_result`를 갖고, `tool_use_id`로 짝을 밝히며, 다음 `user` 메시지에 함께 모여 돌아올 것을 요구한다. | Handle tool calls — Claude API |
| tool_use | 모델 응답 안에서 부를 도구를 지명하는 콘텐츠 블록. `id`, `name`, `input` 필드를 담는다. 프로세스가 죽으면 짝이 되는 `tool_result` 없이 허공에 뜬 `tool_use`가 남는다. | Handle tool calls — Claude API |
| 멱등 | 한 번을 돌리든 여러 번을 돌리든 같은 최종 효과를 내는 조작. 판정 기준은 돌려주는 값이 아니라 효과, 곧 바깥 세계에 남는 최종 상태다. | How we built our multi-agent research system — Anthropic Engineering |
| 부수 효과 원장 | 어떤 부수 효과가 실제로 일어났는지를 `tool_use_id`를 키로 삼아 체크포인트와 별도로 디스크에 적어 두는 기록. 도구가 성공한 그 순간에 쓰며, 재개가 '돌았다'와 '돌지 않았다'를 가릴 수 있게 한다. | How we built our multi-agent research system — Anthropic Engineering |
| effects.json | 부수 효과 원장 파일. `tool_use_id`를 키로 도구 이름과 결과와 시각을 기록하며, 도구가 성공한 즉시, 저장 지점 B보다 한 박자 먼저 쓴다. | How we built our multi-agent research system — Anthropic Engineering |
| tool_use_id | 모델이 각 `tool_use` 블록에 붙이는 고유 식별자. 재개 시 리플레이되어도 바뀌지 않으므로 부수 효과 원장의 자연스러운 멱등 키가 된다. | Handle tool calls — Claude API |
| at-least-once | 체크포인트 기반 재개가 본성상 안겨 주는 실행 시맨틱, 곧 최소 1회. 도구가 끝난 뒤 결과가 기록되기 전에 크래시가 날 수 있어 '돌지 않았다'와 '돌았지만 기록되지 않았다'를 가릴 수 없다. | How we built our multi-agent research system — Anthropic Engineering |
| loadEffects | 부수 효과 원장을 읽는 함수. 파일이 없거나 파싱에 실패하면 재개를 막는 대신 '아직 기록이 없다'로 보고 빈 객체를 돌려준다. | How we built our multi-agent research system — Anthropic Engineering |
| saveEffect | 부수 효과 원장을 디스크에 되쓰는 함수(레슨 4에서는 `saveEffects`라는 이름으로 같은 일을 한다). 임시 파일에 쓰고 이름을 바꾸는 원자적 쓰기를 쓰며, 도구 실행이 성공해 진짜 결과를 손에 쥔 뒤에만 불러야 한다. | How we built our multi-agent research system — Anthropic Engineering |
| 승인 게이트 | 영향이 큰 도구를 실행하기 전에 사람의 확인을 받는 검사. '이것을 해야 하는가'를 묻는 것이며, 부수 효과 원장이 묻는 '이것을 이미 했는가'와는 다르다. | How we built our multi-agent research system — Anthropic Engineering |
| ensureTicket | '생성'을 '있는지 보장'으로 바꿔 쓴 예. 제목으로 먼저 조회해 이미 있으면 그것을 돌려주고 없을 때만 만들므로 설계상 멱등하다. | How we built our multi-agent research system — Anthropic Engineering |
| 덧붙이기 방식의 쓰기 | 누적적인 쓰기 방식(`array.push`, 로그 파일에 한 줄 덧붙이기 같은 것). 부를 때마다 바깥 세계에 항목이 진짜로 하나씩 늘어나 최종 상태가 호출 횟수를 그대로 드러내므로 대체로 멱등하지 않다. | How we built our multi-agent research system — Anthropic Engineering |
| 덮어쓰기 방식의 쓰기 | 대체하는 쓰기 방식(어떤 줄을 정해진 값으로 지정하기, 파일 전체를 쓰는 `write_file` 같은 것). 한 번을 부르든 열 번을 부르든 같은 최종 상태로 끝나므로 대체로 멱등하다. | How we built our multi-agent research system — Anthropic Engineering |
| runToolUses | 한 턴의 `tool_use` 블록들을 실행하는 함수. 부수 효과 원장과 승인 게이트를 얹으면 '원장 확인 → 승인 → 실행 → 원장 기록'의 순서가 된다. | How we built our multi-agent research system — Anthropic Engineering |
| 되감기 | 크래시가 아니라 작업이 경로를 벗어났을 때, 판단 장면을 앞선 턴으로 되돌려 거기서 다시 시작하는 것. 되돌리는 것은 체크포인트이지 이미 내려앉은 외부 부수 효과가 아니다. | Checkpointing — Claude Code Docs |
| 분기 | 같은 체크포인트에서 독립적인 타임라인 둘을 떠내어 서로 다른 경로를 탐색하는 것. 각 타임라인은 자기만의 체크포인트 연속과 텅 빈 부수 효과 원장을 갖는다. | Checkpointing — Claude Code Docs |
| rewindTo | 턴별로 보존된 연속에서 특정 턴의 체크포인트를 집어 오는 함수. 기본값은 그 턴에서 마지막으로 쓰인 저장 지점이다. | Checkpointing — Claude Code Docs |
| forkFrom | 특정 턴의 체크포인트에서 독립적인 타임라인을 떠내는 함수. 새 타임라인은 자기만의 체크포인트 연속과 텅 빈 부수 효과 원장을 갖고 본선과 격리된다. | Checkpointing — Claude Code Docs |
| turn-014-A.json | 턴별 체크포인트 연속의 파일 이름 예. 턴 번호와 저장 지점 글자를 이름에 담아 어느 턴의 어느 순간인지 정확히 가려낸다. | Checkpointing — Claude Code Docs |
| pickLatestPoint | 한 턴에서 마지막으로 쓰인 저장 지점을 찾는 함수. A와 B의 사전순 정렬이 '도구 실행 전 → 도구 결과 기록 후'라는 시간 순서와 그대로 맞아떨어지는 데 기댄다. | Checkpointing — Claude Code Docs |
| 판단 장면 | 체크포인트가 실제로 되돌리는 것. `messages`, `turns`, `pendingToolUse`를 비롯해 스냅숏에 정의해 넣은 필드들이며, 이미 내려앉은 바깥 세계의 행동은 여기 들어가지 않는다. | Checkpointing — Claude Code Docs |
| 드라이런 모드 | 분기하는 동안 외부 행동을 실제로 실행하지 않는 모드. 두 타임라인이 같은 영향이 큰 도구를 건드려 부수 효과가 두 배가 되는 것을 막는다. | How we built our multi-agent research system — Anthropic Engineering |
| 체크포인트 연속 | 가장 최근 것 하나만 남기고 덮어쓰는 대신 턴별로 보존하는 체크포인트 파일의 줄. 되감기와 분기의 전제 조건이며, 갈라 낸 타임라인은 각자 독립된 사본을 갖는다. | Checkpointing — Claude Code Docs |
| Git | 코드의 영구적이고 협업적인 이력을 관리하는 버전 관리 시스템. 분 단위 세션 복구를 맡는 체크포인트, 외부 부수 효과를 맡는 부수 효과 원장과는 맡은 구간이 다르다. | Checkpointing — Claude Code Docs |
| CRASH_AFTER | 모의 크래시가 일어날 시점을 통제하는 환경 변수(`CRASH_AFTER=after-effect-write:3`이면 세 번째 원장 쓰기 뒤에 크래시가 난다). | How we built our multi-agent research system — Anthropic Engineering |
| SimulatedCrash | 프로세스 킬을 흉내 내기 위한 전용 예외 타입. `main()`이 이것만 잡아 로그 한 줄을 찍고 종료 코드 137로 빠져나가므로, 시연이 스택 트레이스가 아니라 진짜 킬처럼 읽힌다. | How we built our multi-agent research system — Anthropic Engineering |
| crashPoint | 환경 변수로 통제되는 모의 크래시 발동 함수. 현재 조작의 레이블을 `CRASH_AFTER`와 견주어 일치하면 `SimulatedCrash`를 던진다. | How we built our multi-agent research system — Anthropic Engineering |
| --resume | 이번 실행이 `loadCheckpoint`를 거쳐 복구 경로를 타야 한다는 것을 알리는 명령줄 플래그. 이것이 없으면 `main()`이 지난번 체크포인트와 원장 파일을 명시적으로 치운다. | How we built our multi-agent research system — Anthropic Engineering |
| 응답 큐 | 진짜 모델 클라이언트를 대신하는 검증용 스텁. 미리 써 둔 응답을 정해진 순서대로 건네 작업 실행을 결정적으로 만들고 크래시 타이밍을 되풀이 가능하게 한다. | How we built our multi-agent research system — Anthropic Engineering |
| makeStubClient | 응답 큐로부터 스텁 모델 클라이언트를 지어 내는 팩토리 함수. 검증에서 진짜 `client.messages.create` 호출을 대신한다. | How we built our multi-agent research system — Anthropic Engineering |
| main() | 프로그램 진입 함수. `--resume`이 있는지 하나만 판단해 복구 경로와 새로 시작하는 경로로 갈라 보내고, `SimulatedCrash`를 한자리에서 잡아 로그를 찍고 빠져나간다. | How we built our multi-agent research system — Anthropic Engineering |
| 세 갈래 | 허공에 뜬 호출을 가르는 `reconcile`의 세 분기. 원장 히트(결과 재사용), 원장 미스 + 읽기 전용(그대로 재실행), 원장 미스 + 부수 효과 있음(모델에게 `is_error`). | Handle tool calls — Claude API |
| 실행이 먼저, 기록이 나중 | 부수 효과 원장의 규율. 도구의 진짜 실행 결과를 손에 쥔 뒤에야 원장에 쓸 수 있으며, 순서를 뒤집으면 돌지도 않은 것에 '이미 끝났음'을 기록하게 된다. | How we built our multi-agent research system — Anthropic Engineering |
| 137 | `SIGKILL`로 죽임을 당한 프로세스의 관례적인 종료 코드. 검증 시연은 이것으로 빠져나가 모의 크래시가 예외가 아니라 진짜 킬처럼 읽히게 한다. | How we built our multi-agent research system — Anthropic Engineering |
| 검증 하네스 | 고정된 응답 큐와 통제된 크래시 지점으로 비결정적인 것들(모델 응답, 크래시 타이밍)을 먼저 고정해, 복구 동작을 한 줄씩 단언할 수 있게 하는 검증 방법. | How we built our multi-agent research system — Anthropic Engineering |
| 균형 감각 | 복잡도가 결과를 눈에 띄게 개선함이 증명될 때에만 체크포인트 장치를 더한다는 원칙. 짧은 작업마다 온전한 체크포인팅이 필요한 것은 아니다. | Building Effective AI Agents — Anthropic Engineering |