코드 읽기·온보딩·리뷰: 낯선 레포를 빠르게 내 것으로

낯선 레포를 열었을 때 가장 큰 적은 "모르는 코드"가 아니라, 어디서부터 봐야 할지 모르는 상태입니다. 이 장의 목표는 그 상태를 빠르게 끝내고, "내가 지금 어디를 보고 있고 다음에 어디를 보면 되는지"가 머릿속에 그려지게 만드는 것입니다.

핵심은 두 가지입니다. 첫째, 레포를 설명하려고 하지 말고 지도를 만든다. 둘째, 코드를 통째로 읽지 말고 엔트리포인트 → 주요 흐름 → 작은 변경 순으로 "확인 가능한 이해"를 쌓는다.

1시간 온보딩의 정의: '읽는 시간'이 아니라 '결정 가능한 상태'

온보딩을 "코드를 많이 읽는 일"로 정의하면 반드시 하루가 걸립니다. 대신 이렇게 정의하면 속도가 달라집니다.

첫째, 이 레포가 해결하는 문제를 한 문장으로 말할 수 있다.

둘째, 핵심 엔트리포인트(요청이 들어오는 지점) 3개를 짚을 수 있다.

셋째, 변경을 넣었을 때 영향 범위를 예측할 수 있다(최소한 테스트/빌드 경로는 안다).

이 세 가지가 되면, 남은 건 "모르는 부분을 필요한 만큼만 학습하는 반복"입니다.

0~10분: 레포의 '외곽선'부터 잡기

코드에 들어가기 전에, 레포가 스스로 말하는 정보를 먼저 읽습니다. README, 실행 스크립트, CI 설정은 "팀이 지금도 믿고 있는 진실"에 가장 가깝습니다.

여기서 Codex의 역할은, 문서를 대신 읽는 게 아니라 요약을 고정된 형식으로 뽑아 이후 작업의 기준을 만드는 것입니다.

예를 들어 TUI에서 이렇게 시작합니다.

이 레포의 목적을 3문장으로 요약해줘.
그 다음:
- 주요 엔트리(웹/CLI/워커/배치 등) 형태
- 로컬 실행 명령(최소 1개)
- 테스트/린트/빌드 명령을 '치트시트'로 정리
형식은 Markdown으로.

그리고 결과를 notes/onboarding.md 같은 파일로 만들어 달라고 요청합니다. GitHub 엔지니어들이 새 코드베이스를 학습할 때도 개인 문서(살아있는 노트)를 유지하고, 명령 치트시트를 만들고, 발견을 축적하는 방식을 권합니다.¹

10~25분: 핵심 엔트리포인트를 '패턴으로' 찾기

엔트리포인트는 "코드 경로의 시작점"입니다. 이걸 못 찾으면, 아무리 많은 파일을 읽어도 퍼즐 조각만 늘어납니다.

좋은 소식은, 엔트리포인트는 프레임워크가 강하게 힌트를 준다는 점입니다. 예를 들어 Spring Boot면 @RestController, Django면 URL 라우팅 설정, gRPC면 .proto의 service 정의가 출발점이 됩니다.²

레포 종류별로, 먼저 "엔트리포인트 후보 파일"을 잡습니다.

• 백엔드 HTTP 서비스: 라우터/컨트롤러/핸들러 파일

• 프론트엔드: 라우팅 설정, 앱 부트스트랩(예: main.tsx), 상태 초기화

• CLI 도구: main()/엔트리 스크립트

• 워커/컨슈머: 큐 리스너, 크론 잡, 핸들러 등록부

그리고 Codex에게 "탐색을 대신 시키는" 게 아니라 "탐색의 목표를 좁히는" 질문을 던집니다.

레포에서 요청이 시작되는 엔트리포인트를 3종류로 분류해줘:
1) HTTP 요청 핸들러
2) 비동기 작업(큐/크론/워커)
3) CLI/배치 엔트리
각 분류별로 후보 파일 경로를 '찾는 방법'(검색 키워드/파일명 패턴)까지 제시해줘.
추정만 하지 말고, 근거가 되는 파일을 먼저 찾아서 인용해.

이때부터는 Codex가 찾은 "근거 파일"을 중심으로 IDE의 점프 기능(정의로 이동, 참조 찾기)으로 호출 경로를 따라가면 됩니다. 낯선 코드베이스를 읽을 때 IDE로 콜스택을 따라 내려가며 시나리오를 노트로 남기는 방식은 특히 효율적입니다.²

25~40분: '대표 시나리오 1개'로 데이터 흐름을 그리기

온보딩이 느려지는 순간은 보통 이때입니다. 엔트리포인트는 찾았는데, 중간 계층(서비스/리포지토리/모듈)이 많아져서 길을 잃습니다.

해결책은 "기능 전체"가 아니라 대표 시나리오 하나를 정해, 데이터가 어디서 들어와 어디로 나가는지만 그리는 것입니다.

1. 입력: HTTP 요청 바디/쿼리/헤더, 또는 메시지 페이로드

2. 변환: 검증/매핑/도메인 로직

3. 출력: DB 쓰기/외부 API 호출/응답 반환

Codex에는 이렇게 시킵니다.

