Community이미지github.com

AS-IS / TO-BE (변경 전후 비교 문서)

하나의 HTML 페이지에 PR, 브랜치, 커밋되지 않은 작업 트리, 여러 저장소에 걸친 PR 묶음, 또는 이슈 하나가 데이터, API 페이로드, 서버 동작, 화면, 사용자 영향이라는 각 계층을 어떻게 바꾸는지 AS-IS와 TO-BE를 나란히 배치하고 인과 사슬로 연결하여 설명합니다. 'AS-IS TO-BE 정리해줘', '이 PR이 화면에 뭘 바꾸는지', 'payload가 어떻게 바뀌고 그래서 뭐가 달라지는지' 등 한국어 요청에도 이 스킬을 따릅니다.

TO-BE (변경 전후 비교 문서)란 무엇인가요?

이 스킬은 코드 변경(PR, 브랜치, 작업 트리, 여러 저장소 PR, 이슈) 시 각 계층(데이터, API 스펙, 동작, 화면, 사용자 영향)의 AS-IS(변경 전)와 TO-BE(변경 후)를 나란히 비교하는 HTML 문서를 자동 생성합니다. Claude Code, Cursor, Codex 등 AI 에이전트에서 사용 가능하며, 변경 사항을 증거 기반 화살표로 연결하여 리뷰어와 기획자가 실제 영향 범위를 한눈에 파악하도록 돕습니다. 주요 기능으로는 실제 산출물(마이그레이션, 스크린샷, 페이로드)만 비교하고, 변경되지 않은 계층은 명시하며, 모든 인과 관계에 파일:줄 또는 커밋을 근거로 제시합니다. 요약 상자와 세 가지 질문 카드(정해야 할 것, 먼저 볼 곳, 직접 확인하는 법)로 의사 결정을 지원하며, 롤아웃 순서와 하위 호환성 정보도 포함됩니다. 레이아웃 자체가 콘텐츠의 일부로 간주되어 420px 너비에서도 가로 스크롤 없이 깔끔하게 보이도록 설계되었습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/chordpli/asis-tobe/tree/main

Installed? Explore more 이미지 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

TO-BE (변경 전후 비교 문서)은(는) 무엇을 하나요?

변경이 닿는 계층을 찾아, 각 계층의 AS-IS(변경 전)와 TO-BE(변경 후)를 나란히 놓고, 증거 기반 화살표로 연결합니다: "이 필드가 사라져서 이 응답이 바뀌고, 그래서 이 화면에서 이 항목이 사라집니다(또는 나타납니다)." 코드가 바뀌었지만 사용자가 보는 화면이 그대로라면, 그렇게 결론을 내리세요. 변경을 지어내지 마세요.

아래 명령어에서 <skill>은 이 스킬의 기본 디렉터리입니다: 이 SKILL.md가 들어 있는 폴더(사용자 설치 시 ~/.claude/skills/asis-tobe, 프로젝트 설치 시 <project>/.claude/skills/asis-tobe). 명령어를 실행하기 전에 실제 경로로 바꾸세요.

