체크포인팅으로 파일 변경 사항 되돌리기

에이전트 세션 중 파일 변경 사항을 추적하고 파일을 이전의 모든 상태로 복원합니다

파일 체크포인팅은 에이전트 세션 중 Write, Edit, NotebookEdit 도구를 통해 수행된 파일 수정 사항을 추적하여 파일을 이전의 모든 상태로 되돌릴 수 있게 합니다. 직접 시도해보고 싶으신가요? 대화형 예제로 이동하세요.

체크포인팅을 사용하면 다음을 수행할 수 있습니다:

원치 않는 변경 사항 실행 취소 - 파일을 알려진 양호한 상태로 복원
대안 탐색 - 체크포인트로 복원한 후 다른 접근 방식 시도
오류 복구 - 에이전트가 잘못된 수정을 수행했을 때

체크포인팅 작동 방식

파일 체크포인팅을 활성화하면 SDK는 Write, Edit 또는 NotebookEdit 도구를 통해 파일을 수정하기 전에 파일의 백업을 생성합니다. 응답 스트림의 사용자 메시지에는 복원 지점으로 사용할 수 있는 체크포인트 UUID가 포함됩니다.

체크포인트는 에이전트가 파일을 수정하는 데 사용하는 다음의 기본 제공 도구와 함께 작동합니다:

도구	설명
Write	새 파일을 생성하거나 기존 파일을 새 콘텐츠로 덮어씁니다
Edit	기존 파일의 특정 부분에 대한 대상 편집을 수행합니다
NotebookEdit	Jupyter 노트북(`.ipynb` 파일)의 셀을 수정합니다

체크포인트 시스템은 다음을 추적합니다:

세션 중에 생성된 파일
세션 중에 수정된 파일
수정된 파일의 원본 콘텐츠

체크포인트로 되돌리면 생성된 파일은 삭제되고 수정된 파일은 해당 시점의 콘텐츠로 복원됩니다.

체크포인팅 구현

파일 체크포인팅을 사용하려면 옵션에서 활성화하고, 응답 스트림에서 체크포인트 UUID를 캡처한 다음, 복원이 필요할 때 rewindFiles()(TypeScript) 또는 rewind_files()(Python)를 호출합니다.

다음 예제는 전체 흐름을 보여줍니다: 체크포인팅을 활성화하고, 응답 스트림에서 체크포인트 UUID와 세션 ID를 캡처한 다음, 나중에 세션을 재개하여 파일을 되돌립니다. 각 단계는 아래에서 자세히 설명됩니다.

import asyncio
from claude_agent_sdk import (
ClaudeSDKClient,
ClaudeAgentOptions,
UserMessage,
ResultMessage,
)


async def main():
# Step 1: Enable checkpointing
options = ClaudeAgentOptions(
enable_file_checkpointing=True,
permission_mode="acceptEdits",  # Auto-accept file edits without prompting
extra_args={
"replay-user-messages": None
},  # Required to receive checkpoint UUIDs in the response stream
)

checkpoint_id = None
session_id = None

# Run the query and capture checkpoint UUID and session ID
async with ClaudeSDKClient(options) as client:
await client.query("Refactor the authentication module")

# Step 2: Capture checkpoint UUID from the first user message
async for message in client.receive_response():
if isinstance(message, UserMessage) and message.uuid and not checkpoint_id:
checkpoint_id = message.uuid
if isinstance(message, ResultMessage) and not session_id:
session_id = message.session_id

# Step 3: Later, rewind by resuming the session with an empty prompt
if checkpoint_id and session_id:
async with ClaudeSDKClient(
ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)
) as client:
await client.query("")  # Empty prompt to open the connection
async for message in client.receive_response():
await client.rewind_files(checkpoint_id)
break
print(f"Rewound to checkpoint: {checkpoint_id}")


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
// Step 1: Enable checkpointing
const opts = {
enableFileCheckpointing: true,
permissionMode: "acceptEdits" as const, // Auto-accept file edits without prompting
extraArgs: { "replay-user-messages": null } // Required to receive checkpoint UUIDs in the response stream
};

const response = query({
prompt: "Refactor the authentication module",
options: opts
});

let checkpointId: string | undefined;
let sessionId: string | undefined;

// Step 2: Capture checkpoint UUID from the first user message
for await (const message of response) {
if (message.type === "user" && message.uuid && !checkpointId) {
checkpointId = message.uuid;
}
if ("session_id" in message && !sessionId) {
sessionId = message.session_id;
}
}

// Step 3: Later, rewind by resuming the session with an empty prompt
if (checkpointId && sessionId) {
const rewindQuery = query({
prompt: "", // Empty prompt to open the connection
options: { ...opts, resume: sessionId }
});

for await (const msg of rewindQuery) {
await rewindQuery.rewindFiles(checkpointId);
break;
}
console.log(`Rewound to checkpoint: ${checkpointId}`);
}
}

main();

체크포인팅 활성화

체크포인팅을 활성화하고 체크포인트 UUID를 수신하도록 SDK 옵션을 구성합니다:

옵션	Python	TypeScript	설명
체크포인팅 활성화	`enable_file_checkpointing=True`	`enableFileCheckpointing: true`	되돌리기 위해 파일 변경 사항을 추적합니다
체크포인트 UUID 수신	`extra_args={"replay-user-messages": None}`	`extraArgs: { 'replay-user-messages': null }`	스트림에서 사용자 메시지 UUID를 가져오는 데 필요합니다

options = ClaudeAgentOptions(
enable_file_checkpointing=True,
permission_mode="acceptEdits",
extra_args={"replay-user-messages": None},
)

async with ClaudeSDKClient(options) as client:
await client.query("Refactor the authentication module")

const response = query({
prompt: "Refactor the authentication module",
options: {
enableFileCheckpointing: true,
permissionMode: "acceptEdits" as const,
extraArgs: { "replay-user-messages": null }
}
});

체크포인트 UUID 및 세션 ID 캡처

replay-user-messages 옵션이 설정되면(위에 표시됨), 응답 스트림의 각 사용자 메시지에는 체크포인트로 사용되는 UUID가 있습니다.

대부분의 사용 사례에서 첫 번째 사용자 메시지 UUID(message.uuid)를 캡처합니다. 이로 되돌리면 모든 파일이 원본 상태로 복원됩니다. 여러 체크포인트를 저장하고 중간 상태로 되돌리려면 여러 복원 지점을 참조하세요.

세션 ID(message.session_id)를 캡처하는 것은 선택 사항입니다. 스트림이 완료된 후 나중에 되돌리려는 경우에만 필요합니다. 체크포인트 전에 위험한 작업 예제처럼 메시지를 처리하는 동안 rewindFiles()를 즉시 호출하는 경우 세션 ID 캡처를 건너뛸 수 있습니다.

checkpoint_id = None
session_id = None

async for message in client.receive_response():
# Update checkpoint on each user message (keeps the latest)
if isinstance(message, UserMessage) and message.uuid:
checkpoint_id = message.uuid
# Capture session ID from the result message
if isinstance(message, ResultMessage):
session_id = message.session_id

