네이티브 → Flutter 전환 は何をしますか？

운영 중인 네이티브 앱을 Flutter 한 코드베이스로 옮깁니다. 이 스킬은 문서를 먼저 만들고, 문서를 근거로 구현하고, 독립 리뷰어가 승인한 것만 다음 단계로 넘기는 방식입니다. 입력은 네이티브 소스 폴더뿐이라고 가정합니다. 분석서·PRD·명세·지시서는 모두 이 스킬이 단계마다 새로 만듭니다.

왜 이렇게 하는가

두 앱 모두 운영 중입니다. 전환 후 업데이트를 받은 기존 사용자가 로그인·결제·저장 데이터 중 하나라도 잃으면 실패입니다. 그래서 "어느 OS 사용자도 기능을 잃지 않는다"가 모든 결정보다 앞섭니다.
원본이 유일한 진실입니다. 기억이나 추측으로 쓴 값은 실기기에서 반드시 틀립니다. 모든 수치·문자열·API·동작에 원본 파일:행 근거를 달고, 근거가 없으면 (추정)이라고 씁니다.
문서가 먼저 합의돼야 병렬 구현이 됩니다. 모듈 에이전트 여러 개가 동시에 일하려면 각자 읽을 명세가 확정돼 있어야 합니다. 명세가 흔들리면 같은 화면을 두 번 고칩니다(실제로 기능 구현 뒤에 UI를 다시 맞추느라 전 화면을 두 번 손댄 사례가 있습니다 → 이 스킬은 디자인 명세를 구현 전에 만듭니다).
작성자와 검토자를 분리합니다. 구현한 쪽의 보고를 믿지 않고, 다른 컨텍스트의 리뷰어가 코드와 명세를 직접 대조해 승인해야 다음으로 갑니다.

입력 모드

시작할 때 모드를 정합니다. 단계 구성은 같고, 단계 안에서 할 일이 달라집니다. 모드별 차이는 각 reference 파일의 "모드별" 절에 있습니다.

모드	입력	핵심 차이
BOTH	iOS 프로젝트 + Android 프로젝트	OS 간 비즈니스·UI 차이를 찾아 하나로 결정합니다. UI 기준 OS를 정하고 예외를 관리합니다. 두 OS 모두 기존 사용자 이관 대상
IOS_ONLY	iOS 프로젝트만	차이 결정이 없습니다. 대신 Android를 새로 지원한다면 "새 플랫폼 공백"(뒤로가기, 런타임 권한, 알림 채널, 시스템 바, 앱 ID·서명·스토어 신규 등록)을 설계합니다
ANDROID_ONLY	Android 프로젝트만	위와 반대입니다. iOS를 새로 지원한다면 Info.plist 권한 문구, APNs·entitlements, 스와이프 뒤로가기, 서명·프로필·App Store 신규 등록을 설계합니다

단일 OS 모드에서도 Flutter 결과물의 대상 플랫폼(원본 OS만 / 두 OS 모두)은 따로 묻습니다.

역할

역할	누가	하는 일
오케스트레이터	이 세션(나)	단계 진행, 에이전트 지시·취합, 공통 파일 수정, 전체 테스트·빌드, 사용자 보고
작성·구현 에이전트	서브에이전트(기본 `model: opus`, 사용자가 지정하면 그 모델)	맡은 범위의 분석·문서·코드 작성
리뷰어	기본 `model: fable` 서브에이전트(독립 컨텍스트). 사용자가 외부 모델(GPT·Gemini 등)을 붙이면 그 모델	문서·코드를 원본·명세와 직접 대조해 승인/수정 요청
사용자	결정권자	정책·UX 선택, 실기기 확인, 계정·키·스토어 작업

리뷰어·공동 작성 규칙(추가만 하는 로그, 자기 이름으로만 승인, 같은 리비전 양측 승인, 리뷰어 교대 인수인계)은 references/collaboration.md에 있습니다. 외부 모델과 일할 때는 사용자가 메시지를 전달하므로, 파일 기반 로그로 대화합니다.

단계 지도

각 단계는 산출물을 만들고, 게이트를 통과해야 다음 단계로 갑니다. 단계에 들어갈 때 해당 reference 파일을 읽습니다.

