Antigravity Agent
f8b21af4be
10_Wiki/Topics 대규모 정리: - 오류 캡처/미완성 stub 문서 227개 제거 - 교차폴더 중복 43클러스터 병합 (63파일 → redirect) - 링크명 정규화: 깨진 링크 수정·redirect 직결·개념 매핑 ~2,400건 - 카테고리 MOC 6개 신규 생성 - Graph 섹션 미해결 related-keyword 링크 10,058건 제거 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
160 lines
5.8 KiB
Markdown
160 lines
5.8 KiB
Markdown
---
|
|
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: [[Abstract_Syntax_Tree|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 + 도구 정리 |
|