# AI 에이전트용 설정·사용 설명서

대상: Warehouse Digital Twin v1.3.2

## 1. 운영 계약

- 원본 master_data.csv와 calendar_weather.csv를 직접 덮어쓰지 않는다.
- 정책 비교는 exact replay가 아니라 model_baseline_fifo와 같은 seed를 기준으로 한다.
- validation.json의 all_passed가 true인 결과만 보고한다.
- SLA뿐 아니라 평균·중앙값·p95 대기시간, overflow, 인력·모델시간을 함께 비교한다.
- 핵심 결론은 holdout과 수요·결근·서비스시간 스트레스에서도 확인한다.
- 시뮬레이션 결과를 실제 인과효과의 증명으로 단정하지 않는다.

## 2. 입력과 출력

고정 입력: master_data.csv, calendar_weather.csv
생성 출력: order_line_history.csv, work_event_log.csv, replenishment_log.csv, inventory_snapshot.csv
검증 출력: manifest.json, validation.json, kpi.json

master_data는 500개 SKU, calendar_weather는 2025-01-01~2025-06-30의 181일 축을 유지한다.

## 3. 웹 실행 순서

1. 비밀번호로 로그인한다.
2. 기본값으로 초기화해 원본 축을 불러온다.
3. 코드 편집기 또는 오른쪽 제어판에서 필요한 변수만 바꾼다.
4. 모든 입력이 검증 완료인지 확인한다.
5. 시뮬레이션을 실행하고 구조 검증 완료를 확인한다.
6. 결과 ZIP을 내려받아 manifest.json, validation.json, kpi.json을 먼저 읽는다.

## 4. 주요 시나리오 필드

- global_demand_multiplier: 전체 수요 배수, 웹 허용 0.5~1.5
- picker_capacity_multiplier: 상시 피커 처리능력, 웹 허용 0.5~2.0
- replenishment_capacity_multiplier: 보충 처리능력, 웹 허용 0.5~2.0
- replenishment_count_mode: demand_linked, fixed_daily, fixed_weekly
- service_time_multiplier: 작업시간 배수, 웹 허용 0.5~2.0
- queue_policy: observed, fifo, edd
- flex_picker_shifts: 최대 4개 규칙, 규칙당 10명·합계 20명 이하

탄력 인력 예시:

{
  "days": ["Tue", "Wed", "Thu"],
  "start_hour": 8,
  "end_hour": 18,
  "additional_workers": 5
}

프로모션 평탄화 효과와 보충 건수 감소 효과를 분리하려면 fixed_weekly를 우선 사용한다.
반사실에서 observed는 미래 관측 순서를 쓸 수 없어 FIFO로 적용되므로 manifest.json의 effective_queue_policy를 확인한다.

## 5. AI 에이전트 시작 프롬프트

이 설명서를 운영 계약으로 따른다. 먼저 기본값을 같은 seed로 실행해 비교 기준을 고정한다. 내가 지정한 가설에 직접 관련된 레버만 바꾸고 validation.json을 통과한 결과만 보고한다. SLA 하나만 최적화하지 말고 p95 대기시간, overflow, 인력·시간 비용, holdout과 스트레스 결과를 함께 제시한다. 실제 인과효과로 단정하지 않는다.

## 6. 보고 형식

가설 / 변경 입력과 이유 / 비교 기준과 seed / 검증 통과 여부 / SLA 변화(%p) / 평균·중앙값·p95 대기시간 / overflow 변화(%p) / 인력·모델시간 / holdout·스트레스 / 한계 / 현장 파일럿 제안 / manifest와 결과 위치

전체 개발·CLI 설명서는 비공개 GitHub 저장소의 AI_AGENT_GUIDE.md를 따른다.