ramp은(는) 무엇을 하나요?
낯선 레포지토리의 주제를 대화형 지도로 변환합니다: 그룹화된 노드, 레이블이 있는 엣지, 클릭 가능한 상세 패널, 실제 런타임 순서를 추적하는 번호별 워크스루.
파이프라인은 의도적으로 분할되어 있습니다. 정적 패스는 어떤 코드가 중요한지 찾고, 당신은 그것이 무엇을 의미하는지 결정하며, 렌더러가 그림을 그립니다. 정적 패스를 건너뛰고 레포지토리를 자유롭게 읽는 것은 더 느리고 파일을 놓칠 수 있습니다. 당신의 패스를 건너뛰면 아무도 배울 게 없는 호출 그래프가 생성됩니다.
워크플로우
1. 스캔
node ~/.claude/skills/ramp/scripts/scan.js <레포> --topic "<주제>" --max 30 --out /tmp/scan.json
경로는 절대 경로입니다. 당신은 스킬 디렉토리가 아닌 대상 레포지토리에서 실행할 것이기 때문입니다.
아직 레포지토리의 구조를 모른다면 먼저 --topic 없이 실행하세요. 언어 구성, 가장 큰 디렉토리, 가장 많이 임포트된 파일(허브) 개요를 출력하며, 보통 좋은 주제를 고르기에 충분합니다.
주제 스캔은 score, matched 용어, 추출된 defs가 있는 nodes(파일)와 그 사이의 edges를 반환합니다. seed: true는 직접적인 주제 일치를 표시하며, 나머지는 그래프 확장으로 추가된 호출자와 피호출자입니다.
아무것도 반환되지 않으면 주제 용어가 코드에 나타나지 않는 것입니다. 사용자가 사용한 용어 대신 코드베이스가 사용하는 용어를 시도해보세요.
2. 읽기
시드 파일과 이름이 암시적인 확장 노드를 읽으세요. 제대로 읽으세요 — 지도의 전체 가치는 설명에 있으며, 파일 목록만으로 유용한 detail을 작성할 수 없습니다.
읽는 동안 특히 다음을 찾으세요:
- 진입점 — 이 흐름이 런타임에 어디서 시작되는가?
- 명확하지 않은 것 — 버그를 방지하는 가드, 실제 작업을 수행하는 설정 플래그, 신규 개발자를 놀라게 할 것
- 실제 순서 — 런타임에 무엇이 무엇을, 어떤 순서로 호출하는가
3. 모델링
모델 JSON을 작성하세요(스키마는 아래 참조). 이 부분은 판단력이 필요한 부분입니다.
4. 렌더링
node ~/.claude/skills/ramp/scripts/render.js /tmp/model.json -o /tmp/<레포>-<주제>.html
엄격하게 검증하며 깨진 모델(엣지의 알 수 없는 노드 ID, 중복 ID, 워크스루 참조 누락)은 렌더링을 거부합니다. 설명되지 않거나 고립된 노드에 대한 경고는 무시하기보다 수정할 가치가 있습니다.
5. 게시
렌더링된 파일을 Artifact 도구로 게시하고 사용자에게 링크를 제공하세요. artifact-design을 먼저 로드하지 마세요 — 템플릿은 이미 설계되었으며, 있는 그대로 게시하세요.
모델 스키마
{
"title": "로그인 흐름",
"repo": "my-app",
"summary": "한두 문장: 대상의 구조와 그것에 대한 가장 유용한 사실 하나.",
"groups": [{ "id": "boot", "label": "앱 부트", "hint": "선택적 툴팁" }],
"nodes": [{
"id": "provider",
"label": "AuthProvider",
"group": "provider",
"role": "세션 상태 소유",
"detail": "신규 개발자가 실제로 필요한 문단.",
"files": ["src/context/AuthContext.jsx:12"],
"symbols": ["AuthProvider", "signInWithGoogle"]
}],
"edges": [{ "from": "provider", "to": "supabase", "label": "getSession, OAuth" }],
"walkthrough": [{ "node": "provider", "text": "이 단계에서 일어나는 일." }]
}
groups는 왼쪽에서 오른쪽으로, 의존성 순서로 배치됩니다 — 진입점은 왼쪽에, 기본 요소는 오른쪽에. 엣지는 임포터에서 임포트된 쪽으로 그려지므로, 그룹이 이 순서를 따르면 깔끔하게 배치됩니다. 최대 6개 그룹까지 고유한 색상이 지정됩니다.
walkthrough는 선택 사항이지만 가장 가르치는 기능입니다. 파일 구조가 아닌 런타임 순서대로 정렬하세요. 노드는 여러 번 나타날 수 있습니다 — 흐름은 되돌아오며, 이를 보여주는 것이 핵심입니다.
좋은 지도와 쓸모없는 지도를 구분하는 기준
노드는 개념이지 파일이 아닙니다. 하나의 아이디어(AuthContext.jsx + AuthContextValue.js)를 가진 두 파일은 하나의 노드가 될 수 있고, 관련 없는 두 책임을 가진 하나의 파일은 두 개가 될 수 있습니다. 실제 파일은 모두 files에 넣으세요.
6–14개의 노드. 40개 노드가 있는 지도는 사용자가 이미 쳐다보고 있던 복잡 덩어리입니다. 흐름을 전달하는 것으로 자르세요 — 스캔의 score 순서가 무엇을 유지할지 알려줍니다. summary에서 무엇을 생략했는지 말하세요.
role은 역할이지, 재진술이 아닙니다. "세션 상태 소유" — "인증 제공자 컴포넌트"가 아닙니다.
detail은 클릭할 가치가 있어야 합니다. 이름에서 명확하지 않은 것을 넣으세요: 왜 이렇게 분할되었는지, 중요한 플래그, 방지하는 실패, 가정하는 것. detail이 레이블만 바꿔 말한다면, 노드를 삭제하거나 실제로 무엇을 하는지 알아내세요.
모든 엣지에 실제 관계를 레이블로 붙이세요 — "사용자에 의해 게이트됨", "getSession, OAuth" — "사용" 또는 "임포트"가 아닙니다.
라인을 인용하세요. files의 path/to/file.ts:42는 정확한 지점을 가리킵니다.
무엇이 중요한지, 무엇이 아닌지 말하세요. 신규 개발자는 어떤 부분을 무시해도 되는지 가장 알아야 합니다.
참고 사항
- 스캔은 의존성이 없는 Node이며 설치가 필요 없습니다. 대상이 git 레포지토리인 경우
.gitignore를 존중합니다. - Swift와 같은 패키지 내 Java/C#에는 파일 수준 임포트가 없습니다. 이러한 경우 스캔은 고유 타입 참조에서 엣지를 유추합니다. 이 엣지는 강력한 힌트로 간주하고 확실성은 낮춰야 합니다.
- 임포트 해석은 정규식 기반이며, 타입 체커가 아닙니다. 상대 경로, 번들러 별칭(
@/), 패키지 스타일 지정자를 경로 접미사로 해석합니다. 동적 임포트와 생성된 임포트는 놓칩니다 — 예상한 파일이 없으면 모델에 직접 추가하세요.