let checkpointId: string | undefined;
let sessionId: string | undefined;

for await (const message of response) {
// Update checkpoint on each user message (keeps the latest)
if (message.type === "user" && message.uuid) {
checkpointId = message.uuid;
}
// Capture session ID from any message that has it
if ("session_id" in message) {
sessionId = message.session_id;
}
}

파일 되돌리기

스트림이 완료된 후 되돌리려면 빈 프롬프트로 세션을 재개하고 체크포인트 UUID와 함께 rewind_files()(Python) 또는 rewindFiles()(TypeScript)를 호출합니다. 스트림 중에도 되돌릴 수 있습니다. 체크포인트 전에 위험한 작업에서 해당 패턴을 참조하세요.

async with ClaudeSDKClient(
ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)
) as client:
await client.query("")  # Empty prompt to open the connection
async for message in client.receive_response():
await client.rewind_files(checkpoint_id)
break

const rewindQuery = query({
prompt: "", // Empty prompt to open the connection
options: { ...opts, resume: sessionId }
});

for await (const msg of rewindQuery) {
await rewindQuery.rewindFiles(checkpointId);
break;
}

세션 ID와 체크포인트 ID를 캡처한 경우 CLI에서도 되돌릴 수 있습니다:

claude -p --resume <session-id> --rewind-files <checkpoint-uuid>

일반적인 패턴

이러한 패턴은 사용 사례에 따라 체크포인트 UUID를 캡처하고 사용하는 다양한 방법을 보여줍니다.

위험한 작업 전에 체크포인트

이 패턴은 가장 최근의 체크포인트 UUID만 유지하며, 각 에이전트 턴 전에 업데이트합니다. 처리 중에 문제가 발생하면 마지막 안전한 상태로 즉시 되돌리고 루프를 벗어날 수 있습니다.

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage


async def main():
options = ClaudeAgentOptions(
enable_file_checkpointing=True,
permission_mode="acceptEdits",
extra_args={"replay-user-messages": None},
)

safe_checkpoint = None

async with ClaudeSDKClient(options) as client:
await client.query("Refactor the authentication module")

async for message in client.receive_response():
# Update checkpoint before each agent turn starts
# This overwrites the previous checkpoint. Only keep the latest
if isinstance(message, UserMessage) and message.uuid:
safe_checkpoint = message.uuid

# Decide when to revert based on your own logic
# For example: error detection, validation failure, or user input
if your_revert_condition and safe_checkpoint:
await client.rewind_files(safe_checkpoint)
# Exit the loop after rewinding, files are restored
break


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
const response = query({
prompt: "Refactor the authentication module",
options: {
enableFileCheckpointing: true,
permissionMode: "acceptEdits" as const,
extraArgs: { "replay-user-messages": null }
}
});

let safeCheckpoint: string | undefined;

for await (const message of response) {
// Update checkpoint before each agent turn starts
// This overwrites the previous checkpoint. Only keep the latest
if (message.type === "user" && message.uuid) {
safeCheckpoint = message.uuid;
}

// Decide when to revert based on your own logic
// For example: error detection, validation failure, or user input
if (yourRevertCondition && safeCheckpoint) {
await response.rewindFiles(safeCheckpoint);
// Exit the loop after rewinding, files are restored
break;
}
}
}

main();

여러 복원 지점

Claude가 여러 턴에 걸쳐 변경을 수행하는 경우, 모든 방식으로 되돌리기보다는 특정 지점으로 되돌리고 싶을 수 있습니다. 예를 들어, Claude가 첫 번째 턴에서 파일을 리팩토링하고 두 번째 턴에서 테스트를 추가하는 경우, 리팩토링은 유지하되 테스트는 실행 취소하고 싶을 수 있습니다.

이 패턴은 모든 체크포인트 UUID를 메타데이터와 함께 배열에 저장합니다. 세션이 완료된 후 이전의 모든 체크포인트로 되돌릴 수 있습니다:

import asyncio
from dataclasses import dataclass
from datetime import datetime
from claude_agent_sdk import (
ClaudeSDKClient,
ClaudeAgentOptions,
UserMessage,
ResultMessage,
)


# Store checkpoint metadata for better tracking
@dataclass
class Checkpoint:
id: str
description: str
timestamp: datetime


async def main():
options = ClaudeAgentOptions(
enable_file_checkpointing=True,
permission_mode="acceptEdits",
extra_args={"replay-user-messages": None},
)

checkpoints = []
session_id = None

async with ClaudeSDKClient(options) as client:
await client.query("Refactor the authentication module")

async for message in client.receive_response():
if isinstance(message, UserMessage) and message.uuid:
checkpoints.append(
Checkpoint(
id=message.uuid,
description=f"After turn {len(checkpoints) + 1}",
timestamp=datetime.now(),
)
)
if isinstance(message, ResultMessage) and not session_id:
session_id = message.session_id

# Later: rewind to any checkpoint by resuming the session
if checkpoints and session_id:
target = checkpoints[0]  # Pick any checkpoint
async with ClaudeSDKClient(
ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)
) as client:
await client.query("")  # Empty prompt to open the connection
async for message in client.receive_response():
await client.rewind_files(target.id)
break
print(f"Rewound to: {target.description}")


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

// Store checkpoint metadata for better tracking
interface Checkpoint {
id: string;
description: string;
timestamp: Date;
}

async function main() {
const opts = {
enableFileCheckpointing: true,
permissionMode: "acceptEdits" as const,
extraArgs: { "replay-user-messages": null }
};

const response = query({
prompt: "Refactor the authentication module",
options: opts
});

const checkpoints: Checkpoint[] = [];
let sessionId: string | undefined;

for await (const message of response) {
if (message.type === "user" && message.uuid) {
checkpoints.push({
id: message.uuid,
description: `After turn ${checkpoints.length + 1}`,
timestamp: new Date()
});
}
if ("session_id" in message && !sessionId) {
sessionId = message.session_id;
}
}

// Later: rewind to any checkpoint by resuming the session
if (checkpoints.length > 0 && sessionId) {
const target = checkpoints[0]; // Pick any checkpoint
const rewindQuery = query({
prompt: "", // Empty prompt to open the connection
options: { ...opts, resume: sessionId }
});

for await (const msg of rewindQuery) {
await rewindQuery.rewindFiles(target.id);
break;
}
console.log(`Rewound to: ${target.description}`);
}
}

main();

직접 시도해보기

이 완전한 예제는 작은 유틸리티 파일을 생성하고, 에이전트가 문서 주석을 추가하도록 하며, 변경 사항을 표시한 다음, 되돌리고 싶은지 묻습니다.

시작하기 전에 Claude Agent SDK가 설치되어 있는지 확인하세요.

테스트 파일 생성

utils.py(Python) 또는 utils.ts(TypeScript)라는 새 파일을 생성하고 다음 코드를 붙여넣습니다:

