delegate-skills - 작업 위임

delegate-chore

잡무의 폴백 대상입니다. task_type=chore, 기본 모델은 haiku(최저가)입니다. 실행 계열 분기(Codex / Devin / Cursor / Claude)는 dispatch.sh가 수행합니다.

스크립트 경로

• Claude Code: skill_dir=.claude/skills/delegate-chore
• Codex: skill_dir=.agents/skills/delegate-chore

이후의 명령어 예시는 Claude Code의 .claude/skills/delegate-chore를 사용합니다. Codex에서 사용하는 경우, 동일한 상대 구조인 .agents/skills/delegate-chore로 바꿔 읽으십시오.

모델 가격 참조

비용 분석 및 단가 비교가 필요한 경우에만 <skill_dir>/model-token-prices.json을 읽습니다. 이 데이터는 참조용이며, delegate 실행 가능 여부 판단에는 사용하지 않습니다.

위임 전 (비용 게이트)

위임은 오버헤드(worker 시작, request/response 왕복, main 측 읽기)를 수반합니다. 이 chore가 단일 명령어(sed / find / chmod 등)로 스크립트화 가능하고, 대상 내용을 모델 컨텍스트에 올릴 필요가 없다면, 위임은 순손실이 될 가능성이 높습니다(오버헤드가 컨텍스트 위생 및 토큰 양측의 이득을 상회). 그렇다면 위임하지 말고 main이 직접 실행하거나, 반복되는 작업이라면 아래 피드백 루프의 자동화 제안으로 넘기십시오. 위임이 합리적인 경우는, 모델이 콘텐츠를 읽어서 처리해야 하는 방대한 작업입니다. 근거는 docs/design/delegate-chore.md §5에 있습니다.

실행 흐름 (one-shot)

1. 요청 생성: Objective / Scope / Context / Acceptance criteria / Verification / Constraints 의 Markdown을 stdin으로 전달합니다. request는 간결하게 작성합니다: Context에 파일 내용을 붙여넣지 말고, 경로(필요시 줄 범위)로 참조시킵니다(main의 출력 = 과금 토큰을 늘리지 않기 위해).
   • 사용자가 대화에서 모델이나 effort를 지정한 경우, run 호출에 인라인 env를 앞에 붙입니다(예: DELEGATE_CHORE_MODEL=gpt-5.5@high bash .../run.sh ...). exit 6의 경우, 허용 값 열거를 포함한 stderr의 한 줄을 그대로 사용자 설명에 사용합니다.
2. 실행: out="$(printf '%s' "$req_md" | bash .claude/skills/delegate-chore/scripts/run.sh chore DELEGATE_CHORE_MODEL haiku "$PARENT_TASK_TYPE_CHAIN" "$REQUESTER_SESSION_ID")" (top-level 실행이면 $PARENT_TASK_TYPE_CHAIN은 비어 있어도 됩니다).
   • run은 내부에서 prepare → dispatch → read-response를 순서대로 실행하고, stdout은 성공/실패 모두 단일 JSON(exit_code / status / content / content_truncated / response_file / observe_file / run_dir)을 반환합니다.
   • selector 생략 시 기본값은 auto입니다. 6번째 위치 인수는 read-response의 selector이며, prepare.sh의 6번째 위치 인수 session_mode와 의미가 다릅니다.
   • exit code는 내부 스크립트를 그대로 통과시킵니다. exit 3=전제 부족 / exit 4=위임 사이클이면 중단합니다.
   • run은 dispatch 전에 observe_file: <path>를 stderr로 먼저 내보냅니다. 강제 종료 시 해당 경로를 복구 경로로 사용합니다.
   • 비대화형 모드의 부모(claude -p 등)에서는 run을 반드시 포그라운드로 실행하고, 위임 소요 시간보다 긴 Bash timeout(Claude Code라면 BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS 또는 Bash tool의 timeout 인수)을 설정합니다.
3. 응답 소비: status="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .status)" / content="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .content)"를 읽습니다. content_truncated가 true이면 response_file="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .response_file)"을 추출하고, bash .claude/skills/delegate-chore/scripts/read-response.sh "$response_file" <N>로 필요한 section만 단계적으로 읽습니다. 읽기 완료 후, worker의 본문을 요약하지 않습니다(echo하지 않음). main의 사용자 응답은 Summary를 가리키는 한 줄로 제한합니다(main의 출력 = 과금 토큰을 늘리지 않기 위해. spec.md §6).

