Pr business docs

PR business 문서 갱신

변경된 코드를 시작점으로 실제 동작을 읽고, 오래된 business 문서를 찾아 안전하게 갱신한다.

문서 작성 기준은 references/business-doc-rules.md, 저장소별 적응 절차는 references/project-adaptation.md를 따른다.

절대 규칙

1. 코드를 읽지 않고 business 문서, 백로그, 커밋 메시지만으로 동작을 쓰지 않는다.
2. 비교 기준과 대상 문서를 먼저 출력하고 사용자 확인을 받은 뒤 초안을 작성한다.
3. 확인 전에는 business 문서를 만들거나 수정하지 않는다. 임시 파일도 만들지 않는다.
4. 사용자와 합의한 문서 밖의 파일은 만들거나 수정하지 않는다.
5. 코드 문제를 발견해도 이 Skill에서는 고치지 않고 보고만 한다.
6. SDD 문서는 이력으로 취급하며 수정하지 않는다.
7. 백로그는 선택 입력이다. 없다는 이유로 중단하지 않는다.
8. 기존 문서는 기본적으로 변경된 동작과 직접 닿은 부분만 갱신한다.
9. 전체 재작성은 이유와 범위를 설명하고 사용자 확인을 별도로 받은 경우에만 수행한다.

Stage 0 - 대상 판정

0-1. 프로젝트 규칙 확인

AGENTS.md, CLAUDE.md와 저장소 문서에서 다음을 찾는다.

• 기본 브랜치와 PR 비교 방식
• business 문서 경로와 이름 규칙
• HTTP, 메시지, 배치 등 진입점 유형
• 호출 계층과 외부 호출·데이터 접근의 종료 지점
• SDD 백로그 경로와 변경 파일 섹션

명시되지 않은 값은 추측하지 말고 사용자에게 묻는다.

0-2. 비교 범위 확정

다음 우선순위로 비교 기준을 찾는다.

1. 사용자가 지정한 base와 작업 범위
2. 현재 PR의 base 정보
3. 원격 저장소의 기본 브랜치와 HEAD의 공통 기준점

staged, unstaged, untracked 작업이 있으면 PR diff와 별도로 표시한다. 어떤 변경을 이번 문서 갱신에 포함할지 사용자에게 확인받는다.

master, main 또는 특정 브랜치를 근거 없이 기본값으로 사용하지 않는다.

0-3. 동작 변경 필터

파일명이 아니라 diff의 실제 행위로 판정한다.

다음은 보통 동작 변경이다.

• 요청·응답 계약, URL, 파라미터, 고정값 변경
• 분기 조건, 호출 순서, 예외 처리 변경
• 메시지 발행·수신·재시도 변경
• 데이터 조회·저장 조건 변경

주석, 설명, 공백, 포맷만 바뀌고 실행 동작이 같으면 제외한다. 판단이 애매하면 제외하지 말고 확인 대상으로 남긴다.

0-4. 진입점 역추적

변경 파일에서 외부 요청을 받는 진입점까지 역참조를 따라간다.

• 진입점이 직접 바뀌었으면 해당 메서드나 핸들러를 기록한다.
• 내부 계층만 바뀌었으면 그 심볼을 호출하는 상위 계층을 찾아 진입점까지 거슬러 올라간다.
• rg를 우선 사용하고 사용할 수 없으면 저장소 검색 도구나 grep을 사용한다.
• 진입점을 찾지 못하면 추정하지 말고 현재까지 확인한 심볼을 보고한다.

0-5. 공유 호출 체인 확장

확인한 진입점이 호출하는 핵심 비즈니스 심볼을 찾는다. 같은 심볼을 사용하는 다른 HTTP, 메시지, 배치, 재시도 진입점을 모두 검색한다.

diff에 없는 진입점도 같은 동작을 공유한다면 문서 후보에 포함한다. 단순히 같은 디렉터리에 있다는 이유만으로 포함하지 않는다.

0-6. business 문서 매핑

프로젝트에서 정한 문서 위치와 제목 인덱스를 사용해 진입점과 기존 문서를 연결한다.

