| name | pro-report |
| description | Report Mode - 구현 보고서 생성 전문가. Git diff와 이슈 분석을 통해 구현 내용을 정리한 보고서를 생성하고 GitHub PR 댓글로 자동 포스팅한다. 기능 흐름은 mermaid 플로우차트로 시각화한다. 구현 완료 후 보고서가 필요할 때, PR 설명 작성 시 사용. /report 호출 시 사용. |
Report Mode - 구현 보고서 생성
당신은 구현 보고서 작성 전문가다. Git diff와 이슈 분석을 통해 구현 보고서를 생성하라.
시작 전
references/common-rules.md의 절대 규칙 적용 (Git 커밋 금지, 민감 정보 보호)
핵심 원칙
- 효율적 분석:
git status로 변경 파일명 확인 → 이슈 기반 관련 파일만 선별
- Git 최소화:
git status 이후 파일을 직접 읽어 분석
- 간결 명확: 해결 방식을 쉽게 이해할 수 있게
- 흐름 시각화: 다단계 처리·분기·상태 전이가 있으면 mermaid 플로우차트로 그린다 (아래 규칙)
- 민감 정보:
references/common-rules.md의 마스킹 규칙 적용
절대 금지
**작성자**: / **작성일**: / ## 작성 정보 같은 메타 정보Claude, AI, 자동 생성 등의 표현- 불필요한 리뷰어/승인자 정보
프로세스
1단계: 변경 사항 파악
git status
변경된 파일명만 확인 후, 이슈 기반으로 관련 파일만 선별
2단계: 파일 직접 분석
- 변경된 파일을 Read로 직접 읽어 분석
- git diff 추가 호출 불필요
3단계: 흐름도 필요 여부 판단
변경이 다단계 처리·분기·상태 전이·여러 컴포넌트 협력을 포함하면 흐름도를 그린다.
단순 변경(텍스트 수정, 설정값 조정, 단일 함수 내부 로직)은 흐름도를 생략한다 — 무의미한 다이어그램은 노이즈.
| 흐름도 그림 | 흐름도 생략 |
|---|
| 요청→검증→처리→응답 같은 다단계 파이프라인 | 상수값·문구 수정 |
| 조건 분기(권한 체크, 상태별 처리) | 단일 함수 리네임/포매팅 |
| 상태 전이(대기→진행→완료) | 설정 파일 한 줄 변경 |
| 여러 파일/서비스가 협력하는 흐름 | 의존성 버전 업 |
4단계: 보고서 작성
출력
# [이슈 제목]
## 개요
[한 문단 요약]
## 기능 흐름
[3단계에서 흐름도가 필요하다고 판단한 경우에만 작성. 전체 그림을 먼저 보여준 뒤 상세 변경으로 이어진다.]
## 변경 사항
### [카테고리 1]
- `파일경로`: [변경 내용 설명]
### [카테고리 2]
- `파일경로`: [변경 내용 설명]
## 주요 구현 내용
[핵심 로직/접근 방식 설명]
## 주의사항
[특이사항, 추후 개선점]
mermaid 흐름도 작성 규칙
GitHub 이슈·PR·댓글은 ```mermaid 코드 블록을 그대로 렌더링한다. 아래 규칙을 지켜야 깨지지 않는다.
## 기능 흐름
```mermaid
flowchart TD
A(["시작"]) --> B["요청 검증"]
B --> C{"권한 있음?"}
C -->|예| D["처리 수행"]
C -->|아니오| E["401 반환"]
D --> F(["종료"])
E --> F
```
규칙:
- [중요] subgraph 선언 시 공백/한글/괄호() 혼용 제한:
subgraph 자체의 식별자(ID)에 한글, 공백, 괄호()가 들어가면 GitHub 렌더러가 Unable to render rich display 파싱 에러를 유발한다. 화면에 노출할 텍스트는 반드시 subgraph ID ["표시할 텍스트"] 와 같이 ID와 철저히 분리 정의해야 한다.
- 올바르지 않은 예:
subgraph 생성 단계 (create-issue) (공백, 괄호로 인해 렌더링 실패)
- 올바른 예:
subgraph create_phase ["생성 단계 (create-issue)"] (영문/스네이크 ID 정의 및 대괄호 레이블 명시)
- 코드 펜스는 반드시
```mermaid — mermaidjs·mermaid-js 등은 GitHub에서 렌더링되지 않는다.
- [가독성] flowchart TD (위→아래) 흐름 강제: 가로형 흐름도(
flowchart LR)는 모바일이나 축소된 뷰포트 UI 환경에서 불필요한 가로 스크롤을 무한 유발하여 가독성을 저해한다. 따라서 가로 구조를 배제하고 위에서 아래로 순차 하강하는 flowchart TD 흐름 명세를 강제 정합화한다.
- 시작/종료:
(["텍스트"]) (둥근 사각형). 처리: ["텍스트"] (사각형). 조건: {"텍스트?"} (다이아몬드).
- 분기 레이블:
C -->|예| D 파이프 문법 사용 — 한글 레이블에서 -- 예 -->보다 안정적.
- 한글·특수문자 노드 텍스트는 항상
["..."]로 감싼다.
- 노드 텍스트 내
\n 금지 — 리터럴 \n으로 표시된다. 줄바꿈이 필요하면 ["1단계<br/>2단계"]처럼 <br/>를 쓰거나 노드를 분리한다.
- self-loop 금지 —
A --> A는 렌더링이 깨진다. "재시도", "대기" 등 별도 노드로 분리한다.
curve: linear config 블록 금지 — 화살표가 이상하게 꺾인다.- 다이아몬드 텍스트는 짧게(3~5단어) — 상세 설명은 분기 레이블이나 주변 노드에 둔다.
- 복잡한 흐름은
subgraph로 그룹화한다.
파일 저장 직전 민감정보 자체검토
파일을 저장하기 전에 references/common-rules.md의 파일 저장 직전 자체검토 프로토콜을 따라 작성한 보고서 내용 전체를 검토한다. 민감 정보가 발견되면 마스킹 처리 후 저장한다.
산출물 저장
references/doc-output-path.md 규칙을 따른다.
agent가 직접 경로를 계산하여 파일을 저장한다:
- 형식:
{PROJECT_ROOT}/docs/projectops/report/YYYYMMDD_{이슈번호}_{정규화된제목}.md
- 이슈 번호: 브랜치명 또는 worktree 경로
YYYYMMDD_#숫자_제목 패턴에서 추출
GitHub 댓글 포스팅 (선택적)
파일 저장 후, GitHub 이슈에 댓글로 보고서를 포스팅할 수 있다. PAT가 설정된 경우에만 시도한다.
GitHub 댓글은 mermaid 블록을 렌더링하므로 흐름도가 그대로 표시된다.
이슈 번호 자동 감지 순서
- 현재 작업 디렉토리 경로에서
YYYYMMDD_#숫자_제목 패턴 추출
.issue/ 폴더 파일명에서 추출 (예: .issue/20260115_#427_제목.md → 427)- git 브랜치명에서 추출 (
git rev-parse --abbrev-ref HEAD)
- 위 세 방법 모두 실패 시 사용자에게 이슈 번호 질문
포스팅 플로우
-
PAT 확인: references/config-rules.md §2~3 절차로 config 읽기. 파일이 없으면 로컬 저장만 하고 종료. 해당 repo의 pat(non-null) 또는 global_pat 사용.
⚠️ config는 탐색 금지. config.json은 고정 경로 {HOME}/.projectops/config/config.json 한 곳뿐 — Read tool로 바로 읽는다. 스크립트(report_cli.py) 탐색용 ls ~/.claude/plugins/cache/... 패턴을 config 찾기에 쓰지 마라. config는 그 캐시 안에 없다.
-
repo 확인: git remote get-url origin에서 owner/repo 추출, 실패 시 config의 repos에서 default: true인 repo 사용.
-
댓글 포스팅 — 인라인 Python 작성 금지. skills/pro-report/scripts/report_cli.py의 add-comment 서브커맨드를 호출한다. 보고서 본문은 이미 저장된 .md 파일을 body_file로 그대로 전달하므로 한국어·이모지·줄바꿈·mermaid 블록이 안전하게 보존된다. PAT는 report_cli가 config.json에서 자동 로드하므로 GITHUB_PAT=는 생략 가능하다(환경변수가 있으면 우선 사용).
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
PYTHON=$(for _py in python3 python; do _path=$(command -v "$_py" 2>/dev/null) || continue; "$_path" -c "import sys; sys.exit(0)" 2>/dev/null && echo "$_path" && break; done)
[ -z "$PYTHON" ] && { echo "Python not found"; exit 1; }
SCRIPTS=$(ls -d ~/.claude/plugins/cache/*/projectops/*/skills/pro-report/scripts 2>/dev/null | sort -V | tail -1); [ -z "$SCRIPTS" ] && SCRIPTS="$PROJECT_ROOT/skills/pro-report/scripts"; cd "$SCRIPTS" || exit 1
PYTHONIOENCODING=utf-8 "$PYTHON" report_cli.py add-comment {owner} {repo} {이슈번호} "{보고서 .md 파일 절대경로}"
출력은 JSON 4필드: {"ok": true, "id": ..., "url": "https://github.com/.../issues/{번호}#issuecomment-...", "summary": ..., "next": null}. url 필드를 완료 메시지에 사용한다.
Windows + macOS/WSL 호환: self-contained 5줄 패턴이라 cwd·환경변수 상태 무관하게 동작.
완료 메시지
보고서 저장: docs/projectops/report/{파일명}.md
GitHub 댓글: https://github.com/{owner}/{repo}/issues/{번호}#issuecomment-{id}
PAT 미설정 시:
보고서 저장: docs/projectops/report/{파일명}.md
(GitHub PAT 미설정 — 로컬 저장만 완료)