원칙

  1. 나란히 비교. AS-IS는 왼쪽, TO-BE는 오른쪽. 절대 세로로 쌓지 않음.
  2. 실제 산출물 비교. 페이로드는 아래 「실물 고르는 순서」대로, 화면은 실제 스크린샷에서, 스키마는 실제 마이그레이션과 모델 diff에서 가져옴. 실제 산출물이 없으면: 「실물 없음: <이유>」。손으로 만든 예시는: 「예시(손으로 만듦)」。
  3. 변경된 계층만 그림. 변경되지 않은 계층은 「변경 없음」과 근거 한 줄. 빈 표는 없음.
  4. 모든 화살표에 근거. 영향 경로의 연결 지점마다 파일:줄 또는 커밋. 근거 없으면 「추정:」 표시.
  5. 이전 스펙을 여전히 사용하는 대상을 명시. 이 변경이 배포된 후에도 예전 코드를 계속 실행하는 대상: 이미 스토어에 올라간 앱 빌드, 예전 페이지가 열려 있는 브라우저 탭, 다른 서비스, 다른 호출처(관리 도구, 봇 등). 이 정보가 병합 및 롤아웃 순서를 결정.
  6. 요약 우선. 맨 위의 요약 상자만으로 결정을 내릴 수 있어야 함: 사용자 언어로 된 한 문장 결론(필드명이나 상태 코드 없음), 사용자에게 무엇이 바뀌는지, 어떻게 배포되는지, 롤백 가능한지; 그룹당 3개 이하 항목. 바로 아래에, 읽는 사람이 다음에 궁금해할 내용에 대해 질문 자체로 명명된 세 가지 카드: 「정해야 할 것」(변경이 대신 결정한 사항), 「먼저 볼 곳」(크기, 먼저 열어볼 파일, 코드가 전제하는 조건), 「직접 확인하는 법」(확인 항목, 실행 방법) — 규칙은 references/document.md("질문 카드") 참조. 결정을 좌우하는 두 가지(배지와 롤백)가 첫 화면에서 가장 잘 보여야 함. 각 사실은 한 번만 언급: 결론이나 경고에 이미 들어간 문장은 리드, 질문 카드, 시나리오에서 반복하지 않음. 아래는 모두 증거. 긴 페이로드와 방대한 표는 <details>로 접음; 삭제하지 않음. 도입부, 진행 스토리, 마무리 멘트 없음.
  7. 레이아웃이 곧 콘텐츠. 420px 너비에서 페이지가 가로로 스크롤되지 않아야 함(표만 예외). 본문 너비는 880px로 제한; 표와 나란히 비교만 전체 너비 사용. code는 식별자에만 사용; 파일 경로와 식별자만 고정폭, 한국어 설명은 절대 고정폭 안 됨. 문장은 70자 내외, 수식어는 생략. 제목 위에 있는 토글로 두 가지 색상 구성 전환: 기본 Dusk(AS-IS 베이지, TO-BE 슬레이트 블루); Bloom(AS-IS 핑크, TO-BE 민트). 시스템 다크 모드 설정을 따르지 않음. 점선과 실선은 항상 색상과 함께 사용. 인라인 코드 강조는 어두운 칩 색상이 아닌 밝은 --a-mark, --b-mark 사용. 각 색상 구성으로 한 번, 420px 너비로 한 번 렌더링.
  8. 업계 용어는 처음에 한 번 설명. 개발자, QA, 기획자가 즉시 이해하는 단어 사용. 한국어 문서에서는 레이어, 필드, API 스펙, 호출처, deprecated, breaking change, mock 응답을 사용하고, 처음 등장할 때만 괄호 안에 쉬운 설명을 덧붙임(예: codegen(서버 스펙으로 자동 생성한 타입 파일)). 내부 용어(「AC」, 화면 별명)는 처음 등장할 때 설명. 용어집: references/terms.md. 용어가 막히면 거기서 읽고, 단계를 건너뛰지 마세요.

계층(Layers)

계층비교할 내용실제 산출물 출처
데이터(데이터)테이블, 필드, 타입, 열거형, 제약 조건, 인덱스. 변경된 엔티티만 그린 엔터티 다이어그램과 모델 코드마이그레이션, ORM 스키마(prisma 등), DDL diff
API 스펙(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(예: 스크린샷용 fake 응답)은 서버의 실제 산출물이 아님. 선택한 출처의 경로를 페이로드 아래에 적음. 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은 오래되어 수백 개 파일이 섞임):
    git fetch origin main
    git merge-base origin/main HEAD
    
    diff에 이슈와 무관한 파일이 포함되면 베이스가 잘못된 것. 계층으로 나누기 전에 다시 계산.
  • 원격 없음: fetch를 건너뛰고 사용자가 지정한 베이스 사용, 또는 작업이 시작된 커밋(git merge-base main HEAD, 또는 커밋되지 않은 작업의 경우 HEAD 자체).
  • 커밋되지 않은 작업 트리: AS-IS는 HEAD, TO-BE는 작업 트리. git diff HEAD는 새 파일을 놓치므로, git ls-files --others --exclude-standard도 읽음. HEAD sha가 필요한 곳에는 「커밋 전」이라고 적음. 비교를 위해 커밋, 스태시, 체크아웃하지 않음.
  • 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" -- <생성된 타입>   # 생성된 타입이 허용하는 값

