hec-ovi/research-skill

Research

심층 연구 결과를 위한 지속적인 프로젝트 범위 저장소입니다. 사용자가 실질적인 연구 질문을 하거나 /research <주제>를 통해 명시적으로 호출하면 이 스킬이 활성화됩니다.

주제 인수(예: /research tailwind-v5)와 함께 호출된 경우, 이를 검색의 시드로 사용하십시오. INDEX.md에서 해당 주제를 조회하는 것으로 시작하세요. 맹목적으로 연구하지 마십시오. 조회로 즉시 답변될 수 있습니다.

사용 시기

• "X를 하는 최신 npm 패키지는 무엇인가요"
• "2026년을 위해 A, B, C를 비교해 주세요"
• "X를 빠르게 클론할 수 있는 엔진/프레임워크/라이브러리는 무엇인가요"
• "Y가 내부적으로 어떻게 작동하는지 조사해 주세요"
• "Z에 대해 심층 분석해 주세요"
• 사용자가 긴 마크다운 연구 자료를 붙여넣고 저장을 요청하는 경우

사용하지 말아야 할 경우

• 계획 단계의 메모
• 작은 사실이나 한 줄짜리 선호도
• 단일 파일에 국한된 코드 수준의 결정
• 단일 출처에서 합성 없이 답변 가능한 간단한 조회
• 개인적인 아이디어나 생각 기록
• 단일 WebSearch 또는 WebFetch의 대체 수단으로 사용

단일 WebSearch + 1-2 문장으로 질문에 답할 수 있다면 이 스킬이 필요하지 않습니다.

설정 (최초 사용 시에만)

프로젝트에서 처음 활성화될 때 한 번 수행하십시오:

1. 프로젝트 루트 확인: git rev-parse --show-toplevel 2>/dev/null || pwd

2. <root>/.research/ 디렉토리가 없으면 생성

3. <root>/.research/INDEX.md를 다음 내용으로 생성:

   # Research index
   
   | Topic | Path | Last verified | One-liner |
   |---|---|---|---|
   

4. <root>/.gitignore에 .research/를 추가. .gitignore가 없으면 생성. 연구 데이터는 독점적인 통찰력을 포함할 수 있으므로 기본적으로 비공개로 유지.

데이터는 <root>/.research/에 위치합니다(.claude/의 형제 디렉토리이지 내부에 중첩되지 않음). 연구 데이터가 프로젝트와 함께 배치되고, 기본적으로 gitignoring되며, 이름으로 쉽게 찾을 수 있도록 최상위 프로젝트 디렉토리입니다. 모든 읽기 및 쓰기는 호스트의 일반 권한 시스템을 통해 이루어지므로 감사 추적은 그대로 유지됩니다.

워크플로우

1. 검색 (읽기 측면 - 이 스킬이 컨텍스트를 저장하는 방법)

이 시스템의 핵심은 점진적 공개입니다: 필요하지 않은 것은 로드하지 마십시오. INDEX.md가 디스패처 역할을 하여, 각 항목을 로드하는 비용을 지불하지 않고 어떤 항목을 로드할지 결정할 수 있게 해줍니다. 가장 저렴한 계층에서 가장 비싼 계층으로 계층 구조를 탐색하십시오. 이전 계층이 질문에 답하지 못할 때만 상위 계층으로 넘어가십시오.

로딩 계층 구조 (가장 저렴 → 가장 비쌈)

계층	로드 대상	예상 토큰 수	시기
1	INDEX.md (항상)	~100-500	모든 검색 시 - 라우팅 테이블
2	항목의 ## Summary만	~50-200	인덱스가 주제 일치를 보일 때
3	전체 FINDINGS.md 본문	~500-3000	Summary가 질문을 다루지 않을 때
4	특정 raw/<file> 문서	다양함 (종종 큼)	조사 결과가 이를 인용하고 주장을 확인해야 할 때
5	상호 참조된 항목 (related:)	계층 2-3 반복	질문이 여러 항목에 걸쳐 있을 때

