[Claude Code] 다이내믹 워크플로우(Dynamic Workflows) 써보기

워크플로우 = Claude가 직접 짠 자바스크립트 오케스트레이션 스크립트임. Claude가 작업을 받아 스크립트를 작성하면, 런타임이 백그라운드에서 그 스크립트를 돌리면서 서브에이전트 수십~수백 개를 병렬로 굴림. 세션은 그동안 계속 반응하고, 끝나면 중간 과정 전부가 아니라 검증된 최종 결과 하나만 돌아옴.

기존 방식이랑 뭐가 다름

핵심은 "누가 계획(plan)을 들고 있느냐"임.

	서브에이전트 / 스킬 / 에이전트 팀	워크플로우
오케스트레이터	Claude 본인 (턴 단위 판단)	스크립트
중간 결과가 사는 곳	Claude 컨텍스트 윈도우	스크립트 변수
재사용되는 단위	워커/지시문 정의	오케스트레이션 자체
규모	턴당 몇 개 위임	런당 수십~수백 개

• 기존엔 Claude가 매 턴 "다음에 뭘 띄울까"를 정하고, 모든 중간 결과가 컨텍스트에 쌓임.
• 워크플로우는 루프·분기·중간 변수를 전부 스크립트가 들고 있음. 그래서 Claude 컨텍스트엔 최종 답만 남음.
• 단순히 에이전트 수만 늘리는 게 아니라, "에이전트들끼리 서로의 결과를 적대적으로 검증(adversarial review)" 같은 반복 가능한 품질 패턴을 코드로 박아둘 수 있음.

어떻게 띄우나

세 가지 방법 있음.

1. 프롬프트에 ultracode 키워드 넣기 — 세션 effort는 그대로 두고 이 작업만 워크플로우로.

   ultracode: src/routes/ 밑 모든 API 엔드포인트의 인증 누락 검사

   "워크플로우로 돌려줘" 같은 자연어도 똑같이 먹힘. (참고: v2.1.160 이전엔 트리거 키워드가 workflow였음. 자연어는 두 버전 다 됨.)

2. /effort ultracode — 켜두면 매 작업마다 Claude가 알아서 워크플로우를 짤지 판단함. 이해→수정→검증으로 한 요청이 워크플로우 여러 개로 쪼개지기도 함. 토큰·시간 많이 씀. 세션 끝나면 풀림.

3. 번들 워크플로우 /deep-research — 바로 체감용. 질문 하나를 여러 각도로 웹 검색·교차검증해서 출처 달린 리포트로 줌.

   /deep-research Node.js 권한 모델이 v20에서 v22로 가며 뭐가 바뀜?

실행 전에 Claude가 계획된 phase들을 보여주며 승인을 물음. 스크립트 원문도 Ctrl+G로 열어볼 수 있음. bypass/claude -p/Agent SDK는 안 묻고 바로 돌아감.

진행 상황 보기 / 저장 / 재사용

• /workflows — 실행 중·완료된 워크플로우 목록. 선택해서 들어가면 phase별 에이전트 수·토큰·경과 시간이 보임. 더 파고들면 각 에이전트의 프롬프트·최근 툴 호출·결과까지 확인 가능.
• 진행 뷰 단축키: p 일시정지/재개, x 중단, r 재시작, s 현재 런 스크립트를 명령으로 저장.
• 저장 위치 두 곳:
  • .claude/workflows/ — 레포 공유용 (clone하는 사람 다 씀)
  • ~/.claude/workflows/ — 내 홈, 모든 프로젝트에서 나만 씀
• 저장하면 /<이름>으로 다음 세션부터 재사용. 매 브랜치마다 돌리는 리뷰 같은 거 굳히기 좋음.
• args로 입력도 넘김. Run /triage-issues on issues 1024, 1025, 1030 식으로 구조화된 데이터가 스크립트 전역 args로 들어감.

직접 써보고 느낀 장점

1. 작업에 맞는 모델을 단계별로 골라 쓰니 토큰이 오히려 줄어듦.
워크플로우의 모든 에이전트는 기본적으로 세션 모델을 쓰지만, 작업에 따라 알아서 다른 모델을 사용함. ex) 리서치 등엔 하이쿠 사용.

