smart-explore

smart-explore 스킬 개요

smart-explore가 하는 일

smart-explore 스킬은 파일을 처음부터 끝까지 읽는 방식이 아니라, 구조적 검색을 중심에 둔 코드베이스 탐색 워크플로입니다. 핵심 역할은 전체 파일을 열기 전에 smart_search, smart_outline, smart_unfold 같은 AST 기반 도구를 먼저 사용해 에이전트가 저장소 구조를 더 빠르게 파악하도록 돕는 것입니다. 코드 내비게이션, 아키텍처 파악, 특정 디버깅 용도로 smart-explore를 검토 중이라면, 이 스킬의 약속은 명확합니다. 먼저 코드를 지도처럼 파악하고, 그다음 정말 필요한 부분만 읽는다는 점입니다.

어떤 사용자가 smart-explore를 설치하면 좋은가

smart-explore는 AI에게 익숙하지 않은 코드베이스를 자주 살펴보게 하고, 불필요한 토큰 낭비나 무작위 파일 탐색을 줄이고 싶은 사용자에게 가장 잘 맞습니다. 특히 다음과 같은 상황에서 유용합니다.

• 코드 리뷰 및 변경 영향도 분석
• 대형 저장소 온보딩
• 기능 이름 뒤에 있는 실제 구현 찾기
• symbol, handler, service, call site를 빠르게 찾기
• 반복적이고 잡음 많은 Read/Grep/Glob 탐색 루프 줄이기

가장 잘 맞는 사용처는 smart-explore for Code Review입니다. 이 경우 모든 줄을 읽는 것보다 구조와 symbol 경계를 파악하는 일이 더 중요하기 때문입니다.

이 스킬이 실제로 해결하는 일

대부분의 저장소 탐색이 실패하는 이유는 에이전트가 너무 일찍 파일 읽기에 들어가기 때문입니다. smart-explore는 이 습관을 바꿉니다. “관련 있어 보일 때까지 파일을 계속 연다” 대신, 다음과 같은 흐름을 강하게 유도합니다.

1. 디렉터리 전반에서 일치하는 symbol 검색
2. 관련 파일의 구조 개요 확인
3. 실제로 필요한 symbol만 펼쳐서 읽기

그래서 smart-explore skill은 단순한 검색 지름길이 아니라, 언제 전체 파일을 읽지 말아야 하는지까지 정해주는 의사결정 규칙에 가깝습니다.

일반적인 프롬프트와 smart-explore가 다른 점

보통의 프롬프트도 모델에게 “효율적으로 하라”고 지시할 수는 있습니다. 하지만 smart-explore는 도구 사용 순서를 구체적으로 제시하고, 저장소를 둘러보는 기본 습관 자체를 대체할 명확한 방법을 제공합니다. 차별점은 문서가 더 많다는 데 있지 않습니다. 핵심은 우선순위를 명시적으로 뒤집는 데 있습니다. 즉, Read, Grep, Glob, 즉흥적인 파일 탐색 대신 smart_search/smart_outline/smart_unfold를 기본 탐색 경로로 삼게 한다는 점입니다.

설치 전에 가장 먼저 확인할 점

도입 여부를 가르는 가장 큰 질문은 “아이디어가 좋은가?”가 아니라 “내 환경에서 이 도구들을 제대로 쓸 수 있는가?”입니다. smart-explore는 관련 MCP 도구가 실제로 노출되는 환경에서만 의미가 있습니다. 스킬 자체는 가볍고 지시 중심이지만, 실제 가치는 에이전트가 이 구조적 탐색 도구들을 정말 호출할 수 있느냐에 달려 있습니다.

smart-explore 스킬 사용 방법

먼저 도구 의존성부터 확인하기

smart-explore install 흐름을 시도하기 전에, 현재 환경이 아래 MCP 도구를 지원하는지 먼저 확인하세요.

• smart_search
• smart_outline
• smart_unfold

이 스킬은 이 도구들을 대체하지도 않고, 함께 번들로 제공하지도 않습니다. 바꾸는 것은 에이전트의 탐색 전략입니다. 클라이언트에서 이 도구 이름들이 보이지 않는다면, smart-explore usage는 실행보다는 아이디어 수준에 머물 가능성이 큽니다.

설치 맥락과 스킬 위치

이 스킬의 저장소 경로는 다음과 같습니다.

plugin/skills/smart-explore

이 저장소 계열에서 일반적으로 쓰는 페이지 단위 설치 패턴은 다음과 같습니다.

