새로운 코드베이스에 효과적으로 온보딩하는 방법: 체계적인 접근 방식

실용적인 읽기 루틴을 집중적인 로컬 설정(Local setup), 페어 프로그래밍(Pairing) 시점에 대한 의사결정, 그리고 진행 과정에서의 절제된 문서화와 결합하여 새로운 코드베이스를 빠르게 마스터하세요.

전체적인 그림과 진입점 (Entry points)

• 제품의 목표와 핵심 흐름(Core flows)을 먼저 파악하세요: 어떤 기능이나 사용자 스토리(User story)가 시스템을 구동하며, 해당 흐름이 어떤 컴포넌트(Components)에 영향을 미치는지 확인합니다.
• 진입점(Entry points)을 정확히 짚어내세요: 일반적인 유스케이스(Use case)가 시작되는 지점(CLI, API 경로, UI 액션, 테스트 등)을 찾습니다. 해당 지점으로부터 외부로 추적하며 여러분이 먼저 다루게 될 영역을 이해하세요.
• 아키텍처(Architecture)를 높은 수준에서 읽으세요: 모놀리식(Monolithic)인지 분산형(Distributed)인지, 주요 도메인(Domains)은 무엇인지, 그리고 데이터 영속성(Persistence)은 어디에 위치하는지 파악합니다.

효과적으로 코드 읽기

• 가장자리(Edges)부터 시작하세요: 구체적인 사용자 액션이나 API 엔드포인트(Endpoint)를 선택하여 데이터 경로를 엔드투엔드(End-to-end)로 따라가 보세요.
• 테스트를 가이드로 활용하세요: 테스트를 실행하고, 실패하는 테스트를 읽고, 그 기대값(Expectations)을 조사하여 의도와 엣지 케이스(Edge cases)를 학습하세요.
• 흐름에 대한 멘탈 모델(Mental model)을 구축하세요: 진입점(Entry point) → 핸들러/컨트롤러(Handler/Controller) → 서비스/도메인(Service/Domain) → 데이터 레이어(Data layer) → 외부 시스템(External systems).
• 커밋 히스토리(Commit history)와 PR(Pull Request) 노트를 읽으세요: 변경 사항과 설계 결정 뒤에 숨겨진 '이유(Why)'를 설명해 줍니다.
• 모든 파일을 한꺼번에 쫓지 마세요: 가볍고 확장 가능한 멘탈 모델(진입점, 핵심 도메인, 영속성, 성장 경로)을 매핑하세요.

스택을 로컬에서 실행하기

• 의존성(Dependencies)을 설치하고 프로젝트를 로컬에서 실행하세요. 앱이나 서비스를 구동할 수 있는 단일 명령 시퀀스를 목표로 합니다.
• 최소한의 재현 가능한 환경(환경 변수(Env vars), Docker 또는 네이티브 설치, 필수 서비스 등)을 통해 작동 가능한 상태로 만드세요.
• 엣지 케이스(Edge cases)를 다루기 전에, 간단한 엔드투엔드(End-to-end) 경로(소위 "해피 패스(Happy path)" 흐름)를 실행하여 구동을 확인하세요.

디버깅 및 로그 (Debugging and logs)

• 디버거(Debugger)를 활성화하고 주요 사용자 흐름(User flow)을 따라 몇 개의 전략적인 중단점(Breakpoints)을 설정하세요. 입력(Inputs), 출력(Outputs), 그리고 상태 전이(State transitions)를 조사하십시오.
• 구조화된 로깅(Structured logging)을 켜세요. 진입점(Entry points), 주요 결정 지점, 그리고 데이터 변이(Data mutations) 주변에 로그 라인을 추가하거나 관찰하십시오.
• 로그 컨텍스트(Log context)를 사용하여 코드 영역을 사용자에게 보이는 동작과 매핑하고, 실패가 어디에서 발생하는지 찾아내십시오.

학습 중 문서화 (Documentation while learning)

• 가볍고 지속적으로 업데이트되는 지도를 작성하세요: 진입점, 주요 모듈, 데이터 흐름(Data flow), 그리고 의존성(Dependencies).
• 온보딩 중인 상위 3가지 흐름에 대해 간략한 다이어그램이나 흐름 노트를 작성하세요. 코드 변경 사항과 동기화된 상태를 유지해야 합니다.
• 진행하면서 질문들을 문서화하세요. 코드 탐색이나 팀원과의 대화를 통해 그 질문들에 대한 답을 찾아가십시오.

질문 및 협업 (Questioning and collaboration)

• 진행을 가로막는 요소를 해소할 수 있도록 정밀한 질문을 하세요: "기능 X의 표준 경로(Canonical path)는 무엇인가요?", "Y에 대한 검증(Validation)은 어디에서 수행되나요?", 또는 "Z를 담당하는 모듈은 무엇인가요?"
• 페어 프로그래밍(Pair)을 할 때와 단독으로 할 때:
  • 익숙하지 않은 도메인, 까다로운 통합 지점(Integration points), 또는 즉각적인 피드백이 가치 있는 고위험 변경 사항을 다룰 때는 페어 프로그래밍을 하세요.
  • 기본적인 멘탈 모델(Mental model)을 구축하고 코드 경로에 대한 자신감이 생긴 후에는, 일상적이고 범위가 명확한 작업은 단독으로 진행하세요.
• 빠른 온보딩을 위해 팀원을 활용하세요: 간략한 코드 워크스루(Code walkthroughs), 도메인 컨텍스트, 그리고 일반적인 작업의 예시를 요청하십시오.

진입점 매핑 및 작업 전략 (Entry-point mapping and task strategies)

• 3가지 핵심 진입점과 그들의 주요 데이터 흐름을 매핑하세요. 이를 탐색을 위한 앵커(Anchors)로 사용하십시오.
• 멘탈 모델을 강화할 수 있는 작업을 우선시하세요: 핵심 흐름의 작은 버그 수정, 임계 경로(Critical path) 주변에 테스트 추가, 또는 문서화의 공백 개선 등입니다.
• 온보딩을 위한 "살아있는 체크리스트(Living checklist)"를 유지하세요: 로컬 실행 방법, 진입점 찾는 법, 주요 흐름에 대한 테스트 읽는 법, 그리고 도메인 질문을 누구에게 해야 하는지 등을 포함합니다.

첫 주에 생산적인 실습이 이루어지는 모습

• 1~2일 차: 전체적인 그림(big picture)을 파악하고, 진입점(entry points)을 찾으며, 앱을 실행하고, 간단한 흐름을 엔드 투 엔드(end-to-end)로 검증합니다.
• 3~4일 차: 테스트와 몇 가지 대표적인 컴포넌트(components)를 읽고, 각각의 역할과 관계를 주석으로 기록합니다.
• 5일 차: 작은 기능 개선이나 버그 수정을 위해 페어 프로그래밍(pair)을 수행하며