낯선 저장소 파악하기가 매주 수작업이 되는 이유#
낯선 저장소에서는 모든 파일을 순서대로 읽기보다 실행 진입점에서 관심 기능과 테스트로 범위를 좁히는 편이 유용합니다. 저장소 파악 가이드는 구조와 관련 파일 경로를 함께 요청하는 예시를 제공합니다.
| 읽는 순서 | 질문 | 직접 대조할 근거 |
|---|---|---|
| 실행 진입점 | 어떻게 시작하는가? | 저장소의 실행 안내와 설정, 진입 파일 |
| 요청 경로 | 관심 기능의 입력과 결과는 어디를 지나는가? | 호출부와 처리 코드, 실제 분기 |
| 테스트 | 어떤 동작이 확인되어 있는가? | 관련 테스트와 그 실행 방법 |
| 남은 의문 | 설명에서 확인하지 못한 부분은 무엇인가? | 빠진 경로와 검증하지 않은 가정 |
Before / After: 낯선 저장소 파악하기의 현재 비용과 자동화 후 결과#
구조 설명과 파일 경로를 함께 요청하면 확인할 후보를 추릴 수 있습니다. 설명은 읽기 시작점이지 정확성의 보증이 아닙니다. 이 페이지에는 실제 저장소 온보딩 전후 시간이나 완성된 노트 비교가 없습니다.
단계별로 하기: 입력 규칙 → 실행 → 검증#
- 저장소와 민감 정보에 접근할 권한 및 조직의 외부 모델 사용 정책을 확인합니다. 인증 정보는 요청과 공유 로그에서 제외하세요.
- 프로젝트 폴더에서 Mirr Code를 열고 저장소 파악 가이드의 요청 예시처럼 진입점, 주요 폴더, 테스트 방법과 각 파일 경로를 요청합니다.
- 관심 기능 하나를 골라 입력에서 처리, 결과까지 이어지는 경로와 불확실한 지점을 물어봅니다.
- 제시된 파일과 호출 관계를 직접 대조하고 관련 테스트의 범위를 확인합니다. 테스트 실행은 부작용을 검토한 뒤 별도로 승인하세요.
예시 요청: “파일을 수정하거나 명령을 실행하지 말고, 실행 진입점과 주요 폴더를 근거 파일 경로와 함께 설명해 줘. 확인하지 못한 부분은 구분해 줘.” 이는 요청 문구일 뿐 읽기 전용을 강제하지 않습니다. 실제 파일·셸 권한을 제한하고 승인 설정을 확인하세요.
검증: 테스트 출력과 체크리스트#
설명에 나온 경로가 실제로 존재하는지, 경로 사이의 연결이 코드에 있는지, 테스트가 설명한 분기를 다루는지 확인하세요. 테스트를 실행하지 않았다면 그 사실을 기록합니다.
추가 검증 필요: 실제 저장소 트리와 진입점 파일
실제 저장소 트리, Mirr의 구조 설명 출력과 온보딩 노트 전후 비교는 아직 확보하지 못했습니다. 위 절차는 재현된 세션이 아닙니다.
주의할 점과 한계#
읽기 요청만으로는 쓰기나 외부 전송이 차단되지 않습니다. 필요한 파일만 접근하도록 운영체제와 서비스 권한을 제한하고, 예상하지 못한 도구 실행은 거절하세요. 외부 서비스 변경은 /rewind로 자동 취소되지 않습니다. 세션 복구의 한계도 확인하세요.
첫 질문을 실행 방법 하나로 좁히기#
처음 보는 저장소에서 폴더 이름을 모두 외우려고 하지 마세요. 먼저 이 프로젝트가 무엇을 실행하는지, 어떤 명령이 진입점을 고르는지와 필요한 환경이 무엇인지 조사합니다. README는 좋은 시작점이지만 실제 패키지 설정, 실행 스크립트와 배포 설정이 같은 버전을 가리키는지 대조해야 합니다. 문서의 명령이 오래됐다면 바로 실행해서 오류를 늘리기보다 현재 설정에서 차이를 찾으세요. 실행 명령에는 설치, 생성, 네트워크와 데이터 변경이 숨어 있을 수 있습니다.
AI에는 실행하지 말고 근거 경로를 제시하도록 먼저 요청할 수 있습니다. 예를 들어 “웹 요청을 받는 진입 파일과 그 파일을 선택하는 설정을 찾아 줘”처럼 질문을 나누세요. 파일 하나가 진입점처럼 보여도 개발 서버, 배치 작업과 테스트가 다른 시작 경로를 쓸 수 있습니다. 확장자와 파일명만으로 확정하지 말고 실제 import, 등록 코드와 설정의 연결을 살펴봅니다. 확인한 연결과 이름으로 추정한 후보를 기록에서 구분하세요.
| 온보딩 질문 | 읽을 근거 | 답변에서 빠지면 안 되는 것 |
|---|---|---|
| 어떻게 시작하는가 | 실행 설정과 진입 코드 | 환경별 차이와 미실행 여부 |
| 요청은 어디로 가는가 | 라우트 등록·호출자·서비스 | 입력에서 결과까지 이어지는 연결 |
| 데이터는 어디서 오는가 | 저장소 계층·외부 클라이언트 | 인증·캐시·오류 경계 |
| 무엇을 바꾸면 영향이 있는가 | 호출자·공개 계약·설정 | 직접 참조 외의 동적 경로 |
| 어떤 동작이 검증됐는가 | 테스트와 실행 기록 | 검증한 조건과 빠진 조건 |
표는 모든 파일을 순서대로 읽는 목차가 아닙니다. 관심 기능에 답하는 데 필요한 근거를 찾는 데 사용하세요. 문서와 코드가 충돌하면 어느 버전과 환경을 보고 있는지 먼저 확인합니다. 테스트용 진입점이 운영 진입점과 다른 것도 가능합니다. 모르는 부분을 억지로 하나의 그림에 넣기보다 “설정 선택 조건 미확인”처럼 질문으로 남기는 편이 이후 조사에 도움이 됩니다.
요청 하나의 경로를 끝까지 따라가기#
관심 있는 화면을 하나 고르고, 그 화면의 요청 생성, API 라우트, 권한 검사, 조회 함수, 응답 변환과 빈 상태 표시를 한 경로로 연결합니다. 실제 파일 이름은 저장소에서 찾아야 하며 이 예시가 특정 프레임워크 구조를 보장하지 않습니다. 각 연결에서 어떤 인자가 넘어가는지와 오류가 어디서 처리되는지 확인하세요. 함수 정의만 읽고 호출자가 전달하는 값을 보지 않으면 동작을 잘못 설명할 수 있습니다.
정상 경로를 찾은 다음에는 빈 결과, 잘못된 입력과 권한 없는 요청을 비교합니다. 코드가 성공할 때만 보면 예외 처리와 보안 경계를 놓치기 쉽습니다. 캐시가 있다면 실제 데이터 요청을 건너뛰는 조건도 살펴보세요. 비동기 작업은 함수가 반환한 뒤에도 이어지는지 확인합니다. 설명에 “항상 DB를 조회한다” 같은 단정을 넣기 전에 캐시·대체 경로와 환경 설정을 검토하세요. 경로를 확인하지 못했다면 그 한계를 표시합니다.
동적 등록이나 콜백 때문에 호출 관계가 바로 보이지 않을 수 있습니다. 정적 검색에서 참조가 없다고 사용되지 않는 코드로 판단하지 마세요. 라우트 매핑, 이벤트 이름, 플러그인 목록과 의존성 주입 설정을 확인하세요. 이런 경계는 도구가 제시한 경로를 코드와 대조하는 이유이기도 합니다. AI의 설명이 그럴듯해도 연결 근거가 없으면 가설입니다. 코드를 삭제하거나 이름을 바꾸는 작업은 온보딩 읽기와 별도 승인 대상으로 둡니다.
테스트를 지도처럼 읽는 방법#
테스트 이름은 어떤 동작을 중요하게 보는지 알려 주지만 실제 assertion도 읽어 보세요. “인증 실패”라는 이름의 테스트가 상태 코드만 검사하고 데이터 노출은 보지 않을 수 있습니다. 사용한 입력, 대체한 외부 의존성과 기대 결과를 기록하세요. 테스트가 통과했다는 말은 실행한 조건에서 assertion이 맞았다는 뜻이며 설명한 전체 요청 경로가 운영에서 검증됐다는 뜻은 아닙니다. 실행하지 않았다면 테스트가 존재한다는 사실만 적습니다.
테스트의 대체 구현이 실제 DB나 외부 API를 대신하는지 확인합니다. 대체 구현이 반환한 고정 데이터로는 인증 설정이나 네트워크 오류를 검증할 수 없습니다. 통합 테스트라 하더라도 어느 서비스를 실제로 사용하는지 살펴보세요. 명령을 실행하기 전 설정과 준비 코드를 읽고 운영 자격 증명이나 외부 쓰기가 없는지 확인하세요. 이름에 test가 들어갔다고 안전한 환경이라고 가정하지 않습니다.
처음부터 전체 테스트를 실행할 필요는 없습니다. 관심 기능의 좁은 검사를 찾고 프로젝트의 안내에 맞춰 필요한 환경을 검토하세요. 좁은 검사가 통과하면 관련 통합 검사를 검토할 수 있지만 범위를 넓히는 권한까지 자동으로 생기지는 않습니다. 실패하면 명령, 환경과 기존 상태를 기록해 새 문제인지 구분합니다. 의존성을 설치하거나 DB를 만드는 작업도 별도 준비이며 코드 설명 요청에 포함돼 있다고 추정하지 마세요.
구조 설명을 검증 가능한 노트로 바꾸기#
노트에는 폴더별 감상보다 질문과 답, 근거 경로를 적습니다. “서비스 계층이 깔끔하다”보다 “이 요청은 이 등록 코드에서 이 처리 함수로 이어지고 이 오류를 여기서 변환한다”가 유용합니다. 파일 경로가 바뀌면 설명이 오래될 수 있으므로 대상 커밋과 조사 범위를 함께 남기세요. 줄 번호만 적지 말고 함수나 설정 키도 붙이면 다음 독자가 찾기 쉽습니다. 외부 문서 링크도 대상 버전에 맞는지 확인합니다.
확정한 사실, 코드로 뒷받침되는 추론과 아직 모르는 것을 나눕니다. 예를 들어 호출 코드에서 재시도 횟수는 확인했지만 실제 운영 설정은 못 봤다면 그 차이를 적으세요. 추론을 지우는 대신 검증할 질문으로 남기면 담당자에게 정확히 물을 수 있습니다. 민감한 설정값과 비공개 경로는 공개용 노트에서 제외합니다. 노트를 저장소에 기록하는 행동도 파일 수정이므로 읽기 전용 조사와 별도 범위입니다.
다음 수정의 영향 범위 찾기#
온보딩의 목적이 이후 작은 수정이라면 바꿀 계약의 호출자를 먼저 살펴봅니다. API 필드 하나가 화면, 테스트, 문서와 배치 작업에서 쓰일 수 있습니다. 함수 이름 검색만으로는 직렬화 필드나 문자열 키를 모두 찾기 어려우므로 계약을 사용하는 위치를 함께 조사하세요. 관심 기능에서 직접 확인한 범위와 저장소 전체의 영향 범위를 구분합니다. 한 경로를 이해했다고 전체 시스템을 파악했다고 보고하지 않는 편이 정확합니다.
변경 후보를 찾은 뒤에도 바로 구현하지 말고 기존 규칙과 관련 테스트를 읽습니다. 같은 책임을 가진 도구나 유틸리티가 이미 있는지도 확인하세요. 새 추상화나 대규모 정리는 온보딩 결과가 아니라 별도 설계 결정입니다. 작은 수정의 성공 기준과 바꾸지 않을 동작을 정한 다음 구현으로 넘어갑니다. 사용자 요청이 구조 설명뿐이라면 다음 작업을 제안할 수는 있어도 파일을 고치거나 PR을 만들면 안 됩니다.
설명이 틀렸을 때 다시 조사할 순서#
먼저 대상 브랜치와 커밋, 실행 환경이 맞는지 확인합니다. 다음으로 설명에 나온 경로가 존재하는지와 실제로 호출되는지 봅니다. 호출이 다른 구현으로 갈라지면 설정 선택 조건을 조사하세요. 테스트에서만 쓰는 파일을 실제 서비스 진입점으로 착각했을 수도 있습니다. 설명을 맞추기 위해 코드를 바꾸지 말고 설명의 가설을 수정하세요. 어떤 근거가 부족했는지 남기면 같은 오해를 반복하지 않을 수 있습니다.
예를 들어 실행 설정은 웹 서버를 가리키는데 설명이 테스트용 진입 파일에서 시작했다면 노트의 출발점을 고쳐야 합니다. 함수 이름이 같더라도 설정이 고른 구현과 테스트가 주입한 구현을 나란히 비교하세요. 문서에만 나오는 오래된 경로는 현재 호출 경로의 근거가 아닙니다.
의존성과 생성 코드를 조사 범위에서 구분하기#
저장소에는 직접 작성한 소스 외에도 생성 파일, 외부 라이브러리와 배포 산출물이 섞일 수 있습니다. 관심 기능의 실제 구현이 어디에 있는지 확인하고 생성 결과를 원본처럼 수정하지 않도록 주의하세요. 생성 규칙과 입력 파일이 있다면 그 관계를 읽어 보세요. 외부 라이브러리의 동작이 필요하면 설치된 버전과 공식 문서를 대조합니다. 저장소의 래퍼가 옵션과 오류 처리를 바꿀 수 있으므로 라이브러리 설명만으로 프로젝트 동작을 확정하지 않습니다.
모노레포에서는 같은 이름의 설정과 패키지가 여러 곳에 있을 수 있습니다. 루트의 실행 명령이 어느 하위 프로젝트를 고르는지와 현재 작업 디렉터리가 무엇인지 확인하세요. 테스트가 다른 패키지의 fixture를 읽는 경우도 있습니다. 파일 목록의 크기보다 실제 요청 경로와 실행 범위를 기준으로 읽는 이유입니다. 관심 없는 패키지를 전부 분석하거나 설치할 필요가 있는지는 별도 판단이며 구조 설명 요청에 포함된다고 추정하지 않습니다.
첫 온보딩 노트의 검토 예시#
다음은 가상 저장소를 읽는 노트의 예시입니다. entry.ts, report-route.ts, report-service.ts, report-client.ts는 설명용 이름이며 실제로 조사한 파일이 아닙니다. 실행 설정이 entry.ts를 선택하고 그 파일에서 보고서 라우트를 등록했다고 가정합니다. 단, 외부 클라이언트의 실제 선택은 환경 설정을 아직 확인하지 못했다고 정합니다.
| 노트에 적으려는 연결 | 소스에서 발견했다고 가정한 근거 | 노트의 판정 | 아직 할 수 없는 주장 |
|---|---|---|---|
| 진입 파일→라우트 | 설정의 진입 파일과 실제 등록 코드가 일치 | 해당 설정에서 확인한 연결 | 다른 환경도 같은 진입점을 쓴다 |
| 라우트→서비스 | 요청 값을 전달하는 호출부가 있음 | 인자·오류 변환까지 코드로 확인 | 정상 요청을 실제 실행했다 |
| 서비스→외부 클라이언트 | 인터페이스만 주입되고 구현 선택은 미확인 | 후보 경계 | 특정 외부 서비스가 호출된다 |
| 테스트→클라이언트 | 고정 응답의 대체 구현 사용 | 테스트 전용 경로 | 실제 인증·네트워크 연결 성공 |
| 오류→대체 응답 | 오류 분기와 반환값이 소스에 있음 | 코드로 본 동작 | 운영에서 그 오류가 재현됐다 |
이 표를 실제 노트로 채울 때는 각 연결에 파일과 함수·설정 키를 붙입니다. 확인된 코드 연결과 실행 관찰을 같은 표시로 합치지 마세요. 외부 클라이언트의 구현이 미확인이라면 그 경계까지만 그림을 그리고 질문을 남깁니다. .env나 비밀 저장소를 무단으로 읽어 빈칸을 채우는 대신 필요한 설정 키와 선택 규칙을 담당자에게 확인하세요. 설정의 역할을 설명하는 데 실제 비밀값이 필요한 것은 아닐 수 있습니다.
이런 노트는 파일 목록을 번역하는 것보다 다음 질문을 분명히 합니다. 가상 예시에서는 새 라우트를 찾는 질문은 끝났지만 외부 데이터의 출처는 아직 모릅니다. 테스트가 반환하는 값만 보고 실제 제공자 이름을 적으면 잘못된 온보딩 자료가 됩니다. 또한 오류 분기를 소스로 읽었다고 장애가 발생했다거나 복구가 검증됐다고 쓰지 않습니다. 증거의 종류를 유지해야 이후 변경과 테스트의 범위를 고를 수 있습니다.
읽기를 멈출 수 있는 기준#
현재 목표가 작은 결함 수정이라면 관련 진입점, 요청 경로와 테스트, 영향 받을 호출자를 설명할 수 있을 때 구현 계획으로 넘어갈 수 있습니다. 모든 파일을 이해해야 한다는 기준은 필요 이상으로 범위를 넓힐 수 있습니다. 반대로 핵심 권한 경계나 데이터 의미를 모른다면 그 부분은 확인하세요. 멈추는 기준을 목표와 연결하면 무엇을 더 읽어야 하는지 판단하기 쉽습니다. 확인하지 않은 영역은 노트에서 지우지 말고 범위 밖 또는 미확인으로 표시하세요.
라우트의 입력 검증만 고친다면 외부 클라이언트의 모든 내부 구현을 읽지 않아도 계획을 세울 수 있습니다. 그러나 반환 데이터의 필드를 바꾸려면 외부 응답과 변환 계약을 더 알아야 합니다. 권한 오류를 고치는 과제라면 인증 주체와 검사 위치를 모른 채 멈출 수 없습니다. 읽기를 끝내는 지점은 파일 수가 아니라 요청한 변경을 설명할 근거로 정하세요. 확인하지 않은 외부 경계는 계속 미확인으로 남기세요.
첫 조사에서 용어가 다르게 쓰이면 작은 용어표를 만들 수도 있습니다. 예를 들어 코드의 account와 문서의 고객이 같은 대상을 가리키는지, 조직과 팀이 다른 권한 단위인지 근거를 확인하세요. 이름만 번역해 같다고 합치지 않습니다. 용어의 의미가 다르면 요청 경로와 데이터 관계도 잘못 설명할 수 있습니다. 기존 도메인 문서가 있다면 먼저 읽고 확인되지 않은 대응은 질문으로 남기는 편이 안전합니다. 이 용어표 역시 실제 근거가 있는 항목만 확정하세요.
다음에 읽을 것#
파악한 경로를 바탕으로 여러 파일 기능 구현이나 한국어 코드 리뷰를 이어서 살펴보세요.
관련#
편집 메모 (2026-11-02): 읽기 범위와 설명 불일치 진단 FAQ를 보충했습니다. 실제 트리·진입점 화면, 구조 설명 명령 출력과 온보딩 노트 전후 기록은 아직 없습니다.