def add(a, b):
return a + b


def subtract(a, b):
return a - b


def multiply(a, b):
return a * b


def divide(a, b):
if b == 0:
raise ValueError("Cannot divide by zero")
return a / b

export function add(a: number, b: number): number {
return a + b;
}

export function subtract(a: number, b: number): number {
return a - b;
}

export function multiply(a: number, b: number): number {
return a * b;
}

export function divide(a: number, b: number): number {
if (b === 0) {
throw new Error("Cannot divide by zero");
}
return a / b;
}

대화형 예제 실행

유틸리티 파일과 같은 디렉토리에 try_checkpointing.py(Python) 또는 try_checkpointing.ts(TypeScript)라는 새 파일을 생성하고 다음 코드를 붙여넣습니다.

이 스크립트는 Claude에게 유틸리티 파일에 문서 주석을 추가하도록 요청한 다음 원본을 복원하기 위해 되돌리고 싶은지 선택할 수 있는 옵션을 제공합니다.

import asyncio
from claude_agent_sdk import (
ClaudeSDKClient,
ClaudeAgentOptions,
UserMessage,
ResultMessage,
)


async def main():
# Configure the SDK with checkpointing enabled
# - enable_file_checkpointing: Track file changes for rewinding
# - permission_mode: Auto-accept file edits without prompting
# - extra_args: Required to receive user message UUIDs in the stream
options = ClaudeAgentOptions(
enable_file_checkpointing=True,
permission_mode="acceptEdits",
extra_args={"replay-user-messages": None},
)

checkpoint_id = None  # Store the user message UUID for rewinding
session_id = None  # Store the session ID for resuming

print("Running agent to add doc comments to utils.py...\n")

# Run the agent and capture checkpoint data from the response stream
async with ClaudeSDKClient(options) as client:
await client.query("Add doc comments to utils.py")

async for message in client.receive_response():
# Capture the first user message UUID - this is our restore point
if isinstance(message, UserMessage) and message.uuid and not checkpoint_id:
checkpoint_id = message.uuid
# Capture the session ID so we can resume later
if isinstance(message, ResultMessage):
session_id = message.session_id

print("Done! Open utils.py to see the added doc comments.\n")

# Ask the user if they want to rewind the changes
if checkpoint_id and session_id:
response = input("Rewind to remove the doc comments? (y/n): ")

if response.lower() == "y":
# Resume the session with an empty prompt, then rewind
async with ClaudeSDKClient(
ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)
) as client:
await client.query("")  # Empty prompt opens the connection
async for message in client.receive_response():
await client.rewind_files(checkpoint_id)  # Restore files
break

print(
"\n✓ File restored! Open utils.py to verify the doc comments are gone."
)
else:
print("\nKept the modified file.")


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";
import * as readline from "readline";

async function main() {
// Configure the SDK with checkpointing enabled
// - enableFileCheckpointing: Track file changes for rewinding
// - permissionMode: Auto-accept file edits without prompting
// - extraArgs: Required to receive user message UUIDs in the stream
const opts = {
enableFileCheckpointing: true,
permissionMode: "acceptEdits" as const,
extraArgs: { "replay-user-messages": null }
};

let sessionId: string | undefined; // Store the session ID for resuming
let checkpointId: string | undefined; // Store the user message UUID for rewinding

console.log("Running agent to add doc comments to utils.ts...\n");

// Run the agent and capture checkpoint data from the response stream
const response = query({
prompt: "Add doc comments to utils.ts",
options: opts
});

for await (const message of response) {
// Capture the first user message UUID - this is our restore point
if (message.type === "user" && message.uuid && !checkpointId) {
checkpointId = message.uuid;
}
// Capture the session ID so we can resume later
if ("session_id" in message) {
sessionId = message.session_id;
}
}

console.log("Done! Open utils.ts to see the added doc comments.\n");

// Ask the user if they want to rewind the changes
if (checkpointId && sessionId) {
const rl = readline.createInterface({
input: process.stdin,
output: process.stdout
});

const answer = await new Promise<string>((resolve) => {
rl.question("Rewind to remove the doc comments? (y/n): ", resolve);
});
rl.close();

if (answer.toLowerCase() === "y") {
// Resume the session with an empty prompt, then rewind
const rewindQuery = query({
prompt: "", // Empty prompt opens the connection
options: { ...opts, resume: sessionId }
});

for await (const msg of rewindQuery) {
await rewindQuery.rewindFiles(checkpointId); // Restore files
break;
}

console.log("\n✓ File restored! Open utils.ts to verify the doc comments are gone.");
} else {
console.log("\nKept the modified file.");
}
}
}

main();

이 예제는 완전한 체크포인팅 워크플로우를 보여줍니다:

체크포인팅 활성화: enable_file_checkpointing=True 및 permission_mode="acceptEdits"로 SDK를 구성하여 파일 편집을 자동으로 승인합니다
체크포인트 데이터 캡처: 에이전트가 실행되는 동안 첫 번째 사용자 메시지 UUID(복원 지점) 및 세션 ID를 저장합니다
되돌리기 프롬프트: 에이전트가 완료된 후 유틸리티 파일을 확인하여 문서 주석을 보고 변경 사항을 실행 취소할지 결정합니다
재개 및 되돌리기: 예인 경우 빈 프롬프트로 세션을 재개하고 rewind_files()를 호출하여 원본 파일을 복원합니다

예제 실행

유틸리티 파일과 같은 디렉토리에서 스크립트를 실행합니다.

python try_checkpointing.py

npx tsx try_checkpointing.ts

에이전트가 문서 주석을 추가한 다음 되돌리고 싶은지 묻는 프롬프트가 표시됩니다. 예를 선택하면 파일이 원본 상태로 복원됩니다.

제한 사항

파일 체크포인팅에는 다음과 같은 제한 사항이 있습니다:

제한 사항	설명
Write/Edit/NotebookEdit 도구만	Bash 명령어를 통해 수행된 변경 사항은 추적되지 않습니다
동일한 세션	체크포인트는 이를 생성한 세션에 연결됩니다
파일 콘텐츠만	디렉토리 생성, 이동 또는 삭제는 되돌리기로 실행 취소되지 않습니다
로컬 파일	원격 또는 네트워크 파일은 추적되지 않습니다

문제 해결

체크포인팅 옵션이 인식되지 않음

enableFileCheckpointing 또는 rewindFiles()를 사용할 수 없는 경우 이전 SDK 버전을 사용 중일 수 있습니다.

해결책: 최신 SDK 버전으로 업데이트합니다:

Python: pip install --upgrade claude-agent-sdk
TypeScript: npm install @anthropic-ai/claude-agent-sdk@latest

사용자 메시지에 UUID가 없음

message.uuid가 undefined이거나 누락된 경우 체크포인트 UUID를 수신하지 못하고 있습니다.

원인: replay-user-messages 옵션이 설정되지 않았습니다.