npx skills add thedotmack/claude-mem --skill smart-explore

상위 SKILL.md 자체에는 별도의 설치 명령이 포함되어 있지 않으므로, 위 명령을 이 스킬 컬렉션의 실질적인 설치 시작점으로 보는 편이 좋습니다. 그다음 로컬 skill loader와 MCP 설정이 올바른지 꼭 확인하세요.

가장 먼저 읽어야 할 파일

다음 파일부터 확인하세요.

• plugin/skills/smart-explore/SKILL.md

이 스킬을 보조하는 추가 README.md, metadata.json, rules/, resources/ 파일은 없습니다. 즉, 실제로 쓸 만한 가이드는 거의 전부 이 한 파일에 모여 있습니다. 빠르게 평가하기에는 장점이지만, 다른 곳에서 더 깊은 예시나 엣지 케이스 문서를 기대하긴 어렵습니다.

smart-explore 사용의 핵심 패턴

이 스킬은 3단계 워크플로를 중심으로 설계되어 있습니다.

1. smart_search로 관련 파일과 symbol 찾기
2. smart_outline으로 전체 파일을 열지 않고 파일 구조 확인하기
3. smart_unfold로 정말 필요한 symbol만 전체 내용 가져오기

이 흐름이 바로 smart-explore guide의 실질적인 핵심입니다. 1단계를 건너뛰고 곧바로 파일 전체를 읽기 시작하면, 사실상 이 스킬을 의도대로 쓰고 있다고 보기 어렵습니다.

첫 프롬프트는 목표와 범위를 함께 줘야 한다

약한 프롬프트:

“Find the bug in auth.”

더 강한 프롬프트:

“Use smart-explore on ./src to find where token refresh is implemented. Start with smart_search for refresh token, outline the top 2 matching files, then unfold the main refresh handler and summarize control flow.”

왜 이 방식이 더 좋은가:

• 에이전트에게 스킬 동작을 명시적으로 실행하라고 지시한다
• 검색어를 분명하게 준다
• 탐색 경로를 좁혀 준다
• 전체 코드보다 먼저 구조를 보게 만든다

막연한 목표를 좋은 smart-explore 프롬프트로 바꾸는 법

강한 smart-explore usage를 원한다면, 프롬프트에 다음 입력을 포함하세요.

• 주제 또는 기능 이름
• 검색 시작 경로
• 원하는 결과 수
• discovery, review, tracing, extraction 중 어떤 목적이 있는지
• 찾았을 때 어떤 symbol을 unfold할지

템플릿:

“Use smart-explore in <path>. Search for <concept>, return up to <n> ranked symbols, outline the most relevant files, then unfold the symbol most likely responsible for <job-to-be-done>. Avoid reading full files unless the outline is insufficient.”

Code Review용 smart-explore 최적 워크플로

코드 리뷰에서는 코드베이스 맥락이 불분명한 상태에서 처음부터 “전체 diff를 리뷰해 달라”고 하지 않는 편이 좋습니다. 더 나은 순서는 다음과 같습니다.

1. 변경과 관련된 feature, class, endpoint, function 이름을 검색한다
2. 변경된 파일들의 outline을 확인해 주변 구조를 파악한다
3. 바뀐 symbol이나 인접 symbol만 unfold한다
4. 변경된 로직을 주변 interface, validator, caller와 비교한다
5. symbol 수준 컨텍스트만으로 부족할 때만 전체 파일을 읽는다

이렇게 하면 잡음을 줄이면서, 변경 코드가 어떤 구조에 연결되어 있는지 더 잘 이해할 수 있습니다.

언제 smart_search를 먼저 써야 하나

정확한 파일은 모르지만 개념은 알고 있을 때 smart_search를 먼저 쓰는 것이 좋습니다. 좋은 질의 예시는 다음과 같습니다.

• feature 이름
• endpoint 이름
• 에러 메시지
• 도메인 용어
• 메서드 이름
• 상태 전이

이 스킬은 구조적 검색이 가능한 상황에서 초기 탐색에 Grep, Glob, Read, find를 쓰지 말라고 분명히 권합니다. 이유는 의사결정 품질입니다. 순위가 매겨진 symbol 일치 결과가 대체로 단순 텍스트 검색 결과보다 바로 행동으로 옮기기 쉽습니다.

언제 smart_outline으로 넘어가야 하나

가능성 높은 파일은 찾았지만 아직 구현 세부사항까지는 들어가고 싶지 않을 때 smart_outline을 쓰세요. 특히 아래가 궁금할 때 적절합니다.