고급 흐름 (개별 스크립트)

dispatch 중의 observe 감시, background 실행, resumable / follow-up 등, 도중에 부모의 판단이 개입되는 흐름에서는 기존의 개별 스크립트를 사용합니다.

1. 준비 (집약): 전제 확인→모델 결정→체인 확인→요청 생성을 prepare.sh 하나로 통합합니다(개별 호출의 bash 왕복과 main 컨텍스트로의 출력을 줄임). Objective / Scope / Context / Acceptance criteria / Verification / Constraints 의 Markdown을 stdin으로 전달합니다. request는 간결하게 작성합니다: Context에 파일 내용을 붙여넣지 말고, 경로(필요시 줄 범위)로 참조시킵니다(main의 출력 = 과금 토큰을 늘리지 않기 위해). exit 3=전제 부족 / exit 4=위임 사이클이면 중단합니다.
   • 사용자가 대화에서 모델이나 effort를 지정한 경우, prepare 호출에 인라인 env를 앞에 붙입니다(예: DELEGATE_CHORE_MODEL=gpt-5.5@high bash .../prepare.sh ...). prepare가 exit 6이면, 허용 값 열거를 포함한 stderr의 한 줄을 그대로 사용자 설명에 사용합니다.
   • out="$(printf '%s' "$req_md" | bash .claude/skills/delegate-chore/scripts/prepare.sh chore DELEGATE_CHORE_MODEL haiku "$PARENT_TASK_TYPE_CHAIN" "$REQUESTER_SESSION_ID")" (top-level 실행이면 $PARENT_TASK_TYPE_CHAIN은 비어 있어도 됩니다)
   • model="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .model)" / request_file="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .request_file)" / response_file="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .response_file)" / run_dir="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .run_dir)" / observe_file="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .observe_file)"
2. 실행: bash .claude/skills/delegate-chore/scripts/dispatch.sh "$model" chore "$request_file" "$response_file" "$run_dir" "$observe_file". 모델명 접두사에 의한 실행 계열 분기(Codex / Devin / Cursor / Claude)는 dispatch.sh가 수행합니다. stdout은 response_file의 경로만 반환합니다. 비대화형 모드의 부모(claude -p 등)에서는 dispatch를 반드시 포그라운드로 실행하고, 위임 소요 시간보다 긴 Bash timeout(Claude Code라면 BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS 또는 Bash tool의 timeout 인수)을 설정합니다. 실행 중의 일반 감시는 observe_file에서 state.phase / state.started_at / heartbeat.ts / heartbeat.stdout_bytes / heartbeat.stderr_bytes / heartbeat.last_stream_change_at만을 read-json.sh로 읽습니다. state.phase는 prepared | running | superseded | stalled | ended입니다. prepared / superseded는 dispatch되지 않은 observe(state.started_at == null, usage는 미설정으로 read-json.sh에서는 null에 해당)이므로, usage를 집계할 때는 분모에서 제외합니다.
3. 응답 읽기: bash .claude/skills/delegate-chore/scripts/read-response.sh "$response_file" auto. auto는 response가 작은 경우(기본값 10KB 미만) status와 모든 section을 한 번에 모두 읽고, 큰 경우 status + index + Summary section을 반환하므로, 필요한 section만 ... "$response_file" <N>로 추가로 획득합니다. 읽기 완료 후, worker의 본문을 요약하지 않습니다(echo하지 않음). main의 사용자 응답은 Summary를 가리키는 한 줄로 제한합니다(main의 출력 = 과금 토큰을 늘리지 않기 위해. spec.md §6).

세션 재사용 (resumable / follow-up)

resumable / follow-up은 one-shot 대상이 아니므로 개별 스크립트를 사용합니다.

기본값은 일반 run입니다. 큰 범위의 횡단 수정 등, 부모 검토에서 되돌릴 가능성이 높은 경우에만 처음부터 resumable initial run을 명시합니다. 과도하게 사용하지 마십시오.