값을 설정하는 서버 코드가 없고(타입이나 열거형 정의만 있음) 생성된 타입이 그 값을 허용하더라도 도달 불가능. 파일:줄을 「변경 없음」의 증거로 기록.

값을 계산하는 위치만 이동한 경우(예: 서버의 ERROR를 이제 앱이 lastError로 계산), 두 공식을 파일:줄과 함께 나란히 배치. 동일한 입력에 대해 같은 값: 같은 화면. 다름: 다른 값을 생성하는 입력 하나를 찾아 그 상태를 캡처.

  • 도달 가능: 4단계에서 캡처.
  • 도달 불가능: 화면 계층은 「현재 데이터로는 변경 없음: <이유와 근거>」. 사라진 상태는 「실물 없음」 아래에 기록하고, 그 상태를 확인하던 테스트 단언 문자열을 통해 예전 모습을 보여줌. 확인이 필요하면 대표 시나리오 하나를 캡처하고 md5로 동일함을 증명.
  • 불확실: 캡처.

4. 계층별 실제 산출물 수집

  • 데이터: 세 부분, 이 순서로.
    1. 엔터티 다이어그램, 펼침. 변경된 엔터티와 직접 연결된 엔터티만, 한쪽당 6개 이하. JSON으로 작성하고 스크립트가 양쪽 모두를 인라인 SVG로 그리도록 함: python3 -I <skill>/scripts/erd.py <spec.json>(spec 형식은 스크립트 헤더에 있음). 절대 손으로 SVG를 그리거나 다이어그램 라이브러리를 로드하지 않음; 페이지는 자체 포함됨. 스크립트가 양쪽을 비교하여 추가, 삭제, 변경된 필드와 엔터티를 자체적으로 표시하므로, 각 쪽을 해당 커밋에서 실제로 있는 그대로 작성.
    2. 모델 코드, 접음(<details>): 코드가 가지고 있는 모델(struct, class, ORM 스키마) 그대로, 베이스와 현재. python3 -I <skill>/scripts/code_diff.py <ASIS.txt> <TOBE.txt> --label "<이름 (경로)>" --start-a <줄> --start-b <줄>로 모델당 한 줄 diff; 새 모델이나 삭제된 모델은 없는 쪽에 /dev/null 사용. 스크립트가 변경된 줄을 계산하고 두 보기(나란히, 합쳐서)를 제공하여 독자가 전환할 수 있게 함; 절대 수동으로 줄 표시하지 않음.
    3. 필드 표, 접음: 다이어그램이 생략한 것(기본값, 제약 조건, 인덱스, 기존 행 처리). 관계가 없는 단일 필드 변경은 다이어그램 불필요: 필드 표에 한 행, 펼쳐서 보여줌. AS-IS에 저장된 스키마가 없던 경우(메모리, 파일), asis_note와 함께 스크립트에 tobe만 제공하고 데이터가 있던 위치(파일:줄)를 명시; 그러면 모델 코드가 AS-IS 증거가 되므로 해당 <details>는 펼쳐둠. 첫 테이블을 생성하는 마이그레이션은 TO-BE. 이미 배포된 마이그레이션을 정리하는 경우, 「이미 반영()」이 영향 경로의 첫 연결.
  • 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. 영향 경로 연결

...

7. 롤아웃 순서 결정

...

8. 배지 결정

...

9. 문서 생성

...

10. 캡처 후 보정 (선택 사항)

...

스크립트

<skill>/scripts/ 아래 스크립트 목록:

스크립트용도입력
erd.py엔터티 다이어그램을 인라인 SVG로 그림JSON spec
code_diff.py두 텍스트 파일의 라인 단위 diff, 나란히/통합 보기텍스트 파일
capture.sh프로젝트별 설정으로 스크린샷 캡처프레임워크 이름, 포트

참고 자료

관련 스킬