• 파일 안에 어떤 class나 function이 있는지
• 찾는 symbol이 실제로 그 파일에 있는지
• 최상위 구조가 어디서 시작하고 끝나는지
• 파일 전체를 읽을 가치가 있는지

큰 파일에서는 전체 읽기가 토큰만 많이 쓰고 효율이 떨어지기 때문에, 이 단계가 특히 유용합니다.

언제 smart_unfold를 써야 하나

필요한 로직이 들어 있을 가능성이 높은 symbol을 식별한 뒤에 smart_unfold를 사용하세요. 다음과 같은 대상을 확인할 때 가장 신호 대비 효율이 높습니다.

• 단일 handler
• 단일 service method
• 단일 resolver
• 단일 reducer
• 단일 utility function

너무 일찍 unfold하면 더 적절한 symbol을 놓칠 수 있습니다. 반대로 너무 늦게 unfold하면 이미 충분히 유력한 파일을 계속 outline만 하느라 시간을 낭비하게 됩니다.

출력 품질을 높이는 실전 프롬프트 예시

예시 1:

“Use smart-explore on ./src to locate the shutdown sequence. Search shutdown, outline the top relevant file, then unfold the main shutdown function and identify its dependencies.”

예시 2:

“Use smart-explore for Code Review on ./app. Search for rate limit, outline matching middleware files, then unfold the enforcement symbol and summarize request flow and likely edge cases.”

예시 3:

“Use smart-explore to find where email verification is triggered. Search verify email, rank up to 10 results, outline the top 3 files, and unfold the symbol that sends or schedules the verification.”

smart-explore 스킬 FAQ

이미 프롬프트를 잘 쓰고 있어도 smart-explore를 설치할 가치가 있나

있습니다. 전제는 환경이 이 스킬이 기대하는 도구를 지원해야 한다는 점입니다. smart-explore의 장점은 단순히 문장을 더 잘 쓰는 데 있지 않습니다. 더 강한 탐색 원칙을 적용한다는 데 있습니다. 에이전트가 파일을 하나씩 헤매는 대신 구조 중심 탐색을 우선하게 만들어 주는데, 실제 시간 낭비는 대개 이 지점에서 발생합니다.

smart-explore는 초보자도 쓰기 쉬운가

어느 정도는 그렇지만, 완전히 쉬운 편은 아닙니다. 아이디어 자체는 단순하지만, 초보자는 symbol 탐색과 파일 읽기의 차이를 이해하지 못하거나 필요한 MCP 도구 지원 없이 스킬만 설치해 막히기 쉽습니다. 처음이라면 저장소 전체 작업부터 시작하지 말고, 좁은 기능 하나를 찾는 작업부터 시작하는 것이 좋습니다.

언제 smart-explore를 쓰지 말아야 하나

다음 경우에는 smart-explore를 건너뛰는 편이 낫습니다.

• 환경에 smart_search, smart_outline, smart_unfold가 없다
• 확인할 정확한 작은 파일과 symbol을 이미 알고 있다
• 저장소가 너무 작아서 구조를 잡는 비용보다 전체 파일 읽기가 더 싸다
• 작업이 코드 구조보다 문서형 서술 중심이다

일반적인 Grep이나 Read와 smart-explore는 어떻게 다른가

Grep은 텍스트 일치 결과를 보여주고, Read는 파일 원문을 그대로 불러옵니다. 반면 smart-explore는 먼저 symbol 단위에서 코드 구조를 찾고 확인하도록 설계되어 있습니다. 그 결과 대체로 순위 품질이 더 좋고, 경계가 더 명확하며, 불필요한 전체 파일 로딩도 줄어듭니다.

smart-explore는 대형 모노레포에 잘 맞나

네. 도구 성능이 현재 환경에서 충분히 나온다는 전제하에, 오히려 가장 잘 맞는 사례 중 하나입니다. 순진하게 파일을 뒤지는 방식이 통하지 않는 대형 저장소일수록 “먼저 인덱싱하고 필요할 때만 가져온다”는 사고방식의 가치가 커집니다.

smart-explore를 Code Review 전용으로만 써도 되나

네. 실제로 코드 리뷰는 가장 분명한 활용처 중 하나입니다. 리뷰어는 변경된 파일 전체를 다시 읽기보다, 주변 symbol과 호출 구조를 빠르게 이해해야 하는 경우가 많기 때문입니다. 리뷰 질문이 “이 변경이 어디와 연결되는가?”일 때 smart-explore for Code Review는 특히 잘 맞습니다.

