long-task-coordinator

long-task-coordinator 스킬 개요

long-task-coordinator가 하는 일

long-task-coordinator는 중단, 인계, 긴 턴 간격을 견뎌야 하는 작업을 조율하는 스킬입니다. 핵심 역할은 단순합니다. 오래 걸리는 작업을 불안정한 채팅 메모리에서 꺼내, 명시적인 상태 전이, 복구 점검, 다음 단계 추적이 가능한 영속 상태 파일로 옮기는 것입니다.

누가 설치하면 좋은가

이 스킬은 agent orchestration, 위임형 리서치, 마이그레이션, 배치 작업처럼 중간에 멈췄다가 나중에 재개하거나 다른 작업자의 결과를 기다려야 하는 업무에 가장 잘 맞습니다. 워크플로에 “이건 내일 다시 이어서 하자” 또는 “먼저 보내 두고 나중에 확인하자”가 자주 포함된다면, long-task-coordinator는 매우 적합한 선택입니다.

실제로 해결하는 문제

사용자가 long-task-coordinator를 설치하는 이유는 단순히 “계획을 더 잘 세우기 위해서”가 아닙니다. 긴 작업을 복구 가능하고, 상태 표현이 정직하도록 만들기 위해서입니다.

• 컨텍스트 손실 후에도 상태를 복구하기
• coordinator와 worker 사이의 소유권 추적하기
• 대기 상태를 명시적으로 표현하기
• 완료되지 않았는데 완료처럼 보이게 하는 잘못된 보고 피하기
• 이전 채팅을 억지로 추론하지 않고 저장된 단일 기준 상태에서 재개하기

일반적인 planning 프롬프트와 다른 점

차별점은 도메인 전문성이 아니라 워크플로 규율에 있습니다.

• 하나의 영속 상태 파일
• 고정 루프: READ -> RECOVER -> DECIDE -> PERSIST -> REPORT -> END
• running, awaiting-result, paused, blocked, complete 같은 명시적 상태
• 보고보다 먼저 저장하는 쪽으로 기울어진 운영 원칙 덕분에 다음 세션에서 안정적으로 복구 가능

잘 맞는 경우와 안 맞는 경우

long-task-coordinator는 작업이 여러 세션에 걸치거나, subagent나 백그라운드 작업이 개입되거나, 체크포인트와 재시도가 필요한 경우에 쓰는 것이 좋습니다. 반대로 한 번에 끝나는 작은 작업에는 과합니다. 저장소에서도 복구가 필요 없는 가벼운 계획 수립 용도는 planning-with-files를 쓰라고 명시하며, 굳이 장기 작업용 오버헤드를 얹지 않도록 안내합니다.

long-task-coordinator 스킬 사용 방법

long-task-coordinator 설치 옵션

저장소의 README에는 스킬을 클라이언트의 skill 디렉터리로 심볼릭 링크하는 수동 설치 방법이 나와 있습니다. 예를 들면 다음과 같습니다.

ln -s /path/to/agent-playbook/skills/long-task-coordinator ~/.claude/skills/long-task-coordinator
ln -s /path/to/agent-playbook/skills/long-task-coordinator ~/.codex/skills/long-task-coordinator
ln -s /path/to/agent-playbook/skills/long-task-coordinator ~/.gemini/skills/long-task-coordinator

skill manager를 쓴다면, 최종 설치 경로가 단순히 repo 루트가 아니라 실제 skills/long-task-coordinator 폴더 내용을 그대로 노출하는지 확인해야 합니다.

먼저 읽어야 할 파일

빠르면서도 안정적으로 도입하려면 다음 순서로 읽는 것이 좋습니다.

1. skills/long-task-coordinator/SKILL.md
2. skills/long-task-coordinator/references/workflow.md
3. skills/long-task-coordinator/evals/prompts.md
4. skills/long-task-coordinator/README.md

이 순서가 효과적인 이유는 다음과 같습니다.