조회 절차

1. 먼저 INDEX.md를 읽으십시오 (계층 1). 한 줄 요약 열을 사용자의 질문과 비교하십시오. 이것이 디스패처입니다 - GBrain의 RESOLVER.md와 동일한 역할입니다.

2. 일치 판단:

   • 강한 일치 - 한 항목의 한 줄 요약이 주제를 명확히 다루는 경우 → 해당 항목으로 3단계로 이동.
   • 여러 가능한 일치 - 각 항목의 ## Summary를 로드(여전히 저렴한 계층 2). 실제로 답변하는 항목을 선택.
   • 약한 일치 / 일치 없음 → 조사 단계로 넘어감. 새 항목이 추가됨.

3. 일치하는 항목의 ## Summary만 읽으십시오 (계층 2):

   sed -n '/^## Summary/,/^## /p' <root>/.research/<slug>/FINDINGS.md
   

   일반적으로 충분합니다.

4. 필요할 때만 한 계층씩 상승:

   • 질문에 Summary 이상의 주장 수준 세부 정보가 필요한 경우 → 전체 FINDINGS.md 본문 로드 (계층 3).
   • 질문이 "X를 이전에 시도한 적이 있는가/무엇이 폐기되었는가?"인 경우 → 해당 섹션만 sed로 추출: sed -n '/^## Discarded approaches/,/^## /p' <root>/.research/<slug>/FINDINGS.md. 나머지는 로드하지 마십시오.
   • 질문이 붙여넣어 인용된 주장을 참조하는 경우 → raw/ 아래의 특정 파일 열기 (계층 4).
   • 질문이 별도 항목으로 다루는 주제에 걸쳐 있는 경우 → related:를 따르고, 각각에 대해 계층 2-3을 반복.

5. 조사 단계로 넘어감. 모드 선택:

   • INDEX.md에 항목이 없는 경우 → 새 항목 모드로 조사.
   • 기존 항목이 질문을 실제로 해결하지 못하는 경우 (문제가 여전히 해결되지 않음) → 병합 모드로 조사 (기존 항목 내용을 서브에이전트에 전달).
   • 빠르게 변화하는 주제에 대한 기존 항목이 오래된 경우 → 병합 모드로 조사 (새로 고침, 인용하지 않음).

절대 하지 말아야 할 것

• 모든 것을 로드하지 마십시오. 스키마는 선택적으로 로드할 수 있도록 존재합니다.
• Summary로 충분할 때 전체 본문을 로드하지 마십시오. 3줄로 답변된다면 300줄을 가져오지 마십시오.
• 추측성으로 raw 문서를 로드하지 마십시오. 무겁습니다. 대부분의 질문에 필요하지 않습니다.
• 이미 이 세션에서 로드한 항목을 다시 읽지 마십시오 - 세션 중에 업데이트되지 않은 경우.

디스패처로서의 INDEX.md

INDEX.md는 오직 로드하지 않고 어떤 항목을 로드할지 결정할 수 있도록 존재합니다. 한 줄 요약 열은 항목 읽기 비용을 지불하기 전에 가진 유일한 신호입니다. 저장할 때 이를 명시적으로 작성하십시오.

INDEX.md를 간결하게 유지하십시오: 약 100행 미만. 그 이상 커지면 정리하거나 보관하십시오. INDEX.md 자체가 부풀어오르는 원천이 되면 전체 토큰 절약 설계가 무너집니다.

2. 조사 (새로운 연구가 필요할 때)

model: "opus" 및 run_in_background: true 로 general-purpose 서브에이전트를 생성하십시오. 조사 단계는 강력한 모델이 필요합니다: 반대 관점 조사 및 합성 단계는 더 작은 모델이 제공할 수 없는 추론 깊이에 의존합니다. 백그라운드 모드는 대화를 계속 인터랙티브하게 유지합니다: 사용자는 연구가 실행되는 동안 계속 작업할 수 있습니다. 에이전트의 완료 알림이 도착하면 저장이 비동기적으로 실행됩니다.

