20만 라인 규모의 코드베이스에 방금 투입되었는데, 무슨 일이 벌어지고 있는지 전혀 모르는 상황을 상상해 보세요. 이 도구가 그 문제를 해결합니다.

대부분의 '내 코드를 설명해 줘' 도구들은 코드를 읽고 멈춰버립니다. 하지만 코드는 무엇이 존재하는지만 알려줄 뿐입니다. 왜 그런지, 그리고 위험 요소(landmines)는 구조와 역사에 존재합니다. wtfismyrepo는 온보딩을 독해 문제가 아닌 그래프 문제로 다룹니다. 즉, 임포트 그래프를 구축하고, PageRank를 실행하여 시스템을 지탱하는 핵심 파일을 찾고, git churn으로부터 취약성(fragility) 점수를 매기며, GitHub 히스토리(열린 PR = 뜨거운 구역, 이슈 = 문제점)를 읽어 정확히 어디서 시작해야 하는지 알려줍니다.

그리고 대부분의 도구들이 잘못 처리하는 부분이 있습니다. 바로 설명 자체입니다. 단일한 선형적 워크스루는 우연히 어떤 각도에서 시작하느냐에 따라 고정됩니다. 그래서 wtfismyrepo는 내부적으로 **ADHD 발산 사고 엔진(ADHD divergent-ideation engine)**을 실행합니다. 이는 여러 온보딩 각도를 병렬로 생성합니다 (신입 개발자, 고고학자, 보안 연구원, 새벽 3시 당직 근무자 등). 이 과정에서 상호 간의 영향을 주고받지 않으며, 이후 비평가 패스(critic pass)를 통해 점수를 매기고 함정을 제거하며 당신과 당신의 목표에 가장 적합한 단일 최적 각도를 심화합니다.

)은 커밋 히스토리(commit history)가 활성화되어 있어야 합니다. 이 리포지토리와 같이 커밋이 하나뿐인 리포지토리는 비어 있으며, 성숙한 코드베이스(mature codebase) 내에서 진정으로 위험한 파일들을 순위 매깁니다.

단 한 번의 명령으로 — Claude Code 에이전트에 기술을 설치합니다 (npm 계정이 필요하지 않습니다):

npx github:nandnijaiswal/wtfismyrepo install

Claude Code를 재시작한 후, 다음과 같이 질문하세요: "wtf is this repo" (이 리포지토리는 대체 뭐야?) · "I'm new here, where do I start?" (여기 처음인데, 어디서부터 시작하면 좋을까?)

변형(Variant)	기능
... install	개인 설치 (~/.claude/skills/) — 모든 프로젝트 적용
... install --project	이 리포지토리에만 설치 (./.claude/skills/)
... uninstall	제거

Cursor / Codex / 다른 에이전트를 사용 중인가요? @~/.claude/skills/wtfismyrepo/SKILL.md를 다음 파일에 추가하세요:

CLAUDE.md

/ AGENTS.md

/ .cursorrules

전체 매트릭스는 documentation/install.md에서 확인할 수 있습니다.

CLI:

npx github:nandnijaiswal/wtfismyrepo . # 현재 위치한 리포지토리 분석
wtfismyrepo . --json # 기계 판독 가능 형식 (기술이 소비하는 데이터 형식) 
wtfismyrepo ../service --no-history --top 5 # 오프라인 모드, 상위 5개만 추출
...

Library:

import { analyze, renderText, buildADHDContext } from "wtfismyrepo";
const report = analyze(".", { history: true, top: 10 });
console.log(renderText(report));
...

전체 레퍼런스: documentation/api.md.

두 개의 엔진이 체인(chained)으로 연결되어 있습니다. 데이터 엔진 (data engine) (결정론적, deterministic)은 실제 구조(ground-truth structure)를 추출하며, ADHD 엔진 (ADHD engine) (발산적, divergent)은 이를 적절한 설명으로 변환합니다.

┌─ DATA ENGINE (deterministic) ────────────────────────────────────────┐
│ files ─► import parser ─► directed import graph ─► PageRank ──┐ │
│ ├─ spine│
...

데이터 엔진 (Data engine):

