/search-first — 코드 작성 전에 먼저 연구하세요
새로운 기능, 유틸리티, 통합을 작성하거나 라이브러리를 선택하기 전에 먼저 기존 솔루션이 있는지 검색하세요. 가장 좋은 코드는 작성하지 않아도 되는 코드입니다.
이 스킬은 규율(discipline)이지 메커니즘이 아닙니다. 검색 방법 — 병렬 서브 에이전트, 실시간 문서 조회, 레지스트리 쿼리 — 은 에이전트 하네스에 속하며 계속해서 변경됩니다. 이 스킬이 고정하는 것은 그러한 변경에도 변하지 않는 부분: 검색 전에 명확히 말하고, 소스 우선순위에 따라 검색하며, 기록 가능한 판정으로 마무리하세요. 규율을 앞세우고, 메커니즘은 위임하세요.
0단계 — 요구사항을 명확히 하기 (필수, 사용자에게 보이는 텍스트)
도구 호출이나 서브 에이전트 전에, 일반 어시스턴트 텍스트(도구 인수 내에 숨기지 않음)로 2-3문장을 작성하여 다음을 명시하세요:
- 어떤 기능이 필요한지 — 구체적으로, "X 지원"이 아니라
- 구현에 사용할 언어/프레임워크
- 제약 조건 — 기존 종속성, 성능 한계, 라이선스 요구사항
이유: 검색 쿼리를 외부화하여 사용자가 노력을 쏟기 전에 방향을 바꿀 수 있고,
감사 가능한 기록을 남깁니다. args에 요구사항을 담은 서브 에이전트 호출은
이 단계를 충족하지 않습니다 — 사용자는 도구 인수가 아닌 채팅 텍스트를 읽습니다.
먼저 텍스트를 내보낸 후, 그 내용을 반영할 수 있는 도구를 호출하세요.
1단계 — 소스 우선순위에 따라 검색
다음 순서로 확인하고, 강력한 일치 항목을 찾으면 일찍 중단하세요:
- 이 리포지토리 — 관련 모듈과 테스트를
rg/grep으로 검색합니다. 이미 존재할 수도 있습니다. - 패키지 레지스트리 — 해당 언어의 npm / PyPI / crates / Go 모듈.
- MCP 서버 — 먼저 이미 구성된 서버, 그 다음 레지스트리. 해당 기능이 이미 연결되어 있을 수 있습니다.
- 설치된 스킬/에이전트/도구 — 하네스에 이미 포함되어 있을 수 있습니다.
- 유지 관리되는 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 — 설치 + 프로젝트 사전