Communitygithub.com

shimo4228/search-first

Claude Code 스킬: 새로운 코드를 작성하기 전에 기존 솔루션을 먼저 조사하도록 강제하여 재발명을 줄입니다.

search-first란 무엇인가요?

이 스킬은 AI 에이전트(Claude Code, Cursor, Codex 등)가 기능, 유틸리티, 통합 또는 라이브러리를 구현하기 전에 반드시 기존 솔루션을 먼저 검색하도록 강제하는 규율 기반 워크플로우입니다. 핵심 원칙은 '검색 전에 요구사항을 명확히 하고, 소스 우선순위에 따라 검색하며, 최종적으로 기록 가능한 판정(verdict)을 내리는 것'입니다. 빠른 모드(에이전트가 직접 검색)와 전체 모드(연구 서브 에이전트에 위임)를 지원하며, 사용자가 '연구 생략'을 요청하더라도 판정 줄을 남겨 의사 결정의 투명성을 유지합니다. 이 스킬은 특정 검색 메커니즘이 아닌 '규율'에 초점을 맞추기 때문에, 검색 방식이 변경되어도 변하지 않는 핵심 절차를 제공합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add shimo4228/search-first

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

/search-first — 코드 작성 전에 먼저 연구하세요

새로운 기능, 유틸리티, 통합을 작성하거나 라이브러리를 선택하기 전에 먼저 기존 솔루션이 있는지 검색하세요. 가장 좋은 코드는 작성하지 않아도 되는 코드입니다.

이 스킬은 규율(discipline)이지 메커니즘이 아닙니다. 검색 방법 — 병렬 서브 에이전트, 실시간 문서 조회, 레지스트리 쿼리 — 은 에이전트 하네스에 속하며 계속해서 변경됩니다. 이 스킬이 고정하는 것은 그러한 변경에도 변하지 않는 부분: 검색 전에 명확히 말하고, 소스 우선순위에 따라 검색하며, 기록 가능한 판정으로 마무리하세요. 규율을 앞세우고, 메커니즘은 위임하세요.

0단계 — 요구사항을 명확히 하기 (필수, 사용자에게 보이는 텍스트)

도구 호출이나 서브 에이전트 전에, 일반 어시스턴트 텍스트(도구 인수 내에 숨기지 않음)로 2-3문장을 작성하여 다음을 명시하세요:

  • 어떤 기능이 필요한지 — 구체적으로, "X 지원"이 아니라
  • 구현에 사용할 언어/프레임워크
  • 제약 조건 — 기존 종속성, 성능 한계, 라이선스 요구사항

이유: 검색 쿼리를 외부화하여 사용자가 노력을 쏟기 전에 방향을 바꿀 수 있고, 감사 가능한 기록을 남깁니다. args에 요구사항을 담은 서브 에이전트 호출은 이 단계를 충족하지 않습니다 — 사용자는 도구 인수가 아닌 채팅 텍스트를 읽습니다. 먼저 텍스트를 내보낸 후, 그 내용을 반영할 수 있는 도구를 호출하세요.

1단계 — 소스 우선순위에 따라 검색

다음 순서로 확인하고, 강력한 일치 항목을 찾으면 일찍 중단하세요:

  1. 이 리포지토리 — 관련 모듈과 테스트를 rg/grep으로 검색합니다. 이미 존재할 수도 있습니다.
  2. 패키지 레지스트리 — 해당 언어의 npm / PyPI / crates / Go 모듈.
  3. MCP 서버 — 먼저 이미 구성된 서버, 그 다음 레지스트리. 해당 기능이 이미 연결되어 있을 수 있습니다.
  4. 설치된 스킬/에이전트/도구 — 하네스에 이미 포함되어 있을 수 있습니다.
  5. 유지 관리되는 OSS/템플릿 — GitHub 코드 검색을 통해 새 코드를 작성하기 전에 확인하세요.

의사 결정 시점에 실시간 문서를 조회하세요(예: context7, 레지스트리 자체). 기억에 의존한 패키지 정보는 나이가 들면 신뢰할 수 없습니다.

2단계 — 결정하고 판정(Verdict) 기록하기

후보를 전체적으로 평가하세요: 기능 적합성, 유지 관리 상태(최근 커밋, 이슈 대응 속도), 커뮤니티, 문서, 라이선스, 종속성 규모. 장단점을 산문으로 설명하세요. 숫자 점수(8/10), 등급, 또는 가중치 표를 할당하지 마세요 — 이는 거짓 정밀도를 만들어냅니다. 하나의 증거 기반 판정이 정직한 결과물입니다.