해결책: 옵션에 extra_args={"replay-user-messages": None}(Python) 또는 extraArgs: { 'replay-user-messages': null }(TypeScript)을 추가합니다.

"No file checkpoint found for message" 오류

이 오류는 지정된 사용자 메시지 UUID에 대한 체크포인트 데이터가 없을 때 발생합니다.

일반적인 원인:

원본 세션에서 파일 체크포인팅이 활성화되지 않았습니다(enable_file_checkpointing 또는 enableFileCheckpointing이 true로 설정되지 않음)
재개 및 되돌리기를 시도하기 전에 세션이 제대로 완료되지 않았습니다

해결책: 원본 세션에서 enable_file_checkpointing=True(Python) 또는 enableFileCheckpointing: true(TypeScript)가 설정되었는지 확인한 다음, 예제에 표시된 패턴을 사용합니다: 첫 번째 사용자 메시지 UUID를 캡처하고, 세션을 완전히 완료한 다음, 빈 프롬프트로 재개하고 rewindFiles()를 한 번 호출합니다.

"ProcessTransport is not ready for writing" 오류

이 오류는 응답을 반복하는 것을 완료한 후 rewindFiles() 또는 rewind_files()를 호출할 때 발생합니다. 루프가 완료되면 CLI 프로세스에 대한 연결이 닫힙니다.

해결책: 빈 프롬프트로 세션을 재개한 다음 새 쿼리에서 되돌리기를 호출합니다:

# Resume session with empty prompt, then rewind
async with ClaudeSDKClient(
ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)
) as client:
await client.query("")
async for message in client.receive_response():
await client.rewind_files(checkpoint_id)
break

// Resume session with empty prompt, then rewind
const rewindQuery = query({
prompt: "",
options: { ...opts, resume: sessionId }
});

for await (const msg of rewindQuery) {
await rewindQuery.rewindFiles(checkpointId);
break;
}

다음 단계

세션: 세션을 재개하는 방법을 알아봅니다. 이는 스트림이 완료된 후 되돌리기에 필요합니다. 세션 ID, 대화 재개 및 세션 포킹을 다룹니다.
권한: Claude가 사용할 수 있는 도구와 파일 수정이 승인되는 방식을 구성합니다. 편집이 발생하는 시기를 더 많이 제어하려는 경우 유용합니다.
TypeScript SDK 참조: query() 및 rewindFiles() 메서드의 모든 옵션을 포함한 완전한 API 참조입니다.
Python SDK 참조: ClaudeAgentOptions 및 rewind_files() 메서드의 모든 옵션을 포함한 완전한 API 참조입니다.

agent-sdk/file-checkpointing.md +796 −0 created

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# 체크포인팅으로 파일 변경 사항 되돌리기

7> 에이전트 세션 중 파일 변경 사항을 추적하고 파일을 이전의 모든 상태로 복원합니다