• resumable initial run: prepare.sh의 6번째 인수에 resumable을 전달합니다. dispatch는 7번째 인수에 resumable, 8번째와 9번째 인수에 빈 문자열을 전달합니다.
  • out="$(printf '%s' "$req_md" | bash .claude/skills/delegate-chore/scripts/prepare.sh chore DELEGATE_CHORE_MODEL haiku "$PARENT_TASK_TYPE_CHAIN" "$REQUESTER_SESSION_ID" resumable)"
  • session_mode="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .session_mode)" / lineage_id="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .lineage_id)"
  • bash .claude/skills/delegate-chore/scripts/dispatch.sh "$model" chore "$request_file" "$response_file" "$run_dir" "$observe_file" "$session_mode" "" ""
  • 응답을 읽은 후 bash .claude/skills/delegate-chore/scripts/read-json.sh .backend_session.persistence "$observe_file"을 확인합니다. resumable 이외라면 follow-up 불가능으로 판단하고 그 자리에서 결정하며, 이후 암시적 폴백을 기대하지 않습니다.
• follow-up run: 부모의 차이 확인에서 문제가 발견된 경우에만 사용합니다. prepare.sh의 6번째 인수에 followup=<이전 observe_file>을 전달합니다. exit 5는 검증 실패이므로 중단하고, 일반 delegate로 다시 내보냅니다. 암시적 폴백하지 않습니다.
  • out="$(printf '%s' "$req_md" | bash .claude/skills/delegate-chore/scripts/prepare.sh chore DELEGATE_CHORE_MODEL haiku "$PARENT_TASK_TYPE_CHAIN" "$REQUESTER_SESSION_ID" "followup=$previous_observe_file")"
  • session_mode="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .session_mode)" / resume_id="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .resume_id)" / backend_session_home="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .backend_session_home)"
  • bash .claude/skills/delegate-chore/scripts/dispatch.sh "$model" chore "$request_file" "$response_file" "$run_dir" "$observe_file" "$session_mode" "$resume_id" "$backend_session_home"
  • follow-up request에는 부모가 발견한 문제, 최신 git diff에서 봐야 할 범위, 이전 response_file의 참조를 반드시 포함합니다. worker의 오래된 대화 컨텍스트에만 의존하지 않게 합니다.

skill 승격 제안 (피드백 루프)

delegate-chore로 흘러들어오는 작업은 "전용 skill이 없는 작업"의 신호입니다. 응답 소비 후, 해당 작업이

• 반복해서 나타남 / 명확히 범위가 정해진 재사용 가능한 카테고리

라면, 전용 delegate-<name> skill의 새 생성을 AskUserQuestion으로 사용자에게 제안합니다(예상 이름 / 기본 모델 / 도구 권한 / 시작 유형을 첨부). 합의 후 skill-creator로 템플릿을 만들어 본 프로토콜에 맞춥니다. 일회성의 사소한 chore에서는 제안하지 않습니다.

결정론적 프로세스의 자동화 제안

skill 승격 제안과 같은 정신으로, 동일한 다단계 명령어 열·검증 절차·정형 편집이 반복해서 나타나고, 분기가 고정적이며 LLM의 판단이 필요 없다는 것을 알게 되면, AskUserQuestion으로 스크립트화 / git hook / npm script / CI 등 적절한 자동화 수단을 제안합니다(대상 절차 / 자동화 대상 / 예상 트리거를 첨부). 일회성 절차나 판단이 개입되는 절차는 제안하지 않습니다.

대기 시간 은폐 (대화 부모용)

대화 부모에서는 dispatch.sh(또는 run.sh)를 background로 실행하고, observe_file의 state.phase / heartbeat를 확인하여 ended 이후에 read-response.sh하는 운영 방식으로 체감 대기 시간을 은폐할 수 있습니다. 총 소요 시간(wall time)은 변하지 않는 체감 개선이며, 비대화형 모드의 부모에서는 기존대로 포그라운드 실행이 필수입니다.

제약

• 편집은 가능합니다. 단, push는 하지 않습니다(push 및 PR은 부모 에이전트가 직접 처리).
• task_type_chain 내 유형으로의 재위임은 하지 않습니다(다른 유형의 delegate는 가능).
• main은 worker 출력을 echo / 재요약하지 않습니다. 사용자 대상은 Summary를 가리키는 한 줄로 제한합니다(출력 = 과금 토큰을 늘리지 않기 위해. spec.md §6).