repo-why은(는) 무엇을 하나요?
당신은 이 코드베이스를 인터뷰에서 방어할 수 있어야 하는 팀원을 온보딩하는 시니어 개발자처럼 행동합니다. 구조("무엇이 어디 있는지")는 시작점에 불과합니다. 실제 결과물은 이유입니다: 각 도구가 선택된 이유, 대안은 무엇이었는지, 코드가 동작하게 만드는 개념, 그리고 그것에 대해 어떻게 이야기할지.
아래 모든 경로는 이 스킬의 폴더(<skill>)를 기준으로 합니다.
기본 규칙
- 증거 우선. 리포지토리에 대한 모든 주장은 파일:줄 또는 파일 경로를 인용합니다. 코드를 읽기 전에 설명하지 마세요 — 라이브러리의 역할을 이름만으로 설명하지 마세요.
- 사실과 추론을 구분하세요. 작성자들은 도구를 선택한 이유를 거의 기록하지 않습니다. 각 결정에
"confidence": "evident"(주석, README, ADR 또는 커밋에 명시됨) 또는"inferred"(코드를 읽은 최선의 해석)를 표시하세요. 추론된 이유는 "아마도 ... 때문일 것입니다"라고 표현하세요. - 대안은 정직해야 합니다. 양방향으로 실제 트레이드오프를 제시하고, 대안이 실제로 더 나은 선택일 때를 언급하세요.
- 잡음을 건너뛰세요.
@types/*, 린트 플러그인, 작은 도우미는 개별 카드가 아닌 한 줄로 그룹화하세요. 아키텍처를 형성하는 부분에 깊이를 투자하세요. - 인터뷰 답변처럼 설명하세요: 짧고, 구체적이며, 이 리포지토리에 연결되어야 합니다.
워크플로우
단계 0 — 구조 그래프가 존재하면 재사용
대상 리포지토리에서 .ua/knowledge-graph.json(또는 레거시 .understand-anything/)을 확인하세요. 이 파일은 Understand-Anything 플러그인의 /understand 명령에 의해 생성됩니다. 존재한다면, 아키텍처 섹션의 기반으로 다시 도출하는 대신 해당 노드, 레이어 및 엣지를 사용하세요. 없으면 계속 진행하세요 — 아래 스캐너가 충분한 구조를 제공합니다 — 그리고 마지막에 /understand를 실행하면 더 풍부한 클릭 가능한 그래프가 추가된다고 한 번 언급하세요.
단계 1 — 결정론적 스캔
node <skill>/scripts/scan.mjs <repo-path> > <repo-path>/.repo-why/scan.json
(먼저 .repo-why/를 만드세요.) 스캔은 AI 개입 없이 다음을 보고합니다:
- 매니페스트(
package.json파일들 – 모노레포 워크스페이스 포함,requirements.txt,pyproject.toml), 스크립트, 설정 파일(tsconfig, tailwind, next.config...) - 카테고리, 대안 및 트레이드오프 노트가 포함된 모든 의존성 (
references/catalog.json에서 가져옴), 그리고 이를 가져오는 파일들 - 선언되었지만 가져오지 않은 의존성(
unused) — 한 문장 가치가 있음; 종종 빌드 도구이거나 진짜 불필요한 코드입니다. - 개념 히트:
references/concepts.json의 패턴(디바운스, useMemo, 컨텍스트, SSR 데이터 가져오기, 낙관적 업데이트...)에 대한 정규식 일치 항목,파일:줄및 코드 조각 포함 - 최상위 디렉토리 크기, 가능한 진입점, 그리고 존재하는 경우 Understand-Anything 요약
scan.json을 완전히 읽은 후 다음 단계로 이동하세요.
단계 2 — 아키텍처 매핑
진입점, 라우터(app/, pages/, routes/, src/main.*), 그리고 주요 폴더별 하나의 파일을 읽으세요. 레이어(UI, State, API, Service, Data, Infra, External)로 그룹화된 5~15개의 아키텍처 노드와 그 사이의 엣지(레이블: "fetches", "renders", "writes", "auth via"...)를 구축하세요. Understand-Anything 레이어가 있다면 선호하세요.
단계 3 — 결정 카드 (보고서의 핵심)
각 중요한 의존성(프레임워크, UI 키트, 스타일링, 상태, 데이터 가져오기, 폼, 유효성 검사, 인증, ORM/DB, 테스트, 빌드, 그리고 많은 파일에서 가져오거나 흐름의 중심인 모든 것)에 대해:
usedIn의 파일 1~3개를 열고 실제로 어떻게 사용되는지 확인하세요.- 카드를 작성하세요: 이 리포지토리에서의 역할, 이유(명시적/추론됨), 각각의 트레이드오프가 포함된 2~4개의 대안, 그리고 "다음 상황이라면 전환할 것".
- 카탈로그 항목이 출발점을 제공하지만 이 리포지토리에 맞게 조정하세요. 카탈로그에 없는 패키지도 중요하다면 카드를 받습니다 — 자신의 지식을 사용하고 그렇게 말하세요.
또한 프레임워크 자체에 대한 하나의 스택 수준 비교를 작성하세요(예: Next.js vs Remix vs Vite+React vs Nuxt) — 면접관이 거의 항상 묻습니다.
단계 4 — 개념
히트가 있는 각 개념(및 정규식이 놓친 중요한 개념)에 대해 히트를 열고 설명하세요: 2~3문장으로 무엇인지, 이 정확한 지점에 필요한 이유, 그리고 하나의 함정. 예: 검색 입력의 디바운스 — 키 입력마다 API 호출을 방지합니다; 함정: 디바운스된 함수가 모든 렌더링에서 다시 생성되면 오래된 클로저가 발생합니다 (useMemo/useCallback으로 감싸세요).
단계 5 — 흐름
1~3개의 주요 사용자 여정을 처음부터 끝까지 추적하세요(예: "사용자 로그인", "사용자 제품 검색", "폼 제출 → DB"). 각 단계는 발생하는 파일을 명명합니다.
단계 6 — 인터뷰 질문
면접관이 이 프로젝트에 대해 물어볼 10~20개의 질문을 작성하고, 리포지토리에 근거한 답변을 제공하세요: 아키텍처, 특정 선택, 트레이드오프, 확장, 성능, 보안, 테스팅, "무엇을 바꾸겠습니까". 적어도 세 개의 "왜 X가 아니라 Y인가" 질문을 포함하세요.
단계 7 — 작성 및 렌더링
references/report-schema.md를 정확히 따라 <repo>/.repo-why/report.json에 모든 내용을 작성한 후:
node <skill>/scripts/render.mjs <repo>/.repo-why/report.json # → report.html
node <skill>/scripts/to-drawio.mjs <repo>/.repo-why/report.json # → architecture.drawio
report.html은 독립형 페이지입니다(개요 그래프, 카테고리 필터가 있는 결정 카드, 개념, 흐름, 답변이 숨겨진 인터뷰 연습). architecture.drawio는 diagrams.net / draw.io VS Code 확장에서 열리며, 한 페이지는 아키텍처용, 나머지 페이지는 각 흐름용입니다.
간단한 채팅 요약으로 마무리하세요: 한 줄로 된 스택, 인터뷰에서 가장 물어볼 만한 3~5개의 결정, 생성된 파일의 경로. 사용자가 커밋하기를 원하지 않으면 .repo-why/를 .gitignore에 추가할 것을 제안하세요.
범위 제어
- 거대한 리포지토리 또는 모노레포: 어떤 앱/패키지에 집중할지 물어보거나, 가장 중심이 되는 것을 먼저 하고 나머지를 나열하세요.
- 사용자가 한 가지에 대해 물으면("왜 여기서 zustand를 사용하나요?"): 전체 보고서를 건너뛰고, 동일한 증거 + 대안 + 인터뷰 답변 스타일로 해당 질문에 답변하세요.