---
name: a10-context-analyzer
description: >
  This skill should be used when the user attaches or references a screenshot, image, or PDF file
  and asks to "컨텍스트 파일 만들어줘", "이 화면 분석해줘", "설계서 보고 맥락 정리해줘",
  "스크린샷으로 LNB 파일 만들어줘", "화면설계서 PDF 읽어서 context 생성해줘",
  "이 파일 보고 GNB/LNB 구조 잡아줘", 또는 화면 이미지나 설계 문서를 첨부하며
  amaranth10-claude-forge 컨텍스트 파일로 변환을 요청할 때.
  스크린샷, 이미지, PDF를 분석해 GNB/LNB 컨텍스트 파일을 자동 생성한다.
version: 0.2.0
---

# 컨텍스트 분석기 (Context Analyzer)

화면 스크린샷, UI 이미지, 화면설계서 PDF를 분석해
amaranth10-claude-forge GNB/LNB 컨텍스트 파일 형식으로 자동 변환한다.

## 입력 유형별 처리 방식

### 스크린샷 / UI 이미지
Claude의 기본 비전 기능으로 직접 분석한다.

분석 항목:
- 화면 제목 및 메뉴 위치 (GNB/LNB 추론)
- 주요 UI 요소 (버튼, 폼, 테이블, 탭 등)
- 화면에서 확인되는 기능 목록
- 라이선스 구분 단서 (화면 내 조건부 영역, 권한 표시 등)
- 연관 데이터 단서 (컬럼명, 레이블, 코드값 등)

### PDF 화면설계서

#### PDF 타입 자동 감지
pdftotext로 전체 텍스트를 추출한 후 타입을 분류한다:
- **text_based**: 텍스트 중심의 설계서 (텍스트 추출 가능)
- **mixed**: 텍스트와 이미지가 섞여 있음
- **image_based**: 스캔 또는 이미지 중심의 설계서

분석 항목:
- 문서 구조에서 GNB/LNB 계층 파악
- 각 화면의 기능 설명 추출
- 화면 목록 및 흐름 파악
- 라이선스 구분 표기 확인
- 테이블/엔티티 명세 추출

**파일명 메타데이터 자동 추출 규칙**

더존 설계서 파일명은 아래 패턴을 따른다. 파일명에서 메타데이터를 자동 추출해 사용한다.

구 형식:
```
[모듈명]기능명_V{버전}_{날짜}.pdf
예: [법무관리]상담관리_V1.2_241107.pdf
    → 모듈: 법무관리
    → 기능: 상담관리
    → 버전: V1.2
    → 날짜: 2024-11-07 (YYMMDD → YYYY-MM-DD 변환)
```

신 형식:
```
YYMMDD_[프로젝트명]기능명_문서종류_v버전.pdf
예: 241107_[Amaranth10]상담관리_화면설계_v1.2.pdf
    → 모듈: Amaranth10 → 법무관리(또는 해당 모듈)
    → 기능: 상담관리
    → 문서종류: 화면설계
    → 버전: v1.2
    → 날짜: 2024-11-07 (YYMMDD → YYYY-MM-DD 변환)
```

파일명에서 날짜가 확인되면 별도로 날짜를 질문하지 않는다.
버전 정보는 history 파일 작성 시 함께 기록한다.

## 3구역 확인 추적 (3-Zone Confirmation Tracking)

화면 이미지가 있어야만 확정할 수 있는 상태 변화, 위치, disabled/hidden 항목들을 추적한다.

| 구역 | 상태 | 설명 |
|-----|------|------|
| 텍스트만 확인 | ✓ | 설계서 텍스트에서 확인됨 (확정 가능) |
| 화면이미지까지 확인 | ✓✓ | 설계서 또는 스크린샷 이미지에서 시각적 확인됨 (최종 확정) |
| 미확인 | _ | 텍스트나 이미지 모두에서 미확인 (추론일 뿐) |

**핵심 원칙:** 상태값 변화 흐름, UI 요소 위치, disabled/hidden 상태는 화면 이미지 확인 전까지 확정하지 않는다.
이들은 설계서 텍스트와 실제 운영 화면이 다를 수 있기 때문이다.

## 100MB+ PDF 처리

페이지가 많은 PDF는 아래 순서로 처리한다:

1. `pdfminer.six` 설치 및 텍스트 추출
   ```bash
   pip install pdfminer.six --break-system-packages
   ```
2. 페이지 범위를 20~30페이지 단위로 분할해 순차 추출
3. 전체 목차/구조 파악 (첫 10페이지)
4. GNB별로 분할해 순차 처리
5. 각 GNB 처리 후 중간 결과 저장
6. 전체 완료 후 module-overview.md 및 _timeline.md 생성

한 번에 처리하려 하지 않는다. 모듈이 크면 "어느 GNB부터 시작할까요?"를 먼저 묻는다.

## 출력 파일 결정 규칙

| 분석 결과 | 생성 파일 |
|---------|---------|
| 단일 LNB 화면 1-3개 | lnb-detail.md 1개 |
| 단일 GNB 전체 | gnb-overview.md + lnb-detail.md 여러 개 |
| 모듈 전체 설계서 | module-overview.md + gnb-overview.md + lnb-detail.md 전체 |

