---
name: codebase-scout
description: 새로운 코드베이스(GitHub 레포 또는 로컬 디렉토리)에 처음 진입해 entry point, 핵심 모듈, 빌드/실행, 의존성을 파악할 때 사용. `/codebase` 호출에 반응.
metadata:
  language: ko
---

# codebase-scout

새 레포의 지형을 빠르게 그린다. 깊은 분석이 아니라 **"무엇이 어디 있고, 어떻게 돌아가는지"** 파악이 목적.

## 입력
- GitHub URL 또는 로컬 경로
- 대상 프로젝트명
- (선택) 특히 알고 싶은 부분 (예: "추론 파이프라인", "평가 코드")

## 절차

1. **시작 전**: 대상 프로젝트의 `PLAN.md` 확인.
2. **광범위 우선(broad first)**:
   - README, package manifest (`package.json` / `pyproject.toml` / `Cargo.toml` 등) 우선 읽기
   - `tree -L 2` 또는 `ls`로 top-level 구조 파악
   - 라이선스·언어·주 의존성 확인
3. **좁히기**: 사용자가 지정한 영역, 또는 추론·학습·평가 같은 핵심 디렉토리로 진입
4. **Subagent 활용**: 광범위 검색은 `Explore` subagent에게 위임 (메인 컨텍스트 보존)
   - 호출 시 objective / output format / tools / boundary 4요소 명시
5. 저장: `projects/<project>/code-notes/<org-repo>.md`
6. PLAN.md "자원" 섹션에 1줄 인덱스 추가.

## 출력 템플릿

````markdown
# <org/repo> 또는 <레포 이름>

## 메타데이터
- URL / 경로: ...
- 커밋 / 태그: ...
- 언어: ...
- 라이선스: ...
- 스타: NNN (확인일 YYYY-MM-DD)
- 조사 날짜: YYYY-MM-DD

## 목적
이 레포가 무엇을 하는지 한 문단.

## 실행 방법
- 빌드 / 설치: ...
- 실행: ...
- 테스트: ...
- 최소 재현 예제 (가능한 한 짧게)

## 디렉토리 구조 (top-level)
- `src/foo/` — ...
- `src/bar/` — ...

## 핵심 모듈
### `<module>`
- 역할:
- 진입점:
- 주요 함수/클래스:
- 의존:

(반복)

## 의존성
- 런타임:
- 개발:
- 흥미로운 transitive:

## 흥미로운 패턴
- ...

## 한계 / 주의
- 미완성 영역, 알려진 이슈, 우리 용도와의 mismatch

## 우리 프로젝트와의 연결
- 가져다 쓸 수 있는 부분
- 참조 구현으로만 볼 부분
- 피해야 할 부분
````

## 노력 스케일링
- **지형도만**: 1 subagent, README + tree + manifest. 도구 호출 3–10회.
- **표준 정찰**: 위 + 핵심 디렉토리 2–3곳 진입. 도구 호출 10–20회.
- **깊은 정찰**: 위 + 특정 모듈 함수 단위 추적. 도구 호출 20+회.

먼저 지형도만 그리고, 필요시 깊이 들어간다.