---
id: wiki-2026-0508-코드베이스-읽기-지식
title: 코드베이스 읽기 지식
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Codebase Reading, Code Comprehension, 코드 읽기]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [code-reading, comprehension, onboarding, software-engineering]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: Polyglot
  framework: Any
---

# 코드베이스 읽기 지식

## 매 한 줄
> **"매 code 읽기 = 매 entry point → 매 data flow → 매 state mutation 의 매 trace"**. 매 senior engineer 가 매 unfamiliar repo 에 매 30분 안 에 매 mental model 을 매 구축 하는 매 능력 의 매 backbone — 매 entry point 식별, 매 data shape 추적, 매 boundary 파악, 매 test 의 매 활용. 매 2026 의 매 LLM (Claude Opus 4.7, GPT-5) 은 매 powerful assistant 이지만 매 humans 가 매 framing 을 매 driver.

## 매 핵심

### 매 4-step approach
1. **매 Entry point 식별** — main(), index.ts, route handler, CLI command.
2. **매 Data shape 추적** — type / schema / DB model 의 매 핵심 entity.
3. **매 Boundary 파악** — module / service / network / DB의 매 split.
4. **매 Test 활용** — 매 의도 의 매 executable spec.

### 매 도구
- **매 LSP / IDE**: go-to-definition, find-references, call-hierarchy.
- **매 Search**: ripgrep, ast-grep, sourcegraph, GitHub code search.
- **매 Git**: blame, log -S "<phrase>", bisect.
- **매 LLM**: Claude Opus 4.7 of Cody / Cursor / Continue 의 매 codebase context.
- **매 Visualization**: dependency-cruiser, madge.

### 매 응용
1. 매 onboarding (new repo 의 매 30min mental model).
2. 매 bug 추적 (root cause).
3. 매 refactor / migration 계획.
4. 매 security review.

## 💻 패턴

### Pattern 1: 매 Entry Point 매핑
```bash
# 매 Node.js
cat package.json | jq '.main, .scripts'
# → 매 index.ts? bin/cli.ts? server.ts?

# 매 Python
grep -r "if __name__" --include="*.py" | head
cat pyproject.toml | grep -A2 "scripts"

# 매 Go
grep -r "func main" --include="*.go"
```

### Pattern 2: 매 Data Shape Discovery
```bash
# 매 Type / interface 의 매 enumerate
rg "^(export\s+)?(interface|type|class|struct)\s+\w+" -t ts -t go -t rust

# 매 DB schema
find . -name "schema.prisma" -o -name "*.sql" -path "*migration*"

# 매 OpenAPI / GraphQL
find . -name "openapi.yaml" -o -name "*.graphql"
```

### Pattern 3: 매 Call Hierarchy via ast-grep
```bash
# 매 ast-grep 으로 매 specific call 의 매 추적
ast-grep --pattern 'fetch($URL)' --lang ts

# 매 React component usage
ast-grep --pattern '<UserCard $$$/>' --lang tsx
```

### Pattern 4: 매 Git Archaeology
```bash
# 매 매 phrase 가 매 언제 매 들어왔나
git log -S "calculatePrice" --source --all

# 매 매 함수 의 매 history
git log -L :calculatePrice:src/pricing.ts

# 매 매 file 의 매 contributor
git shortlog -sn -- src/pricing.ts
```

### Pattern 5: 매 Dependency Graph
```bash
# 매 dependency-cruiser
npx dependency-cruiser --output-type dot src | dot -Tsvg > deps.svg

# 매 madge — 매 circular dep
npx madge --circular --extensions ts,tsx src/
```

### Pattern 6: 매 Test-First Reading
```bash
# 매 test 가 매 의도 의 매 spec — 매 implementation 전 에 매 test 부터
find . -path "*test*" -name "*.test.ts" | head
# 매 read describe / it 의 매 outline → 매 module purpose 파악
```

### Pattern 7: 매 LLM-Assisted (Claude Opus 4.7)
```typescript
// 매 Cursor / Cody / Continue 에 매 context 제공:
// "매 Read src/payment/*.ts and explain the entry point + main data flow.
//  매 List the top 5 functions by call frequency.
//  매 Identify any cross-module side effects."

// 매 LLM 의 매 strength: 매 fast summary, 매 pattern recognition.
// 매 LLM 의 매 weakness: 매 long-tail bug, 매 implicit assumption — 매 verify with test.
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| 매 First contact | README → entry point → top-level routes |
| 매 Bug hunt | Failing test 부터, git bisect, log -S |
| 매 Refactor planning | dependency-cruiser, find-references |
| 매 Security review | Input boundary (network, file, env), trust traversal |
| 매 LLM 활용 | Claude Opus 4.7 의 매 codebase context for summary |

**기본값**: 매 entry → 매 data shape → 매 test → 매 LLM 의 4-step.

## 🔗 Graph
- 부모: [[코드_분석_도구_Code_Analysis_Tools]] · [[AI 기반 코드 분석 도구 (AI-Powered Code Analysis Tools)]]
- 변형: [[정적 분석(Static Analysis)]] · [[코드_속성_그래프_CPG]]
- 응용: [[하이브리드 코드 리뷰]] · [[풀 리퀘스트 워크플로우]]
- Adjacent: [[AST(Abstract_Syntax_Tree)]] · [[AI 코드 리뷰]]

## 🤖 LLM 활용
**언제**: 매 unfamiliar repo onboarding, 매 large refactor planning, 매 cross-module dependency mapping, 매 bug root cause hypothesis.
**언제 X**: 매 trivial change (1줄 fix), 매 매 own 의 매 maintained file, 매 highly proprietary codebase 의 매 LLM 외부 전송 금지.

## ❌ 안티패턴
- **매 line-by-line 처음 부터**: 매 mental model 의 매 부재 — 매 6시간 후 도 매 lost.
- **매 implementation-first (test 무시)**: 매 의도 misunderstand.
- **매 LLM 의 매 blind trust**: 매 hallucinated function / file path 의 매 무비판 수용.
- **매 dependency graph 의 매 무시**: 매 circular dep 의 매 hidden cost.
- **매 git log 의 매 unused**: 매 "왜 이렇게 되었나" 의 매 history 의 매 답.

## 🧪 검증 / 중복
- Verified (Code Reading by Diomidis Spinellis, GitHub repo onboarding studies, Sourcegraph engineering blog 2026).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — codebase reading 4-step + 도구 정리 |