판정상황조치
채택정확히 일치하고, 잘 유지 관리되며, 허용 라이선스바로 설치하여 사용
확장좋은 기반이지만 부분적으로 맞음설치 + 얇은 래퍼/설정
조합여러 약한 일치 항목2-3개의 작은 패키지를 결합
구축적합한 것이 없음직접 작성 — 하지만 찾은 내용을 바탕으로

모든 과정은 인식 가능한 하나의 판정 줄로 끝나야 합니다 — 이 줄이 결과물입니다:

Verdict: <채택|확장|조합|구축> — <패키지 또는 "직접"> — <증거 기반 이유>

판정 줄이 없는 검색은 불완전한 과정입니다: 작업은 수행했지만 사용자(또는 다음 단계)가 활용할 수 있는 결정을 남기지 않았습니다 — 이 워크플로우의 가장 흔한 실패입니다. 이유는 증거(별표, 마지막 커밋 날짜, 특정 기능 일치)로 뒷받침하고, 형용사("좋아 보임", "인기 있음")는 절대 사용하지 마세요.

빠른 모드 vs 전체 모드

  • 빠른 모드(인라인) — 단순하고 명백한 필요: 스스로 0-2단계를 실행하고 몇 번 검색한 후 판정을 제시합니다.
  • 전체 모드(위임) — 복잡한 필요: 0단계 후, 검색을 연구 서브 에이전트(하네스가 제공하는 솔루션 발견 도구)에 넘깁니다. 요구사항을 서브 에이전트 프롬프트에 반영하고, 후보와 위 형식의 판정을 반환하도록 합니다. 진정으로 어려운 질문에 대해서는 대규모 다중 소스 연구를 예약하세요 — 라이브러리 찾기는 연구 보고서보다 가볍습니다.

사용자가 "연구 생략"을 요청한 경우

사용자가 연구를 생략하라고 요청하면("그냥 구현해", "시간 없어", "아무거나 써"), 구현 전에 여전히 결정을 판정 줄로 기록하세요 — 연구 생략은 그 자체로 결정이므로, 다른 과정과 마찬가지로 판정을 받습니다(이것은 선택을 감사 가능하게 유지하고 방향 수정 창을 열어둡니다):

요청에 따라 연구를 건너뜁니다 — X에 대한 기존 라이브러리가 있는지 확인하지 않았습니다. Verdict: <채택|구축> — <임시 선택 또는 "직접"> — 요청에 따라 연구 없이 선택됨; 60초 스캔을 원하면 말씀해 주세요.

이유: 사용자는 이미 솔루션이 존재한다는 것을 모를 수 있습니다. 묵시적 생략은 방향을 수정할 기회를 빼앗습니다. 판정 줄 이후에는 검색 없이 진행하세요 — 이를 우회하여 전체 연구를 수행하는 데 사용하지 마세요.

안티 패턴

  • 바로 코드로 뛰어들기 — 유틸리티가 이미 있는지 확인하지 않고 작성.
  • MCP/설치된 기능 무시 — 이미 연결된 것을 다시 구축.
  • 과도한 커스터마이징 — 라이브러리를 너무 감싸서 이점을 잃음.
  • 종속성 비대화 — 작은 기능 하나를 위해 거대한 패키지 설치.
  • 판정 없는 검색 — 작업은 했지만 결정을 기록하지 않음.

예시 (설명용 — 라이브로 패키지 확인 필요)

이 예시들은 판정이 어떻게 읽히는지 보여줍니다. 특정 패키지에 대한 현재 보증이 아닙니다. 특정 패키지에 의존하기 전에 다시 검색하세요.

  • 데드 링크 확인 → 모든 링크 유형을 다루는, 유지 관리되고 허용 라이선스의 링크 확인 규칙 → Verdict: 채택 — textlint-rule-no-dead-link — 활발한 유지 관리, MIT, 완전한 커버리지
  • Qiita 교차 게시 → 유지 관리되지 않는 부분 래퍼만 존재 → Verdict: 구축 — 직접 — 유지 관리되는 완전한 솔루션 없음; HTTP 클라이언트를 통해 플랫폼 API 재사용
  • JP 용어 일관성 → 프로젝트 설정이 필요한 사전 기반 검사기 → Verdict: 확장 — textlint-rule-prh — 설치 + 프로젝트 사전

관련 스킬