시스템 디프은(는) 무엇을 하나요?

**시스템 디프(system diff)**는 실행 중인 시스템에 변경이 미치는 영향을 보여줍니다: 추가, 제거 또는 변경되는 컴포넌트와 흐름, 개체가 이제 이동할 수 있는 상태, 뒤집히는 사실들, 그리고 새롭게 발생할 수 있는 장애 방식입니다. 라인 디프는 증거이고, 시스템 디프는 리뷰어가 필요한 이야기입니다.

변경 사항을 명세(spec)로 모델링하고, 스크립트가 명세를 비트(beat: 제목, 각 다이어그램의 이전/이후, 장애, 마무리)로 구성된 비디오로 렌더링합니다. 아래에서 <script>는 이 스킬 폴더에 있는 scripts/system-diff.mjs의 절대 경로입니다.

1. 설정 확인

node <script> doctor를 실행합니다. 설정이 완료된 머신에서는 Ready.로 끝납니다.

다른 메시지로 끝나거나 node가 없는 경우, 사용자에게 /setup-system-diff를 실행하라고 요청하고 중단하세요. 이 명령어는 이 스킬에 필요한 모든 것을 설치합니다.

2. 변경 사항 수집

변경 사항은 풀 리퀘스트, 브랜치 또는 커밋 범위입니다. 지정된 것이 없으면 현재 브랜치를 기준 브랜치(풀 리퀘스트의 경우 베이스 브랜치, 그 외에는 저장소의 기본 브랜치)와 비교합니다. 어느 쪽도 명확하지 않으면 사용자에게 물어보세요.

변경 사항의 헤드(HEAD)에 해당하는 체크아웃에서 작업하세요. 4단계에서 증거를 디스크의 파일과 대조하기 때문입니다.

전체 디프(gh pr diff <number> 또는 git diff <base>...<head>)와 풀 리퀘스트 설명(또는 커밋 메시지)을 읽습니다.
호출(call), 쿼리(query), 스케줄(schedule), 설정 값(config value), 스키마(schema), 권한(permission)을 건드리는 모든 헝크(hunk)에 대해, 베이스와 헤드에서 해당 코드 주변을 충분히 읽어 런타임에 누가 누구를 호출하는지 파악합니다.

베이스와 헤드 각각에 대해 다음을 말할 수 있을 때 완료됩니다: 무엇이 실행되는지, 각 요소가 무엇과 통신하는지, 무엇을 저장하는지, 그리고 각각이 의존하는 요소가 다운되었을 때 어떤 일이 일어나는지.

3. 시스템 변경 모델링

변경 사항을 주장(claim)으로 나열하세요. 각 주장은 이를 보여주는 path:line을 가집니다. 주장은 4단계의 명세가 되고 6단계에서 사용자에게 전달됩니다.

컴포넌트(Components): 실행되거나 데이터를 보관하는 것들 (예: 서비스, 작업, 큐, 테이블, 외부 API). 흐름을 따라가는 데 필요한 변경되지 않은 컴포넌트도 포함합니다.
흐름(Flows): 한 컴포넌트가 다른 컴포넌트를 호출, 읽기 또는 쓰기하는 것.
상태와 전이(States and transitions): 한 개체가 거쳐가는 단계 (예: 주문, 작업, 세션, 연결)와 이를 다음 단계로 이동시키는 이벤트.
사실(Facts): 시스템에 대한 한 가지 사실로, 이전 값과 이후 값이 있는 것 (예: 설정 값, 제한, 스키마, 권한, 소요 시간).
장애 모드(Failure mode): 가장 중요한 새로운 장애 방식. 일반적으로 새로운 컴포넌트나 의존성이 중단되는 경우이며, 기존 의존성의 장애 비용이 증가하거나 개체가 특정 상태에 갇히는 경우도 포함됩니다. 그때 어떤 일이 발생하는지(각 컴포넌트가 무엇을 하는지, 개체가 어디에 도달하는지)를 설명합니다.

모든 주장은 이를 보여주는 라인을 인용합니다. 인용할 라인이 없는 주장은 추측이며 비디오에서 제외됩니다.

