/search-first — 코드를 작성하기 전에 먼저 연구하세요
'기존 솔루션을 먼저 검색한 후 구현하는' 워크플로우를 체계화합니다.
트리거
다음 상황에서 이 스킬을 사용하세요:
- 기존 솔루션이 있을 법한 새 기능을 시작할 때
- 의존성 또는 통합을 추가할 때
- 사용자가 "X 기능을 추가해줘"라고 요청하고 코드를 작성하려 할 때
- 새로운 유틸리티, 헬퍼, 추상화를 만들기 전에
워크플로우
┌─────────────────────────────────────────────┐
│ 0. 도구 가용성 사전 확인 │
│ 검색 채널을 신뢰하기 전에 먼저 확인하고, │
│ 건너뛴 채널은 정직하게 보고합니다 │
├─────────────────────────────────────────────┤
│ 1. 필요 분석 │
│ 필요한 기능이 무엇인지 정의 │
│ 언어/프레임워크 제약 조건 파악 │
├─────────────────────────────────────────────┤
│ 2. 병렬 검색 (리서처 에이전트) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ npm / │ │ MCP / │ │ GitHub / │ │
│ │ PyPI │ │ Skills │ │ 웹 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────┤
│ 3. 평가 │
│ 후보군 평가 (기능성, 유지보수 상태, │
│ 커뮤니티, 문서, 라이선스, 의존성) │
├─────────────────────────────────────────────┤
│ 4. 결정 │
│ ┌─────────┐ ┌──────────┐ ┌─────────┐ │
│ │ 채택 │ │ 확장 │ │ 맞춤 │ │
│ │ 그대로 │ │ /래핑 │ │ 구축 │ │
│ └─────────┘ └──────────┘ └─────────┘ │
├─────────────────────────────────────────────┤
│ 5. 구현 │
│ 패키지 설치 / MCP 구성 / │
│ 최소한의 맞춤 코드 작성 │
└─────────────────────────────────────────────┘
결정 매트릭스
| 신호 | 조치 |
|---|---|
| 정확히 일치하고, 잘 유지되며, MIT/Apache 라이선스 | 채택 — 설치하여 바로 사용 |
| 부분 일치, 좋은 기반 | 확장 — 설치 + 얇은 래퍼 작성 |
| 여러 개의 약한 일치 | 조합 — 2~3개의 작은 패키지 결합 |
| 적합한 것을 찾지 못함 | 구축 — 맞춤 작성하되, 연구 결과를 참고 |
사용 방법
0단계: 도구 가용성 사전 확인
이는 에이전트 가이드로, 실행 가능한 설정 스크립트가 아닙니다. 작업과 프로젝트에 관련된 채널만 확인하세요.
| 채널 | 확인 방법 | 누락 시 대처 |
|---|---|---|
| 저장소 검색 | rg --files 및 대상 rg 쿼리 | 보이는 파일만 검사했다고 명시 |
| 패키지 레지스트리 | npm --version, python -m pip --version 또는 프로젝트 패키지 매니저 | 웹/문서 검색을 사용하고 레지스트리 적용 범위를 주장하지 않음 |
| GitHub CLI | gh auth status | 공개 웹 또는 로컬 git 기록만 사용 |
| MCP/문서 도구 | 사용 가능한 도구 목록 또는 로컬 MCP 구성 | 공식 문서/웹 검색으로 대체 |
| 스킬 디렉토리 | 해당하는 경우 ls ~/.claude/skills ~/.codex/skills | 로컬 스킬 카탈로그를 사용할 수 없었다고 말함 |
빠른 모드 (인라인)
유틸리티를 작성하거나 기능을 추가하기 전에, 정신적으로 다음을 실행하세요:
- 이 기능이 이미 저장소에 존재하는가? → 먼저 관련 모듈/테스트에서
rg검색 - 이게 일반적인 문제인가? → npm/PyPI 검색
- 이에 대한 MCP가 있는가? →
~/.claude/settings.json확인 및 검색 - 이에 대한 스킬이 있는가? →
~/.claude/skills/확인 - GitHub 구현/템플릿이 있는가? → 새로운 코드를 작성하기 전에 유지 관리되는 오픈소스에 대한 GitHub 코드 검색 실행
전체 모드 (에이전트)
중요한 기능의 경우 리서처 에이전트를 실행하세요:
Agent(subagent_type="general-purpose", prompt="
[DESCRIPTION]에 대한 기존 도구 연구:
언어/프레임워크: [LANG]
제약 조건: [ANY]
검색: npm/PyPI, MCP 서버, Claude Code 스킬, GitHub
반환: 권장 사항이 포함된 구조화된 비교
")
이전 Claude Code 문서에서는 이것을 Task(...)라고 부를 수 있습니다. 활성화된 harness에서 노출된 현재 agent/subagent 도구 이름을 사용하세요.
카테고리별 검색 단축키
개발 도구
- 린팅 →
eslint,ruff,textlint,markdownlint - 포맷팅 →
prettier,black,gofmt - 테스팅 →
jest,pytest,go test - 사전 커밋 →
husky,lint-staged,pre-commit
AI/LLM 통합
- Claude SDK → 최신 문서는 Context7
- 프롬프트 관리 → MCP 서버 확인
- 문서 처리 →
unstructured,pdfplumber,mammoth
데이터 및 API
- HTTP 클라이언트 →
httpx(Python),ky/undici(Node) - 검증 →
zod(TypeScript),pydantic(Python) - 데이터베이스 → 먼저 MCP 서버 확인
콘텐츠 및 퍼블리싱
- 마크다운 처리 →
remark,unified,markdown-it - 이미지 최적화 →
sharp,imagemin
통합 포인트
플래너 에이전트와 함께
플래너는 1단계(아키텍처 검토) 전에 리서처를 호출해야 합니다:
- 리서처가 사용 가능한 도구를 식별
- 플래너가 이를 구현 계획에 통합
- 계획에서 "바퀴 재발명"을 방지
아키텍트 에이전트와 함께
아키텍트는 다음을 위해 리서처를 참고해야 합니다:
- 기술 스택 결정
- 통합 패턴 발견
- 기존 참조 아키텍처
반복 검색 스킬과 함께
점진적 발견을 위해 결합:
- 1주기: 광범위 검색 (npm, PyPI, MCP)
- 2주기: 상위 후보군 상세 평가
- 3주기: 프로젝트 제약 조건과의 호환성 테스트
예시
예시 1: "데드 링크 검사 추가"
필요: 마크다운 파일에서 끊어진 링크 확인
검색: npm "markdown dead link checker"
발견: textlint-rule-no-dead-link (점수: 9/10)
조치: 채택 — npm install textlint-rule-no-dead-link
결과: 맞춤 코드 제로, 실제 검증된 솔루션
예시 2: "HTTP 클라이언트 래퍼 추가"
필요: 재시도 및 타임아웃 처리가 있는 탄력적인 HTTP 클라이언트
검색: npm "http client retry", PyPI "httpx retry"
발견: got (Node) with retry plugin, httpx (Python) with built-in retry
조치: 채택 — retry 구성으로 got/httpx 직접 사용
결과: 맞춤 코드 제로, 프로덕션에서 검증된 라이브러리
예시 3: "설정 파일 린터 추가"
필요: 스키마에 대한 프로젝트 설정 파일 검증
검색: npm "config linter schema", "json schema validator cli"
발견: ajv-cli (점수: 8/10)
조치: 채택 + 확장 — ajv-cli 설치, 프로젝트별 스키마 작성
결과: 패키지 1개 + 스키마 파일 1개, 맞춤 검증 로직 없음
안티 패턴
- 코드로 바로 뛰어들기: 존재하는지 확인하지 않고 유틸리티 작성
- MCP 무시: MCP 서버가 이미 해당 기능을 제공하는지 확인하지 않음
- 조용히 건너뛰기: 검색 채널을 사용할 수 없었는데 "아무것도 찾지 못함"이라고 보고
- 과도한 맞춤화: 라이브러리를 너무 많이 래핑하여 이점을 잃음
- 의존성 비대: 하나의 작은 기능을 위해 거대한 패키지 설치