• SKILL.md는 발동 조건과 핵심 규칙을 정의합니다
• references/workflow.md는 실제로 쓸 수 있는 상태 파일 패턴을 보여줍니다
• evals/prompts.md는 무엇이 “올바른 동작”인지 예시로 보여줍니다
• README.md는 설치 방식과 핵심 루프를 다시 확인해 줍니다

이 스킬에 필요한 입력

long-task-coordinator는 다음 정보가 주어질 때 가장 잘 작동합니다.

• 작업 목표
• 구체적인 성공 기준
• 이미 진행 중인 작업인지 여부
• 영속 상태 파일을 둘 위치
• 현재 활성화된 worker 또는 subagent 할당
• 시간 또는 조건 같은 다음 체크포인트 트리거
• 이미 알고 있는 blocker나 의존성

이 정보가 없어도 모델이 시작은 할 수 있지만, 가정이 늘어나고 조율 기록의 품질은 떨어집니다.

거친 요청을 좋은 호출로 바꾸기

약한 요청:

Help me keep track of this migration.

더 나은 요청:

Use long-task-coordinator for this migration. Create or recover a durable state file at docs/migration-state.md. Goal: migrate service auth to OAuth2. Success criteria: tests pass, rollout notes written, old auth path disabled. We may hand work to subagents and resume across sessions. If any work is in flight, use an explicit waiting state instead of implying failure.

더 강한 버전이 결과를 개선하는 이유는 저장 위치, 범위, 완료 판단 방식, 조율 스타일을 처음부터 분명하게 정해 주기 때문입니다.

영속 상태 파일은 초반에 만들어라

운영 습관 중 가장 중요한 것은 작업이 복잡해지기 전에 상태 파일을 먼저 만드는 것입니다. 참고 문서에서는 다음과 같은 경로를 권장합니다.

• docs/<topic>-execution-plan.md
• docs/<topic>-state.md
• worklog/<topic>-state.md

최소한 다음 항목은 저장해 두어야 합니다.

• Goal
• Success criteria
• Status
• Current step
• Completed work
• Next action
• Next checkpoint
• Blockers
• Owners

여기가 도입의 핵심 포인트입니다. 상태 파일을 생략하면 long-task-coordinator의 가치 대부분을 놓치게 됩니다.

매 라운드마다 복구 루프를 사용하라

저장소에 제시된 핵심 루프는 long-task-coordinator 활용의 실전 중심입니다.

READ -> RECOVER -> DECIDE -> PERSIST -> REPORT -> END

실무적으로는 다음을 의미합니다.

1. 먼저 저장된 상태를 읽는다
2. 현재 상태가 여전히 유효한지 확인한다
3. 위임한 작업의 결과가 돌아왔는지 확인한다
4. 계속 진행할지, 기다릴지, 재시도할지, 일시중지할지, 종료할지 결정한다
5. 갱신된 상태를 파일에 쓴다
6. 그 다음에만 사용자에게 보고한다

이 순서가 다음 세션의 복구 가능성을 지켜 줍니다.

명시적 상태를 쓰되, 특히 awaiting-result를 적극 활용하라

이 스킬의 미묘하지만 큰 장점 중 하나는 awaiting-result 상태입니다. 많은 agent는 이미 보낸 작업이 아직 진행 중일 뿐인데도 실패했거나 끝난 것처럼 포장해 버립니다. 이 스킬은 더 깔끔한 모델을 제공합니다.

• coordinator가 직접 작업 중일 때는 running
• worker나 job이 아직 실행 중일 때는 awaiting-result
• 의도적으로 멈춘 경우는 paused
• 외부 제약 때문에 진행할 수 없으면 blocked
• 성공 기준이 실제로 충족됐을 때만 complete

Agent Orchestration 관점에서는 이 구분이 스킬 전체에서 가장 유용한 요소 중 하나입니다.

위임 작업에 권장되는 워크플로

실전에서 좋은 운영 패턴은 다음과 같습니다.