일부 변경 사항은 시스템을 그대로 둡니다: 리팩터링, 포맷팅, 테스트, 주석, 코드에서만 보이는 이름 변경 등. 이런 경우 사용자에게 변경 사항에 시스템 디프가 없으며 어떤 종류의 변경인지 알리고, 비디오 없이 종료합니다. 실행 중인 시스템이 보는 것(예: 라우트, 테이블, 큐, 설정 키)의 이름 변경은 시스템 변경입니다.

주장에 따라 비디오가 그리는 다이어그램이 결정됩니다:

컴포넌트 뷰(Component view): 연결 상태(와이어링)가 변경될 때 (컴포넌트나 흐름이 추가/제거되거나, 흐름이 다른 것을 전달하는 경우).
상태 차트(Statechart): 생명 주기가 변경될 때 (상태 값이 추가/제거되거나, 재시도/취소 단계가 나타나거나, 이벤트가 다른 곳으로 이끄는 경우).
연결과 생명 주기는 동일하지만 값만 변경되는 경우(예: 타임아웃 증가)는 사실(fact)로, 컨텍스트를 제공하는 다이어그램 아래에 표시합니다.
둘 다(Both): 둘 다 변경되고 각각이 다른 하나가 보여줄 수 없는 것을 보여줄 때. 각 다이어그램은 두 개의 비트를 추가하므로, 하나의 다이어그램이 완전히 설명할 수 있는 변경은 하나만 사용합니다.

디프의 모든 헝크가 주장으로 다뤄지거나 시스템을 변경하지 않는 것으로 분류되고, 다이어그램을 선택했을 때 완료됩니다.

4. 명세 작성

주장을 명세(spec)로 변환합니다. SPEC.md의 모든 필드, 레이아웃 규칙, 캡션 및 내레이션 작성 방법을 따르세요. 저장소 외부의 임시 폴더에 system-diff.json으로 저장합니다.

node <script> check <spec> --repo <repository root>를 실행합니다.

정확히 The spec is valid.라고 출력되고 경고가 없을 때 완료됩니다. check는 인용된 각 라인이 존재하는지 확인합니다. 해당 라인이 주장을 보여주는지는 사용자가 확인해야 합니다.

5. 시트 빌드 및 검토

node <script> build <spec> --repo <repository root> --out <scratch folder>를 실행합니다. 비디오 경로, 경고, 연락처 시트(contact sheet: 각 비트의 프레임이 하나씩 포함된 이미지), 동일한 프레임을 전체 크기로 보관하는 stills 폴더를 출력합니다.

연락처 시트로 전체 그림을 확인하고, 스틸로 작은 텍스트를 확인하며 각 프레임을 점검합니다:

모든 레이블, 값, 캡션이 온전하고 읽기 쉬운지;
모든 흐름 선이 연결되지 않은 상자나 레이블을 피해 깔끔하게 지나가는지;
각 이전(before) 프레임은 이전에 존재했던 것만 보여주고, 각 이후(after) 프레임은 변경으로 추가된 모든 것을 보여주는지;
상태 차트의 시작 점(dot)이 개체가 시작하는 상태 위에 있는지;
장애 프레임이 올바른 컴포넌트나 상태를 표시하며, 각 메모가 설명하는 대상의 하단 가장자리에 위치하는지;
각 캡션이 해당 프레임의 내용을 설명하는지.

명세를 수정하고 빌드가 No warnings.를 출력하고 시트가 모든 검사를 통과할 때까지 다시 빌드합니다. 대부분의 프레임 문제는 텍스트를 줄이거나 상자를 다른 셀로 이동하면 해결됩니다. 둘 다 해결되지 않는 문제는 이름을 붙여 인계 시 언급합니다.

6. 인계

사용자에게 비디오 경로, 무엇을 보여주는지에 대한 한 문장, 증거와 함께 주장 목록, 그리고 생략했거나 확신이 없는 내용을 전달합니다. 비디오를 어디든 게시하는 것은 사용자의 결정입니다.

시스템 디프