#	단계	산출물 (`<ws>/docs/` 아래)	게이트	읽을 파일
0	착수·환경 확인	`00-kickoff.md`(모드, 대상 플랫폼, 아키텍처, 원칙, 결정 대기 목록)	사용자 확인	`references/00-kickoff.md`
1	원본 분석	`analysis/<os>_analysis.md`, `analysis/api_inventory.md`, `analysis/screen_inventory.md`, (BOTH) `analysis/business_diff.md` / (단일 OS) `analysis/new_platform_gaps.md`	리뷰어 승인	`references/01-analysis.md`
2	PRD	`prd.md`(결정표 D-번호, API 계약, 화면·기능 요구, 이관·보안, 단계·게이트, 인수 시나리오) + `logs/prd_log.md`	리뷰어·나 같은 리비전 완료 선언 + 사용자 결정 반영	`references/02-prd.md`
3	UI 인벤토리·디자인 명세	`design/<os>_ui_inventory.md`, `design_spec.md`(토큰·컴포넌트·에셋·문자열·화면별·플랫폼 예외·실기기 확인 목록), `decisions.md`(U-번호) + `logs/design_log.md`	화면별 양측 승인	`references/03-design-spec.md`
4	구현 지시서	`impl_plan.md`(아키텍처 규약, Phase·모듈·계층별 작업 ID, 역참조 표)	리뷰어 승인, 누락 0	`references/04-impl-plan.md`
5	공통 기반·플랫폼 POC	Flutter 프로젝트, flavor·env, core(네트워크·에러·MVI·디자인 시스템·문자열·에셋·라우터), 플랫폼 어댑터·플러그인	실기기 POC 통과	`references/05-build.md`
6	모듈별 구현	모듈마다 data→domain→presentation→test, `logs/impl_log.md`	모듈마다 리뷰어 승인	`references/05-build.md`
7	통합 테스트·수정	전체 테스트 통과, 커버리지 게이트, 빌드	0 실패	`references/05-build.md`
8	실기기 QA 루프	`qa_device_checklist.md`, 사용자 피드백 → U-결정 → 수정 → 문서 동기화	사용자 "완료"	`references/06-device-qa.md`
9	서명·배포	서명·프로필·Firebase·CI·`release_runbook.md` (새 OS는 신규 등록)	원본 OS: 같은 앱 ID·인증서·높은 버전 / 새 OS: 신규 서명·업로드 가능	`references/07-release.md`
10	유지보수 문서	`<flutter>/docs/01~07`, `README.md`	리뷰어 승인	`references/08-maintenance-docs.md`

단계를 건너뛰어 달라는 요청(예: "분석은 됐고 PRD부터")이 오면, 이전 단계 산출물이 있는지 확인하고 없으면 무엇이 빠졌는지 알린 뒤 사용자가 정한 대로 진행합니다. 기능 구현이 이미 끝난 Flutter 앱을 원본 UI에 맞춰 달라는 요청은 references/05-build.md의 "변형 경로"를 따릅니다.

지켜야 할 원칙

이 원칙들은 각 단계 문서 맨 앞에 옮겨 적어 에이전트들이 같은 기준으로 판단하게 합니다.

기존 사용자 차단 금지. 결정 하나 때문에 한쪽 OS 사용자가 로그인·결제·자산 사용을 못 하게 되면 그 결정은 틀렸습니다. 기존 데이터에 닿는 검증(예: 로그인 형식 검사)은 느슨하게, 새 입력 정책은 서버와 같게 합니다.
서버 변경 없음이 기본 전제. 별도 지시가 없으면 현행 API 계약 안에서 해결합니다. 서버가 필요한 개선은 "오픈 이슈"로 분리합니다.
결함은 재현하지 않습니다. 원본 버그를 "동등성" 이유로 옮기지 않습니다. 기대 결과를 결정하고 회귀 테스트로 고정합니다. 단, 사용자에게 보이는 결과가 바뀌면 결정 목록에 올려 사용자에게 확인받습니다.
UI 기준 OS(BOTH, 전환 기간 한정). 시각이 다르면 기준 OS 값을 씁니다. 어느 OS를 기준으로 할지는 사용자에게 묻고, 기본값을 정해 두지 않습니다. 이 원칙은 원본을 옮기는 동안의 판단 기준입니다. 전환이 끝나면 "현재 Flutter 동작이 기준, 변경은 사용자 결정"으로 바뀝니다(10단계). 예외는 세 종류만: (a) 기준 OS를 따르면 다른 OS 사용자가 기능을 못 쓰거나 플랫폼 고유 동작이 깨짐, (b) 기준 OS 동작이 PRD 결정과 충돌, (c) 기준 OS 값이 명백한 버그(시각은 유지, 동작만 정정).
근거 필수. 원본 파일:행. 근거 없는 값은 (추정), 실기기에서 재야 하는 값은 (실기기), 원본 어디에도 없어 새로 정한 값은 (신규 정의).
원본에 없던 것을 들이지 않습니다. 원본 앱에 없던 외부 SDK·외부 서비스·추가 설정값(예: 상용 보안 SDK, 알림 메일 주소)을 "더 좋아 보여서" 넣지 않습니다. 원본 방식을 먼저 이식하고, 바꾸고 싶으면 이유와 함께 사용자에게 묻습니다.
보이는 문구·기능을 임의로 빼지 않습니다. 원본 안내 문구가 실제 동작과 달라 보여도 지우지 말고 사용자에게 묻습니다(문구를 살릴지, 동작을 문구에 맞출지).
결정은 ID로 남깁니다. PRD 결정 D-n, 사용자 UX 결정 U-n. 결정이 바뀌면 코드·테스트·명세·결정 기록을 한 번에 고칩니다. 매 작업 라운드가 끝날 때마다 문서를 코드에 맞춥니다.
비밀값은 출력하지 않습니다. 키스토어 비밀번호, API 시크릿 등은 파일로만 옮기고 대화·로그에 찍지 않습니다. 어떤 파일을 저장소에 커밋할지는 사용자 정책을 따릅니다(references/07-release.md).

