AS-IS / TO-BE
변경 사항이 닿는 계층을 찾고, 각 계층에 대해 AS-IS와 TO-BE를 나란히 배치하며, 계층 간을 증거 기반 화살표로 연결합니다: "이 필드가 삭제되어 응답이 바뀌고, 그 결과 이 화면에서 이 항목이 사라지거나 나타납니다." 코드가 바뀌었지만 사용자에게 보이는 것이 동일하다면, 그 사실을 결론으로 명시하세요. 변경 사항을 임의로 만들어내지 마세요.
아래 명령어에서 <skill>은 이 스킬의 기본 디렉토리입니다: 이 SKILL.md가 들어 있는 폴더입니다 (사용자 수준 설치의 경우 ~/.claude/skills/asis-tobe, 프로젝트 수준 설치의 경우 <project>/.claude/skills/asis-tobe). 명령어를 실행하기 전에 실제 경로로 바꾸세요.
원칙
- 나란히. AS-IS는 왼쪽, TO-BE는 오른쪽. 절대 세로로 쌓지 않습니다.
- 실물 비교. 페이로드는 아래 "실물 고르는 순서"에 따라, 화면은 실제 스크린샷에서, 스키마는 실제 마이그레이션과 모델 diff에서 가져옵니다. 실물이 없으면: 「실물 없음: <이유>」. 손으로 만든 예시: 「예시(손으로 만듦)」.
- 변경된 계층만 그림. 변경되지 않은 계층은 「변경 없음」과 증거 한 줄만 표시합니다. 빈 표는 없습니다.
- 모든 화살표에 증거가 있습니다. 영향 경로의 각 연결에 대해
파일:줄또는 커밋을 명시합니다. 증거가 없으면 「추정:」으로 표시합니다. - 누가 여전히 예전 스펙을 사용하는지 말하세요. 이 변경 사항이 출시된 후에도 예전 코드를 계속 실행하는 것들: 이미 스토어에 있는 앱 빌드, 여전히 예전 페이지가 열려 있는 브라우저 탭, 다른 서비스, 관리자 도구나 봇과 같은 다른 호출처. 이에 따라 병합 및 출시 순서가 결정됩니다.
- 요약 우선. 상단의 요약 상자만으로 결정을 내릴 수 있어야 합니다: 사용자의 언어로 된 한 문장 결론 (필드명이나 상태 코드 없음), 사용자에게 무슨 변경이 있는지, 어떻게 출시되는지, 롤백 가능한지; 그룹당 최대 3개 항목. 바로 아래에, 세 개의 카드가 모든 독자가 다음에 궁금해할 질문에 답하며, 역할이 아닌 질문으로 이름을 붙입니다: 「정해야 할 것」 (변경 사항이 누군가를 대신해 결정한 것), 「먼저 볼 곳」 (크기, 먼저 열어볼 파일, 코드가 전제하는 사항), 「직접 확인하는 법」 (확인 항목, 실행 방법) — 규칙은 references/document.md ("질문 카드")를 참조하세요. 결정을 좌우하는 두 가지(뱃지와 롤백)는 첫 화면에서 가장 잘 보여야 합니다. 각 사실을 한 번만 말하세요: 이미 결론이나 경고에 포함된 문장은 리드, 질문 카드, 시나리오에서 반복하지 않습니다. 아래의 모든 것은 증거입니다. 긴 페이로드와 방대한 표는
<details>로 접되, 삭제하지 마세요. 서론, 진행 스토리, 마무리 멘트는 없습니다. - 레이아웃이 콘텐츠입니다. 420px 너비에서 페이지는 가로 스크롤이 생기지 않아야 합니다 (표만 허용). 본문 너비는 880px로 제한되며, 표와 나란히 비교만 전체 너비를 사용합니다. 표 내의
code는 식별자에만 사용하고, 파일 경로와 식별자만 고정폭으로, 한국어 설명은 절대 고정폭으로 하지 않습니다. 문장은 약 70자, 수식어는 자릅니다. 제목 위의 토글로 전환되는 두 가지 색상 구성: 기본 Dusk (베이지 AS-IS, 슬레이트 블루 TO-BE), Bloom (핑크 AS-IS, 민트 TO-BE). 시스템 다크 모드 설정을 따르지 않습니다. 점선과 실선은 항상 색상을 동반합니다. 인라인 코드 하이라이트는 어두운 칩 색상이 아닌 밝은--a-mark,--b-mark를 사용합니다. 각 구성과 420px에서 한 번씩 렌더링합니다. - 업계 용어는 한 번만 설명합니다. 개발자, QA, 기획자가 즉시 이해하는 용어를 사용하세요. 한국어 문서에서는 레이어, 필드, API 스펙, 호출처, deprecated, breaking change, mock 응답을 사용하며, 첫 번째 사용 시에만 괄호 안에 간단한 설명을 추가합니다 (예: codegen(서버 스펙으로 자동 생성한 타입 파일)). 내부 전문 용어(「AC」, 만든 화면 별명 등)는 첫 사용 시 무엇인지 명시하세요. 용어집: references/terms.md. 용어가 막히면 거기서 읽고, 단계를 건너뛰지 마세요.
계층
| 계층 | 비교 대상 | 실물 출처 |
|---|---|---|
| 데이터 | 테이블, 필드, 타입, enum, 제약 조건, 인덱스. 변경된 엔티티만의 다이어그램, 모델 코드 | 마이그레이션, ORM 스키마(prisma 등), DDL diff |
| API 스펙 | 요청 및 응답 페이로드, 이벤트, codegen 타입. 필드별 추가, 삭제, 타입 변경, 의미 변경 | OpenAPI diff, 응답 DTO, 테스트 fixture |
| 동작 | 같은 입력에 대해 서버와 클라이언트가 생성하는 결과 | 테스트 단언 diff, 상태 전이 코드 |
| 화면 | 같은 상태의 화면 캡처 두 장 | 프로젝트의 스크린샷 도구 (references/adapters.md, 「프로젝트 어댑터」) |
| 사용자 영향 | 사용자가 할 수 있게 되거나 할 수 없게 되는 것, 변하는 수치. 출시 순서로 인한 중간 상태 포함 | 이슈 AC, 위 계층들의 합, 호환성 표 |
계층별 체크리스트와 일반적인 함정: references/layers.md를 참조하세요.
실물 고르는 순서 (API 스펙)
서버 테스트 fixture > OpenAPI 예시 > 기록된 실제 호출 > 클라이언트 mock 응답. 완전한 형태로 존재하는 첫 번째 것을 선택하세요. 상위 출처가 부분적일 경우 (변수로 빌드된 fixture, 또는 테스트가 인라인으로 요청을 빌드하고 필드별로 단언하는 경우) 실제 호출을 기록했다면, 패널에 상위 출처를 표시하고 전문은 기록된 호출을 표시하며, 각각 출처를 라벨링합니다. 기록된 호출은 실행마다 달라지는 값(id, 타임스탬프)을 포함하므로, code_diff.py --mask id,time으로 이러한 페이로드를 비교하고 출처 줄에 그렇게 명시하여, 새로운 id가 변경된 필드로 계산되지 않게 합니다. 클라이언트 mock (예: 스크린샷용 가짜 응답)은 서버의 실제 아티팩트가 아닙니다. 선택한 출처의 경로를 페이로드 아래에 작성하세요. fixture가 변수로 빌드되어 전체 JSON이 없는 경우, 테스트의 기대값에서 옮겨 적고 「예시(테스트 기대값에서 옮김)」으로 라벨링하며, 축약된 부분은 …를 사용하세요. 기대값에 없는 필드는 채우지 말고 …로 남겨두세요. 다른 곳에서 값을 빌려온 경우(mock 응답 등), 해당 필드 옆에 출처를 표시하세요.
절차
1. 범위 설정
- PR 입력: PR 번호로 diff를 가져옵니다 (
gh pr diff <n> -R <repo>). 경로나 브랜치만 주어지면 스택된 PR의 메인을 베이스로 잡아 다른 사람의 변경 사항을 섞어버립니다. - 이슈 입력: 각 저장소에서 PR을 찾습니다 (
gh pr list -R <repo> --search <key> --state all). 두 개 이상의 저장소는 하나의 문서에 넣습니다. - PR 없음: 작업 트리에서
git diff <base>...HEAD를 사용하며,<base>는 포크 포인트로, 저장소 루트에서 계산합니다 (로컬main은 오래되어 수백 개의 파일을 섞습니다):
diff에 이슈와 무관한 파일이 포함되면 베이스가 잘못된 것입니다. 계층으로 나누기 전에 다시 계산하세요.git fetch origin main git merge-base origin/main HEAD - 원격 없음: fetch를 건너뛰고 사용자가 지정한 베이스를 사용하며, 그렇지 않으면 작업을 시작한 커밋을 사용합니다 (
git merge-base main HEAD, 또는 언커밋된 작업의 경우HEAD자체). - 언커밋된 작업 트리: AS-IS는
HEAD, TO-BE는 작업 트리입니다.git diff HEAD는 새 파일을 놓치므로git ls-files --others --exclude-standard도 읽어야 합니다. 헤드 SHA가 요청되는 곳마다 「커밋 전」이라고 씁니다. 비교를 위해 커밋, stash, 체크아웃하지 마세요. - PR이나 이슈 없음: 대상은 그것이 무엇인지에 따라 이름이 붙여집니다 (「 작업 트리 변경」, 「 브랜치」). 출시 표는 출시되는 단위 (브랜치, 「작업 트리 커밋」)당 한 행을 얻으며 PR 셀에 그것을 명명하고, 이슈 키는 생략되며 만들지 않습니다.
- 저장소당 한 줄
<repo> <짧은 베이스 SHA> → <짧은 브랜치 SHA>를 작성합니다. 보고서에서 그대로 사용하세요. 문서에서 PR과 SHA는 요약 카드의 출시 순서 표와 베이스 표 (references/document.md)에 한 번만 들어가며, 헤더에는 넣지 않습니다.
2. 변경된 파일들을 계층에 할당
각 파일은 하나 이상의 계층에 할당되며, 불명확하면 엽니다. 테스트 파일은 할당되지 않으며, 동작 계층의 증거입니다. 이 표는 문서가 어떤 계층 섹션을 가질지 결정하며, 작업 자료이므로 문서에 인쇄되지 않습니다.
3. 먼저 화면이 실제로 변경되는지 결정
화면 코드가 변경되었더라도, 캡처하기 전에 묻습니다: 변경된 분기가 현재 데이터로 도달 가능한가? 분기가 의존하는 값을 하나 선택하고 서버가 실제로 그 값을 생성하는지 찾습니다.
# 예제: 앱에서 stockState === 'SOLD_OUT'일 때 「품절」 뱃지를 보여주던 분기를 제거한 경우
git -C <서버 저장소> grep -n "SOLD_OUT" -- <소스 파일> # 서버가 어느 응답에 이 값을 넣는가?
git -C <앱 저장소> grep -n "stockState" -- <생성된 타입> # 생성된 타입이 허용하는 값
값을 설정하는 서버 코드가 없는 경우 (타입이나 enum 정의만 있는 경우) 도달 불가능하며, 생성된 타입이 허용하더라도 마찬가지입니다. 「변경 없음」의 증거로 파일:줄을 기록합니다.
값을 계산하는 위치만 이동하는 경우 (예: 서버의 ERROR가 이제 앱에서 lastError로 계산됨), 두 공식을 파일:줄과 함께 나란히 놓습니다. 같은 입력에 같은 값: 같은 화면. 다름: 다른 값을 생성하는 입력을 하나 찾아 그 상태를 캡처합니다.
- 도달 가능: 4단계에서 캡처합니다.
- 도달 불가능: 화면 계층은 「현재 데이터로는 변경 없음: <이유와 근거>」를 받습니다. 사라진 상태를 「실물 없음」 아래에 기록하고, 그 상태를 확인했던 테스트 문자열을 통해 예전 모양을 보여줍니다. 확인이 필요하면, 대표 시나리오 하나를 캡처하고 md5로 동일함을 보여줍니다.
- 확실하지 않음: 캡처합니다.
4. 계층별 실물 수집
- 데이터: 세 부분, 이 순서대로.
- 엔티티 다이어그램, 펼쳐서 표시. 변경된 엔티티와 직접 연결된 엔티티만, 변당 6개 이하. JSON으로 작성하고 스크립트가 양쪽을 인라인 SVG로 그리게 합니다:
python3 -I <skill>/scripts/erd.py <spec.json>(spec 형식은 스크립트 헤더에 있습니다). SVG를 직접 그리거나 다이어그램 라이브러리를 로드하지 마세요; 페이지는 자체 포함되어야 합니다. 스크립트는 두 변을 비교하여 자체적으로 추가, 제거, 변경된 필드와 엔티티를 표시하므로, 각 변을 그 커밋에서의 실제 모습 그대로 작성하세요. - 모델 코드, 접음 (
<details>): 코드가 보유한 대로의 모델 (struct, class, ORM 스키마)을 베이스와 현재 시점에서. 모델당 한 줄 diff는python3 -I <skill>/scripts/code_diff.py <ASIS.txt> <TOBE.txt> --label "<이름 (경로)>" --start-a <줄> --start-b <줄>로 생성하며, 새 모델이나 제거된 모델은 누락된 변에/dev/null을 사용합니다. 스크립트는 변경된 줄을 계산하고 독자가 전환할 수 있도록 두 보기(나란히, 합쳐서)를 모두 출력하며, 줄을 직접 표시하지 마세요. - 필드 표, 접음: 다이어그램이 생략한 것 (기본값, 제약 조건, 인덱스, 기존 행 처리). 관계가 없는 단일 변경 필드는 다이어그램이 필요 없습니다: 필드 표에 한 행, 펼쳐서 표시. AS-IS가 저장된 스키마가 없는 경우 (메모리, 파일),
asis_note에 데이터가 있던 위치(파일:줄)를 명시하여 스크립트에tobe만 제공하고, 모델 코드가 AS-IS 증거가 되므로 해당<details>는 펼쳐서 둡니다. 첫 번째 테이블을 생성하는 마이그레이션은 TO-BE입니다. 이미 출시된 마이그레이션을 정리하는 경우, 「이미 반영()」이 영향 경로의 첫 번째 링크입니다.
- 엔티티 다이어그램, 펼쳐서 표시. 변경된 엔티티와 직접 연결된 엔티티만, 변당 6개 이하. JSON으로 작성하고 스크립트가 양쪽을 인라인 SVG로 그리게 합니다:
- API 스펙: 전후 페이로드를
scripts/code_diff.py(모델 코드와 동일한 스크립트, 페이로드당 한 번 호출, 긴 것은--context 3, 기록된 호출은--mask id,time)의 라인 diff로 표시합니다. 그 아래에필드 | AS-IS | TO-BE | 시맨틱 변경. 이름이나 타입만 변경된 경우 두 셀을 한 줄로 병합합니다:<code class="old">start_time</code> → <code class="new">starts_at</code>. 호출처:- 각 저장소에서
git grep <필드>, 저장소 루트에서 (서브디렉토리는 경로를 상대적으로 만들어 0건을 반환합니다). - 출시된 버전에서도:
git grep -n <필드> <SHA>. 그 결과가 병합 및 출시 순서와 뱃지를 결정합니다. 이 작업을 하기 전에 references/adapters.md ("출시된 버전 찾기")를 읽으세요. 필수: 빌드 목록의 SHA만 확정되며, 다른 것은 「추정:」입니다. 출처가 일치하지 않으면 모든 SHA를 grep하고 하나라도 일치하면 「배포된 앱이 읽는다」로 간주합니다. 태그 이름만으로 선택하지 마세요 (태그는 같은 저장소의 다른 배포 가능 항목에 속할 수 있습니다). 빌드 목록이 실패할 경우 (예: 빌드 서비스 로그인 불가)의 간편한 폴백: 이슈나 릴리스 노트의 SHA, 그렇지 않으면 「추정:」 하한. - Codegen 출력은 호출처가 아닙니다; 서버 스펙에서 다시 생성됩니다. 별도로 「다시 뽑으면 무엇이 바뀌나」를 기록하세요.
- 또한 클라이언트의 mock 응답과 테스트 fixture에서 제거된 필드를
git grep합니다. 남아 있으면, 서버 출시 후 codegen이 다시 생성될 때 타입체크가 깨질 수 있습니다. 해당 파일들을 마지막 출시 단계 (「codegen 재생성과 fixture 정리」)로 나열하세요.
- 각 저장소에서
- 동작:
입력·상태 | AS-IS | TO-BE | 근거(테스트 이름). - 화면: 캡처하기 전에 references/screens.md ("캡처")를 읽으세요. 같은 시나리오, 데이터, 언어, 크기로 양쪽에서, 하나의 임시 작업 트리 (AS-IS용 베이스, TO-BE용 브랜치) 또는, 언커밋된 작업이거나 건드리면 안 되는 저장소의 경우 저장소 외부의 두 복사본에서, 설치와 캡처를 백그라운드에서 수행하고 md5를 비교한 다음, 10단계가 필요한 것을 다시 측정한 후 서버를 중지하고 임시 작업 트리나 복사본을 제거합니다 (사용자가 재현 가능하게 유지하길 원하면 유지); 절대 커밋하지 마세요. mock 캡처 도구가 없으면, 각 버전의 실제 서버를 자체 포트에서 실행하고 캡처합니다. 프로젝트별 캡처 명령어: references/adapters.md. 플랫폼을 캡처할 수 없는 경우(예: 네이티브) 또는 3단계에서 분기가 도달 불가능함을 발견한 경우에만 캡처를 건너뛰고, 그렇지 않으면 「실물 없음: <이유>」와 테스트 단언 문자열을 표시합니다. 확실하지 않으면 캡처합니다.
4b. 시나리오 레일 채우기
「시나리오별 전후」를 채우기 전에 references/scenario-rail.md를 읽으세요. 다른 도메인의 셀 이름: references/domains.md를 참조하세요.
| 골격 | 웹/앱 캡처 |
|---|---|
| ... | ... |
5. 계층 간 연결
한 계층의 각 변경 사항에 대해, 그 변경이 어떻게 다음 계층에 영향을 미치는지 또는 사용자에게 전달되는지 추적합니다. 파일:줄 또는 커밋 형태의 증거로 각 연결을 뒷받침합니다. 연결을 추정해야 하는 경우 「추정:」으로 표시합니다.
6. 호환성 표 작성
| 구성 요소 | AS-IS 버전 | TO-BE 버전 | 호환성 노트 |
|---|---|---|---|
| 서버 | - | ||
| 웹 앱 | - | ||
| 모바일 앱 | <앱 스토어 버전> | <앱 스토어 버전> | - |
| 기타 서비스 | <서비스 이름> | <서비스 이름> | - |
7. 출시 순서 결정
| 단계 | 작업 | 롤백 가능? | 영향받는 사용자 |
|---|---|---|---|
| 1 | 서버 배포 | 예/아니오 | - |
| 2 | 웹 앱 배포 | 예/아니오 | - |
| 3 | 모바일 앱 스토어 출시 | 아니오 | - |
| ... | ... | ... | ... |
8. 뱃지 결정
뱃지는 변경의 성격을 나타냅니다:
- 하위 호환: TO-BE 서버가 AS-IS 클라이언트와 계속 작동함
- 비호환: TO-BE 서버가 AS-IS 클라이언트와 작동하지 않음, 동시 출시 필요
- 사용자에게 보임: 화면 변경 있음
- 사용자에게 보이지 않음: 화면 변경 없음
9. 요약 카드 채우기
「정해야 할 것」, 「먼저 볼 곳」, 「직접 확인하는 법」 카드를 채웁니다. 각 카드는 독자가 다음으로 궁금해할 질문에 답합니다.
10. 최종 확인
- 모든 증거가 검증되었는가?
- 모든 화살표에 출처가 있는가?
- 변경되지 않은 계층이 적절히 표시되었는가?
- 페이지가 420px에서 가로 스크롤 없이 표시되는가?
- 두 색상 구성에서 모두 잘 보이는가?
- 요약만으로 결정을 내릴 수 있는가?
참조
- references/document.md - 문서 구조와 질문 카드 규칙
- references/layers.md - 계층별 체크리스트와 일반적인 함정
- references/screens.md - 화면 캡처 지침
- references/adapters.md - 프로젝트별 어댑터와 출시된 버전 찾기
- references/scenario-rail.md - 시나리오 레일 채우기 지침
- references/domains.md - 도메인별 셀 이름
- references/terms.md - 용어집