네이티브 → 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 | 에이전트 지시서·리뷰 지시서·보고 형식 |