TL;DR

  • codebase-guide는 저장소를 읽어 실제 코드에 근거한 온보딩 문서를 단일 오프라인 HTML 파일로 생성하는 도구임.
  • 프로젝트 개요, 구성 요소, 실제 요청의 코드 흐름, 작업별로 열 파일과 함수를 하나의 안내서에 담음.
  • 다이어그램과 코드 발췌는 실제 코드에서 가져오며, 불확실하거나 사용되지 않는 것으로 보이는 항목은 추측하지 않고 표시함.
  • 약 14만 줄의 Rust와 TypeScript로 구성된 Tauri·React 데스크톱 앱 Let me cook!을 대상으로 안내서를 작성한 사례가 제시됨.
  • Claude 플러그인으로 설치해 /codebase-guide를 실행하며, 기본 출력 경로는 docs/codebase-guide.html임.

왜 유용한가

  • 처음 접하는 사람은 평이한 문장으로 된 프로젝트 소개, 용어 설명, 전체 시스템 다이어그램으로 구조를 파악할 수 있음.
  • 익숙한 사람은 기능과 일반 작업을 시작할 파일 및 함수에 연결하는 ‘찾아볼 위치’ 표를 이용해 필요한 파일을 찾을 수 있음.
  • 코드 발췌에는 실제 줄 번호가 포함되고, 안내서가 작성된 커밋이 기록되며, 불분명하거나 사용되지 않는 것으로 보이는 항목은 추측 대신 표시됨.
  • 글꼴, 스타일, 다이어그램을 포함한 단일 파일이며 docs/에 커밋하거나 새 직원에게 전달하거나 PDF로 인쇄할 수 있음.

안내서 구성

  • 모든 안내서는 1분 개요, 핵심 용어, 주요 구성 요소, 실제 실행 흐름의 단계별 추적, 알아둘 패턴, 찾아볼 위치, 직접 실행하는 방법, 접어서 볼 수 있는 심화 설명의 여덟 섹션으로 구성됨.

한 장으로 보는 전체 시스템

  • 각 상자는 코드베이스의 실제 구성 요소를 나타내고 해당 폴더 이름이 표시됨.
  • 실선 화살표는 호출을, 점선 화살표는 이벤트를 나타냄.

각 구성 요소의 디스크 위치

  • 폴더 지도는 모든 구성 요소를 해당 디렉터리에 연결하며, 번호는 아래쪽의 구성 요소 카드와 일치함.

실제 실행 흐름의 단계별 추적

  • 시퀀스 다이어그램은 실제 함수들을 따라 단일 요청의 흐름을 보여줌.
  • 다이어그램 아래 번호가 붙은 단계에는 각 화살표에 해당하는 파일과 함수가 명시됨.

코드베이스의 관례

  • 반복되는 관례마다 실제 코드 발췌, 발췌된 줄 범위, 해당 방식을 사용하는 이유가 제시됨.

찾아볼 위치

  • 수행하려는 작업을 기준으로 표를 확인하면 살펴볼 위치와 시작할 함수가 안내됨.

설치

  • 다음 두 명령으로 Claude 플러그인 마켓플레이스를 추가하고 codebase-guide를 설치함.
  • claude plugin marketplace add dimitritholen/codebase-guide
  • claude plugin install codebase-guide@codebase-guide

사용법

  • /codebase-guide 명령으로 실행하며, 같은 이름의 스킬을 가진 다른 설치 플러그인이 없으면 짧은 형식도 사용 가능함.
  • 코드베이스 안내서, 온보딩 문서, 아키텍처 개요를 요청하거나 “이 저장소를 설명해줘”라고 말해 실행할 수도 있음.
  • 다른 경로를 지정하지 않으면 docs/codebase-guide.html에 안내서가 작성되며, 그 밖의 파일은 수정되지 않음.

설정

  • design_system 설정은 안내서의 디자인을 지정하며, meridian과 builtin을 선택할 수 있고 기본값은 meridian임.
  • meridian은 글꼴을 포함한 편집 디자인 시스템이며, builtin은 스킬 자체 템플릿을 사용함.
  • /config에서 설정을 바꾸거나 CODEBASE_GUIDE_DESIGN_SYSTEM 환경 변수로 한 번의 셸 실행에 적용할 수 있음.
  • 새 디자인 시스템이 충족해야 하는 계약은 design-systems/README.md에 설명됨.

요구 사항

  • 디자인 시스템 설정을 확인하려면 python3이 필요함.
  • 디자인 시스템 초안을 단일 오프라인 HTML 파일로 내보내려면 node가 필요하며, builtin 사용 시에는 필요하지 않음.

테스트

  • 키나 네트워크 없이 tests/*.test.sh에 있는 테스트를 셸에서 차례로 실행할 수 있음.

라이선스

  • 함께 제공되는 Newsreader와 Public Sans 글꼴은 SIL Open Font License를 따름.
  • 라이선스 고지는 design-systems/meridian/assets/fonts/의 글꼴 파일 옆에 있으며, 내보내는 모든 안내서에 포함됨.