에이전트 운용 규칙

범위 소유권. 모듈 에이전트는 자기 모듈 폴더만 고칩니다. 공통 파일(core, app, 의존성, 에셋, 문자열)이 필요하면 직접 고치지 않고 최종 보고의 "공통 요청"에 적습니다. 오케스트레이터가 모아서 한 번에 반영합니다. 병렬 작업 중 충돌을 막는 가장 싼 방법입니다.
테스트 시점. 모듈을 하나씩 순차로 할 때는 에이전트가 자기 모듈 테스트까지 돌립니다. 여러 모듈을 병렬 웨이브로 돌릴 때는 에이전트가 자기 폴더 dart analyze만 통과시키고, 전체 flutter test·빌드는 웨이브가 끝난 뒤 오케스트레이터가 한 번에 돌립니다. 여러 에이전트가 동시에 같은 build/를 쓰면 툴이 깨집니다.
리뷰어는 보고를 믿지 않습니다. 리뷰 지시에 "작업 에이전트의 보고 대신 코드와 명세를 직접 비교하라"를 넣습니다. 리뷰어는 코드를 고치지 않습니다.
짧은 보고. 에이전트 최종 보고는 줄 수를 제한합니다(템플릿은 templates/). 긴 내용은 로그 파일에 쓰게 합니다.
병렬 실행. 독립적인 분석·모듈·문서 작업은 한 번에 여러 Agent 호출로 띄웁니다. 이 스킬이 호출된 것 자체가 다중 에이전트 진행에 대한 동의이므로, 웨이브가 크면 Workflow 도구(작성→리뷰→수정 파이프라인)를 써도 됩니다. 웨이브 크기와 모델을 시작 전에 사용자에게 한 줄로 알립니다.
재개. 각 로그 파일 맨 위에 진행 상태 표를 두고 항상 최신으로 유지합니다. 세션이 끊기면 00-kickoff.md와 각 로그의 진행 상태 표만 읽고 이어 갑니다.

사용자에게 물어야 할 때

다음은 내가 정하지 않습니다. 선택지와 추천안을 근거와 함께 짧게 제시하고 답을 받습니다.

착수 질문 목록(references/00-kickoff.md)
비즈니스 차이 중 사용자에게 보이는 결과가 달라지는 것, 서버 확인이 필요한 것
UI 기준 OS와 그 예외 중 기능·시각이 크게 바뀌는 것
원본에 없던 라이브러리·서비스 도입, 원본 기능·문구 제거
계정이 필요한 작업(Apple Developer, Play Console, Firebase 콘솔), 비밀값 위치
저장소 커밋 정책, 원격 저장소 공개 여부

사용자가 "추천대로 해"라고 하면 추천안을 결정으로 기록(U-번호)하고 진행합니다.

단계 종료 보고

각 단계가 끝나면 사용자에게 다음만 짧게 보고합니다: 만든 문서(경로), 리뷰 결과(지적 건수·반영·반려와 이유), 사용자 결정이 필요한 항목(추천안 포함), 다음 단계. 검증하지 않은 것은 검증하지 않았다고 씁니다.

참고 파일

파일	언제
`references/00-kickoff.md`	시작할 때
`references/01-analysis.md`	원본 분석
`references/02-prd.md`	PRD 작성·합의
`references/03-design-spec.md`	UI 인벤토리·디자인 명세
`references/04-impl-plan.md`	구현 지시서
`references/05-build.md`	공통 기반·모듈 구현·통합 테스트
`references/06-device-qa.md`	실기기 QA 루프
`references/07-release.md`	서명·flavor·Firebase·CI·출시
`references/08-maintenance-docs.md`	유지보수 문서
`references/collaboration.md`	공동 작성·리뷰·교대 규칙
`references/pitfalls.md`	실제 전환에서 터진 문제와 예방법 — 단계 5 이후 수시로
`templates/*.md`	에이전트 지시서·리뷰 지시서·보고 형식

네이티브 → Flutter 전환