ct-tran-plan

name	ct:tran-plan
description	특정 메소드, Controller API, Service, 배치 진입점의 현재 호출 흐름을 분석해 AS-IS 콜트리, 현재 구조 판단, TO-BE 콜트리, 서비스 책임, 메서드 매핑을 포함한 전환 계획 문서를 작성할 때 사용한다. `$ct-tran-plan`, `ct-tran-plan`, `전환계획`, `이 메소드 기준으로 전환 문서 작성`, `AS-IS/TO-BE 콜트리 문서` 요청에 사용한다.

ct-tran-plan

특정 메소드를 기준으로 구조 변경 판단 문서를 만든다. 핵심은 현재 콜트리와 문제 근거를 바탕으로 목표 콜트리를 작성하는 것이다. 이 스킬은 신규 전환 계획 문서를 생성한다.

입력 기준

사용자가 아래 중 하나를 주면 바로 시작한다.

• 메소드명
• 클래스명과 메소드명
• 파일 경로와 메소드명
• Controller API 진입점
• Service 또는 배치 진입점

대상이 모호하면 질문은 하나만 한다.

• 예: "execute 메소드가 여러 개입니다. 기준 클래스명을 알려주세요."

문서 확인 기준

프로젝트 문서는 있으면 먼저 확인한다.

• AGENTS.md
• .0_my/core_project.md
• .0_my/core_code_style.md
• .0_my/core_workflow.md

프로젝트 문서가 없으면 작업을 중단하지 않는다.

• 소스 코드와 기존 문서 패턴을 기준으로 작성한다.
• 공통 로그, 네이밍, 테스트 실행 기준은 단정하지 않는다.
• 미확정 항목은 확인 필요로 분리한다.

파일 생성 기준

항상 신규 문서로 생성한다.

• 파일명 기본 형식: .0_my/{doc_prefix}_tobe_{methodName}_transition_plan.md
• doc_prefix
  • Controller/API: api
  • Service: service
  • Batch: batch

분석 순서

분석은 콜트리부터 시작한다.

1. 대상 메소드 위치를 찾는다.
2. 대상 메소드 본문을 읽는다.
3. 직접 호출하는 Service, DAO/Mapper, 외부 연동, private helper를 추적한다.
4. 의미 있는 호출만 현재 콜트리에 남긴다.
5. 현재 콜트리에서 책임 집중, 중복 검증, 저장 책임, 외부 호출, 후처리, 응답 조립 문제를 판단한다.
6. 현재 구조 판단을 문제점 -> 근거 -> 결과 -> 목표 기준 흐름으로 쓴다.
7. 목표 콜트리를 작성한다.
8. 서비스 책임과 현재 메서드 매핑을 작성한다.
9. 기존 유지 기준과 신규 제안 기준을 분리한다.
10. 운영 로그 기준은 프로젝트 로그 규칙에 맞춰 패턴과 예제로 작성한다.

콜트리 작성 규칙

콜트리는 판단 가능한 수준까지만 펼친다.

• 루트는 사용자가 지칭한 메소드다.
• 비즈니스 의미가 있는 호출만 남긴다.
• 단순 getter/setter, 단순 add, 단순 DTO 필드 세팅은 생략한다.
• 외부 API, 메시지, 결제, 쿠폰, 재고, 파일, 메일, SMS, MQ 호출은 남긴다.
• DB 쓰기, 상태 변경, 실패 저장, 보상 처리, 후처리는 남긴다.
• private helper는 흐름 판단에 필요할 때만 펼친다.

현재 구조 판단 작성 규칙

현재 구조 판단은 나열식 세부 근거가 아니라 결정 가능한 설명으로 작성한다.

형식:

## 현재 구조 판단
현재 콜트리는 {핵심 문제 요약} 구조다.

- 문제점: {문제}
  - 근거
    - {콜트리에서 확인한 근거}
  - 결과
    - {구조 변경 시 생기는 영향}
  - 목표 기준
    - {TO-BE에서 지켜야 할 기준}

작성 기준:

• 입력 조립처럼 작은 기능을 각각 섹션으로 만들지 않는다.
• 판단에 필요한 문제 단위로 묶는다.
• 코드 증거는 콜트리와 메서드명으로 설명한다.
• 목표 기준은 바로 뒤 목표 콜트리와 이어져야 한다.

목표 콜트리 작성 규칙

목표 콜트리는 현재 콜트리의 책임을 서비스 경계로 옮긴 형태로 작성한다.