파일이 많을 경우 먼저 구조 요약을 보여주고 사용자 확인 후 생성한다.

## 분석 → 파일 생성 프로세스

**1단계 — 구조 파악**
입력 파일에서 GNB/LNB 계층 구조를 추론한다.
불명확한 경우 추론 근거를 설명하고 사용자에게 확인을 요청한다.

**2단계 — 기능 추출**
각 화면/LNB별로 아래 항목을 추출한다.
- 기능 목적
- 주요 기능 목록 및 현재 구현 상태 추론
- 라이선스 적용 범위 (화면에서 단서가 없으면 "확인 필요"로 표기)
- 연관 데이터 (테이블명, 필드명 등 — 화면 레이블에서 추론)

**3단계 — 불확실 항목 표시**
화면에서 직접 확인되지 않아 추론한 항목은 반드시 아래 형식으로 표시한다.

```
- 연관 테이블: `lawsuit_master` _(화면 레이블 기반 추론, 확인 필요)_
```

**4단계 — 파일 저장**
`{모듈명}/context/{GNB명}/{LNB명}.md` 경로에 저장한다.
모듈명과 경로를 알 수 없으면 사용자에게 질문한다.

**5단계 — 설계 히스토리 파일 생성**
PDF 내 Document History(버전 이력) 섹션이 있으면 반드시 아래 경로에 히스토리 파일도 함께 생성한다.

```
{모듈명}/history/requests/{날짜}-{기능명}-설계히스토리.md
```

날짜는 파일명 또는 Document History의 최신 날짜를 사용한다.
버전별 변경 내용, 담당자, 주요 설계 결정사항을 포함한다.
`_timeline.md`가 없으면 함께 생성하고, 있으면 신규 항목을 추가한다.

**6단계 — 원본 보관 분류 제안**
분석 완료 후 `문서/` 폴더 내 원본 배치 위치를 제안한다.

```
문서/01_신규/                    ← 새로 추가된 설계서
문서/02_삭제가능/                ← context 파일로 완전히 변환됨, 원본 불필요
문서/03_장기참조/                ← 변경 이력, 아키텍처 결정 근거로 참고 필요
```

**7단계 — 연쇄 업데이트 (Cascade R1 + R2)**

context 파일을 신규 생성하거나 대폭 변경했으므로, 아래 연쇄 업데이트를 수행한다.
이 단계를 건너뛰면 module-overview.md, 프로젝트 파일, 문서 인덱스와 context 간 불일치가 발생한다.

**R1 — module-overview.md 반영:**
1. `module-overview.md`의 **GNB 목록** 테이블에서 해당 GNB의 상태·LNB 수 갱신
2. `module-overview.md`의 **context 파일 인덱스** 테이블에 새 파일 추가 또는 갱신
3. `module-overview.md` 상단 **최종 업데이트** 날짜 갱신

**R2 — 관련 프로젝트 연결 정보 확인:**
1. `_projects/_dashboard.md`에서 해당 모듈과 관련된 PRJ 파일을 확인
2. 관련 PRJ 파일의 `04. 연결 정보`에 새로 생성된 context 파일 경로가 누락되어 있으면 추가

**문서/INDEX.md 반영:**
- 분석한 원본 문서(PDF 등)가 `문서/INDEX.md`에 없으면 항목 추가
- 이미 있으면 상태(맥락화 완료 등) 갱신

**8단계 — 보완 요청**
생성된 파일에서 추론으로 채운 항목 목록을 요약하고,
사용자가 직접 확인·보완해야 할 항목을 안내한다.

## 파일 배치 기준: 함수형 사실 vs 변경 이유 분리

생성된 파일은 목적에 따라 저장 위치를 구분한다:

| 내용 | 저장 위치 | 예시 |
|-----|---------|------|
| 현재 기능 정의 (화면 구성, 필드, 버튼) | `context/{GNB}/{LNB}.md` | 상담 목록 화면 구성, 필드 정의 |
| 설계 변경 이유 및 버전 이력 | `history/requests/{날짜}-{기능}-설계히스토리.md` | "V1.0에서 추가된 이유", "V1.2에서 UI 변경" |
| 개발 차수별 주요 변경 | `history/phase-N.md` | "1차 개발에서 기본 기능 완성", "2차에서 라이선스 분기 추가" |

## 참고 파일

- 추출 기준: `references/extraction-rules.md`
- 생성 파일 형식: `${CLAUDE_PLUGIN_ROOT}/templates/context/`
- lnb-detail.md 형식: `references/output-format.md`


## 마크다운 링크 규칙 (필수)

마크다운 파일 작성·업데이트 시 **모든 경로·파일 참조는 클릭 가능한 상대 링크**로 작성한다.

```markdown
# 나쁜 예 (클릭 불가)
법무관리/tasks/_current.md에서 확인

# 좋은 예 (클릭 가능)
[법무관리/tasks/_current.md](../법무관리/tasks/_current.md)에서 확인
```

- 상대 경로는 현재 파일 위치 기준
- 코드블록 안의 폴더 구조 다이어그램은 예외 (링크 불필요)
- 상세 규칙은 douzone-forge CLAUDE.md의 "마크다운 링크 표기 규칙" 섹션 참조