'로그인'(또는 가장 대표적인) 플로우를 하나 골라,
엔트리포인트부터 최종 DB/외부 호출까지 함수/메서드 경로를 나열해줘.
각 단계마다 "왜 다음 단계로 넘어가는지(호출 이유)"를 한 줄로 설명해.
결과는 번호 목록으로.

이 산출물이 생기면, 이제부터는 "파일을 읽는 것"이 아니라 "경로의 특정 구간을 검증"하는 작업이 됩니다.

40~55분: 작은 변경으로 '이해를 확정'하기

코드 이해는 읽어서 끝나지 않습니다. 진짜 내 것이 되는 순간은 내가 변경을 넣고, 예상한 결과가 나오는지 확인했을 때입니다.

이 단계에서 추천하는 첫 변경은 '기능 추가'가 아니라 다음 중 하나입니다.

• 문서/치트시트 보강(방금 만든 notes/onboarding.md를 정리)

• 로그 1줄 추가(핵심 플로우의 특정 지점 확인)

• 테스트 1개 추가(대표 시나리오의 기대 동작을 코드로 고정)

GitHub에서도 새 코드베이스를 배울 때 작은 이슈("Good First Issue")부터 시작해 자연스러운 진입점을 만들고, 테스트를 통해 의도를 확인하는 접근을 강조합니다.¹

Codex에게는 "작은 변경"을 강제로 설계하게 만드세요.

내 목표는 '작은 PR'이야.
방금 정리한 대표 시나리오에서,
(1) 변경 파일 2개 이하
(2) diff 200줄 이하
(3) 테스트 또는 문서 변경을 포함
조건을 만족하는 첫 PR 아이디어 3개를 제안해줘.

55~60분: /review + diff 기반 검토 루틴으로 '실수 방지 장치' 만들기

온보딩이 빨라질수록 실수도 늘기 쉽습니다. 특히 낯선 레포에서는 diff를 오래 들여다보는 순간 인지 부하가 급격히 올라가고, 앞부분 맥락을 잊어버리는 일이 흔합니다.⁴

그래서 마지막 5분은 "내가 다음부터 자동으로 하게 될 리뷰 루틴"을 고정합니다.

루틴 A: 커밋 전 3분 /review

Codex CLI의 /review는 스테이징된 변경을 대상으로 코드 리뷰 에이전트를 실행하는 워크플로로 소개됩니다.³

습관은 간단합니다.

# 1) 변경을 의도대로 스테이징
git add -p

# 2) Codex TUI에서
/review

/review 결과를 읽을 때는 "좋다/나쁘다"가 아니라, 아래 분류로 다시 정리합니다.

• 반드시 수정(Blocking): 보안/데이터 손상/호환성/테스트 실패 가능성

• 권장 수정(Important): 에러 처리/관측성/성능 퇴화 가능성

• 제안(Suggestion): 가독성/구조/네이밍

루틴 B: diff를 '큰 그림 → 핵심 변경 → 주변 맥락' 순서로 읽기

리뷰는 줄 단위로 바로 들어가면 맥락을 놓치기 쉽습니다. 다음 순서를 고정해두면 빠르고 안전합니다.

먼저 전체 범위를 봅니다.

git diff --stat

그 다음 핵심 파일만 봅니다.

git diff -- path/to/core_file

마지막으로 "주변 맥락(위아래 몇 줄)"을 IDE에서 확인합니다. diff는 바뀐 줄을 잘 보여주지만, 의도와 의존성은 숨기기 때문에 주변 코드를 보는 습관이 필요합니다.⁴

루틴 C: 세션 변경 추적용 /diff

긴 세션에서는 "내가 뭘 바꿨지?"가 곧 리스크가 됩니다. Codex CLI에서 /diff는 세션 시작 시점 대비 변경을 보여주는 명령으로 안내됩니다.³

/diff

온보딩 초기에 이 루틴이 특히 좋은 이유는, 레포의 표준(포맷/스타일/규약)을 아직 몸에 익히기 전이라 "의도치 않은 변경"이 쉽게 섞이기 때문입니다.

온보딩 산출물: 1시간 뒤에 남겨야 할 파일 1개

1시간 온보딩의 성패는 "내 머리에 남았는가"가 아니라 "내일의 내가 바로 이어갈 수 있는가"로 결정됩니다. 다음 템플릿을 notes/onboarding.md로 남기세요.

# 프로젝트 온보딩 노트

## 이 프로젝트는 무엇을 한다(3문장)

## 로컬 실행 치트시트
- 

## 테스트/린트/빌드 치트시트
- 

## 엔트리포인트 3개
- 

## 대표 시나리오 1개: 호출 경로
1.
2.
3.

## 위험한 지점/주의사항
- 

## 다음에 할 '작은 PR' 후보
- 

이 파일이 있으면, 낯선 레포는 더 이상 낯설지 않습니다. 다음부터는 "지도에 표시된 구간"만 확장하면 됩니다.

참고

¹How GitHub engineers learn new codebases

²🧠 How to Learn Unfamiliar Codebases

³How to Use Slash Commands in OpenAI Codex CLI

⁴The Cognitive Load Problem in Code Reviews: Why Diffs Are Not Enough