1. 작업과 성공 기준을 정의한다
2. 상태 파일을 만든다
3. 범위가 분명한 작업을 worker에게 할당한다
4. 담당자와 기대되는 반환 조건을 기록한다
5. 대기 중이라면 상태를 awaiting-result로 둔다
6. 기억이 아니라 복구 절차로 재개한다
7. 완료된 항목과 다음 액션을 갱신한다
8. 기준을 점검한 뒤에만 complete로 표시한다

이 패턴은 “계속 진행해” 같은 열린 프롬프트보다 안전합니다. 인계와 책임이 추적 가능해지기 때문입니다.

실무에서 잘 먹히는 프롬프트 패턴

좋은 long-task-coordinator 프롬프트에는 대체로 복구 언어가 포함됩니다. 예를 들면 다음과 같습니다.

• “Use long-task-coordinator and recover from any existing state before proposing next steps.”
• “Persist the updated status before reporting.”
• “If a worker is still in flight, mark awaiting-result and define the next checkpoint.”
• “Do not mark complete unless the saved state and success criteria agree.”

이 패턴은 저장소의 eval 프롬프트와 직접 맞닿아 있으며, 근거 없는 확신을 줄이는 데 도움이 됩니다.

도입 시 흔한 실수

대부분의 실패는 기능 부족이 아니라 프로세스의 빈틈에서 나옵니다.

• 파일 대신 채팅 기록에 의존하기
• 정의된 상태 대신 애매한 상태 문구 쓰기
• 저장된 상태를 갱신하기 전에 진행 상황부터 보고하기
• 위임 작업의 owner를 기록하지 않기
• acceptance criteria를 확인하지 않고 완료 처리하기
• 조율 오버헤드가 불필요한 짧은 작업에 이 스킬을 적용하기

long-task-coordinator 스킬 FAQ

간단한 작업에도 long-task-coordinator를 설치할 가치가 있나

대개는 없습니다. 작업이 짧고, 한 세션 안에 끝나며, 복구가 필요 없다면 long-task-coordinator는 오히려 오버헤드가 됩니다. 저장소에서도 이 스킬은 한 턴을 넘어 지속되거나 영속 상태에 의존하는 작업을 위한 것이라고 분명히 위치시킵니다.

planning-with-files와는 어떻게 다른가

planning-with-files는 구조화된 계획이 주목적인 경우 더 가벼운 선택지입니다. 반면 long-task-coordinator는 재개 가능성, 명시적 대기 상태, 중단 후 복구를 위해 설계되었습니다. 단순한 단계 정리보다 상태 무결성이 더 중요할 때 이쪽을 선택하면 됩니다.

long-task-coordinator는 Agent Orchestration에 적합한가

그렇습니다. 가장 명확하게 잘 맞는 용도 중 하나입니다. 이 스킬은 coordinator-worker 구성, 위임 실행, 백그라운드 작업, 다중 세션 인계를 염두에 두고 설계되었습니다. owner 추적과 awaiting-result 상태는 특히 Agent Orchestration에서 유용합니다.

특정 runtime이나 framework가 필요한가

아니요. README에서는 이 스킬을 의도적으로 추상적이고 이식 가능하게 만들었다고 설명합니다. 특정 도메인이나 runtime을 전제하지 않습니다. 핵심 요구 사항은 agent가 워크스페이스 안의 영속 파일을 읽고 쓸 수 있어야 한다는 점입니다.

초보자도 이 long-task-coordinator 스킬을 쓸 수 있나

가능합니다. 다만 자신이 조율하려는 작업 자체는 이미 이해하고 있어야 합니다. 스킬 개념은 단순하지만, 초보자는 이 스킬을 과하게 적용하는 경우가 많습니다. 중단, 위임, 재개 가능성이 핵심이 아니라면 더 단순한 planning 스킬로 시작하는 편이 낫습니다.

언제 long-task-coordinator를 쓰지 말아야 하나

