deploy-checklist

name	deploy-checklist
description	PR 변경 내용을 분석하여 이번 배포에 맞는 DEV/PROD 체크리스트를 자동 생성합니다. /pr 이후 사용.
when_to_use	배포 체크리스트, 배포 전 확인할 것, DEV와 PROD 점검 목록. PR 본문은 pr.
allowed-tools	Read, Write, Glob, Grep, Bash

역할

현재 브랜치의 변경 사항을 분석하여, 이번 배포에서 실제로 확인해야 할 항목만 추려낸 체크리스트를 생성한다. 템플릿(.local.claude/deploy-checklist-template.md)에서 해당 항목만 활성화하고, 해당 없는 섹션은 제거한다.

/pr 이후에 사용하는 것을 권장. PR 작성 시 이미 분석한 변경 범위를 체크리스트로 연결.

외부 데이터 의존

데이터	경로	필수/선택	부재 시 동작
프로젝트 컨텍스트	CLAUDE.md	선택	일반 SW 가정으로 진행, [프로젝트 규칙 미확인] 태그
봇 인덱스	bot/INDEX.md 또는 .local.claude/ONBOARDING.md	선택	디렉터리 Glob 으로 fallback
비즈니스 규칙	.local.claude/biz-rules.md	선택	Tier 1(도메인 무관) 점검만 수행
모듈 상세	.local.claude/modules/{name}.md	선택	코드 Grep 직접 fallback
비즈니스 규칙 변경 영향 매핑	.local.claude/biz-rules.md 의 변경 영향 매핑 섹션	선택	배포 영향 체크 축소, 일반 체크리스트만
회귀 테스트 시나리오	.local.claude/regression-scenarios.md 또는 **/tests/regression/	선택	회귀 섹션 생략, 수동 검증 권장
PR 초안	.local.claude/pr/ 최신 또는 git branch	선택	이슈번호와 URL 자동 추출 불가, 사용자 질문으로 fallback

레포지토리 정보

GitHub owner/repo/base branch 는 프로젝트 컨텍스트에서 추출:

• git remote -v 로 remote URL 확인
• 추출 불가 시 사용자 확인

정보 수집

1단계: 변경 분석

# 변경된 파일 목록
git diff develop --stat

# 커밋 로그
git log develop..HEAD --oneline

# 변경 파일 상세 (파일명만)
git diff develop --name-only

2단계: PR 파일 확인 (있으면)

.local.claude/prs/ 에서 오늘 날짜 또는 가장 최근 PR 파일을 읽는다. 이미 분석된 영향범위/테스트 방법이 있으면 재활용.

3단계: 변경 영향 분류

변경된 파일 경로를 분석하여 아래 영향 매트릭스를 채운다:

모듈 영향 판별

프로젝트 모듈에서 영향으로의 매핑은 다음 위치에서 추출:

