runtime-notes.md

런타임 노트 — 실행 환경별 안내

1. 에이전트 팀 API와 순차 폴백

오케스트레이터 스킬은 에이전트 팀 API(TeamCreate/TaskCreate/팀 SendMessage — 실험 기능)를 1차 경로로 기술한다. 이 API가 없어도 킷은 동작한다: 같은 파이프라인을 전경(foreground) Agent 호출의 순차 실행으로 수행하면 된다. Phase 순서와 산출물 파일 계약(_workspace/01…06)은 동일하며, 실제 운영에서 전 단계 전경 실행으로 완주가 검증됐다.

주의: 백그라운드로 재개된 서브에이전트는 파일 Write/Edit가 거부될 수 있다. 수정 루프(writer 개정)는 전경 실행하거나, 검수 승인된 수정안을 리더(메인 세션)가 직접 반영한다.

2. 모델 선택 — 단계별 티어와 성능 폴백

공개판 기본값은 단계별 모델 티어다: 학술 판단 단계(designer·analyst·writer·reviewer·finalizer)는 model: inherit(세션 모델 상속), 문헌·근거조사(paper-investigator)는 sonnet. 세션을 opus로 돌려도 검색·수집이 무거운 모델을 기다리지 않게 한 배치다.

자매 킷(policy-research-kit·rnd-proposal-kit)은 문서 변환 단계를 haiku로 내리지만 이 킷은 그러지 않는다 — paper-finalizer는 순수 변환이 아니라 한국어 학술 교정교열을 겸하기 때문이다. 교정 없이 승인본을 docx로 재변환만 하는 부분 재실행이라면 그 호출에 한해 haiku 지정이 안전하다.

• 품질 우선: 학위논문·저널 투고처럼 품질이 우선이면 스폰 시 opus급 지정(업시프트)을 권장. 이론 계보 판별이 까다로운 주제는 조사도 상위 지정.
• 속도 우선: "빨리"라고 요청하거나 투고 마감이 임박하면 오케스트레이터가 쾌속 프로파일(문헌조사 분할 병렬·집필 장 배치 분할·수정 루프 1회)로 전환한다. 어느 단계가 안내 예산을 크게 넘으면 지연 폴백 래더가 남은 단계를 순서대로 경량화한다(분할·병렬화 → 다운시프트 → 루프 축소 → 사용자 범위 협상). 상세: 오케스트레이터 스킬의 "실행 프로파일 — 표준 vs 쾌속" 절.
• 실패 시 업시프트: 하위 모델 단계가 자체 검증에 실패하면 한 단계 위 모델로 1회 재스폰한다. 검증 게이트(reviewer)와 데이터분석(analyst)은 어떤 프로파일에서도 모델을 낮추지 않는다.

3. 한글(.hwpx) 경로 — kordoc

claude mcp add kordoc -- npx -y kordoc@latest mcp

• 지정 양식이 있으면 폼 채우기(parse_form→fill_form), 없으면 generate_document 표준 생성.
• kordoc 미설치·장애 시: 마크다운/docx 산출까지 진행하고 변환만 보류한다. MCP 게이트 장애 시 npx -y kordoc@latest 직접 구동 우회도 스킬에 문서화돼 있다.
• 기존 .hwp를 입력으로 줄 때의 한계: .hwp→마크다운 추출은 표·그림을 평탄화한다. 기존 보고서의 검수·보완 작업은 "원본 수정 가이드" 산출 방식을 권장한다(추출본 재생성으로 원본을 대체하지 않는다).
• 독점 기관 양식은 이 저장소에 포함되지 않는다(BYO-template). 자기 기관 양식은 런타임에 _workspace/00_input/으로 제공하라.

4. 해외 조사 현지화 — geo-search (선택)

조사 스킬 3종(policy-research / rnd-research / paper-research)에는 SERP API 래퍼(scripts/geo_search.py)가 내장돼 있다. 기본 WebSearch가 US 로케일 고정인 한계를 보완해 "일본 사례는 일본어로, 독일 통계는 독일어로" 검색한다.

• 키 설정(둘 중 하나): SERPER_API_KEY(serper.dev, 권장) 또는 SERPAPI_KEY(serpapi.com, 무료 100/월). 환경변수 또는 ~/.serper/key 파일.
• 키가 없으면 스킬이 자동으로 WebSearch 폴백을 쓴다 — 필수 아님.

5. 산출물 워크스페이스

모든 킷은 작업 디렉토리에 _workspace/를 만들어 단계 산출물(설계→게이트 판정→근거→초안→검수→최종)을 파일로 남긴다. 재실행·부분 수정("3장만 다시", "hwpx만 재생성")은 이 파일들을 기준으로 동작하므로 _workspace/를 지우지 말 것. 저장소에 커밋하지 않도록 .gitignore에 포함돼 있다.