EugineKosenko/majordom

analyze-fig

Figma 내보내기(.fig)를 Figma API에 의존하지 않고 분석합니다: 노드 트리, 텍스트 및 래스터는 파일 자체에서 읽어오며, .fig에 없는 작성자 댓글은 MCP를 통해 링크로 별도로 가져옵니다. 결과는 spcfctn/ui/ 디렉터리의 md 파일이며, 이후 Figma를 다시 읽는 대신 이 파일들로 작업합니다.

실행하지 않을 경우

이미 분석된 레이아웃에 대한 질문(예: "필터 댓글에 무엇이 있나요?", "화면에 어떤 열이 있나요?")은 이 스킬 대신 spcfctn/ui/*.md를 읽어서 해결하세요. 분석은 새로 추가되거나 업데이트된 .fig 파일이 있을 때, 또는 md 파일에 답변이 없을 때만 필요합니다(spcfctn-code.md 참조).

디렉터리 (초안 전용 디렉터리 draft, git 외부)

• spcfctn/ui/draft/ — 입력 .fig 파일 (및 기타 초안). 사용자가 파일을 넣습니다.
• spcfctn/ui/draft/<이름>/ — 압축 풀기 결과: message.json (모든 노드), meta.json, images/, screens.json, screens.txt, 그리고 수집된 댓글(comments.json). .fig에서 재생성되며 git에 포함되지 않습니다. 별도의 raw/ 및 data/ 디렉터리는 없습니다 (modeling.md 참조).
• spcfctn/ui/*.md — 분석 결과; 이것만 git에 남습니다.

<이름>은 소문자, 하이픈으로 구분된 파일 이름입니다 (예: internal-interfaces).

0단계 — 준비

• 프로젝트의 spcfctn/ 디렉터리를 찾으세요. 없으면 사용자에게 생성을 요청하세요 (spcfctn-code.md 참조). ui/ 아티팩트와 그 하위 디렉터리 draft/는 직접 생성하세요.
• spcfctn/ui/.gitignore를 확인하세요 (아티팩트 리포지토리): draft가 포함되어야 합니다 (modeling.md 참조); 누락된 항목은 gitignore.org를 통해 추가하세요.
• Fig 파일: 사용자가 이름을 지정합니다; 지정되지 않은 경우 spcfctn/ui/draft/*.fig를 표시하고 물어보세요.
• 프로젝트의 CLAUDE.md (문체, 규칙) 및 기존 spcfctn/ui/*.md를 읽으세요: 분석은 해당 구조와 용어를 이어가야 하며 처음부터 시작하지 않아야 합니다.
• python3 및 zstd가 PATH에 필요합니다.

1단계 — 압축 풀기 및 디코딩

python3 ~/.claude/skills/analyze-fig/scripts/fig.py spcfctn/ui/draft/X.fig spcfctn/ui/draft/<이름>

포맷 버전, 노드 수, 블롭 수, 이미지 수를 출력합니다. 스크립트는 버전 106에서 테스트되었습니다; 다른 버전이나 오류가 있는 경우 포맷을 추측하거나 다른 디코더를 읽지 말고 사용자에게 알리세요. meta.json에는 exported_at (내보내기 시간)이 포함되며, 이는 5단계에서 필요합니다. message.json은 크므로 직접 출력하지 마세요.

2단계 — 섹션 및 화면으로 분할

python3 ~/.claude/skills/analyze-fig/scripts/screens.py spcfctn/ui/draft/<이름>

페이지, 섹션 (최상위 프레임), 화면 (자식) 목록을 텍스트 및 래스터 개수와 함께 출력합니다. 핵심은 screens.txt입니다: 각 화면에 대해 텍스트 레이어가 위에서 아래로, 왼쪽에서 오른쪽으로 그룹화된 행 (필터, 열 헤더, 버튼이 읽히는 방식)과 래스터 링크가 포함됩니다.

• 개수를 예상 값(예: 이전 md)과 비교하세요; 불일치 시 중단하세요.
• 텍스트 레이어는 텍스트가 없는 요소(빈 아이콘)와 래스터 내용을 볼 수 없습니다. images/의 각 래스터에 대해 파일을 열고(Read) 텍스트 레이어에 없는 내용을 설명하세요; 이미지에서 읽은 것임을 표시하세요. 트리 및 텍스트가 주요 증거이며, 이미지는 보조 자료입니다.
• 컴포넌트 인스턴스(INSTANCE)는 스크립트가 볼 수 없는 재정의된 텍스트를 가질 수 있으며, screens.txt가 이에 대해 경고합니다.

3단계 — spcfctn/ui/*.md 작성

• 섹션당 하나의 md 파일 (또는 섹션이 하나인 경우 파일 하나). 파일이 이미 존재하면 전체를 읽고 업데이트하세요; 덮어쓰지 마세요: md 파일은 에이전트만 관리하지만 이전에 명확히 한 내용을 잃어서는 안 됩니다.
• 문체는 프로젝트의 CLAUDE.md를 따릅니다.
• 구조 (job/vale/kylada의 spcfctn/ui/internal-dashboard.md 예시 참조): 소스 및 검증 정보 (읽은 내용, 내보내기 날짜, 화면 및 텍스트 수)가 포함된 서문, 레이아웃 읽기 규칙, UI 레이블과 내부 용어의 일치 여부, 화면 순서 (레이아웃 순서의 필터, 목록 버튼, 열, 행 작업), 미해결 질문.
• 레이아웃 텍스트나 댓글이 아닌, 자신의 해석은 모두 inferred로 표시하세요.
• 레이아웃 읽기에 대한 프로젝트별 규칙(예: 열 헤더 아래의 Select는 정렬 제어)은 프로젝트의 CLAUDE.md에서 가져와 적용하세요; 직접 만들어 내지 마세요.

4단계 — 링크를 통한 MCP 댓글

.fig 파일에는 댓글이 없습니다 (확인됨): 댓글은 Figma 서버에만 남아 있습니다.

• Figma 파일 링크가 필요합니다 (node-id 포함 또는 미포함). 없으면 사용자에게 요청하세요.
• 프로젝트에 연결된 Figma MCP 서버의 comments MCP 도구만 사용하세요 (서버 이름은 연결된 서버 목록에서 가져옴); file 매개변수는 링크입니다. 해당 도구가 없으면 사용자에게 알리세요. 공식 figma-cs는 댓글을 반환하지 않으며, 토큰을 사용한 REST를 직접 호출하거나 .env를 건드리지 마세요.
• node_id 없이 호출하면 파일의 모든 댓글을 분기별로 반환합니다 (번호, 날짜, 상태, 노드 @id, 텍스트, 답변). 불필요한 refresh는 하지 마세요. 댓글 엔드포인트는 파일 읽기와 별도로 계산되며, 읽기가 429를 반환해도 작동합니다.
• 화면에 바인딩:
  • @id가 screens.json의 화면 id와 일치하면 화면이 결정됩니다.
  • 섹션 또는 페이지의 @id인 경우 기하학적으로 화면을 결정하며, 이를 위해 댓글의 node_id와 node_offset이 필요합니다. 키 노드 X Y 형식 (예: #144 979:3 500 5471)의 라인을 구성하여 입력으로 전달하세요: python3 ~/.claude/skills/analyze-fig/scripts/place.py spcfctn/ui/draft/<이름> < 라인. 출력: 키, 섹션, 화면; 또는 점이 화면 위에 없는 경우 이유와 가장 가까운 화면.
  • 출력을 확인하세요: comments 도구가 node_offset를 출력하지 않을 수 있습니다 (스킬 생성 당시 그랬습니다). 그런 경우 섹션 또는 페이지에 대한 댓글을 정확히 배치할 수 없습니다: 텍스트로 화면을 추측하지 말고, 섹션에 할당하고 화면 미결정으로 표시한 후 사용자에게 댓글 배치를 위해 오프셋이 필요하다고 알리세요.
• 답변(↳)은 부모 스레드에 속합니다.

5단계 — 댓글이 파일과 일치하는지 확인

결정된 화면이 있는 각 댓글 (및 섹션 댓글 그룹)에 대해 확인하세요:

• 댓글에 언급된 필드, 열, 버튼, 값이 이 화면의 텍스트 레이어에 존재하는지 (Amount of integrated services ↔ Services 열; 인용문; 값 목록).
• 댓글이 레이아웃과 모순되지 않는지 (열 개수, 순서, 요소 유형, "필터 있음" / "없음").
• 날짜: 댓글이 meta.json의 exported_at보다 최신이면 내보내기가 오래된 것입니다. 그런 경우 spcfctn/ui/draft/에 최신 내보내기를 요청하세요.
• 댓글 노드가 파일에 없으면 (삭제 또는 이름 변경) 고아 댓글입니다.
• 화면도 없고 인식 가능한 내용도 없는 댓글.

불일치를 작은 표 (번호 #N, 화면, 불일치 내용)로 요약하고 사용자에게 무엇이 올바른지 질문하세요: 조용히 수정하거나 레이아웃과 댓글 사이에서 직접 선택하지 마세요. 답변을 받을 때까지 md에서 conflict로 표시하세요.

6단계 — 요약 작성

• md에 작성자 댓글 섹션을 추가하세요: 요약 (댓글이 무엇을 명확히 하는지) 및 번호 #N이 포함된 화면별 모든 댓글. 댓글이 inferred 항목을 명확히 하는 경우 기록을 수정하고 댓글을 참조하세요.
• 서문의 "Verification"을 업데이트하세요: 읽은 내용 (.fig, 버전, 내보내기 날짜, 텍스트, 래스터, 댓글, 수집 날짜) 및 포함되지 않은 항목.
• 미해결 질문은 별도 목록으로; 사용자 답변은 "Resolved"로 이동하세요.
• 요청 없이 커밋하지 마세요. 구두로 (한국어) 요약하세요: 섹션 수, 화면 수, 댓글 수, 불일치 수 및 명확히 해야 할 사항.

하지 말아야 할 것

• 토큰을 사용한 Figma REST를 호출하지 말고, .env를 읽거나 편집하지 마세요.
• 타사 코드(kiwi 디코더 등)를 읽지 마세요: 포맷은 이미 scripts/에서 구현되었습니다.
• .fig 파일과 분석 결과(draft/ 아래 모든 것)를 git에 넣지 마세요.
• 텍스트 레이어가 있을 때 댓글 화면을 단어로 추측하거나, 레이아웃 내용을 이미지로 추측하지 마세요.