turn-eta — 작업 완료 시점 예측 및 기록

turn-eta — 작업 완료 시점을 예측하고 실제 소요 시간에서 학습하기

작업을 시작하기 전에 단계를 번호 목록으로 작성하고 완료 시점을 예측합니다. 각 단계가 실제로 소요된 시간을 측정합니다. 턴이 종료되면 실제 완료 시간을 응답 마지막에 포함합니다. 다음 예측은 이 로그를 참조합니다.

실행 시점

실제 작업이 포함된 모든 턴 — 파일 편집, 명령어 실행, 코드베이스 검색 등.

• 작업이 포함된 턴 → 작업 시작 전에 plan을 호출하고, 출력 내용을 순서 그대로 응답 첫 부분에 포함하세요: 먼저 **ETA …** 줄을 단독으로, 그 다음 번호 단계 목록. 완료 시간이 독자가 원하는 핵심이며, 아래 단계는 그 추론 과정입니다. 각 단계가 완료될 때마다 step <id>를 호출하고, 턴 작업이 모두 끝나면 done <id>를 호출하세요.
• 마지막 문단도 시간 정보이며, 어떤 시간을 쓸지는 아직 실행 중인 작업이 있는지에 따라 달라집니다.
  • 응답을 작성하기 전에 모든 작업이 완료됨 → done이 출력하는 전체 블록(완료 시점 시간)을 사용합니다. ETA는 이미 만료되었으므로 다시 출력하면 독자에게 이미 틀린 예측을 제시하게 됩니다. 대신 단계별 시간이 어디서 차이가 발생했는지 보여줍니다.
  • 아직 실행 중인 작업이 있음(백그라운드 작업, 위임된 작업 등) → 예측: **ETA 17:45**. 응답을 작성하는 시점에 다시 계산하고, plan이 출력한 숫자를 그대로 붙여넣지 마세요.
• 대화 전용 턴(질문에 답변, 구축할 내용 결정) → 아무것도 하지 마세요. 노이즈입니다.
• 한 줄짜리 수정은 이 절차에 적합하지 않습니다. 단계가 두 개 이상일 때 사용하세요.

명령어

순수 Node.js, 설치 불필요. 스킬이 설치된 위치에서 호출하세요.

# 작업 전 — 단계를 명명하고 ETA 획득
node <skill>/scripts/eta.js plan \
  "오류 재현" "날짜 파서 수정" "픽스처 업데이트" "테스트 재실행" \
  --provider anthropic --model claude-opus-5 --size M

# **ETA 17:45** (14분)
#
# 1. 오류 재현
# 2. 날짜 파서 수정
# 3. 픽스처 업데이트
# 4. 테스트 재실행
#
# 4단계, ~14분 (anthropic/claude-opus-5 M 기준 3.5분/단계, 6턴)
#
# (최근 6개 예측은 3분 초과)
# 턴 ID: 48i35qek

# 각 단계 완료 시 — 실제 소요 시간 측정 및 나머지 단계 재예측
node <skill>/scripts/eta.js step 48i35qek
# 2/4 날짜 파서 수정 — 8분 6초
#
# **ETA 17:49** (4분 후)

# 턴 작업이 모두 완료되었을 때
node <skill>/scripts/eta.js done 48i35qek
# **완료 17:48** (예측 14분 / 실제 17분)

# 현재 로그 조회
node <skill>/scripts/eta.js stats

단계를 숫자로만 세지 말고 이름을 붙이세요. plan은 숫자만 입력하면 거부합니다. 확인할 수 없는 개수는 계획이 아닙니다 — 이름이 붙은 단계는 작업 시작 전에 독자가 "3번 건너뛰기"라고 말할 수 있게 합니다. 번호 목록을 응답 상단에 배치한 후 작업을 진행하세요.

자신의 --provider와 --model을 반드시 전달하세요. 셸은 어떤 모델이 구동 중인지 알 수 없습니다. 자신을 식별하는 식별자를 사용하세요 — --provider anthropic --model claude-opus-5, --provider openai --model gpt-5-codex, --provider google --model gemini-3-pro. 누락되면 unknown/unknown으로 기록되며, 동작은 하지만 모든 모델이 함께 집계됩니다.

--size는 S(작은 수정), M(보통, 기본값), L(큰 덩어리) 중 하나입니다. 대략적이어도 괜찮습니다. 작은 턴이 큰 턴의 평균을 끌어내리는 것을 방지할 뿐입니다.

턴 ID는 필수입니다. plan이 출력하는 ID를 step과 최종 done까지 전달하세요 — step 48i35qek, done 48i35qek. 동일한 프로젝트에서 작업하는 다른 에이전트도 같은 로그에 기록하므로, ID 없이 호출하면 우연히 열려 있는 다른 에이전트의 턴을 종료할 수 있습니다. step과 done은 이제 ID 없이 호출을 거부합니다. 4시간 동안 접근되지 않은 턴은 포기된 것으로 간주합니다.

로그 저장 위치

<프로젝트 루트>/.eta/<provider>/<model>/log.tsv

프로젝트 내부에 저장되므로, 권한이 작업 디렉토리로 제한된 에이전트도 자신의 기록을 읽을 수 있습니다. 프로젝트 루트는 가장 가까운 상위 .git 디렉토리이며, 없으면 현재 디렉토리입니다. Provider와 model은 폴더로 구분되므로 한 모델의 속도가 다른 모델에 영향을 주지 않습니다.

.eta/를 .gitignore에 추가하세요. 이는 현재 머신과 턴에 대한 측정값으로, 다른 사람에게는 의미가 없고 모든 턴에서 변경됩니다.

TURN_ETA_DIR을 다른 .eta 디렉토리로 설정하면 여러 프로젝트 간에 기록을 공유할 수 있습니다. 로컬 로그가 너무 부족할 때만 참조됩니다.

예측 정확도 향상 방법

done은 예측값, 실제값, 단계별 시간을 기록합니다. plan이 이 기록을 읽고 단계당 중간값(minutes per step) 을 계산하며, 가장 일치하는 범위부터 바깥쪽으로 확장하고 최소 3개의 완료된 턴이 있는 첫 번째 단계에서 멈춥니다:

1. 현재 provider + model + 동일한 size
2. 현재 provider + model
3. 현재 provider, 모든 model
4. 이 프로젝트의 .eta 전체
5. TURN_ETA_DIR의 공유 로그 (동일한 순서)
6. 그 외에는 단계당 4분

평균(mean) 대신 중간값(median)을 사용하므로, 한 턴이 오래 걸려도 이후 모든 예측을 왜곡하지 않습니다. 각 단계에서 최근 20개 턴만 고려합니다. plan은 사용된 단계를 출력하므로 예측의 근거를 항상 확인할 수 있습니다.

턴 중간에 step은 해당 기록과 현재 턴의 실제 진행 속도를 혼합하며, 완료된 작업량에 따라 가중치를 부여합니다: 4단계 중 1단계에서는 기록이 3/4 비중을 차지하고, 3단계에서는 현재 턴이 3/4 비중을 차지합니다. 첫 단계가 느리더라도 완료 시간이 급격히 변하지 않도록 합니다.