• Facade가 있으면 흐름 제어와 실패 기준 조율을 담당하게 둔다.
• Facade 입력은 기존 DTO, List, Map, JSON 객체 유지를 기본값으로 한다.
• 신규 입력 조립 서비스는 기본 제안에 포함하지 않는다.
• 전체 흐름을 하나의 트랜잭션으로 묶는 제안은 기본값으로 두지 않는다.
• DB 저장, 외부 호출, 결과 반영, 후처리는 트랜잭션 경계를 분리한다.
• 외부 호출 서비스는 외부 결과를 반환하고, 내부 반영 서비스가 저장과 상태 기록을 맡는다.
• 기존 응답 코드와 상태 코드 변경이 없으면 변경 기준으로 쓰지 않는다.

입력/출력 유지 기준

입출력은 기존 구조 유지를 기본값으로 한다.

• 기존 Controller/Service에서 사용하던 DTO, List, Map, JSON 객체를 우선 유지한다.
• 신규 command/request 객체나 assembler는 사용자가 요구하거나 코드 구조상 필요할 때만 제안한다.
• 사용자가 별도 요구사항을 주면 그 요구사항을 입력/출력 설계에 우선 적용한다.
• 사용자가 파라미터, DTO, 응답, 상태 코드 유지 조건을 명시하면 목표 콜트리, 서비스 책임, 현재 메서드 매핑, 응답 유지 기준에 같은 조건을 반영한다.
• 기존 응답 포맷, 응답 코드, 외부 노출 상태 코드는 변경하지 않는 것을 기본값으로 한다.

권장 문서 구조

문서 구조는 아래 순서를 기본으로 한다.

# `{methodName}` 구조 변경 기준

## 목적
## 입력 기준
## 전체 흐름 기준
## 현재 콜트리
## 현재 구조 판단
## 목표 콜트리
## 변경 효과
## 서비스 책임
## 컨트롤러 책임
## 검증 책임
## 현재 메서드 매핑
## 처리 단계값
## 응답 유지 기준
## 실패/보상 처리 기준
## 테스트케이스 기준
## 운영 로그 기준
## 확인 필요

섹션 적용 기준:

• Controller가 대상이 아니면 컨트롤러 책임을 진입점 책임으로 바꾼다.
• 변경 효과는 목표 콜트리 뒤에 작성한다.
• 변경 효과는 현재 구조 판단과 목표 콜트리에서 도출 가능한 항목만 작성한다.
• 실패/보상 처리 기준은 보상 호출, 무결성 등록/삭제, 외부 승인 후 내부 반영 실패가 코드에서 확인되는 경우 작성한다.
• 기존 메서드 유지, 내부 분해 제외, 단계적 전환 같은 범위 제한 기준은 사용자가 요청한 경우 작성한다.
• 응답 정책 변경이 없으면 응답 유지 기준으로만 쓴다.
• 실패 정책 변경이 없으면 실패 처리 변경 기준을 만들지 않는다.
• 자동 취소처럼 기존 정책과 같은 내용은 별도 변경 기준으로 만들지 않는다.
• 확인 필요는 프로젝트 문서나 코드로 확정할 수 없는 항목이 있을 때만 쓴다.
• 이력관리는 프로젝트 문서 패턴에 맞춘다.
• 기존 문서들이 이력관리를 사용하면 신규 문서에도 포함할 수 있다.
• 사용자가 이력관리 제외를 요청하면 포함하지 않는다.
• 문서는 신규 파일로 생성한다.

서비스 책임 작성 규칙

서비스 책임은 표로 짧게 쓴다.

| 서비스 | 책임 | 출력 |
|---|---|---|
| `TargetFacadeService` | 처리 순서 제어, 실패 기준 제어 | 처리 결과 |
| `TargetValidationService` | 저장 전 검증 | 검증 결과 |

주의:

• 서비스별 설명 섹션을 따로 길게 만들지 않는다.
• 목표 콜트리와 서비스 책임 표가 중복되면 서비스 책임 표만 둔다.
• 책임은 실행 기준으로 적고 추상 명사를 줄인다.

서비스명 작성 규칙

서비스명은 특정 구현 기술보다 도메인 단위를 우선한다.

• 서비스명은 특정 상품명, 벤더명, 처리 방식보다 업무 도메인 중심으로 만든다.
• 여러 하위 처리를 묶는 서비스는 공통 업무 의미를 드러내는 이름을 사용한다.
• 초안의 서비스명은 후보이며, 사용자가 검토하면서 도메인 용어에 맞게 조정할 수 있다.