• 매칭되는 문서는 기존 파일명을 유지한다.
• 매칭되지 않으면 신규 문서 후보와 이름을 제안한다.
• 여러 진입점을 하나의 문서로 묶으려면 이유를 설명하고 사용자 확인을 받는다.

0-7. 백로그 교차검증

백로그가 있으면 변경 파일 목록과 diff를 대조한다.

• diff에만 있는 파일: 미귀속 후보
• 백로그에만 있는 파일: 미변경 후보
• 이름이 다른 섹션이 있을 수 있으므로 특정 제목 검색 결과가 없다는 이유만으로 백로그 정보가 없다고 단정하지 않는다.

백로그가 없으면 이 단계를 건너뛴다.

0-8. 범위 확인

다음을 출력하고 사용자 확인을 받는다.

## 비교 기준
{base, HEAD, working tree 포함 여부}

## 동작 변경 파일
{파일과 판정 근거}

## 진입점
{직접 진입점과 공유 호출 체인으로 확장한 진입점}

## 대상 문서
{기존 문서, 신규 후보, 제외 문서와 이유}

## 백로그 교차검증
{미귀속, 미변경, 백로그 없음}

## 확인 필요
{사용자가 결정할 범위}

Stage 1 - 코드 읽기

확인받은 진입점에서 시작해 실제 동작이 끝나는 지점까지 읽는다.

진입점 -> 비즈니스 처리 -> 데이터 접근 또는 외부 호출 -> 후처리·재시도

프로젝트 구조에 없는 계층을 억지로 찾지 않는다. 변경 파일과 백로그는 읽기 시작점이지 전체 범위가 아니다.

Stage 2 - 갱신 방식 선택

기존 문서

기존 문서 전체를 먼저 읽고 변경된 동작과 직접 닿은 문장·섹션을 찾는다.

• 바뀐 동작은 현재 코드 근거로 수정한다.
• 바뀌지 않은 서술은 임의로 삭제하거나 다시 쓰지 않는다.
• 기존 서술이 코드와 충돌하면 충돌 지점과 근거를 보고한다.
• 문서 구조가 깨졌거나 광범위하게 오래된 경우에만 전체 재작성을 제안한다.

신규 문서 또는 전체 재작성

호출 체인 전체를 읽고 모든 동작 문장에 코드 근거를 댄다. 전체 재작성은 기존의 검증된 내용을 잃을 수 있으므로 이유와 예상 변경 범위를 보여주고 별도 확인을 받는다.

Stage 3 - 초안과 대조

초안에는 새로 쓰거나 바꾸는 문장마다 파일:라인 근거를 붙인다. 저장할 문서에서는 근거 각주를 제거할 수 있지만, 검토 출력에는 유지한다.

• 근거를 찾지 못한 문장: 삭제하거나 확인 필요로 이동
• 코드와 기존 문서가 충돌하는 문장: 코드를 따르되 차이를 보고
• 컨텍스트에서 근거가 밀려난 문장: 기억으로 쓰지 않고 작업을 분할

Stage 4 - 저장

초안과 기존 문서 대비 변경점을 보여주고 사용자 확인을 받은 뒤 저장한다.

저장 후 다음을 확인한다.

• 확인받은 대상 문서만 변경됐다.
• 각 문서 제목에 진입점 식별 정보가 있다.
• 위험하거나 예외적인 동작을 기록하는 섹션이 있다. 없으면 없음이라고 명시했다.
• SDD와 코드 파일은 수정하지 않았다.

최종 출력

## 변경한 문서
{파일과 갱신 이유}

## 기존 문서와 달라진 점
{코드 근거로 수정한 내용}

## 확인하지 못한 점
{남은 불확실성 또는 없음}

## 발견한 코드 이슈
{보고만 할 문제 또는 없음}

## 다음 작업
{분리한 호출 체인 또는 없음}

금지

• 비교 기준을 확인하지 않고 diff 범위 확정
• 코드를 읽지 않고 기존 문서를 요약해 새 문서 작성
• 기존 문서를 자동으로 전체 재작성
• 확인 전 파일 생성·수정
• 대상 밖 문서, SDD, 코드 수정
• 진입점 유형이나 호출 계층을 특정 프레임워크 기준으로 단정
• 문서 개수만으로 작업 범위 분할