Codebase 탐색

문제

코드는 계속 바뀌는데 문서가 따라잡았는지 확인할 방법이 막막합니다. 문서를 처음부터 다시 읽으면 시간이 아깝고, 안 읽으면 드리프트를 놓칩니다.

문서가 모르는 변경 목록부터 뽑기
기준점을 실질 커밋으로 잡기
감사 스크립트가 exit 1을 내는지 먼저 확인
드리프트 목록 검토
문서 갱신

이유

문서-코드 드리프트 감사는 이 명령 하나로 시작합니다.

git log --oneline $(git log -1 --format=%H -- docs/{doc}.md)..HEAD -- {코드 경로}

기준점은 style 커밋을 건너뛴 실질 커밋이어야 합니다. 포맷 전용 커밋을 기준으로 잡으면 그 이전의 기능 커밋이 감사 범위에서 통째로 빠집니다.

이 방법에는 구멍이 둘 있습니다. 무제 커밋(update·wip)과 경로 필터 과협착입니다. 대량의 재빌드·자동 생성 파일 사이에 소수의 공용 계층 변경이 섞여 있으면, 경로를 좁혀 조회하는 방식으로는 그 변경이 통째로 빠져나갈 수 있습니다. 보완책은 방향을 뒤집는 것입니다. 계약 파일 쪽에서 git log --oneline -3 -- src/<계약파일>.ts를 물어, 그 파일이 최근에 바뀌었는지 직접 확인합니다.

이 감사 스크립트 자신도 새 게이트입니다. 정규식 하나가 어긋나면 검사는 조용히 전부 통과하고, 그 축만 죽은 채로 초록이 됩니다. 순서는 검사를 추가하고, 알려진 드리프트로 실패를 먼저 확인하고, 수정한 뒤, 초록을 확인하는 것이어야 합니다. 처음부터 초록이 나오는 새 게이트는 검사가 아무 것도 안 보고 있다는 신호일 수 있습니다.

문서끼리의 모순도 같은 감사 대상입니다. 브레인스토밍 문서가 며칠 사이 쌓이면 결론이 정반대인 문서 두 벌이 폐기 표시 없이 공존합니다. 결론이 다른 것 자체는 문제가 아닙니다. 폐기된 전제에 기댄 결론이 그대로 살아 있는 것이 문제입니다. 정반대로 보이는 노선 논쟁은 대개 층위 혼동입니다. 층을 분리하면 두 결론이 양립합니다. 숫자 싸움은 대체로 카운팅 단위 차이거나 축 혼동입니다.

사실 오류의 출처가 pull 안 된 로컬 체크아웃인 경우가 있습니다. 같은 커밋을 인용해도 로컬 워킹트리가 원격보다 뒤처져 있으면 실물과 다른 구성을 근거로 서술하게 됩니다. 사내 레포를 근거로 서술할 때는 브랜치·pull 상태를 먼저 확인하고, 원격 조회가 실패했으면 “로컬 체크아웃 기준 서술”임을 명시합니다.

예시

문서가 모르는 변경부터 뽑습니다.

git log --oneline $(git log -1 --format=%H -- docs/feature.md)..HEAD -- src/feature/

경로 필터가 놓칠 수 있으니 계약 파일 쪽에서도 확인합니다.

git log --oneline -3 -- src/contracts/feature.ts

AI가 만든 라이브러리 비교문은 표면 사실은 잘 맞히지만 무료/유료 경계와 버전 프레이밍에서 낙관적으로 틀리기 쉽습니다. 다음 네 가지를 대조합니다.

최신 버전은 registry.npmjs.org/{pkg}의 dist-tags를 봅니다.
deprecated 여부는 같은 JSON의 필드에서 확인합니다.
무료/유료 경계는 공식 컴포넌트 목록의 Pro 배지로 가릅니다.
유지보수 상태는 GitHub raw README로 확인합니다.

큰 생성물은 2단 조회로 판독합니다. 먼저 키워드로 광역 grep해 줄 번호를 함께 받고, 다음 호출에서 그 구간만 slice로 정독합니다. 줄 길이 상한이 없으면 base64 데이터 URI 한 줄이 응답을 다 채웁니다.

노이즈가 큰 조사는 서브에이전트에 맡겨 결론만 받습니다. 파일 덤프가 이쪽 컨텍스트에 들어오지 않습니다.

PR은 다음 명령 조합으로 파악합니다.

gh pr view <n> --json title,body,headRefName,baseRefName,files
git merge-base <base> <head>
git log --oneline origin/<head> ^origin/<base>

마지막 결과가 0개면 이미 머지된 브랜치입니다.

하지 말 것

포맷 전용 커밋을 기준점으로 잡기. 그 이전의 기능 커밋이 감사 범위에서 통째로 빠집니다.

새 감사 스크립트를 한 번도 실패시켜보지 않고 처음 나온 초록을 믿기. 정규식이 어긋나 아무것도 안 보고 있을 수 있습니다.

원격 확인 없이 로컬 체크아웃만 보고 단정적으로 서술하기. pull 안 된 워킹트리가 사실 오류의 실제 출처였던 경우가 있습니다.

Codebase 탐색

문제

추천

이유

예시

하지 말 것