264Claude는 목록을 구조화된 데이터로 전달하므로 스크립트는 먼저 구문 분석하지 않고도 `args`에서 배열 및 객체 메서드를 직접 호출할 수 있습니다. `args`가 생략되면 스크립트 내부의 전역 변수는 `undefined`입니다.264Claude는 목록을 구조화된 데이터로 전달하므로 스크립트는 먼저 구문 분석하지 않고도 `args`에서 배열 및 객체 메서드를 직접 호출할 수 있습니다. `args`가 생략되면 스크립트 내부의 전역 변수는 `undefined`입니다.
265 265
266<h2 id="example-workflow-prompts">266<h2 id="example-workflow-prompts">
267 예제 워크플로우 프롬프트267 워크플로 프롬프트 예시
268</h2>268</h2>
269 269
270워크플로우는 작업이 한 에이전트가 컨텍스트에 보유할 수 있는 것보다 크거나, 같은 단계를 많은 항목에 걸쳐 실행해야 할 때 가장 적합합니다. 아래 프롬프트는 일반적인 형태를 보여줍니다. 각각은 Claude에게 해당 작업을 위한 워크플로우를 작성하고 실행하도록 요청합니다; 스크립트를 직접 작성하지 않습니다.270워크플로는 작업이 하나의 에이전트가 컨텍스트에 담을 수 있는 범위보다 크거나, 같은 단계를 여러 항목에 걸쳐 실행해야 할 때 가장 적합합니다. 아래 프롬프트는 일반적인 형태를 보여 줍니다. 각 프롬프트는 Claude에게 해당 작업을 위한 워크플로를 작성하고 실행하도록 요청하므로, 스크립트를 직접 작성할 필요가 없습니다.
271 271
272<h3 id="audit-many-files-for-the-same-issue">272<h3 id="audit-many-files-for-the-same-issue">
273 많은 파일을 같은 문제에 대해 감사하기273 여러 파일에서 같은 문제 감사하기
274</h3>274</h3>
275 275
276파일당 하나의 에이전트를 확산시킨 후 발견 사항을 수집하고 검증합니다.276파일마다 에이전트를 하나씩 분산 실행한 다음, 발견 사항을 수집하고 검증합니다.
277 277
278```text wrap theme={null}278```text wrap theme={null}
279use a workflow to audit every route handler under src/routes/ for missing authentication checks, and adversarially verify each finding before reporting it279use a workflow to audit every route handler under src/routes/ for missing authentication checks, and adversarially verify each finding before reporting it
280```280```
281 281
282<h3 id="keep-fixing-until-a-check-passes">282<h3 id="keep-fixing-until-a-check-passes">
283 검사가 통과할 때까지 계속 수정하기283 검사를 통과할 때까지 계속 수정하기
284</h3>284</h3>
285 285
286검사기를 실행하고, 실패한 것을 수정하며, 통과하거나 진행이 멈출 때까지 반복합니다.286검사기를 실행하고, 실패한 부분을 수정한 뒤, 통과하거나 더 이상 진전이 없을 때까지 반복합니다.
287 287
288```text wrap theme={null}288```text wrap theme={null}
289use a workflow to run npx tsc --noEmit and keep fixing the reported errors until the type check passes or two rounds in a row make no progress289use a workflow to run npx tsc --noEmit and keep fixing the reported errors until the type check passes or two rounds in a row make no progress
290```290```
291 291
292<h3 id="migrate-many-files-in-parallel">292<h3 id="migrate-many-files-in-parallel">
293 많은 파일을 병렬로 마이그레이션하기293 여러 파일을 병렬로 마이그레이션하기
294</h3>294</h3>
295 295
296마이그레이션할 파일을 발견하고, 편집이 충돌하지 않도록 각각을 격리된 복사본에서 변환하며, 각 결과를 검증합니다.296마이그레이션할 파일을 찾고, 편집이 충돌하지 않도록 각 파일을 격리된 사본에서 변환한 다음, 각 결과를 검증합니다.
297 297
298```text wrap theme={null}298```text wrap theme={null}
299use a workflow to migrate every component under src/components/ from JavaScript to TypeScript, working on each file in its own isolated copy299use a workflow to migrate every component under src/components/ from JavaScript to TypeScript, working on each file in its own isolated copy
300```300```
301 301
302<h3 id="review-every-changed-file-and-write-one-summary">302<h3 id="review-every-changed-file-and-write-one-summary">
303 모든 변경된 파일을 검토하고 하나의 요약 작성하기303 변경된 모든 파일을 리뷰하고 하나의 요약 작성하기
304</h3>304</h3>
305 305
306파일당 하나의 검토자를 실행한 후 모든 발견 사항을 하나의 에이전트에 전달하여 순위를 매기고 중복을 제거합니다.306파일마다 리뷰어를 실행한 다음, 모든 발견 사항을 하나의 에이전트에 전달하여 순위를 매기고 중복을 제거합니다.
307 307
308```text wrap theme={null}308```text wrap theme={null}
309use a workflow to review every file changed in this PR for correctness issues, then merge the per-file findings into one ranked summary309use a workflow to review every file changed in this PR for correctness issues, then merge the per-file findings into one ranked summary
310```310```
311 311
312<h3 id="research-a-topic-across-many-sources">312<h3 id="research-a-topic-across-many-sources">
313 많은 소스에서 주제 연구하기313 여러 출처에 걸쳐 주제 조사하기
314</h3>314</h3>
315 315
316변경 로그, 문제, 문서에 걸쳐 읽기를 확산시킨 후 종합합니다. 번들된 `/deep-research` 워크플로우가 이를 수행합니다; 더 좁은 버전을 설명할 수도 있습니다.316변경 로그, 이슈, 문서에 걸쳐 리더를 분산 실행한 다음 종합합니다. 번들로 제공되는 `/deep-research` 워크플로가 이 작업을 수행하며, 더 좁은 범위의 버전을 직접 설명할 수도 있습니다.
317 317
318```text wrap theme={null}318```text wrap theme={null}
319use a workflow to research how our three competitors handle rate limiting: read their public docs and recent changelog entries in parallel, then compare the approaches319use a workflow to research how our three competitors handle rate limiting: read their public docs and recent changelog entries in parallel, then compare the approaches
320```320```
321 321
322<h3 id="find-issues-until-the-list-stops-growing">322<h3 id="find-issues-until-the-list-stops-growing">
323 목록이 더 이상 증가할 때까지 문제 찾기323 목록이 더 이상 늘어나지 않을 때까지 문제 찾기
324</h3>324</h3>
325 325
326라운드에서 계속 검색하고 새 라운드가 새로운 것을 찾지 못하면 중지합니다.326여러 라운드에 걸쳐 계속 탐색하고, 새 라운드에서 새로운 것이 발견되지 않으면 중단합니다.
327 327
328```text wrap theme={null}328```text wrap theme={null}
329use a workflow to find flaky tests in this repo: run the suite repeatedly, record which tests fail intermittently, and stop once two rounds in a row find nothing new329use a workflow to find flaky tests in this repo: run the suite repeatedly, record which tests fail intermittently, and stop once two rounds in a row find nothing new
330```330```
331 331
332<h3 id="what-the-saved-script-looks-like">332<h3 id="what-the-saved-script-looks-like">
333 저장된 스크립트가 어떻게 보이는지333 저장된 스크립트의 모습
334</h3>334</h3>
335 335
336[워크플로우를 저장](#save-the-workflow-for-reuse)하면 `.claude/workflows/`의 파일은 `meta` 블록 다음에 서브에이전트를 조율하는 스크립트 본문을 보유합니다. 일반적으로 편집할 필요가 없지만, 여기는 Claude가 생성한 것을 인식할 수 있도록 작은 것의 형태입니다:336[워크플로를 저장](#save-the-workflow-for-reuse)하면 `.claude/workflows/`의 파일에는 `meta` 블록과 그 뒤에 서브에이전트를 오케스트레이션하는 스크립트 본문이 담깁니다. 일반적으로 이 파일을 편집할 필요는 없지만, Claude가 생성한 내용을 알아볼 수 있도록 작은 스크립트의 형태를 아래에 보여 드립니다.
337 337
338```javascript theme={null}338```javascript theme={null}
339export const meta = {339export const meta = {
352return audits.filter(Boolean)352return audits.filter(Boolean)
353```353```
354 354
355본문은 최상위 `await`를 포함한 순수 JavaScript입니다. `agent()`는 하나의 서브에이전트를 생성하고, `pipeline()`은 목록의 각 항목당 하나를 실행하며, `parallel()`은 에이전트 작업 집합을 동시에 실행하고 모두가 완료될 때까지 기다립니다.355본문은 최상위 `await`를 사용하는 일반 JavaScript입니다. `agent()`는 서브에이전트 하나를 생성하고, `pipeline()`은 목록의 항목마다 하나씩 실행하며, `parallel()`은 에이전트 작업 집합을 동시에 실행하고 모두 완료될 때까지 기다립니다.
356 356
357`agent()` 호출은 실행 중에 중지하거나 복구 불가능한 API 오류가 발생하면 `null`로 해결됩니다. `pipeline()`은 결과 배열에 각 `null`을 유지하므로, 예제는 해당 항목을 제거하기 위해 `.filter(Boolean)`으로 끝납니다.357사용자가 실행 도중에 `agent()` 호출을 중지하거나 해당 호출이 복구할 수 없는 API 오류를 만나면, 호출은 `null`로 확인됩니다. `pipeline()`은 각 `null`을 결과 배열에 그대로 유지하므로, 예시는 [모든 시도에서 멈춘 에이전트](#when-an-agent-stalls-and-restarts)의 슬롯을 포함한 해당 항목을 제거하기 위해 `.filter(Boolean)`으로 끝납니다.
358 358
359[자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서 스크립트가 `agent()`에 전달하는 프롬프트는 분류기가 해당 서브에이전트의 작업을 검토할 때 사용자로부터의 요청으로 계산되지 않습니다. Claude Code는 이를 스크립트가 계산한 텍스트로 표시하기 때문입니다.359[자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서 분류기가 서브에이전트의 작업을 검토할 때, 스크립트가 `agent()`에 전달하는 프롬프트는 사용자의 요청으로 간주되지 않습니다. Claude Code가 이를 스크립트가 계산한 텍스트로 표시하기 때문입니다.
360 360
361`agent()` 호출에 `schema`를 전달하면, 서브에이전트는 산문 대신 형태와 일치하는 JSON을 반환합니다. Claude Code는 서브에이전트를 시작하기 전에 스키마를 확인합니다: 스키마가 자신과 모순된다는 것을 증명할 수 있을 때, 호출은 모순을 명명하는 오류로 실패하며, 서브에이전트는 시작되지 않습니다. 증명할 수 있는 한 가지 모순은 `additionalProperties: false`가 제외하는 `required` 키입니다.361`agent()` 호출에 `schema`를 전달하면, 해당 서브에이전트는 산문 대신 그 형태에 맞는 JSON을 반환합니다. Claude Code는 서브에이전트를 시작하기 전에 스키마를 검사합니다. 스키마가 자기모순임을 증명할 수 있으면 호출은 해당 모순을 명시한 오류와 함께 실패하며, 서브에이전트는 시작되지 않습니다. 증명할 수 있는 모순의 한 예는 `additionalProperties: false`가 배제하는 `required` 키입니다.
362 362
363서브에이전트의 출력이 5번의 시도 후에도 검증에 실패하면, 호출은 마지막 검증 실패를 포함하는 오류로 실패합니다. 시도 횟수를 변경하려면 [`MAX_STRUCTURED_OUTPUT_RETRIES`](/docs/ko/env-vars)를 설정하십시오.363서브에이전트의 출력이 다섯 번 시도한 후에도 여전히 검증에 실패하면, 호출은 마지막 검증 실패 내용을 포함한 오류와 함께 실패합니다. 시도 횟수를 변경하려면 [`MAX_STRUCTURED_OUTPUT_RETRIES`](/docs/ko/env-vars)를 설정합니다.
364 364
365<h3 id="edit-a-saved-script">365<h3 id="edit-a-saved-script">
366 저장된 스크립트 편집하기366 저장된 스크립트 편집하기
367</h3>367</h3>
368 368
369[저장한 워크플로우](#save-the-workflow-for-reuse)를 변경하려면 해당 `.js` 파일을 편집하거나 Claude에게 변경을 요청하십시오. 편집하거나 요청하기 전에 `/workflow-authoring` [번들된 스킬](/docs/ko/skills#bundled-skills)을 실행하여 Claude가 작동하는 스크립트 작성 참조를 로드하십시오. 스킬에는 Claude Code v2.1.248 이상이 필요합니다.369[저장한 워크플로](#save-the-workflow-for-reuse)를 변경하려면 해당 `.js` 파일을 편집하거나 Claude에게 변경을 요청합니다. 편집하거나 요청하기 전에 `/workflow-authoring` [번들 스킬](/docs/ko/skills#bundled-skills)을 실행하여 Claude가 참고하는 스크립트 작성 레퍼런스를 로드합니다. 이 스킬에는 Claude Code v2.1.248 이상이 필요합니다.
370 370
371현재 세션에서 편집된 버전을 실행하려면 [`/reload-skills`](/docs/ko/commands#all-commands)를 실행하여 워크플로우 디렉터리를 다시 읽은 후 `/<name>`을 다시 실행하십시오.371현재 세션에서 편집된 버전을 실행하려면 [`/reload-skills`](/docs/ko/commands#all-commands)를 실행하여 워크플로 디렉터리를 다시 읽은 다음, `/<name>`을 다시 실행합니다.
372 372
373Claude Code는 스크립트를 로드하고 실행할 때 파일의 각 부분에 다음 규칙을 적용합니다:373Claude Code는 스크립트를 로드하고 실행할 때 파일의 각 부분에 다음 규칙을 적용합니다.
374 374
375* **`meta` 블록**: `export const meta`를 첫 번째 문으로 유지하고, `name`과 `description`을 포함하는 순수 객체 리터럴로 유지하십시오. 변수, 함수 호출 또는 스프레드와 같은 리터럴 값 이외의 것을 포함하면, Claude Code는 `/` 자동완성에서 `/<name>`을 제거합니다.375* **`meta` 블록**: `export const meta`를 첫 번째 문으로 유지하고, `name`과 `description`을 가진 일반 객체 리터럴로 유지합니다. 변수, 함수 호출, 스프레드처럼 리터럴 값이 아닌 것이 포함되어 있으면 Claude Code는 `/` 자동 완성에서 `/<name>`을 제외합니다.
376* **본문**: `agent()`, `pipeline()`, `parallel()` 외에도 `phase()`를 호출하여 진행 보기에서 다음 에이전트를 제목 아래에 그룹화하고, `log()`를 호출하여 단계 위에 메시지를 표시하며, [`args`](#pass-input-to-a-saved-workflow) 전역을 읽을 수 있습니다. 본문에 구문 오류가 있으면, Claude Code는 워크플로우를 실행할 때 이를 보고합니다.376* **본문**: `agent()`, `pipeline()`, `parallel()` 외에도 `phase()`를 호출하여 이후의 에이전트를 진행 상황 보기에서 하나의 제목 아래로 그룹화하고, `log()`를 호출하여 단계 위에 메시지를 표시하며, [`args`](#pass-input-to-a-saved-workflow) 전역 변수를 읽을 수 있습니다. 본문에 구문 오류가 있으면 Claude Code는 워크플로를 실행할 때 이를 보고합니다.
377* **`phases`**: `meta`에 나열하면, `phase()`에 전달하는 각 항목에 정확히 제목을 지정하십시오. 항목이 없는 `phase()` 제목은 자체 진행 그룹을 가집니다.377* **`phases`**: `meta`에 나열하는 경우, 각 항목에 `phase()`에 전달하는 제목을 정확히 그대로 지정합니다. 항목이 없는 `phase()` 제목은 별도의 진행 상황 그룹을 갖게 됩니다.
378* **타임스탬프 및 무작위성**: Claude Code는 스크립트 내에서 `Date.now()`, `Math.random()`, 인수 없는 `new Date()`를 throw하므로, [재시작된 실행](#resume-after-a-pause)이 동일한 `agent()` 호출을 반복합니다. 대신 `args`를 통해 타임스탬프를 전달하십시오.378* **타임스탬프와 무작위성**: Claude Code는 스크립트 내에서 `Date.now()`, `Math.random()`, 인수 없는 `new Date()`가 예외를 발생시키도록 하여, [다시 시작된 실행](#resume-after-a-pause)이 동일한 `agent()` 호출을 반복하도록 합니다. 대신 `args`를 통해 타임스탬프를 전달합니다.
379 379
380[단일 실행의 스크립트](#how-a-workflow-runs)를 저장된 복사본이 아닌 편집할 수도 있습니다. [일시 중지 후 재개](#resume-after-a-pause)는 편집된 스크립트를 재시작할 때 어떤 에이전트가 다시 실행되는지를 다룹니다. Workflow 도구의 입력에 대해서는 [Agent SDK 참조](/docs/ko/agent-sdk/typescript#workflow)의 항목을 참조하십시오.380저장된 사본 대신 [단일 실행의 스크립트](#how-a-workflow-runs)를 편집할 수도 있습니다. 편집된 스크립트를 다시 시작할 때 어떤 에이전트가 다시 실행되는지는 [일시 중지 후 재개하기](#resume-after-a-pause)에서 다룹니다. Workflow 도구의 입력에 대해서는 [Agent SDK 레퍼런스](/docs/ko/agent-sdk/typescript#workflow)의 해당 항목을 참조하세요.
381 381
382<h2 id="how-a-workflow-runs">382<h2 id="how-a-workflow-runs">
383 워크플로우가 어떻게 실행되는지383 워크플로우가 어떻게 실행되는지
463* 제한이 24시간 이내에 재설정됩니다. 주간 제한은 더 멀리 재설정될 수 있습니다.463* 제한이 24시간 이내에 재설정됩니다. 주간 제한은 더 멀리 재설정될 수 있습니다.
464* 실행이 아직 두 번 대기하지 않았습니다. 세 번째로 제한에 도달하면 에이전트가 실패합니다.464* 실행이 아직 두 번 대기하지 않았습니다. 세 번째로 제한에 도달하면 에이전트가 실패합니다.
465 465
466<h3 id="when-an-agent-stalls-and-restarts">
467 에이전트가 멈추고 다시 시작될 때
468</h3>
469
470출력이 충분히 오랫동안 도착하지 않는 에이전트는 같은 프롬프트로 처음부터 다시 시작합니다. [`/workflows`](#watch-the-run)에서 해당 에이전트의 이름에 `(retry 1)` 접미사가 붙고 세부 정보에 `attempt 2 (stalled)`가 표시됩니다. 재시작은 자동으로 이루어지므로 별도로 조치할 필요가 없습니다.
471
472새 시도는 멈춘 시도의 트랜스크립트 없이 시작됩니다. 멈춘 시도가 이미 변경한 파일은 변경된 상태로 유지되며, 해당 시도가 사용한 토큰은 실행의 총계에 그대로 남습니다. 정체 기간은 Claude Code가 시도를 종료하기 전에 에이전트의 출력을 기다리는 시간입니다. 에이전트가 자체 도구 호출이나 [사용 한도 재설정](#when-a-run-hits-your-usage-limit)을 기다리는 데 보내는 시간은 정체 기간에 포함되지 않습니다.
473
474에이전트는 `r`로 요청한 재시작을 포함하여 최대 다섯 번까지 다시 시작합니다. 여섯 번째 시도도 멈추면 `agent()` 호출이 실패하며, 오류의 시작 부분에 그 이유가 표시됩니다:
475
476* `agent stalled on all 6 attempts`: 모든 시도가 정체 기간 내내 출력 없이 지나갔습니다. 에이전트의 작업 특성상 그만큼 오래 출력이 없는 경우 정체 기간을 늘립니다
477* `agent lost its reply on all 6 attempts`: 모든 시도의 응답 스트림이 멈췄고 Claude Code가 기다리기를 포기했습니다. [스트리밍 유휴 감시](/docs/ko/network-config#streaming-idle-watchdogs)가 먼저 응답을 종료했으므로 정체 기간을 늘려도 도움이 되지 않으며, 해당 감시의 타임아웃은 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`로 설정합니다
478* `agent abandoned after 6 attempts`: 시도들이 서로 다른 방식으로 종료되었으며, 오류에 순서대로 나열됩니다
479
480정체 기간이 끝나기 전에 에이전트가 출력을 생성할 시간을 더 주려면:
481
482* **단일 에이전트**: 해당 에이전트의 `agent()` 호출에 `stallMs`를 밀리초 단위로 전달합니다. 예를 들어 30분의 경우 `agent(prompt, { stallMs: 1800000 })`입니다
483* **모든 에이전트**: [`CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`](/docs/ko/env-vars#variables)를 설정합니다. 이 값은 워크플로 외부의 서브에이전트에도 적용됩니다
484
485실패 후 실행이 계속되는지는 스크립트가 에이전트를 호출한 방식에 따라 달라집니다:
486
487* **[`parallel()` 또는 `pipeline()`](#what-the-saved-script-looks-like) 내부**: 에이전트의 결과 대신 `null`로 실행이 계속됩니다
488* **직접 await한 경우**: 실행이 오류와 함께 종료됩니다
489
490다시 시도하려면 Claude에게 워크플로를 다시 시작하도록 요청합니다. 무엇이 다시 실행되는지는 [일시 중지 후 재개](#resume-after-a-pause)에서 다룹니다.
491
466<h3 id="cost">492<h3 id="cost">
467 비용493 비용
468</h3>494</h3>