• CLAUDE.md 의 "프로젝트 구조" 섹션
• bot/INDEX.md 또는 .local.claude/INDEX.md (있을 시)
• .local.claude/modules/*.md 카탈로그 (있을 시)

매핑 패턴 예시 (변경 파일 경로를 모듈로 매핑):

• 비즈니스 모듈 디렉터리는 해당 모듈명
• 공통 모듈 (cmn, common, shared, core 등 키워드)은 전체 영향 가능
• Web/API 진입점 (controller, ctrl)은 컨트롤러 영향
• 스케줄러와 외부연동 디렉터리는 해당 컴포넌트

[1M 활용] 서브 분할 없이 메인에서 직접 다중 파일 동시 로드 후 교차:

• 로드: .local.claude/biz-rules.md 의 변경 영향 매핑 섹션, .local.claude/modules/{변경모듈들}.md, 이벤트 카탈로그 (bot/*.md 또는 modules 이벤트 섹션), 회귀 테스트 시나리오 파일(있을 시)
• 교차: {biz-rules 변경 영향 매핑 vs 이번 diff 의 실제 변경 유형}, {modules 이벤트 발행 vs regression 시나리오 커버}, {고객사 분기 변경 vs 환경 설정 파일}

영향 범위 판별

Tier 1: 도메인 무관 일반 변경 유형 (모든 프로젝트 공통):

변경 유형	일반 판별 패턴	활성화 카테고리
SQL 변경	DAO, Mapper, Repository 파일 변경	DEV-3(격리/테넌트), DEV-5(회귀)
API 변경	Controller, Service 메서드 추가/수정	DEV-3(격리/테넌트), DEV-5(회귀)
DB 스키마	DDL 파일, 테이블/컬럼 추가 언급	PROD-1(안전장치 강화), DEV-1/PROD-2(환경 정합성)
설정 변경	application*.yml, .env* 등 환경 설정	PROD-7(환경별), DEV-7/PROD-8(스케줄러)
외부 연동	HTTP 클라이언트, 외부 API 호출	DEV-6(외부연동), PROD-6, PROD-2(IP 화이트리스트/CORS)
프론트엔드만	HTML, JS, CSS (백엔드 변경 없음)	DEV-4(기능 검증)만

Tier 2: 프로젝트 도메인 특화 변경 유형 (.local.claude/biz-rules.md 의 변경 영향 매핑 섹션 자동 활용):

biz-rules.md 에 변경 영향 매핑 표가 있으면 그 표의 변경 유형을 자동 추가.

자주 등장하는 카테고리 예시 (프로젝트마다 다름):

• 공통 코드값 추가: 운영 DB 정합성 (코드값 누락이 가장 흔한 사고)
• 이벤트 발행 변경: 수신 모듈 연쇄 회귀
• 승인 모듈 변경: 모든 승인 흐름 회귀
• 격리 키(있는 프로젝트만) 변경: 데이터 격리 회귀
• 환경별 분기 변경: 해당 환경 동기화 점검

이벤트 영향 추적

변경된 파일에 이벤트 관련 코드가 있으면, 연쇄 영향을 추적:

프로젝트의 이벤트 카탈로그는 다음 위치에서 추출:

• bot/INDEX.md 또는 .local.claude/ONBOARDING.md (이벤트 흐름 섹션)
• .local.claude/modules/*.md (각 모듈의 "이벤트 연동" 섹션)
• 코드 직접 검색: Grep "@EventListener|EventPublisher" --include "*.java"

이벤트 발행측이 변경되면 수신측 모듈도 회귀 테스트 대상에 포함.

체크리스트 생성 규칙

항상 포함 (모든 배포)

• 배포 기본 정보
• DEV-1 (배포 실행)
• DEV-2 (기동 확인): [필수]만
• DEV-4 (변경 기능 직접 검증): PR의 테스트 방법 섹션을 테이블에 자동 채움
• PROD-1 (안전장치): [필수]만
• PROD-2 (배포 실행)
• PROD-3 (기동 확인): [필수]만
• PROD-4 (변경 기능 빠른 재확인)
• PROD-8 로그/에러: [필수]만
• 최종 판정

조건부 포함

조건	포함 섹션	상세 수준
SQL/API 변경	DEV-3(격리/테넌트), PROD-5	[필수]
모듈 간 영향 또는 이벤트 변경	DEV-5(회귀)	회귀 테스트 시나리오 파일(있을 시)에서 해당 모듈 시나리오를 읽어 체크리스트에 포함
외부 연동 변경	DEV-6, PROD-6	해당 연동 대상만
설정 파일 변경	DEV-7, PROD-8 스케줄러	[필수] + 해당 스케줄러
공통 모듈 (cmn/common/shared/core) 변경	DEV-3 + DEV-5 전체 + DEV-6	[필수] + [상세]
고객사 분기 변경	PROD-7 해당 고객사 섹션	전체
DB 스키마 변경	PROD-1 [상세](롤백 DDL)	[필수] + [상세]
프론트엔드만 변경	DEV-4만	나머지 전부 제거

제거 규칙

• 조건에 해당하지 않는 섹션은 통째로 제거 (취소선이 아닌 제거)
• [상세] 항목은 조건에 해당할 때만 포함, 아니면 제거
• 회귀 테스트(DEV-5)는 변경된 모듈 + 이벤트 연쇄 모듈의 항목만 남기고 나머지 모듈 제거
• 외부 연동(DEV-6)은 변경된 연동 대상만 남기고 나머지 제거
• 스케줄러(PROD-8)는 스케줄러 모듈 변경이 아니면 [필수] 항목 (예: 매일 발송되는 작업 등) 만

DEV-4 자동 채우기

PR 파일 또는 git diff 분석에서 테스트 시나리오를 추출하여 테이블을 채운다:

1. PR 파일의 "테스트 방법" 섹션이 있으면 그대로 테이블 행으로 변환
2. PR 파일이 없으면 변경된 Controller/HTML/JS에서 URL과 기능을 추출 (프로젝트 라우팅 컨벤션 따름):
   • 백엔드 매핑 어노테이션은 URL로
   • 템플릿 파일명은 화면 경로로
   • JS 파일명은 대응 화면으로

예시:

| # | 화면 (URL/메뉴) | 확인할 기능 | 예상 결과 (완료 조건) | DEV 확인 | PROD 확인 |
|---|----------------|-----------|-------------------|----------|-----------|
| 1 | /view/{module}/{page} | {기능명} | {기능 정상 동작} | [ ] | [ ] |
| 2 | /api/{module}/{endpoint} | API 응답 | 200 OK + 데이터 정상 | [ ] | [ ] |

출력 형식

[메타인지] 체크리스트 산출 직전, 핵심 결론 Top 3 (활성화된 섹션 선정, DEV-5 회귀 범위, PROD-7 고객사 분기)에 대해:

1. 근거 재점검 (변경 파일 경로에서 활성화 섹션으로의 매핑이 실제 diff로 환원되는가)
2. 전제 검증 (공통 모듈 변경이면 DEV-3, DEV-5, DEV-6 모두 활성화됐는가)
3. 반대 증거 ("이 회귀 시나리오가 과대 아닌가? 이 고객사 분기가 왜 영향받나, 설정 차이가 실제로 있나?")

파일 저장

Frontmatter (CONTRACT 7-2절 표준): category: deploys, retention: 30d

• 경로: .local.claude/deploys/YYYY-MM-DD-#이슈번호-{간략설명}.md
• 이슈 번호는 브랜치명에서 추출 (feature/#123-xxx에서 #123)
• 디렉터리 없으면 mkdir -p로 생성

화면 출력

체크리스트 전문을 화면에 출력한다. 상단에 요약:

## 배포 체크리스트 요약

- **변경 모듈**: {모듈 목록}
- **영향 범위**: {변경 유형}
- **활성화된 검증**: 기동확인 + 기능검증 + ... (조건부 포함 결과)
- **DEV 확인 항목**: N개
- **PROD 확인 항목**: N개
- **저장 위치**: `.local.claude/deploys/YYYY-MM-DD-#N-{설명}.md`

제약사항

• 템플릿(.local.claude/deploy-checklist-template.md)의 구조와 문구를 기반으로 생성. 임의 항목 추가 금지
• 판별이 애매한 경우 포함하는 방향으로 (안 해서 사고나는 것 > 불필요하게 한 번 더 확인하는 것)
• $ARGUMENTS가 있으면 추가 맥락으로 활용 (예: /deploy-checklist {고객사} 동기화 포함)
• PR 파일이 없어도 git diff만으로 생성 가능

다른 스킬과의 경계

질문	담당	이 스킬
PR 본문 작성 (변경 요약과 테스트 방법)	/pr	[다루지 않음]
PRD/SRS 기반 QA 체크리스트 설계	/qa	[다루지 않음]
MCP Playwright 실측 실행 (경량/심층)	/qa-run-light, /qa-run-deep	[다루지 않음]
변경분 분석으로 이번 배포용 DEV/PROD 수동 체크리스트 생성	이 스킬	[핵심]

검증 시나리오

공통 3블록(빈 / 부분 / 풀 데이터)은 CONTRACT 6-1절 참조.

이 스킬의 고유 실패 시나리오

[의존성 부재] 회귀 테스트 시나리오 파일 부재

• 신호: 회귀 테스트 시나리오 파일 없음 또는 프로젝트에 정의 안 됨
• 대응: 체크리스트의 회귀 섹션 생략, 대신 "수동 검증 권장 영역" 서술로 대체 + 사용자에게 시나리오 파일 작성 권장

[사용자 개입 필요] 이슈번호 자동 추출 실패

• 신호: PR 제목, 커밋 메시지, 브랜치명에서 이슈번호 패턴(#123, PROJ-45 등) 미검출
• 대응: AskUserQuestion. "이 배포에 연결할 이슈번호를 알려주세요 / 해당사항 없음"