handoff-md은(는) 무엇을 하나요?
모든 리포지토리에서 이식 가능한 AI 컨텍스트 파일을 생성하여 AI 모델이 세션과 도구 간에 프로젝트를 즉시 이해할 수 있도록 돕습니다.
이 스킬은 리포지토리를 분석하고, 핵심 구조, 주요 파일, 설정, 의존성 및 기타 중요한 정보를 단일 마크다운 파일(handoff.md)로 모읍니다. AI 에이전트(예: Claude Code, Cursor, Codex 등)는 이 파일을 읽고 프로젝트의 목적, 아키텍처, 빌드 방법 및 확장 방법에 대한 빠른 이해를 얻을 수 있습니다.
사용법
- 터미널에서 프로젝트의 루트 디렉토리로 이동합니다.
- 다음 명령어를 실행합니다:
npx handoff-md handoff.md파일이 생성됩니다.- 이 파일을 AI 도구에 제공하거나, 컨텍스트로 로드하거나, 저장소에 커밋할 수 있습니다.
지원 플랫폼
- Claude Code
- Claude Desktop 앱
- Cursor
- Codex CLI
- 기타 AI 기반 개발 도구
구성
기본적으로 handoff.md는 다음과 같은 정보를 포함합니다:
- 프로젝트 개요:
package.json,README.md등에서 추출한 프로젝트 메타데이터 - 디렉토리 구조: 주요 디렉토리 및 파일의 트리 표현
- 의존성: 주요 런타임 및 개발 의존성
- 스크립트:
package.json에 정의된 npm 스크립트 - 설정 파일:
.env.example,tsconfig.json,eslintrc.js등의 내용 (비밀 정보는 제외) - 주요 파일: 주요 소스 파일의 요약 또는 스니펫 (파일 크기 또는 중요도에 따라)
옵션
npx handoff-md --output custom-context.md # 사용자 정의 출력 파일 이름
npx handoff-md --depth 3 # 디렉토리 탐색 깊이
npx handoff-md --include "src/,lib/" # 특정 디렉토리만 포함
npx handoff-md --exclude "node_modules,dist" # 특정 디렉토리 제외
스킬 작동 방식
- 스캔: 리포지토리 파일과 디렉토리를 탐색합니다.
- 분석: 중요 파일 및 구성(
package.json,README,.gitignore등)을 식별합니다. - 추출: 파일 내용을 읽고 구조화된 정보를 추출합니다.
- 생성: AI 친화적인 마크다운 파일(
handoff.md)로 모든 정보를 컴파일합니다.
이렇게 생성된 파일은 AI에게 프로젝트를 요약하여 제공하므로, AI가 프로젝트의 컨텍스트를 이해하는 데 필요한 수동 힌트나 긴 설명 없이도 작업을 수행할 수 있습니다.
예시
생성된 handoff.md의 예시 구조
# 프로젝트 이름
## 개요
이 프로젝트는 Node.js로 작성된 웹 API입니다.
## 디렉토리 구조
- `src/`
- `routes/`
- `controllers/`
- `models/`
- `config/`
## 의존성
- express: ^4.18.2
- mongoose: ^7.0.0
## 스크립트
- `npm run dev`: 개발 서버 시작
- `npm test`: 테스트 실행
주의 사항
handoff.md에는 민감한 정보(비밀 키, API 토큰,.env파일 내용)를 포함하지 마십시오.- 중요한 프로젝트인 경우,
.gitignore에handoff.md를 추가하여 실수로 커밋되지 않도록 합니다. - 파일이 매우 클 수 있으므로, 큰 리포지토리에서는 깊이 또는 포함/제외 옵션을 사용하여 결과를 관리 가능한 크기로 유지하는 것을 권장합니다.