Unfold은(는) 무엇을 하나요?
하나의 HTML 페이지를 생성합니다: 시스템의 부분들을 수준별로 펼쳐 보여주는 개요도입니다. 엔진(assets/template.html)은 그리기, 배치, 확대/축소, 추적 및 편집을 처리합니다. 당신의 임무는 코드를 이해하고 다이어그램 데이터(JSON)를 작성하여, 프로젝트에 대해 전혀 모르는 독자가 시스템을 설명할 수 있게 되는 것입니다.
모든 수준에서 페이지는 세 가지 질문에 답합니다: 무엇이 들어오고, 무엇이 처리되며, 무엇이 나오는가?
품질 기준
- 정확성. 모든 노드와 엣지는 실제로 살펴본 코드에 의해 뒷받침됩니다.
source는path/file.py:symbol과 같은 위치를 명시합니다. 모든 노드에confidence를 표시하세요:read,peeked또는inferred. 추론된 내용은 모두 사용자에게 목록으로 제공됩니다. - 코드베이스에 적합함. 프로젝트 자체 용어(모듈 이름, 토픽 및 경로 이름을 그대로 사용)와 각 부분에 맞는 다이어그램 유형(4단계 참조)을 사용하세요.
- 간결함. 레이블은 2
4단어, 캡션은 한 줄, 참고 사항은 13문장이며 그 이상은 없습니다. 세부 정보는 한 번의 클릭 또는 한 번의 호버로 확인할 수 있으며, 캔버스에는 절대 표시되지 않습니다. - 처음부터 탐색 가능.
meta.summary는 시스템의 목적을 한 문장으로 설명합니다. 짧은meta.glossary는 프로젝트의 전문 용어를 정의합니다. 참고 사항은 호버 힌트 역할을 하는 문장으로 시작합니다.
워크플로우
1. 요청 분석
의도가 먼저입니다: 맵의 목적입니다. 범위, 깊이, 수준 유형, 투어, 미디어 및 용어집을 설정합니다. references/intents.md에는 각 의도에 대한 기본값이 있습니다.
- 프롬프트에 이미 명시되어 있다면 묻지 마세요. "이 프로젝트를 설명해줘"는 학습을 의미합니다. "재시도 로직은 어떻게 작동하나요?"는 설명을 의미합니다. "이 PR이 무엇을 변경하나요?"는 검토를 의미합니다. "금요일에 발표합니다"는 시연을 의미합니다.
- 그렇지 않으면 스캔하기 전에 한 가지 질문을 하세요. 옵션: 코드베이스 학습, 내 작업 시연, 특정 세부 사항 설명, 변경 사항 검토, 또는 기타(문서화 또는 인계, 단일 경로 디버그, 리팩터링 계획, 데이터 흐름 감사).
- 그런 다음 최대 두 개의 후속 질문을 하세요.
references/intents.md에서 해당 의도에 맞는 질문을 선택하세요. 대화에서 이미 답변된 질문은 건너뛰세요. - 답변을
meta.intent와meta.audience로 기록하세요. 기존 페이지를 확장할 때는 다시 묻지 않고 해당meta.intent를 재사용하세요.
그런 다음, 동일한 대화 또는 짧은 배치 내에서 다음을 결정하세요:
- scope: 대상 리포지토리 또는 그 일부
- audience: 신규 개발자, 검토자, 관리자 또는 발표
- focus: 가장 중요한 부분(가장 깊이 있게 다룰 부분)
- confidentiality: 페이지는 공유되므로, 달리 지시하지 않는 한 호스트, 비밀, 고객 이름 및 미공개 계획은 제외하세요.
코드가 없으면 사용자의 설명을 기반으로 작업하세요. 부분, 흐름 또는 숫자를 절대 임의로 만들지 마세요.
2. 예산 내에서 단계적으로 코드베이스 읽기
대규모 리포지토리는 컨텍스트에 맞지 않으며, 전체 파일을 훑어보는 것은 컨텍스트를 낭비합니다. 다이어그램이 근거를 확보하는 즉시 중단하고 단계적으로 읽으세요.
| 단계 | 명령어 | 얻는 것 | 비용 |
|---|---|---|---|
| 지도 | python scripts/scan_repo.py REPO [--section NAME] | 언어, 레이아웃, 매니페스트, 진입점, file:line과 함께 I/O 신호, 부분 간 임포트, 먼저 읽어야 할 목록 | 적음, --budget으로 제한됨 |
| 윤곽 | python scripts/scan_repo.py REPO --outline [PREFIX] | 모든 클래스와 함수, 시그니처 및 첫 번째 독스트링 라인(본문 제외) | 중간, --budget으로 제한됨 |
| 증거 | python scripts/peek.py REPO file:line file:symbol ... | 각 참조 주변 라인만 병합, 고정된 라인 및 토큰 예산 내 | 호출당 적음 |
| 심층 | 전체 파일 읽기 | 사용자 관심 영역의 핵심 로직을 담은 3~8개 파일만 | 많음 |
단계별 작업 방법:
- README, 문서 및 지도(Map)부터 시작하세요.
- 중요한 폴더에 대해 윤곽(Outline)을 사용하세요. 대규모 리포지토리의 경우 모든 것을 대상으로 실행하기보다는 최상위 부분별로 실행하세요.
- 그리려는 모든 I/O 신호 및 진입점과 모든 프로세스 수준 뒤에 있는 함수에 대해
peek을 사용하세요. - 로직이 정말 복잡한 경우에만 전체 파일을 읽으세요.
- 실행 중인 증거 목록(노드 →
file:symbol)을 유지하세요. 이것이source필드가 됩니다. - 스캔은 정규식 기반이므로 동적 연결을 놓치고 문자열 내 패턴과 같은 일부 위양성을 보고합니다. 그리기 전에
peek으로 확인하세요.
토큰 예산. 모든 명령은 비용(≈N tokens)으로 끝납니다. 맵에 필요한 만큼만 사용하세요:
- 윤곽을 확인하기 전에는 전체 파일을 절대 읽지 마세요. 넓은 라인 범위가 아닌
file:symbol을 Peek하고, 여러 참조를 하나의peek호출로 일괄 처리하세요. - 잘린 목록은
… N more; rerun with --section X로 끝납니다. 다이어그램에 필요한 경우에만 가져오세요. 대규모 리포지토리에서는--outline PREFIX를 사용하여 한 번에 한 부분씩 윤곽을 그리세요. - 그리려는 모든 노드에
source가 있으면 읽기를 중단하세요. unfold.py check및outline으로 확인하세요. JSON이나 페이지를 다시 읽지 마세요. 작은 편집으로diagram.json을 패치하고, 전체를 다시 출력하지 마세요.
비용, 스캔 캐시 및 건너뛰는 항목: references/reading-code.md (토큰 예산).
3. 시스템 경계 확정
입력(요청, 구독한 토픽, CLI 인수, 읽은 파일, 센서, 구성)과 출력(응답, 게시한 토픽, 쓴 파일, 명령, DB 쓰기)을 나열하세요. 모든 아키텍처 및 프로세스 수준에서 "role": "input" 또는 "role": "output"으로 표시하세요.
4. 각 수준에 대한 다이어그램 선택
개요는 항상 architecture여야 합니다: 4~10개의 부분, 저장소 및 외부 시스템, 왼쪽에 입력, 오른쪽에 출력. 열어볼 가치가 있는 각 부분은 해당 코드에 적합한 하위 유형을 얻습니다:
| 내부 코드가… | type | 그리기 |
|---|---|---|
| 서로 호출하거나 메시지를 주고받는 여러 부분 | architecture | rounded 부분, cylinder 저장소, cloud 외부 시스템 |
| 입력에 대한 일련의 단계: 핸들러, 파이프라인, 작업 또는 알고리즘 | process | pill 시작/종료, rect 단계, diamond 결정(레이블이 지정된 분기), 점선 루프백 |
| 시간 경과에 따른 부분 간 상호 작용: 요청 수명 주기, 핸드셰이크, 액션 목표 | sequence | 참가자를 왼쪽에서 오른쪽으로 노드로 표시; 순서대로 메시지를 엣지로 표시; 반환은 점선 |
| 상태와 이벤트에 의해 구동되는 동작: 상태 머신, 모드 관리자, 연결, 행동 트리 상태 | state | initial 및 final 마커, pill 상태, 이벤트 또는 가드로 레이블이 지정된 엣지 |
| 데이터 구조, 스키마, ORM 모델, 메시지 정의 | data | fields가 있는 table 노드("id: int PK"), 카디널리티로 레이블이 지정된 엣지 |
| 클래스와 그 관계: 객체 모델, 플러그인 계층 구조 | class | fields 및 methods가 있는 class 노드; rel이 있는 엣지(inherits, implements, composition, …) |
| 시스템이 있는 세계: 사용자, 주변 시스템, 각 컨테이너의 기술 | c4 | 사람은 person, tech가 있는 부분, cloud 외부 시스템, 그룹은 경계 |
| 실행 위치: 호스트, 장치, 클러스터, 컨테이너 | deployment | node3d 머신, 환경 그룹, 각각에 tech |
| 모듈 또는 패키지 임포트 | dependency | rect 모듈, 임포터에서 임포트된 대상으로의 엣지 |
| 행동 트리(py_trees, BehaviorTree.CPP, Nav2) | behaviour | bt가 있는 노드(sequence, selector, parallel, decorator, action, condition); 실행 순서대로 부모 → 자식 엣지 |
| 계층 구조: 구성 트리, 메뉴, 문서, 토픽 | tree | 순서대로 부모 → 자식 엣지 |
| 릴리스, 마이그레이션, 부팅 또는 시작 순서 | timeline | 각각 date가 있는 순서대로 노드 |
코드가 더 깊이 들어가는 곳에서는 더 깊이 들어가고, 참고 사항으로 충분한 곳에서는 멈추세요. 내부에 3개 이상의 의미 있는 요소가 있는 경우에만 부분을 여세요. 각 수준을 약 12개 노드로 유지하고, 그 이상은 중첩하세요. references/reading-code.md에는 웹 서비스, ROS 2, 파이프라인, CLI, 펌웨어, 프론트엔드 및 모노리포지토리에 대한 패턴이 있습니다.
5. 코드에 시각 자료가 있는 경우 추가
리포지토리에 스크린샷, 아키텍처 이미지, 데모 GIF 또는 비디오가 포함된 경우(docs/, assets/ 및 README에서 확인), "media": {"src": "relative/path.png", "caption": "…"}를 사용하여 첨부하거나, 부분에 여러 개를 제공하려면 목록으로 첨부하세요. 미디어가 있는 노드는 썸네일 배지를 표시하고 뷰어를 엽니다. "shape": "image"가 있는 노드는 캔버스에 그림을 표시합니다. 데모의 경우, 표시하는 부분의 스크린샷을 사용자에게 요청하세요.
unfold.py build는 로컬 파일을 인라인으로 포함합니다. 게시된 claude.ai 페이지는 원격 이미지를 차단하므로 로컬 파일을 선호하세요.
6. 단어 작성
meta.summary: 시스템이 누구를 위해 무엇을 하는지 한 문장.meta.glossary: 최대 8개의 프로젝트 용어, 각각 10단어 이하의 정의.- 수준별
caption: 목적에 대한 한 줄, 예: "팔이 움직이기 전에 모든 목표가 도달 가능한지 확인됩니다". - 노드의
note: 첫 번째 문장은 호버 시 표시되므로 독립적으로 작동해야 합니다. 최대 두 문장이 더 세부 카드에 표시됩니다. - 엣지 레이블: 흐르는 것을 1~3단어로.
7. 투어 작성
학습 및 시연의 경우(그리고 맵에 2개 이상의 수준이 있는 경우 항상), meta.tours 항목을 하나 추가하세요: 개발자가 설명하는 순서대로 입력에서 출력까지 59단계. 각 단계는 2문장의 path(개요에서부터 열 노드 ID 목록)와 선택적으로 강조할 node를 title 및 1text와 함께 지정합니다. 시연의 경우 발표자 notes를 추가하세요. 학습의 경우 하나의 quiz 단계({"q", "answer": node id, "explain"})로 끝냅니다. 투어가 작성되지 않은 경우 페이지에서도 투어를 생성하므로, 작은 단일 수준 맵의 경우 이 단계를 건너뛰세요.
8. 확인, 검토, 빌드
python scripts/unfold.py check diagram.json # 오류는 실패 처리; 모든 경고 읽기
python scripts/unfold.py outline diagram.json # 한 화면에 전체 트리
python scripts/unfold.py drift diagram.json --repo REPO # 모든 소스가 여전히 확인됨
python scripts/unfold.py build diagram.json page.html --repo REPO # meta.repo를 커밋에 고정
생성한 내용의 사본을 diagram.generated.json으로 diagram.json 옆에 보관하세요. 다시 매핑하려면 필요합니다.
자신이 신규 개발자라고 생각하고 윤곽을 읽어보세요:
- 시스템을 설명할 수 있습니까?
- 모든 수준이 입력 → 처리 → 출력에 답합니까?
- 각 하위 유형이 올바른 유형입니까?
Playwright와 같은 브라우저 자동화 도구를 사용할 수 있다면 개요와 각 유형의 내부 수준 하나를 스크린샷으로 찍고, 겹치거나 교차하는 부분을 수정하세요.
9. 전달
claude.ai에서 Artifact 도구를 사용하여 /mnt/user-data/outputs/에서 page.html을 게시하고 capabilities: {"artifact": {}, "downloads": true}를 설정하여 저장 및 내보내기를 활성화하세요. 다른 곳에서는 파일을 전달하세요. 오프라인에서 작동합니다.
그런 다음 사용자에게 몇 줄로 알려주세요:
- 개요에 표시되는 내용
- 추론된 부분
- 페이지를 읽는 방법: 클릭하여 열기, 호버하여 추적, Esc 또는 축소하여 돌아가기,
/로 검색, 투어 또는T로 가이드 투어,P로 발표, 편집으로 변경 - 내보내기는 PNG, SVG, PDF, Mermaid, draw.io 및 Excalidraw를 제공하여 슬라이드, README 및 기타 도구에 사용할 수 있음
사용자가 나중에 페이지를 편집한 경우, 이전 사본이 아닌 python scripts/unfold.py extract page.html diagram.json에서 계속 진행하세요.
코드 변경 후 다시 매핑하려면 --changed-since <meta.repo.commit>으로 스캔하고, 동일한 ID로 diagram.generated.json의 사본을 업데이트한 다음 unfold.py merge를 사용하여 편집된 맵에 병합하여 수동 편집 내용이 유지되도록 하세요. 단계: references/reading-code.md (Re-mapping).
참고
references/intents.md: 각 의도가 변경하는 사항과 후속 질문.references/schema.md: 모든 필드, 수준 유형, 모양 및 색상.references/reading-code.md: 코드를 수준으로 변환, 생태계별 패턴 포함.- 단일 다이어그램을 위해
assets/template.html을 변경하지 마세요. 엔진 변경은 리포지토리에서 테스트와 함께 이루어져야 합니다.