9파일 체크포인팅은 에이전트 세션 중 Write, Edit, NotebookEdit 도구를 통해 수행된 파일 수정 사항을 추적하여 파일을 이전의 모든 상태로 되돌릴 수 있게 합니다. 직접 시도해보고 싶으신가요? [대화형 예제](#try-it-out)로 이동하세요.

11체크포인팅을 사용하면 다음을 수행할 수 있습니다:

13* **원치 않는 변경 사항 실행 취소** - 파일을 알려진 양호한 상태로 복원

14* **대안 탐색** - 체크포인트로 복원한 후 다른 접근 방식 시도

15* **오류 복구** - 에이전트가 잘못된 수정을 수행했을 때

17<Warning>

18 Write, Edit, NotebookEdit 도구를 통해 수행된 변경 사항만 추적됩니다. Bash 명령어(예: `echo > file.txt` 또는 `sed -i`)를 통해 수행된 변경 사항은 체크포인트 시스템에서 캡처되지 않습니다.

19</Warning>

21<h2 id="how-checkpointing-works">

22 체크포인팅 작동 방식

23</h2>

25파일 체크포인팅을 활성화하면 SDK는 Write, Edit 또는 NotebookEdit 도구를 통해 파일을 수정하기 전에 파일의 백업을 생성합니다. 응답 스트림의 사용자 메시지에는 복원 지점으로 사용할 수 있는 체크포인트 UUID가 포함됩니다.

27체크포인트는 에이전트가 파일을 수정하는 데 사용하는 다음의 기본 제공 도구와 함께 작동합니다:

29| 도구 | 설명 |

30| ------------ | ---------------------------------- |

31| Write | 새 파일을 생성하거나 기존 파일을 새 콘텐츠로 덮어씁니다 |

32| Edit | 기존 파일의 특정 부분에 대한 대상 편집을 수행합니다 |

33| NotebookEdit | Jupyter 노트북(`.ipynb` 파일)의 셀을 수정합니다 |

35<Note>

36 파일 되돌리기는 디스크의 파일을 이전 상태로 복원합니다. 대화 자체를 되돌리지는 않습니다. `rewindFiles()`(TypeScript) 또는 `rewind_files()`(Python)를 호출한 후에도 대화 기록과 컨텍스트는 그대로 유지됩니다.

37</Note>

39체크포인트 시스템은 다음을 추적합니다:

41* 세션 중에 생성된 파일

42* 세션 중에 수정된 파일

43* 수정된 파일의 원본 콘텐츠

45체크포인트로 되돌리면 생성된 파일은 삭제되고 수정된 파일은 해당 시점의 콘텐츠로 복원됩니다.

47<h2 id="implement-checkpointing">

48 체크포인팅 구현

49</h2>

51파일 체크포인팅을 사용하려면 옵션에서 활성화하고, 응답 스트림에서 체크포인트 UUID를 캡처한 다음, 복원이 필요할 때 `rewindFiles()`(TypeScript) 또는 `rewind_files()`(Python)를 호출합니다.

53다음 예제는 전체 흐름을 보여줍니다: 체크포인팅을 활성화하고, 응답 스트림에서 체크포인트 UUID와 세션 ID를 캡처한 다음, 나중에 세션을 재개하여 파일을 되돌립니다. 각 단계는 아래에서 자세히 설명됩니다.

55<CodeGroup>

56 ```python Python theme={null}

57 import asyncio

58 from claude_agent_sdk import (

59 ClaudeSDKClient,

60 ClaudeAgentOptions,

61 UserMessage,

62 ResultMessage,

63 )

66 async def main():

67 # Step 1: Enable checkpointing

68 options = ClaudeAgentOptions(

69 enable_file_checkpointing=True,

70 permission_mode="acceptEdits", # Auto-accept file edits without prompting

71 extra_args={

72 "replay-user-messages": None

73 }, # Required to receive checkpoint UUIDs in the response stream

74 )

76 checkpoint_id = None

77 session_id = None

79 # Run the query and capture checkpoint UUID and session ID

80 async with ClaudeSDKClient(options) as client:

81 await client.query("Refactor the authentication module")

83 # Step 2: Capture checkpoint UUID from the first user message

84 async for message in client.receive_response():

85 if isinstance(message, UserMessage) and message.uuid and not checkpoint_id:

86 checkpoint_id = message.uuid

87 if isinstance(message, ResultMessage) and not session_id:

88 session_id = message.session_id

90 # Step 3: Later, rewind by resuming the session with an empty prompt

91 if checkpoint_id and session_id:

92 async with ClaudeSDKClient(

93 ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)

94 ) as client:

95 await client.query("") # Empty prompt to open the connection

96 async for message in client.receive_response():

97 await client.rewind_files(checkpoint_id)

98 break

99 print(f"Rewound to checkpoint: {checkpoint_id}")

100

101

102 asyncio.run(main())

103 ```

104

105 ```typescript TypeScript theme={null}

106 import { query } from "@anthropic-ai/claude-agent-sdk";

107

108 async function main() {

109 // Step 1: Enable checkpointing

110 const opts = {

111 enableFileCheckpointing: true,

112 permissionMode: "acceptEdits" as const, // Auto-accept file edits without prompting

113 extraArgs: { "replay-user-messages": null } // Required to receive checkpoint UUIDs in the response stream

114 };

115

116 const response = query({

117 prompt: "Refactor the authentication module",

118 options: opts

119 });

120

121 let checkpointId: string | undefined;

122 let sessionId: string | undefined;

123

124 // Step 2: Capture checkpoint UUID from the first user message

125 for await (const message of response) {

126 if (message.type === "user" && message.uuid && !checkpointId) {

127 checkpointId = message.uuid;

128 }

129 if ("session_id" in message && !sessionId) {

130 sessionId = message.session_id;

131 }

132 }

133

134 // Step 3: Later, rewind by resuming the session with an empty prompt

135 if (checkpointId && sessionId) {

136 const rewindQuery = query({

137 prompt: "", // Empty prompt to open the connection

138 options: { ...opts, resume: sessionId }

139 });

140

141 for await (const msg of rewindQuery) {

142 await rewindQuery.rewindFiles(checkpointId);

143 break;

144 }

145 console.log(`Rewound to checkpoint: ${checkpointId}`);

146 }

147 }

148

149 main();

150 ```

151</CodeGroup>

152

153<Steps>

154 <Step title="체크포인팅 활성화">

155 체크포인팅을 활성화하고 체크포인트 UUID를 수신하도록 SDK 옵션을 구성합니다:

156

157 | 옵션 | Python | TypeScript | 설명 |

158 | ------------- | ------------------------------------------- | --------------------------------------------- | -------------------------------- |

160 | 체크포인트 UUID 수신 | `extra_args={"replay-user-messages": None}` | `extraArgs: { 'replay-user-messages': null }` | 스트림에서 사용자 메시지 UUID를 가져오는 데 필요합니다 |

161

162 <CodeGroup>

163 ```python Python theme={null}

164 options = ClaudeAgentOptions(

165 enable_file_checkpointing=True,

166 permission_mode="acceptEdits",

167 extra_args={"replay-user-messages": None},

168 )

169

170 async with ClaudeSDKClient(options) as client:

171 await client.query("Refactor the authentication module")

172 ```

173

174 ```typescript TypeScript theme={null}

175 const response = query({

176 prompt: "Refactor the authentication module",

177 options: {

178 enableFileCheckpointing: true,

179 permissionMode: "acceptEdits" as const,

180 extraArgs: { "replay-user-messages": null }

181 }

182 });

183 ```

184 </CodeGroup>

185 </Step>

186

187 <Step title="체크포인트 UUID 및 세션 ID 캡처">

188 `replay-user-messages` 옵션이 설정되면(위에 표시됨), 응답 스트림의 각 사용자 메시지에는 체크포인트로 사용되는 UUID가 있습니다.

189

190 대부분의 사용 사례에서 첫 번째 사용자 메시지 UUID(`message.uuid`)를 캡처합니다. 이로 되돌리면 모든 파일이 원본 상태로 복원됩니다. 여러 체크포인트를 저장하고 중간 상태로 되돌리려면 [여러 복원 지점](#multiple-restore-points)을 참조하세요.

191

192 세션 ID(`message.session_id`)를 캡처하는 것은 선택 사항입니다. 스트림이 완료된 후 나중에 되돌리려는 경우에만 필요합니다. [체크포인트 전에 위험한 작업](#checkpoint-before-risky-operations) 예제처럼 메시지를 처리하는 동안 `rewindFiles()`를 즉시 호출하는 경우 세션 ID 캡처를 건너뛸 수 있습니다.

193

194 <CodeGroup>

195 ```python Python theme={null}

196 checkpoint_id = None

197 session_id = None

198

199 async for message in client.receive_response():

200 # Update checkpoint on each user message (keeps the latest)

201 if isinstance(message, UserMessage) and message.uuid:

202 checkpoint_id = message.uuid

203 # Capture session ID from the result message

204 if isinstance(message, ResultMessage):

205 session_id = message.session_id

206 ```

207

208 ```typescript TypeScript theme={null}

209 let checkpointId: string | undefined;

210 let sessionId: string | undefined;

211

212 for await (const message of response) {

213 // Update checkpoint on each user message (keeps the latest)

214 if (message.type === "user" && message.uuid) {

215 checkpointId = message.uuid;

216 }

217 // Capture session ID from any message that has it

218 if ("session_id" in message) {

219 sessionId = message.session_id;

220 }

221 }

222 ```

223 </CodeGroup>

224 </Step>

225

226 <Step title="파일 되돌리기">

227 스트림이 완료된 후 되돌리려면 빈 프롬프트로 세션을 재개하고 체크포인트 UUID와 함께 `rewind_files()`(Python) 또는 `rewindFiles()`(TypeScript)를 호출합니다. 스트림 중에도 되돌릴 수 있습니다. [체크포인트 전에 위험한 작업](#checkpoint-before-risky-operations)에서 해당 패턴을 참조하세요.

228

229 <CodeGroup>

230 ```python Python theme={null}

231 async with ClaudeSDKClient(

232 ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)

233 ) as client:

234 await client.query("") # Empty prompt to open the connection

235 async for message in client.receive_response():

236 await client.rewind_files(checkpoint_id)

237 break

238 ```

239

240 ```typescript TypeScript theme={null}

241 const rewindQuery = query({

242 prompt: "", // Empty prompt to open the connection

243 options: { ...opts, resume: sessionId }

244 });

245

246 for await (const msg of rewindQuery) {

247 await rewindQuery.rewindFiles(checkpointId);

248 break;

249 }

250 ```

251 </CodeGroup>

252

253 세션 ID와 체크포인트 ID를 캡처한 경우 CLI에서도 되돌릴 수 있습니다:

254

255 ```bash theme={null}

256 claude -p --resume <session-id> --rewind-files <checkpoint-uuid>

257 ```

258 </Step>

259</Steps>

260

261<h2 id="common-patterns">

262 일반적인 패턴

263</h2>

264

265이러한 패턴은 사용 사례에 따라 체크포인트 UUID를 캡처하고 사용하는 다양한 방법을 보여줍니다.

266

267<h3 id="checkpoint-before-risky-operations">

268 위험한 작업 전에 체크포인트

269</h3>

270

271이 패턴은 가장 최근의 체크포인트 UUID만 유지하며, 각 에이전트 턴 전에 업데이트합니다. 처리 중에 문제가 발생하면 마지막 안전한 상태로 즉시 되돌리고 루프를 벗어날 수 있습니다.

272

273<CodeGroup>

274 ```python Python theme={null}

275 import asyncio

276 from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage

277

278

279 async def main():

280 options = ClaudeAgentOptions(

281 enable_file_checkpointing=True,

282 permission_mode="acceptEdits",

283 extra_args={"replay-user-messages": None},

284 )

285

286 safe_checkpoint = None

287

288 async with ClaudeSDKClient(options) as client:

289 await client.query("Refactor the authentication module")

290

291 async for message in client.receive_response():

292 # Update checkpoint before each agent turn starts

293 # This overwrites the previous checkpoint. Only keep the latest

294 if isinstance(message, UserMessage) and message.uuid:

295 safe_checkpoint = message.uuid

296

297 # Decide when to revert based on your own logic

298 # For example: error detection, validation failure, or user input

299 if your_revert_condition and safe_checkpoint:

300 await client.rewind_files(safe_checkpoint)

301 # Exit the loop after rewinding, files are restored

302 break

303

304

305 asyncio.run(main())

306 ```

307

308 ```typescript TypeScript theme={null}

309 import { query } from "@anthropic-ai/claude-agent-sdk";

310

311 async function main() {

312 const response = query({

313 prompt: "Refactor the authentication module",

314 options: {

315 enableFileCheckpointing: true,

316 permissionMode: "acceptEdits" as const,

317 extraArgs: { "replay-user-messages": null }

318 }

319 });

320

321 let safeCheckpoint: string | undefined;

322

323 for await (const message of response) {

324 // Update checkpoint before each agent turn starts

325 // This overwrites the previous checkpoint. Only keep the latest

326 if (message.type === "user" && message.uuid) {

327 safeCheckpoint = message.uuid;

328 }

329

330 // Decide when to revert based on your own logic

331 // For example: error detection, validation failure, or user input

332 if (yourRevertCondition && safeCheckpoint) {

333 await response.rewindFiles(safeCheckpoint);

334 // Exit the loop after rewinding, files are restored

335 break;

336 }

337 }

338 }

339

340 main();

341 ```

342</CodeGroup>

343

344<h3 id="multiple-restore-points">

345 여러 복원 지점

346</h3>

347

348Claude가 여러 턴에 걸쳐 변경을 수행하는 경우, 모든 방식으로 되돌리기보다는 특정 지점으로 되돌리고 싶을 수 있습니다. 예를 들어, Claude가 첫 번째 턴에서 파일을 리팩토링하고 두 번째 턴에서 테스트를 추가하는 경우, 리팩토링은 유지하되 테스트는 실행 취소하고 싶을 수 있습니다.

349

350이 패턴은 모든 체크포인트 UUID를 메타데이터와 함께 배열에 저장합니다. 세션이 완료된 후 이전의 모든 체크포인트로 되돌릴 수 있습니다:

351

352<CodeGroup>

353 ```python Python theme={null}

354 import asyncio

355 from dataclasses import dataclass

356 from datetime import datetime

357 from claude_agent_sdk import (

358 ClaudeSDKClient,

359 ClaudeAgentOptions,

360 UserMessage,

361 ResultMessage,

362 )

363

364

365 # Store checkpoint metadata for better tracking

366 @dataclass

367 class Checkpoint:

368 id: str

369 description: str

370 timestamp: datetime

371

372

373 async def main():

374 options = ClaudeAgentOptions(

375 enable_file_checkpointing=True,

376 permission_mode="acceptEdits",

377 extra_args={"replay-user-messages": None},

378 )

379

380 checkpoints = []

381 session_id = None

382

383 async with ClaudeSDKClient(options) as client:

384 await client.query("Refactor the authentication module")

385

386 async for message in client.receive_response():

387 if isinstance(message, UserMessage) and message.uuid:

388 checkpoints.append(

389 Checkpoint(

390 id=message.uuid,

391 description=f"After turn {len(checkpoints) + 1}",

392 timestamp=datetime.now(),

393 )

394 )

395 if isinstance(message, ResultMessage) and not session_id:

396 session_id = message.session_id

397

398 # Later: rewind to any checkpoint by resuming the session

399 if checkpoints and session_id:

400 target = checkpoints[0] # Pick any checkpoint

401 async with ClaudeSDKClient(

402 ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)

403 ) as client:

404 await client.query("") # Empty prompt to open the connection

405 async for message in client.receive_response():

406 await client.rewind_files(target.id)

407 break

408 print(f"Rewound to: {target.description}")

409

410

411 asyncio.run(main())

412 ```

413

414 ```typescript TypeScript theme={null}

415 import { query } from "@anthropic-ai/claude-agent-sdk";

416

417 // Store checkpoint metadata for better tracking

418 interface Checkpoint {

419 id: string;

420 description: string;

421 timestamp: Date;

422 }

423

424 async function main() {

425 const opts = {

426 enableFileCheckpointing: true,

427 permissionMode: "acceptEdits" as const,

428 extraArgs: { "replay-user-messages": null }

429 };

430

431 const response = query({

432 prompt: "Refactor the authentication module",

433 options: opts

434 });

435

436 const checkpoints: Checkpoint[] = [];

437 let sessionId: string | undefined;

438

439 for await (const message of response) {

440 if (message.type === "user" && message.uuid) {

441 checkpoints.push({

442 id: message.uuid,

443 description: `After turn ${checkpoints.length + 1}`,

444 timestamp: new Date()

445 });

446 }

447 if ("session_id" in message && !sessionId) {

448 sessionId = message.session_id;

449 }

450 }

451

452 // Later: rewind to any checkpoint by resuming the session

453 if (checkpoints.length > 0 && sessionId) {

454 const target = checkpoints[0]; // Pick any checkpoint

455 const rewindQuery = query({

456 prompt: "", // Empty prompt to open the connection

457 options: { ...opts, resume: sessionId }

458 });

459

460 for await (const msg of rewindQuery) {

461 await rewindQuery.rewindFiles(target.id);

462 break;

463 }

464 console.log(`Rewound to: ${target.description}`);

465 }

466 }

467

468 main();

469 ```

470</CodeGroup>

471

472<h2 id="try-it-out">

473 직접 시도해보기

474</h2>

475

476이 완전한 예제는 작은 유틸리티 파일을 생성하고, 에이전트가 문서 주석을 추가하도록 하며, 변경 사항을 표시한 다음, 되돌리고 싶은지 묻습니다.

477

478시작하기 전에 [Claude Agent SDK가 설치](/ko/agent-sdk/quickstart)되어 있는지 확인하세요.

479

480<Steps>

481 <Step title="테스트 파일 생성">

482 `utils.py`(Python) 또는 `utils.ts`(TypeScript)라는 새 파일을 생성하고 다음 코드를 붙여넣습니다:

483

484 <CodeGroup>

485 ```python utils.py theme={null}

486 def add(a, b):

487 return a + b

488

489

490 def subtract(a, b):

491 return a - b

492

493

494 def multiply(a, b):

495 return a * b

496

497

498 def divide(a, b):

499 if b == 0:

500 raise ValueError("Cannot divide by zero")

501 return a / b

502 ```

503

504 ```typescript utils.ts theme={null}

505 export function add(a: number, b: number): number {

506 return a + b;

507 }

508

509 export function subtract(a: number, b: number): number {

510 return a - b;

511 }

512

513 export function multiply(a: number, b: number): number {

514 return a * b;

515 }

516

517 export function divide(a: number, b: number): number {

518 if (b === 0) {

519 throw new Error("Cannot divide by zero");

520 }

521 return a / b;

522 }

523 ```

524 </CodeGroup>

525 </Step>

526

527 <Step title="대화형 예제 실행">

528 유틸리티 파일과 같은 디렉토리에 `try_checkpointing.py`(Python) 또는 `try_checkpointing.ts`(TypeScript)라는 새 파일을 생성하고 다음 코드를 붙여넣습니다.

529

530 이 스크립트는 Claude에게 유틸리티 파일에 문서 주석을 추가하도록 요청한 다음 원본을 복원하기 위해 되돌리고 싶은지 선택할 수 있는 옵션을 제공합니다.

531

532 <CodeGroup>

533 ```python try_checkpointing.py theme={null}

534 import asyncio

535 from claude_agent_sdk import (

536 ClaudeSDKClient,

537 ClaudeAgentOptions,

538 UserMessage,

539 ResultMessage,

540 )

541

542

543 async def main():

544 # Configure the SDK with checkpointing enabled

545 # - enable_file_checkpointing: Track file changes for rewinding

546 # - permission_mode: Auto-accept file edits without prompting

547 # - extra_args: Required to receive user message UUIDs in the stream

548 options = ClaudeAgentOptions(

549 enable_file_checkpointing=True,

550 permission_mode="acceptEdits",

551 extra_args={"replay-user-messages": None},

552 )

553

554 checkpoint_id = None # Store the user message UUID for rewinding

555 session_id = None # Store the session ID for resuming

556

557 print("Running agent to add doc comments to utils.py...\n")

558

559 # Run the agent and capture checkpoint data from the response stream

560 async with ClaudeSDKClient(options) as client:

561 await client.query("Add doc comments to utils.py")

562

563 async for message in client.receive_response():

564 # Capture the first user message UUID - this is our restore point

565 if isinstance(message, UserMessage) and message.uuid and not checkpoint_id:

566 checkpoint_id = message.uuid

567 # Capture the session ID so we can resume later

568 if isinstance(message, ResultMessage):

569 session_id = message.session_id

570

571 print("Done! Open utils.py to see the added doc comments.\n")

572

573 # Ask the user if they want to rewind the changes

574 if checkpoint_id and session_id:

575 response = input("Rewind to remove the doc comments? (y/n): ")

576

577 if response.lower() == "y":

578 # Resume the session with an empty prompt, then rewind

579 async with ClaudeSDKClient(

580 ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)

581 ) as client:

582 await client.query("") # Empty prompt opens the connection

583 async for message in client.receive_response():

584 await client.rewind_files(checkpoint_id) # Restore files

585 break

586

587 print(

588 "\n✓ File restored! Open utils.py to verify the doc comments are gone."

589 )

590 else:

591 print("\nKept the modified file.")

592

593

594 asyncio.run(main())

595 ```

596

597 ```typescript try_checkpointing.ts theme={null}

598 import { query } from "@anthropic-ai/claude-agent-sdk";

599 import * as readline from "readline";

600

601 async function main() {

602 // Configure the SDK with checkpointing enabled

603 // - enableFileCheckpointing: Track file changes for rewinding

604 // - permissionMode: Auto-accept file edits without prompting

605 // - extraArgs: Required to receive user message UUIDs in the stream

606 const opts = {

607 enableFileCheckpointing: true,

608 permissionMode: "acceptEdits" as const,

609 extraArgs: { "replay-user-messages": null }

610 };

611

612 let sessionId: string | undefined; // Store the session ID for resuming

613 let checkpointId: string | undefined; // Store the user message UUID for rewinding

614

615 console.log("Running agent to add doc comments to utils.ts...\n");

616

617 // Run the agent and capture checkpoint data from the response stream

618 const response = query({

619 prompt: "Add doc comments to utils.ts",

620 options: opts

621 });

622

623 for await (const message of response) {

624 // Capture the first user message UUID - this is our restore point

625 if (message.type === "user" && message.uuid && !checkpointId) {

626 checkpointId = message.uuid;

627 }

628 // Capture the session ID so we can resume later

629 if ("session_id" in message) {

630 sessionId = message.session_id;

631 }

632 }

633

634 console.log("Done! Open utils.ts to see the added doc comments.\n");

635

636 // Ask the user if they want to rewind the changes

637 if (checkpointId && sessionId) {

638 const rl = readline.createInterface({

639 input: process.stdin,

640 output: process.stdout

641 });

642

643 const answer = await new Promise<string>((resolve) => {

644 rl.question("Rewind to remove the doc comments? (y/n): ", resolve);

645 });

646 rl.close();

647

648 if (answer.toLowerCase() === "y") {

649 // Resume the session with an empty prompt, then rewind

650 const rewindQuery = query({

651 prompt: "", // Empty prompt opens the connection

652 options: { ...opts, resume: sessionId }

653 });

654

655 for await (const msg of rewindQuery) {

656 await rewindQuery.rewindFiles(checkpointId); // Restore files

657 break;

658 }

659

660 console.log("\n✓ File restored! Open utils.ts to verify the doc comments are gone.");

661 } else {

662 console.log("\nKept the modified file.");

663 }

664 }

665 }

666

667 main();

668 ```

669 </CodeGroup>

670

671 이 예제는 완전한 체크포인팅 워크플로우를 보여줍니다:

672

673 1. **체크포인팅 활성화**: `enable_file_checkpointing=True` 및 `permission_mode="acceptEdits"`로 SDK를 구성하여 파일 편집을 자동으로 승인합니다

674 2. **체크포인트 데이터 캡처**: 에이전트가 실행되는 동안 첫 번째 사용자 메시지 UUID(복원 지점) 및 세션 ID를 저장합니다

675 3. **되돌리기 프롬프트**: 에이전트가 완료된 후 유틸리티 파일을 확인하여 문서 주석을 보고 변경 사항을 실행 취소할지 결정합니다

676 4. **재개 및 되돌리기**: 예인 경우 빈 프롬프트로 세션을 재개하고 `rewind_files()`를 호출하여 원본 파일을 복원합니다

677 </Step>

678

679 <Step title="예제 실행">

680 유틸리티 파일과 같은 디렉토리에서 스크립트를 실행합니다.

681

682 <Tip>

683 스크립트를 실행하기 전에 IDE 또는 편집기에서 유틸리티 파일(`utils.py` 또는 `utils.ts`)을 엽니다. 에이전트가 문서 주석을 추가할 때 파일이 실시간으로 업데이트되는 것을 볼 수 있으며, 되돌리기를 선택하면 원본으로 되돌아갑니다.

684 </Tip>

685

686 <Tabs>

687 <Tab title="Python">

688 ```bash theme={null}

689 python try_checkpointing.py

690 ```

691 </Tab>

692

693 <Tab title="TypeScript">

694 ```bash theme={null}

695 npx tsx try_checkpointing.ts

696 ```

697 </Tab>

698 </Tabs>

699

700 에이전트가 문서 주석을 추가한 다음 되돌리고 싶은지 묻는 프롬프트가 표시됩니다. 예를 선택하면 파일이 원본 상태로 복원됩니다.

701 </Step>

702</Steps>

703

704<h2 id="limitations">

705 제한 사항

706</h2>

707

708파일 체크포인팅에는 다음과 같은 제한 사항이 있습니다:

709

710| 제한 사항 | 설명 |

711| --------------------------- | ------------------------------------- |

712| Write/Edit/NotebookEdit 도구만 | Bash 명령어를 통해 수행된 변경 사항은 추적되지 않습니다 |

713| 동일한 세션 | 체크포인트는 이를 생성한 세션에 연결됩니다 |

714| 파일 콘텐츠만 | 디렉토리 생성, 이동 또는 삭제는 되돌리기로 실행 취소되지 않습니다 |

715| 로컬 파일 | 원격 또는 네트워크 파일은 추적되지 않습니다 |

716

717<h2 id="troubleshooting">

718 문제 해결

719</h2>

720

721<h3 id="checkpointing-options-not-recognized">

722 체크포인팅 옵션이 인식되지 않음

723</h3>

724

725`enableFileCheckpointing` 또는 `rewindFiles()`를 사용할 수 없는 경우 이전 SDK 버전을 사용 중일 수 있습니다.

726

727**해결책**: 최신 SDK 버전으로 업데이트합니다:

728

729* **Python**: `pip install --upgrade claude-agent-sdk`

730* **TypeScript**: `npm install @anthropic-ai/claude-agent-sdk@latest`

731

732<h3 id="user-messages-don-t-have-uuids">

733 사용자 메시지에 UUID가 없음

734</h3>

735

736`message.uuid`가 `undefined`이거나 누락된 경우 체크포인트 UUID를 수신하지 못하고 있습니다.

737

738**원인**: `replay-user-messages` 옵션이 설정되지 않았습니다.

739

740**해결책**: 옵션에 `extra_args={"replay-user-messages": None}`(Python) 또는 `extraArgs: { 'replay-user-messages': null }`(TypeScript)을 추가합니다.

741

742<h3 id="no-file-checkpoint-found-for-message-error">

743 "No file checkpoint found for message" 오류

744</h3>

745

746이 오류는 지정된 사용자 메시지 UUID에 대한 체크포인트 데이터가 없을 때 발생합니다.

747

748**일반적인 원인**:

749

750* 원본 세션에서 파일 체크포인팅이 활성화되지 않았습니다(`enable_file_checkpointing` 또는 `enableFileCheckpointing`이 `true`로 설정되지 않음)

751* 재개 및 되돌리기를 시도하기 전에 세션이 제대로 완료되지 않았습니다

752

753**해결책**: 원본 세션에서 `enable_file_checkpointing=True`(Python) 또는 `enableFileCheckpointing: true`(TypeScript)가 설정되었는지 확인한 다음, 예제에 표시된 패턴을 사용합니다: 첫 번째 사용자 메시지 UUID를 캡처하고, 세션을 완전히 완료한 다음, 빈 프롬프트로 재개하고 `rewindFiles()`를 한 번 호출합니다.

754

755<h3 id="processtransport-is-not-ready-for-writing-error">

756 "ProcessTransport is not ready for writing" 오류

757</h3>

758

759이 오류는 응답을 반복하는 것을 완료한 후 `rewindFiles()` 또는 `rewind_files()`를 호출할 때 발생합니다. 루프가 완료되면 CLI 프로세스에 대한 연결이 닫힙니다.

760

761**해결책**: 빈 프롬프트로 세션을 재개한 다음 새 쿼리에서 되돌리기를 호출합니다:

762

763<CodeGroup>

764 ```python Python theme={null}

765 # Resume session with empty prompt, then rewind

766 async with ClaudeSDKClient(

767 ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)

768 ) as client:

769 await client.query("")

770 async for message in client.receive_response():

771 await client.rewind_files(checkpoint_id)

772 break

773 ```

774

775 ```typescript TypeScript theme={null}

776 // Resume session with empty prompt, then rewind

777 const rewindQuery = query({

778 prompt: "",

779 options: { ...opts, resume: sessionId }

780 });

781

782 for await (const msg of rewindQuery) {

783 await rewindQuery.rewindFiles(checkpointId);

784 break;

785 }

786 ```

787</CodeGroup>

788

789<h2 id="next-steps">

790 다음 단계

791</h2>

792

793* **[세션](/ko/agent-sdk/sessions)**: 세션을 재개하는 방법을 알아봅니다. 이는 스트림이 완료된 후 되돌리기에 필요합니다. 세션 ID, 대화 재개 및 세션 포킹을 다룹니다.

794* **[권한](/ko/agent-sdk/permissions)**: Claude가 사용할 수 있는 도구와 파일 수정이 승인되는 방식을 구성합니다. 편집이 발생하는 시기를 더 많이 제어하려는 경우 유용합니다.

795* **[TypeScript SDK 참조](/ko/agent-sdk/typescript)**: `query()` 및 `rewindFiles()` 메서드의 모든 옵션을 포함한 완전한 API 참조입니다.

796* **[Python SDK 참조](/ko/agent-sdk/python)**: `ClaudeAgentOptions` 및 `rewind_files()` 메서드의 모든 옵션을 포함한 완전한 API 참조입니다.

agent-sdk/file-checkpointing.md 2026-06-09 06:34 UTC to 2026-06-10 23:57 UTC

체크포인팅으로 파일 변경 사항 되돌리기

체크포인팅 작동 방식

체크포인팅 구현

체크포인팅 활성화

체크포인트 UUID 및 세션 ID 캡처

파일 되돌리기

일반적인 패턴

위험한 작업 전에 체크포인트

여러 복원 지점

직접 시도해보기

테스트 파일 생성

대화형 예제 실행

예제 실행

제한 사항

문제 해결

체크포인팅 옵션이 인식되지 않음

사용자 메시지에 UUID가 없음

"No file checkpoint found for message" 오류

"ProcessTransport is not ready for writing" 오류

다음 단계