/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 구현/템플릿이 있는가? → 새로운 코드를 작성하기 전에 유지 관리되는 OSS에 대한 GitHub 코드 검색 실행
전체 모드 (에이전트)
중요한 기능의 경우 리서처 에이전트를 실행하세요:
Agent(subagent_type="general-purpose", prompt="
다음에 대한 기존 도구 연구: [설명]
언어/프레임워크: [언어]
제약 조건: [모든 조건]
검색: npm/PyPI, MCP 서버, Claude Code 스킬, GitHub
반환: 권장 사항이 포함된 구조화된 비교
")
이전 Claude Code 문서에서는 이것을 Task(...)라고 부를 수 있습니다. 현재 활성화된 harness에서 노출된 에이전트/서브에이전트 도구 이름을 사용하세요.
카테고리별 검색 단축키
개발 도구
- 린팅 →
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(TS),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
결과: 커스텀 코드 0줄, 검증된 솔루션
예시 2: "HTTP 클라이언트 래퍼 추가"
필요: 재시도 및 타임아웃 처리가 있는 복원력 있는 HTTP 클라이언트
검색: npm "http client retry", PyPI "httpx retry"
발견: got (Node) + retry 플러그인, httpx (Python) + 내장 retry
조치: 채택 — got/httpx를 retry 설정과 함께 직접 사용
결과: 커스텀 코드 0줄, 프로덕션 검증된 라이브러리
예시 3: "설정 파일 린터 추가"
필요: 프로젝트 설정 파일을 스키마에 대해 검증
검색: npm "config linter schema", "json schema validator cli"
발견: ajv-cli (점수: 8/10)
조치: 채택 + 확장 — ajv-cli 설치, 프로젝트별 스키마 작성
결과: 패키지 1개 + 스키마 파일 1개, 커스텀 검증 로직 없음
안티 패턴
- 바로 코드로 뛰어들기: 존재 여부를 확인하지 않고 유틸리티 작성
- MCP 무시하기: MCP 서버가 이미 기능을 제공하는지 확인하지 않음
- 조용히 건너뛰기: 검색 채널을 사용할 수 없었는데 "찾을 수 없음"이라고 보고
- 과도한 커스터마이징: 라이브러리를 너무 많이 래핑하여 이점을 상실
- 의존성 비대: 작은 기능 하나를 위해 거대한 패키지 설치