스캔 (Scan)— git으로 추적되는 파일 목록을 나열하고 (.gitignore 준수), 파싱 가능한 소스 코드(JS/TS/JSX/Python/Go)를 읽습니다. 그래프 (Graph)— 실제 import / require / from 문을 파싱하고, 내부 파일로 해석하여, 누가 누구에게 의존하는지에 대한 그래프를 구축합니다. PageRank— 댐핑(damping) 및 댕글링 노드(dangling-node) 처리가 포함된 거듭제곱 반복법(power iteration)을 사용합니다. 높은 랭크(rank) = 스파인(spine, 중추).
변동성 (Churn)— git log

파일당 변경 빈도(change-frequency).취약성 (Fragility)—normalize(centrality) × normalize(churn)

중심성이 높으면서(Central) 변동성(Churn)도 높은 파일은 주의해서 다뤄야 합니다.이력 (History)—gh

열려 있는 PR(Pull Request) (→ 핫 존(hot zones)), 병합된 PR (→ 컨벤션(conventions)), 이슈(issues) (→ 고충 및 good-first-issues).

ADHD 엔진 (UditAkhourii/adhd, MIT) — wtfismyrepo explain

분석 내용을 ADHD 문제와 컨텍스트(context)로 패키징한 다음, 발산(diverge) → 점수화(score) → 클러스터링(cluster) → 심화(deepen) 루프를 실행합니다. 이를 통해 설명이 첫 번째 결과에 고착(anchoring)되는 대신, 여러 병렬적인 관점에서 선택될 수 있도록 합니다. adhd-agent가 설치되어 있지 않으면, CLI는 포맷팅된 ADHD 프롬프트를 출력하며, 스킬(skill)은 Claude를 생성기로 사용하여 동일한 루프를 실행합니다.

이 엔진은 테스트(PageRank 정확성, import 파싱, 점수화, 설치, ADHD 컨텍스트 구축)를 거쳤으며, Node 18 / 20 / 22 환경의 CI(지속적 통합)에서 실행됩니다. 심층 분석: documentation/how-it-works.md.

페이지	내용
설치 (Install)	모든 설치 경로 — 스킬(skill), CLI, 라이브러리, 에이전트별
...
또한: SKILL.md — 실행 가능한 Claude Code 스킬.

bin/wtfismyrepo.mjs CLI 엔트리 (analyze · install · uninstall)
src/
index.mjs 공개 라이브러리 인터페이스
...

이 프로젝트는 초기 단계의 프로젝트입니다. 다음과 같은 초기 이슈와 PR(Pull Request)을 특히 환영합니다:

• Rust / Java / Ruby import 파싱
• GitHub REST API를 통한 gh 비의존적(free) 이력 확인
• 디렉토리별 "책임(responsibility)" 요약
• npm 배포 (npx wtfismyrepo 사용, github: 접두사 불필요)
• 온보딩 보고서의 HTML/JSON 내보내기

스파인(spine) 랭킹이 잘못되어 보이거나, 파싱해야 할 언어를 발견한 저장소(repo)가 있나요? 이슈를 열어주세요. 현재 가장 유용한 기여입니다.

설명 레이어는 Udit Akhouri(MIT)가 개발한 ADHD — Parallel Divergent Ideation for Coding Agents를 기반으로 작동합니다. wtfismyrepo는 ADHD의 diverge→score→cluster→deepen 엔진과 프레임 기반 생성 방식을 코드베이스 온보딩 문제에 맞게 조정했습니다 — src/onboarding-frames.mjs 및 src/explain.mjs를 참조하세요.

인지 프레임 (cognitive-frame) 설계와 생성자/비판자 (generator/critic) 분리는 ADHD의 것이며, 코드베이스 특정 프레임 (codebase-specific frames) 및 분석→문제 매핑 (analysis→problem mapping)은 이 프로젝트의 것입니다.

MIT © Nandni Jaiswal

결정론적 데이터 엔진 (deterministic data engine)은 src/에 있으며,

ADHD 설명 레이어 (ADHD explanation layer)는 src/explain.mjs와 src/onboarding-frames.mjs에 있습니다.

실행 가능한 기술 (runnable skill)은 SKILL.md입니다.

이제 나아가 길을 잃지 마세요.