솔직한 단서: 런 전체로 보면 에이전트가 많아 토큰을 더 쓸 수도 있음. 절약 효과는 "적절한 모델 라우팅 + 컨텍스트 비오염"에서 나오는 거지 무조건 줄어드는 마법은 아님. 그래서 모델 선택을 손봐주는 게 핵심임.

2. 하네스에서 오케스트레이션을 걷어내도 됨.
예전엔 서브에이전트 프롬프트 폴더나 스킬, 별도 하네스로 직접 오케스트레이터를 짜야 했음. 이제 그 조율 로직을 스크립트가 들고 가니까 하네스가 가벼워짐. 이미 만들어둔 오케스트레이터가 있으면 그걸 가리키며 "같은 일 하는 워크플로우로 만들어줘"라고 시킬 수도 있음. 조율은 코드로 굳고, 사람은 결과만 받음.

단점 (그리고 보완 팁)

각 서브에이전트가 정확히 뭘 하는지 한눈에 파악하기 어려움.
중간 결과가 컨텍스트 밖 스크립트 변수에 살고 최종 답만 돌아오는 구조라, 디버깅·신뢰 측면에선 "블랙박스" 느낌이 남.

보완책:

• /workflows 진행 뷰에서 phase → agent로 드릴인하면 각 에이전트의 프롬프트·툴 호출·결과를 직접 볼 수 있음. 답답할 땐 여기부터.
• 모든 런은 스크립트를 ~/.claude/projects/ 밑 파일로 떨궈둠. Claude한테 그 경로 물어서 직접 읽거나, 수정해서 다시 돌리거나, 이전 런과 diff 떠볼 수 있음.
• 단계 간 사람 검토가 꼭 필요하면, 한 워크플로우로 다 묶지 말고 단계별로 워크플로우를 쪼개서 사이사이 직접 확인.

실전 팁 모음

• 작게 먼저 재보기 — 레포 전체 말고 디렉터리 하나, 넓은 질문 말고 좁은 질문으로 한 번 돌려 토큰 감 잡기. 캡 덕에 폭주는 막히지만, 비용 가늠은 직접 해야 함.
• 모델 미리 확인 — 큰 런 전에 /model 체크. 평소 작은 모델로 바꿔뒀다면 그대로 큰 작업에 안 들어가게.
• allowlist 미리 채우기 — 서브에이전트는 항상 acceptEdits 모드로 돌고 내 tool allowlist를 상속함. 파일 편집은 자동 승인되지만, allowlist 밖 셸 명령·웹 페치·MCP 툴은 런 중간에 멈춰 물어봄. 긴 런은 필요한 명령을 미리 등록.
• 중단해도 손해 적음 — 같은 세션 안에서는 재개 가능. 끝난 에이전트는 캐시된 결과를 돌려주고 나머지만 새로 돎. 단, Claude Code를 종료하면 다음 세션에선 처음부터.
• 구조화 출력은 schema로 — 다음 단계가 결과를 소비해야 하면, "JSON으로 줘"라고 비는 대신 스키마를 줘서 검증된 구조로 강제하는 게 훨씬 안정적임.

제약 / 끄는 법

• 런 도중 사용자 입력 못 넣음(에이전트 권한 프롬프트만 멈춤). 동시 실행 최대 16개(코어 적으면 더 적게), 런당 총 1,000개 상한. 워크플로우 스크립트 자체는 파일·셸을 직접 못 만짐 — 실제 작업은 에이전트가 함.
• 끄기: /config에서 Dynamic workflows 토글 / ~/.claude/settings.json에 "disableWorkflows": true / 환경변수 CLAUDE_CODE_DISABLE_WORKFLOWS=1. 조직 전체는 managed settings나 admin 페이지에서.

언제 꺼내 쓰나

한 대화로 조율하기엔 에이전트가 너무 많이 필요할 때, 또는 조율 자체를 읽고 다시 돌릴 수 있는 스크립트로 굳히고 싶을 때. 코드베이스 전역 버그 스윕, 500파일 마이그레이션, 출처 교차검증이 필요한 리서치, 커밋 전 여러 각도로 스트레스 테스트하고 싶은 계획 같은 게 딱임.

---

리서치 프리뷰 기능이라 동작·옵션이 바뀔 수 있음. 최신 내용은 공식 문서 확인: code.claude.com/docs/en/workflows