서브에이전트는 연구를 수행하고 합성 결과를 구조화된 텍스트로 반환합니다. 파일을 전혀 작성하지 않습니다. 모든 파일 쓰기는 메인 에이전트(귀하)가 저장 단계에서 처리합니다. 이 분할은 책임을 명확히 합니다: 서브에이전트는 컨텍스트가 없으며 귀하의 스키마나 INDEX.md 레이아웃을 알 필요가 없습니다.

명명 규칙. 도구의 description 매개변수를 Research investigation: <topic>(3~5단어)으로 설정하십시오. 이렇게 하면 연구 스킬 스폰이 하니스 UI에서 식별 가능해집니다.

완료 알림 시: 에이전트의 반환을 구문 분석하고, 저장을 즉시 적용하며, 사용자에게 간략한 알림을 표시하십시오(예: "<topic>에 대한 연구가 <path>에 저장되었습니다"). 요청하지 않는 한 전체 조사 결과를 채팅에 덤프하지 마십시오.

서브에이전트는 사전 컨텍스트가 전혀 없습니다. 이 스킬, CLAUDE.md 또는 우리의 대화를 볼 수 없습니다. 완전히 브리핑하십시오. 이 하니스에서는 계속(continuation)이 없습니다. 에이전트를 재개하기 위한 SendMessage 도구를 사용할 수 없습니다. 단발성(one-shot)입니다. 공백이 남아 있으면 정제된 브리핑으로 다시 스폰하십시오.

모드(새 항목 vs 병합)는 검색 단계 5에서 결정되었습니다. 그에 따라 서브에이전트를 브리핑하십시오:

• 새 항목 모드 - 표준 브리핑, 제공할 기존 컨텍스트 없음.
• 병합 모드 - 기존 항목의 ## Summary 및 관련 ## Findings 섹션을 브리핑에 붙여넣고, *"항목의 현재 상태 - 확인, 업데이트 또는 대체"*로 명확히 표시하십시오. 서브에이전트에게 현재 잘못된 주장을 플래그 지정하라고 지시하십시오.

브리핑 체크리스트

모든 조사 브리핑에는 다음이 반드시 포함되어야 합니다:

• "사전 컨텍스트가 전혀 없습니다" 서문
• 오늘의 실제 날짜 (먼저 date +%Y-%m-%d 실행; 리터럴 문자열 전달)
• WebSearch 쿼리에 대한 연도 고정 규칙 (서브에이전트의 모델이 현재 연도에 대해 무엇을 알고 있는지 신뢰하지 마십시오)
• 사소하지 않은 주장당 최소 2개의 독립적인 출처. 출처는 반환 끝에 단일 ## Sources 블록에 수집됨; 인라인으로 인용하지 마십시오.
• 아래 인지 단계를 명시적인 번호 단계로 포함
• 서브에이전트의 필수 출력 형식 (아래)
• Findings 본문에 대한 엄격한 [n] 없음 / 인라인 URL 없음 규칙 (필수 출력 형식 참조)
• 병합 모드 전용: 서브에이전트가 확인/대체해야 하는 기존 항목 내용

인지 단계 (서브에이전트 브리핑에 그대로 포함)

서브에이전트는 이를 개별 단계로 진행합니다. 4단계는 매우 중요합니다:

1. 분해 - 질문을 해결할 하위 주장을 나열합니다. 각각을 해결하는 증거를 식별합니다.
2. 수집 - 각 하위 주장에 대해 ≥2개의 독립적인 출처를 찾습니다 (연도 고정 WebSearch → 상위 결과에 대한 WebFetch). 그대로 인용합니다. 아직 합성하지 마십시오.
3. 검증 - 숫자, 벤치마크, 버전 주장을 재도출합니다. 실패하는 것을 플래그 지정합니다.
4. 반대 관점 조사 - "이것이 왜 잘못되었는가 / 사기인가 / 비판받는가 / 더 이상 사용되지 않는가 / 알려진 문제인가"를 적극적으로 검색합니다. 발견된 가장 강력한 반대 의견을 명시합니다. 이 단계를 건너뛰는 것이 가장 흔한 서브에이전트 실패 모드입니다. 브리핑에서 명시적으로 지적하십시오.
5. 합성 - 평결 + 인용 + 명시적으로 나열된 잔여 의견 차이. 조용한 선택 없음.

필수 서브에이전트 출력 형식

브리핑에는 명시적인 인용 규칙이 포함되어야 합니다. 학술 스타일 작성으로 훈련된 서브에이전트는 기본적으로 [1], [2] 인라인 인용을 사용합니다. 명시적인 지침 없이는 잡음이 많은 출력을 생성합니다. 평이한 언어로 규칙을 명시하십시오. 브리핑에 붙여넣을 권장 그대로 사용 블록:

인용 규칙. 주의 깊게 읽고 정확히 따르십시오:

• [n] 번호가 매겨진 인용을 사용하지 마십시오. Findings 본문에 [1], [2] 또는 대괄호 숫자를 넣지 마십시오.
• Findings 본문에 URL을 넣지 마십시오.
• 인라인 각주 표시, 앵커 또는 종류에 관계없이 주장별 인용 태그를 추가하지 마십시오.
• Findings는 일반 산문 단락으로 작성하십시오.
• 주장의 해석이 어떤 출처가 말했는지에 따라 달라지는 경우, 산문으로 출처 이름을 지정하십시오(대괄호 없이, "README에 따르면", "littlemight.com에 따르면", "HN-시뮬레이터 댓글 작성자는 주장합니다..."). URL이나 [n] 없음.
• 모든 출처를 반환 끝의 단일 ## Sources 블록에 넣으십시오. 출처당 한 개의 글머리 기호: - url - fetched YYYY-MM-DD. 메인 에이전트가 이 블록을 FINDINGS.md 프론트매터로 옮깁니다.
• 출처 수 규율은 유지됩니다: 사소하지 않은 주장당 최소 2개의 독립적인 출처. 규율은 인라인 태깅이 아닌 출처 수에 존재합니다.

필수 출력 형태 (서브에이전트가 반환하는 것):

## Summary
3~6줄 TL;DR.

## Findings
일반 산문. `[n]` 표시 없음. 인라인 URL 없음. 해석에 중요한 경우에만 산문으로 인라인 출처 이름 지정.

## Strongest objection (from contrarian pass)
1~2문장, 또는 "none found".

## Sources
- url - fetched YYYY-MM-DD
- url - fetched YYYY-MM-DD

## (Merge mode only) Supersedes
- 기존 항목에서 현재 잘못된 주장 + 이유

서브에이전트는 파일을 쓰지 않습니다. 귀하는 이 반환을 구문 분석하고 저장 규칙을 적용합니다.

공백 처리

서브에이전트의 반환에 공백이 있는 경우:

• 작은 공백 (누락된 사실 하나, 특정 관점 하나) → 집중 WebSearch/WebFetch로 직접 채우십시오. 다시 스폰하는 것보다 저렴합니다.
• 큰 공백 (전체 섹션이 얕음, 반대 관점 조사가 분명히 건너뛰어짐) → 특정 공백을 명명하는 정제된 브리핑으로 다시 스폰하십시오. 이전 반환은 폐기됩니다(아직 파일이 작성되지 않았음).

3. 저장 (쓰기 측면 - 메인 에이전트가 모든 파일 쓰기를 소유)

저장 전 검토

서브에이전트의 구조화된 형식은 내용을 검증하지 않습니다. 형식은 "템플릿을 따랐다"는 신호일 뿐, 내용이 정확하고, 출처가 명확하며, 요청된 것과 관련이 있는지 확인하지 않습니다. 저장을 적용하기 전에 이 4가지 포인트 검사를 실행하십시오:

1. 관련성: Summary가 실제로 요청된 것에 답변합니까? 에이전트가 모호한 주제를 명확히 한 경우(여러 해석 중 하나를 선택), 사용자의 의도와 일치하는지 확인하십시오. 틀리면 더 엄격한 브리핑으로 다시 스폰하십시오. 저장하지 마십시오.
2. 출처 품질: ## Sources 블록에서 기본 URL과 집계된 WebSearch 스니펫의 수를 세십시오. 대부분의 출처가 특정 가져온 URL 없이 검색 결과 요약인 경우, 항목이 보이는 것보다 약합니다. 직접 WebFetch로 기본 URL을 채우거나, ## Open questions에서 명시적으로 약점을 플래그 지정하여 저장하십시오.
3. 반대 관점 조사 증거: 사소하지 않은 주제에서 "none found"는 드뭅니다. "none found"를 받았다면 회의적이어야 합니다: 주제가 진정으로 논란의 여지가 없거나(드물음), 서브에이전트가 4단계를 건너뛰었거나(일반적). 건너뛴 경우, 직접 반대 관점 검색으로 채우거나 다시 스폰하십시오.
4. 인용 정리: 반환에 브리핑의 [n] 금지 규칙에도 불구하고 Findings 본문에 [n] 표시가 포함된 경우, FINDINGS.md를 쓰기 전에 이를 제거하십시오. 이것은 알려진 실패 모드입니다(서브에이전트가 학술 인용 습관으로 되돌아감). 노이즈를 하류로 전달하지 마십시오. Findings 본문의 인라인 URL도 마찬가지로 제거하십시오. 출처는 프론트매터에 속합니다.

검토에서 수정 가능한 공백이 발견되면, 집중 WebSearch/WebFetch로 직접 채우십시오(다시 스폰하는 것보다 저렴). 공백이 체계적이면 정제된 브리핑으로 다시 스폰하십시오. 절반만 완성된 항목을 쓰지 마십시오.

저장 적용

조사가 합성을 반환한 후(또는 사용자가 결과를 붙여넣은 후), 귀하(메인 에이전트, 절대 서브에이전트가 아님)가 데이터 계층을 마무리합니다. 검색 단계 5에서 선택한 모드에 따라 두 가지 경로가 있습니다:

새 항목 경로:

1. <root>/.research/<topic-slug>/를 생성합니다.
2. 파일 스키마를 사용하여 FINDINGS.md를 작성합니다. 프론트매터: created 및 last_verified = 오늘; status: active; sources는 서브에이전트 반환에서; raw:는 생략(아직 raw 없음); related: [](교차 링크가 적용되지 않는 한).
3. INDEX.md를 읽고, 행을 추가합니다: 주제, 경로, 오늘 날짜, 특정 한 줄 요약.

병합 경로:

1. 기존 FINDINGS.md를 읽습니다.
2. 프론트매터 업데이트: last_verified = 오늘; 새 출처 추가.
3. 서브에이전트의 ## Supersedes 목록 적용: 각 명명된 주장을 ## Findings에서 ## Discarded approaches로 이동하고 날짜 + 이유를 추가합니다. 충돌 처리 참조.
4. 새 주장으로 ## Findings 업데이트/확장.
5. 변경 사항을 요약하는 ## Timeline 항목을 추가합니다.
6. INDEX.md를 읽고, 행의 Last verified 열을 업데이트합니다. 그림이 변경된 경우 한 줄 요약도 업데이트합니다.

사용자가 다시 물을 가능성이 있는 방식과 일치하는 kebab-case 슬러그를 사용하십시오 - 예: tailwind-v5, 2d-engines-clonable, orm-comparison-2026. 슬러그는 모호성을 제거해야 합니다.

4. 과거

… [번역 잘림]