다음 경우에는 피하는 것이 좋습니다.

• 작업이 한 번에 끝나는 경우
• 나중에 다시 이어서 할 필요가 없는 경우
• 위임된 worker나 백그라운드 프로세스가 없는 경우
• 상태 파일을 유지하는 추가 단계를 원하지 않는 경우

이런 상황에서는 일반 프롬프트가 더 빠를 수 있습니다.

long-task-coordinator 스킬 개선 방법

더 강한 성공 기준부터 잡아라

품질을 가장 크게 좌우하는 레버는 더 날카로운 완료 판단 기준입니다. “마이그레이션 완료”처럼 쓰는 대신 다음과 같이 기준을 적으세요.

• auth 테스트 통과
• production config 업데이트 완료
• 롤백 노트 추가
• legacy 경로 비활성화

기준이 좋아질수록 모델이 작업을 너무 일찍 닫아 버리기 어려워집니다.

상태 파일은 구체적이고 다시 찾기 쉽게 만들어라

임의의 scratch 파일에 상태를 숨기지 마세요. docs/oauth-migration-state.md처럼 예측 가능한 경로에 두는 것이 좋습니다. 좋은 복구는 다음 세션이 추측 없이 실제 파일을 다시 찾을 수 있어야 성립합니다.

소유권을 명시적으로 기록하라

더 나은 long-task-coordinator 운영을 위해서는 누가 무엇을 맡는지 항상 남겨 두는 것이 좋습니다.

• Origin: 작업을 정의함
• Coordinator: 상태와 순서를 관리함
• Worker: 범위가 정해진 작업을 수행함

이 작은 습관만으로도 여러 agent가 참여할 때 중복 작업, 정체, 역할 혼선을 줄일 수 있습니다.

체크포인트 조건이 드러나는 프롬프트로 개선하라

약한 체크포인트는 “나중에 다시 확인해”입니다. 강한 체크포인트는 “worker가 테스트 결과를 반환하거나 15:00 UTC가 되면, 둘 중 먼저 오는 시점에 재개해”입니다. 트리거가 명확할수록 coordinator가 표류할 가능성이 줄어듭니다.

거짓 진척 보고를 막아라

흔한 실패 패턴 중 하나는 매끄럽게 들리지만 믿기 어려운 진행 보고입니다. 이를 막으려면 스킬에 다음을 지시하세요.

• 먼저 저장된 상태를 읽기
• 그 상태가 여전히 정확한지 검증하기
• 요약 전에 업데이트를 저장하기
• waiting과 blocked를 구분하기
• complete 판단 근거를 success criteria에 맞춰 설명하기

이렇게 해야 세션이 바뀌어도 long-task-coordinator 출력의 신뢰도를 유지할 수 있습니다.

eval 프롬프트를 acceptance test처럼 활용하라

evals/prompts.md는 단순 스모크 테스트 이상으로 유용합니다. 자신만의 변형 사용법을 점검하는 로컬 체크리스트처럼 다뤄 보세요.

• 중단된 작업을 안전하게 재개할 수 있는가?
• 대기 상태를 정직하게 표현하는가?
• 저장된 상태를 근거로 완료를 입증하는가?

커스터마이즈한 사용 방식이 이 테스트를 통과하지 못한다면, 현재 orchestration 패턴은 아직도 너무 느슨하다는 뜻입니다.

첫 실행 후 바로 다듬어라

첫 번째 조율 라운드가 끝나면 상태 파일을 직접 확인하고 모호한 부분을 조여야 합니다.

• 애매한 상태 표현 교체
• 빠진 owner 추가
• blocker 명확화
• 지나치게 큰 다음 액션 분할
• 실제로 작동하는 체크포인트 조건 추가

long-task-coordinator는 저장된 상태가 더 구체적일수록 빠르게 좋아집니다. 이후의 모든 복구가 기억이 아니라 그 파일에 의존하기 때문입니다.