현재 메서드 매핑 작성 규칙

현재 메서드 매핑은 AS-IS 코드와 TO-BE 서비스를 연결한다.

| 기존 위치 | 목표 서비스 | 기준 메서드 |
|---|---|---|
| `{rootMethod}` 입력 조립 구간 | `TargetFacadeService` | 기존 DTO, 리스트, 요청 객체 조립 |

작성 기준:

• 현재 코드의 메서드명을 그대로 쓴다.
• 이동 기준을 서비스 책임과 맞춘다.

현재 코드와 TO-BE 후보 구분

현재 구조 설명과 현재 메서드 매핑의 기준 메서드는 실제 코드에 있는 이름을 사용한다.

목표 콜트리와 서비스 책임에는 TO-BE 후보 서비스명과 후보 메서드명을 사용할 수 있다.

TO-BE 후보는 현재 코드 근거처럼 설명하지 않는다.

기존 유지와 변경 구분

기존 정책과 신규 제안을 섞지 않는다.

• 기존 유지
  • 기존 입력 DTO/List/Map/JSON 구조
  • 기존 응답 DTO/JSON 구조
  • 응답 포맷
  • 응답 코드
  • 외부 노출 상태 코드
  • 기존 후처리 실패 응답 정책
• 신규 제안
  • 서비스 책임 분리
  • 목표 콜트리
  • 처리 단계값
  • 운영 로그 패턴
  • 메서드 매핑

변경이 없는 내용은 별도 변경 기준 섹션으로 만들지 않는다.

변경 효과 작성 규칙

변경 효과는 현재 구조 판단과 목표 콜트리에서 확인한 효과만 작성한다.

• 작성 대상

  • 현재 구조 판단의 문제점이 목표 구조에서 줄어드는 지점
  • 목표 콜트리에서 새로 분리한 서비스 경계의 효과
  • 기존 처리 순서 유지로 줄어드는 변경 위험
  • 기존 응답, 상태 코드, 외부 연동 정책 유지로 줄어드는 영향 범위
  • 사용자 프롬프트에 명시된 파라미터, DTO, 응답, 상태 코드 유지 효과

• 작성 기준

  • 효과 항목은 현재 콜트리, 현재 구조 판단, 목표 콜트리 중 하나와 연결한다.
  • 효과 설명은 구현자가 전환 범위를 판단할 수 있는 수준으로 쓴다.

실패/보상 처리 기준 작성 규칙

실패/보상 처리 기준은 기존 코드에서 확인한 실패 처리 흐름만 작성한다.

• 작성 대상

  • 예외 유형별 응답 기준
  • 보상 호출 조건
  • 무결성 등록 조건
  • 무결성 삭제 조건
  • 외부 승인 성공 후 내부 반영 실패 처리
  • 운영 확인이 필요한 실패 지점
  • 사용자 프롬프트에 명시된 파라미터, DTO, 응답, 상태 코드 유지 조건

• 작성 기준

  • 목표 콜트리에는 처리 흐름을 쓴다.
  • 실패/보상 처리 기준에는 실행 조건과 응답 기준을 쓴다.
  • 형식은 코드 흐름을 가장 짧게 설명할 수 있는 목록 또는 표를 사용한다.

테스트케이스 기준

테스트케이스 상세 목록은 별도 문서 예정으로만 남긴다.

• 사용자가 테스트케이스까지 요청하면 별도 테스트 문서로 분리한다.

운영 로그 작성 규칙

프로젝트 로그 규칙이 있으면 그 기준을 따른다. 없으면 코드에서 확인한 기존 로그 패턴만 기준으로 쓴다.

권장 형식:

기본 패턴:

- 형식: `[Component][Tag] 메시지 - 업무식별자: {}, step: {}`

단계 로그 예시:

log.info("[TargetFacadeService][START] 처리 시작 - ordNo: {}, relCausNo: {}, step: {}", ordNo, "-", "RECEIVED");

외부 연동 로그 예시:

log.info("[ExternalApprovalService][EXTERNAL] 외부 승인 요청 - ordNo: {}, relCausNo: {}, step: {}, provider: {}", ordNo, "-", "APPROVAL_REQUESTED", provider);

민감정보 기준:

• 마스킹 대상과 출력 제외 값은 프로젝트 규칙을 따른다.
• 프로젝트 규칙이 없으면 코드 패턴 기준으로 쓰고 확인 필요에 남긴다.