다른 사람의 코드 읽기

어떤 코드베이스든 이해하는 체계적인 방법

⏱ 예상 ~8분

01 · 읽기

대부분의 초보자가 놀라는 비밀이에요. 프로 엔지니어는 코드를 쓰는 시간보다 읽는 시간이 더 길어요.

팀에 합류하거나, 프로젝트를 바꾸거나, 심지어 몇 주 뒤에 자기 코드로 돌아와도, 한 번도 써본 적 없는(혹은 썼던 걸 기억 못 하는) 코드를 이해해야 해요. 마구잡이로 스크롤하면서 이해되길 바라는 건 안 통해요. 시스템이 필요해요.

다행인 점은요? 코드 읽기는 기술이고, 다른 기술처럼 연습할수록 쉬워져요. 어떤 코드베이스에든 쓸 수 있는 반복 가능한 프로세스를 배워볼게요.

💡 상상해 봐요새 코드베이스를 읽는 건 새 도시를 탐험하는 것과 같아요. 무작정 거리를 돌아다니진 않죠. 먼저 지도(README)를 보고, 주변에 뭐가 있는지(의존성) 살피고, 큰길(진입점)을 찾고, 그다음 동네를 하나씩(모듈) 둘러봐요.

방금 다른 사람의 프로젝트를 받았어요. Task API예요. 이 코드를 본 적이 없죠. 터미널에서 코드 읽기 프로토콜을 한 단계씩 적용해 볼게요.

코드 읽기 프로토콜 1단계: README 읽기. README는 프로젝트가 뭘 하는지, 어떻게 설치하는지, 어떻게 실행하는지 알려줘요. 항상 여기서 시작하세요.

(이 섹션은 인터랙티브해요 — JavaScript를 켜 주세요.)

2단계: package.json 확인. 의존성은 어떤 기술을 쓰는지 알려줘요. 스크립트는 어떻게 실행하고 테스트하는지 알려주고요.

(이 섹션은 인터랙티브해요 — JavaScript를 켜 주세요.)

3단계: 진입점 찾기와 구조 살피기. package.json에서 app.js가 진입점이라는 걸 알았죠. 먼저 폴더 구조를 보고, 그다음 메인 파일을 읽어요.

(이 섹션은 인터랙티브해요 — JavaScript를 켜 주세요.)

코드 읽기 프로토콜 — 새 코드베이스라면 이 단계를 따라가세요

README.md는 프로젝트가 뭘 하는지, 어떻게 설치하는지, 어떻게 실행하는지 알려줘요. 항상 여기서 시작하세요. README가 없다는 것도 정보예요. 문서화가 부실한 프로젝트일 가능성이 있죠.

의존성은 어떤 기술을 쓰는지 알려줘요. 스크립트는 어떻게 실행하고 테스트하는지 알려주고요. "dependencies"에서 주요 라이브러리를 확인하고, "scripts"에서 "start", "test", "build" 같은 명령을 살펴보세요.

코드가 어떻게 정리돼 있나요? src/, public/, routes/, models/ 같은 폴더를 보면 아키텍처의 힌트가 보여요. 모든 게 한 폴더에 평평하게 있으면 작은 프로젝트라는 뜻이에요. 이름이 명확한 중첩 폴더가 있으면 잘 정리된 프로젝트라는 뜻이고요.

보통 index.js, app.js, 또는 main.js예요. 프로그램이 여기서 시작하죠. package.json의 "main" 필드나 "start" 스크립트가 어디를 봐야 하는지 알려줘요.

진입점에서 require()나 import 문을 따라가 의존성 트리를 파악하세요. 각 import는 다음 퍼즐 조각으로 데려가요. 한 번에 다 이해하려 하지 마세요. 먼저 연결을 매핑하세요.

Claude Code에 '이 프로젝트의 개요를 알려줘'라고 하면 바로 고수준 요약을 받아요. Claude는 모든 파일을 읽고 몇 초 만에 코드베이스 지도를 그려줘요. 손으로 하면 몇 시간 걸리는 일이죠.

새 프로젝트를 탐험할 때, 가장 먼저 읽어야 할 파일은 _____ 예요.

새 코드베이스를 탐험할 때 가장 먼저 읽어야 할 것은?

⚠ 전체 인터랙티브 경험에는 JavaScript가 필요해요. JavaScript를 켜고 새로 고침해 주세요.

※ 이 사이트는 독립 운영되는 교육 프로젝트로, Anthropic의 공식 제품이 아니에요. Claude™ 는 Anthropic, PBC 의 상표예요.