service-migration

# 서비스 응답 마이그레이션 이 예제에는 애플리케이션이 없다. 사용자가 제공한 실제 소스와 목표 응답 계약을 기준으로 실행한다. 상태·통신 도구는 대상 프로젝트에 설치된 `.agents/skills/harness/scripts/`를 사용한다. 도구가 없으면 기본 하네스 설치가 필요함을 알리고 로컬 상태·통신 기록을 완료했다고 주장하지 않는다. ## 준비와 작업 계약 1. 적용되는 `AGENTS.md`, 실제 생산자·소비자·테스트 파일, 기존 변경과 목표 응답을 확인한다. 코드가 없으면 누락 경로를 보고하고 완료를 주장하지 않는다. 2. 현재 노출된 에이전트 도구의 스키마와 역할 목록을 확인한다. `service_contract_mapper`, `service_contract_migrator`를 사용할 수 있으면 선택한다. 미발견 역할은 정의를 읽어 사용 가능한 빌트인 역할의 작업 지시로 전달한다. 도구가 없으면 메인이 순차 수행하고 한계를 보고한다. 3. `plan.example.json`을 실제 경로·완료 기준·불변 계약 입력으로 바꾸고 run.py init으로 새 v2 실행을 만든다. init이 프로젝트 루트, 입력·계약 지문, 결정·스킬 경로, 작업별 input.md를 기록한다. 수정 대상은 ownership에 두고 불변 inputs와 겹치지 않게 한다. 선행 산출물은 dependencies를 통해 start 시점에 전달한다. 예제 계획을 실행 기록으로 덮어쓰지 않는다. 4. 작업마다 최신 input.md와 실제 동료 ID·역할·담당 경계 목록을 전달한다. 독립 작업에는 작은 완결된 패킷을 주고, 관련 에이전트를 재사용할 때도 변경된 결정·계약·스킬을 다시 읽게 한다. 모델은 부모 설정을 상속한다. 자식은 추가 에이전트를 생성하지 않는다. ## 실행 그래프 | 단계 | 역할 | 의존성과 소유권 | | --- | --- | --- | | 01 생산자 조사 | `service_contract_mapper` | API 직렬화·오류 응답을 읽고 메시지로 반환, 쓰기 없음 | | 02 소비자 조사 | `service_contract_mapper` | 파서·타입·사용처를 읽고 메시지로 반환, 쓰기 없음 | | 메인 계약 확정 | 메인 | 01·02 결과로 목표 shape과 호환성·오류 처리 확정 | | 03 생산자 변경 | `service_contract_migrator` | 01·02 이후, 실제 배정된 API 파일만 수정 | | 04 소비자 변경 | `service_contract_migrator` | 03 검증 후, 실제 배정된 클라이언트 파일만 수정 | | 05 독립 리뷰 | 사용 가능한 빌트인 역할 | 04 이후, 양쪽 형식·null·오류 동작을 읽기 전용 검토 | | 06 실행 QA | 사용 가능한 빌트인 역할 또는 메인 | 05 이후, 실제 테스트 실행과 허용된 캐시·로그만 작성 | 01·02는 독립 작업이므로 슬롯이 허용하면 병렬 실행한다. 메인은 그동안 목표 계약과 검증 기준을 정리한다. 03·04는 순서를 지키며 모듈 완료 시 해당 경계의 관련 검사를 수행한다. 같은 빌드 캐시를 쓰는 검사는 순차 실행한다. ## 소유권과 결과 - 메인만 장부·공용 타입·설정·lockfile·`AGENTS.md`를 수정하고 최종 통합을 수행한다. 공용 변경이 필요하면 작업자가 근거를 제안한다. - 작업자는 혼자 작업하지 않는다. 배정된 파일만 수정하고 다른 작업자의 변경을 되돌리지 않는다. - 읽기 전용 조사·리뷰는 결과 메시지를 반환하고 메인이 작업 디렉토리에 기록한다. QA는 실행 산출물만 쓰고 제품 코드 수정은 담당 소유자에게 반환한다. - 결과는 `run_id`, `task_id`, `status`(`completed`/`blocked`/`failed`), `summary`, `artifacts`, `checks`, `issues`를 포함한다. 각 검사는 `name`, `required`, `status`(`passed`/`failed`/`not_run`), 실제 `command`와 `evidence`를 기록한다. 수동 검토는 명령을 생략한다. - 메인은 run.py result로 실제 결과와 근거를 등록한다. 필수 검사는 모두 passed와 실제 근거가 있어야 하며 최소 한 개의 필수 검사가 필요하다. 필수 입력 누락·실패가 있으면 해당 소비자를 시작하지 않는다. - 결과 등록과 네이티브 세션 유휴·중단은 별개다. 실제 ID를 레지스트리에 연결하고 유휴·중단을 확인하기 전에는 다른 작성자에게 소유권을 넘기지 않는다. 로컬 상태 변경이 세션을 멈추거나 슬롯을 반환하지 않는다. ## 동료 간 소통 중요한 발견은 영향을 받는 동료와 메인에게 먼저 알린다. 생산자 mapper는 소비자 mapper에게 불명확한 오류 형식을 질문하고, 소비자 mapper는 근거와 함께 답한다. migrator는 계약 변경 제안, 선행 입력 준비, 차단 사유, 의미 있는 이정표와 인계를 전달한다. 메인이 확정한 결정만 적용하며 동료가 서로 소유권을 바꾸지 않는다. 쓰기 가능한 역할은 communication.py로 중요한 발신을 먼저 기록하고 실제 네이티브 메시지 도구로 전달한다. 실제 전송 결과를 별도 사건으로 기록하고 답변·수신 확인을 원래 이벤트 ID에 연결한다. 읽기 전용 역할의 기록·라우팅은 메인이 담당한다. 로그는 `_workspace/communications/<run-id>.jsonl`에 명시적으로 추가되며 네이티브 대화 전체를 자동 수집하거나 메시지를 보내지 않는다. 반복 생존 보고 대신 새 정보가 있는 순간에 소통한다. ## 오류·후속 실행·완료 일시적 실패는 원인 확인 후 1회 추가 시도한다. QA 결함은 담당 소유자가 수정하고 최대 2회 재검증한다. 한도 후 필수 실패는 실패로 남기며 전체 완료를 선언하지 않는다. 부분 재실행은 run.py resume으로 새 실행을 만든다. 변경된 입력·계약·결과와 하위 작업이 무효화되면 최신 패킷으로 다시 실행하고 이전 기록은 보존한다. 실제 프로젝트의 관련 테스트와 생산자·소비자의 응답 형식 비교가 완료 기준이다. 메인은 validate.py --project . --run ID --complete로 결과·산출물·필수 검사 근거·최신성을 확인한다. 정적 검토와 실행 검사를 구분하고, 최종 보고에 변경 파일·실제 결과·미실행 항목을 적는다. 이 시작 예제의 존재 자체를 런타임 통과 근거로 사용하지 않는다.