a10-context-analyzer

컨텍스트 분석기 (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 설치 및 텍스트 추출

   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

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

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

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

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

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