smart-explore 스킬을 더 잘 활용하는 방법

넓은 검색어보다 더 똑똑한 검색어를 써라

smart-explore 출력 품질은 첫 번째 질의에 크게 좌우됩니다. 좋은 검색어는 보통 도메인 용어와 동작을 함께 담습니다. 예를 들면:

• refresh token
• session revoke
• password reset
• shutdown
• rate limit

반대로 auth, user처럼 지나치게 넓은 질의는 잡음 많은 symbol 집합을 돌려주기 쉬워, 이후 워크플로 전체의 품질도 떨어뜨립니다.

항상 경로 범위를 포함하라

smart-explore usage를 개선하는 가장 쉬운 방법 중 하나는 ./src, ./app, 패키지 디렉터리처럼 검색 시작 경로를 명시하는 것입니다. 범위를 주지 않으면 특히 큰 저장소에서 결과가 더 시끄럽고 느려질 수 있습니다.

검색만 시키지 말고 순위화와 선택까지 요구하라

에이전트에게 단순히 검색만 하라고 하지 마세요. 선택까지 하게 만들어야 합니다. 예:

“Search for invoice export in ./services, rank the top 8 symbols, explain which 2 are most likely relevant, then outline those files before unfolding one symbol.”

이렇게 하면 중간에 선택 단계가 강제되어, 맹목적으로 도구만 계속 도는 일을 줄일 수 있습니다.

너무 빨리 전체 파일을 읽지 않도록 outline을 활용하라

흔한 실패 패턴은 첫 검색 결과가 나오자마자 전체 파일 읽기로 되돌아가는 것입니다. smart-explore에서 더 좋은 결과를 얻고 싶다면, 에이전트에게 다음처럼 분명히 말하세요.

“Do not read full files unless the outline does not provide enough context.”

이 한 줄이 스킬의 핵심 장점에 맞게 워크플로를 유지해 줍니다.

Code Review에서는 변경 맥락을 반영한 프롬프트로 smart-explore를 강화하라

코드 리뷰에서는 변경 영역과 아키텍처 질문을 함께 넣어야 합니다. 예:

“Use smart-explore on ./src/payments to review the new refund path. Search refund, outline affected files, unfold the entry-point symbol and the main downstream processor, then check for validation, idempotency, and error handling gaps.”

이 방식은 “이 코드 리뷰해 줘”보다 낫습니다. 리뷰 리스크가 있는 구조 쪽으로 탐색 방향을 명확히 잡아 주기 때문입니다.

주요 실패 패턴을 미리 경계하라

가장 가능성이 높은 문제는 다음과 같습니다.

• MCP 도구 지원 누락
• 너무 막연한 검색어
• 검색 후 바로 결론으로 점프하기
• 파일 outline 없이 잘못된 symbol을 unfold하기
• 구조 우선 방식이 오히려 오버헤드가 되는 작은 저장소에 이 스킬을 적용하기

이 문제들은 해결 가능하지만, SKILL.md의 문장 다듬기보다 훨씬 더 중요합니다.

처음 결과가 아쉽더라도 처음부터 다시 하지 말고 좁혀 가며 반복하라

좋은 smart-explore guide 활용법은 한 번에 끝내는 것이 아니라 점진적으로 좁혀 가는 것입니다. 첫 실행 후에는 다음을 시도하세요.

• 더 구체적인 용어로 질의를 다듬기
• 경로 범위 좁히기
• max_results 늘리거나 줄이기
• 두 번째 후보 파일도 outline하기
• 첫 번째 일치 결과만 보지 말고 인접 symbol도 unfold하기

이렇게 하는 편이 워크플로를 버리고 무작위 파일 읽기로 돌아가는 것보다 대체로 결과가 더 좋습니다.

smart-explore 스킬 자체를 더 강하게 만들려면

현재 smart-explore 문서는 쓸 수는 있지만 꽤 얇은 편입니다. 다음이 추가되면 도입 장벽이 더 낮아질 것입니다.

• 명시적인 설치 섹션 1개
• search부터 unfold까지 이어지는 초보자 예시 1개
• 코드 리뷰 예시 1개
• “언제 쓰지 말아야 하는가”를 짧게 정리한 섹션 1개
• MCP/도구 선행 조건을 앞부분에서 분명히 설명하는 메모 1개

이런 보완이 있으면 설치 전 추측이 줄고, 첫 시도에서 smart-explore skill을 올바르게 발동시키기도 훨씬 쉬워집니다.