컨텐츠로 건너뛰기
레시피 생태계 소스 코드 문서

낯선 코드베이스 살펴보기

아무도 설명해주지 않은 프로젝트를 인계받았을 때, OpenCode는 훌륭한 안내자가 됩니다. import 그래프를 읽고, 진입점을 식별하며, 한 시간 안에 행동할 수 있는 지도를 만들어 줍니다.

이 레시피를 사용하는 경우

  • 새 팀에 합류했거나 유지보수되지 않는 저장소를 인계받은 경우
  • 코드베이스가 너무 커서 모든 파일을 읽는 것이 비현실적인 경우
  • 자신 있게 변경해야 하지만 아직 경계가 어디인지 모르는 경우

사전 준비

  • 프로젝트 루트를 가리키도록 설치된 OpenCode
  • 실행할 수 있는 빌드 또는 테스트 명령어
  • 저장소 전체에 대한 읽기 권한 (암호화된 서브모듈 없음)

단계

  1. 전체 구조 파악하기

    OpenCode에게 프로젝트 형태, 기술 스택, 진입점을 몇 문단으로 요약해 달라고 요청하세요.

    프로젝트 루트를 읽고 요약하세요: 언어와 프레임워크, 디렉터리 구조, 주요 진입점, 빌드/실행 명령어. 특이한 점이 있으면 강조하세요.

  2. 아키텍처 매핑하기

    한 페이지짜리 아키텍처 맵을 요청하세요: 모듈, 각 모듈의 책임, 그리고 모듈 간 통신 방식.

    모듈 맵을 그리세요: 어떤 디렉터리가 어떤 책임을 지고, 최상위 파일이 어디서 무엇을 import하는지. 의존성 방향(UI → service → data)이 있으면 표시하세요.

  3. 진입점 찾기

    요청, 작업, 명령이 시스템에 들어오는 지점을 식별하세요. 대부분의 버그와 기능 작업이 여기서 일어납니다.

    모든 진입점을 나열하세요: HTTP 라우트, CLI 명령, cron 작업, 메시지 핸들러, 예약된 작업. 각각에 대해 파일 경로와 한 줄 설명을 알려주세요.

  4. 대표 요청 추적하기

    하나의 종단간 흐름을 골라 처음부터 끝까지 따라가 보세요. 직관을 키우는 가장 빠른 방법입니다.

    단일 사용자 요청을 HTTP 라우트부터 서비스 계층, 데이터베이스까지 추적하세요. 호출 체인을 보여주고 각 계층의 책임을 설명하세요.

  5. 탐색 가이드 작성하기

    OpenCode에게 결과를 본인 및 팀원이 참조할 수 있는 CODEBASE_MAP.md로 정리해 달라고 요청하세요.

    저장소 루트에 CODEBASE_MAP.md를 작성하세요: 1) 한 문단 프로젝트 요약, 2) 모듈 맵, 3) 진입점 목록, 4) 추적한 예제 흐름 하나, 5) 관찰된 컨벤션(네이밍, 에러 처리, 로깅).

  6. 작은 변경으로 검증하기

    작지만 실제 변경(오타 수정, 로그 메시지 개선 등)을 하고 빌드, 린트, 테스트가 여전히 통과하는지 확인하세요.

    npm run build && npm test

핵심 프롬프트

저는 이 저장소를 처음 접합니다. 프로젝트 루트 전체를 읽고 다음을 생성하세요: (1) 한 문단 프로젝트 요약, (2) 의존성 방향을 포함한 모듈 맵, (3) 파일 경로가 포함된 모든 진입점, (4) 계층을 따라 추적된 종단간 요청 흐름 하나, (5) 네이밍, 에러, 로깅에 대해 관찰된 컨벤션. 저장소 루트에 CODEBASE_MAP.md로 출력하세요.

검증

  • CODEBASE_MAP.md가 커밋되어 팀과 공유됨
  • 추적한 예제 흐름을 수동으로 따라갔을 때 현실과 일치
  • 작지만 의도적인 변경이 빌드와 테스트를 통과

흔한 실수

  • 맵을 맹신하기: 그것을 진실이 아닌 가설로 다루세요. 리팩터링 전에 반드시 검증하세요.
  • 진입점을 건너뛰기: 대부분의 버그는 경계에 있습니다. 진입점 목록이 다이어그램보다 유용합니다.
  • 오래된 컨벤션: 코드의 오래된 부분은 팀이 이미 버린 패턴을 따를 수 있습니다. 각 영역의 최신 파일 날짜를 기록해 두세요.

관련 문서

  • 빠른 시작 — 새 프로젝트에서 OpenCode 실행하기
  • 설정 — OpenCode 동작을 제어하는 opencode.json 파일

관련 레시피

관련 문서

다음 단계