knowledge-transfer은(는) 무엇을 하나요?

프로젝트 지식을 동료 간에 전송합니다: 짧은 비기술 온보딩 문서와 AI가 축적한 프로젝트 메모리를 프로젝트 리포지토리 내부에 패키징하여 신규 동료가 방향을 잡고 AI가 정보를 바탕으로 작업을 시작할 수 있도록 합니다.

사용법

Claude Code 독립형 스킬:

/knowledge-transfer            # 자동 모드 감지 (아래 참고)
/knowledge-transfer export     # 떠나는 동료: 인수인계 패키지 생성
/knowledge-transfer import     # 신규 동료: 메모리 검증 + 설치, 문서 읽기

Claude Code 플러그인 설치:

/knowledge-transfer:knowledge-transfer
/knowledge-transfer:knowledge-transfer export
/knowledge-transfer:knowledge-transfer import

Codex 또는 SKILL.md를 읽는 다른 에이전트:

$knowledge-transfer            # 자동 모드 감지
$knowledge-transfer export     # 떠나는 동료
$knowledge-transfer import     # 신규 동료

모드 감지 (인수 없음)

프로젝트 루트에 handover/manifest.json이 존재하면 → 가져오기 모드 선언.
그렇지 않으면 → 내보내기 모드 선언.

감지된 모드를 한 줄로 표시하고 진행합니다. 사용자는 언제든지 재정의할 수 있습니다.

계약 사항

다음을 생성하기 전에 먼저 읽으십시오:

references/package-format.md — 패키지 구조 및 매니페스트 스키마
references/privacy-filter.md — 내보낼 수 있는 항목과 없는 항목
references/onboarding-template.md — 문서의 구조, 어조 및 길이
references/agent-memory.md — Claude, Codex 또는 다른 에이전트에서 메모리를 찾고 설치하는 방법

내보내기 단계

프로젝트를 떠나는 동료가 프로젝트 루트에서 실행합니다.

1. 프로젝트 분석

README, 에이전트 안내 파일(CLAUDE.md, AGENTS.md, GEMINI.md, .cursor/rules/ 등 존재하는 경우), 최상위 구조, 진입점 및 주요 설정 파일을 읽습니다. 대규모 코드베이스의 경우 모든 것을 인라인으로 읽지 말고 서브에이전트를 사용하십시오.
식별 항목: 프로젝트의 기능, 3~~7개의 주요 구성 요소, 설명할 가치가 있는 2~~3개의 종단 간 논리적 흐름.
프로젝트의 주 언어 감지(README, 문서, 최근 커밋 메시지 기준); 온보딩 문서는 해당 언어로 작성합니다. 불명확하거나 혼합된 경우 → 영어.

2. 메모리 읽기

references/agent-memory.md를 사용하여 현재 에이전트의 프로젝트 메모리 소스를 찾습니다.
이 프로젝트 또는 리포지토리로 범위가 지정된 메모리만 읽습니다. 전역 사용자 환경 설정이나 관련 없는 프로젝트 기록은 내보내지 마십시오.
메모리 디렉토리가 없거나 메모리가 없음 → 문서만으로 진행하고, 매니페스트에 memories: {"exported": 0, "excluded": 0}을 설정하고 패키지에 메모리가 포함되어 있지 않다고 사용자에게 알립니다.

3. 메모리 필터링

references/privacy-filter.md를 모든 메모리에 엄격히 적용합니다. 이식 가능한 버전(재작성, 중립적)과 메모리별 제외 목록 및 이유를 생성합니다.

4. 패키지 작성

handover/가 이미 존재하면 중지하고 덮어쓰기 전에 물어보십시오.
references/onboarding-template.md에 따라 handover/ONBOARDING.md를 작성합니다.
각 남은 메모리를 이식 가능한 형식으로 handover/memories/<slug>.md에 작성합니다.
스키마에 따라 handover/manifest.json을 작성합니다(커밋 SHA는 git rev-parse HEAD에서 가져옴, git 리포지토리가 아니면 commit 생략, git config에 이름이 없으면 author 생략).

5. 최종 체크리스트 — 완료 선언 전 검증

handover/ 트리 전체에서 동료의 이름, 이메일 및 사용자 이름을 grep으로 검색: 결과 0.
handover/memories/에 user 유형의 메모리 없음.
ONBOARDING.md는 600~1000단어(wc -w)이며 6개의 템플릿 섹션을 포함합니다.
내보낸 메모리에서 인용된 모든 파일/경로가 프로젝트에 존재합니다.
manifest.json이 파싱되고 개수가 실제 파일과 일치합니다.

사용자에게 패키지 내용, 제외 목록 및 이유를 보고하고 handover/를 리포지토리에 커밋할 것을 제안합니다. 허락 없이 커밋하지 마십시오.

가져오기 단계

신규 동료가 클론 후 프로젝트 루트에서 실행합니다.

1. 패키지 읽기

handover/manifest.json, handover/ONBOARDING.md 및 handover/memories/의 모든 파일을 읽습니다.
handover/가 없으면 → 중지: 떠나는 동료가 먼저 /knowledge-transfer export를 실행한 다음 결과를 커밋해야 한다고 설명합니다.
manifest.version을 알 수 없으면 → 중지하고 이 패키지에 대해 스킬이 너무 오래되었다고 말합니다.

2. 각 메모리를 현재 코드와 대조하여 검증

리포지토리가 git이고 매니페스트에 commit이 있으면 git diff --stat <commit>..HEAD를 실행하여 내보내기 이후 변경된 영역을 확인합니다.
각 메모리에 대해 인용된 파일, 경로 및 식별자가 여전히 존재하는지 확인합니다(Glob/Grep, 추정하지 않음). 분류:
- 유효 — 모든 것이 일치함 → 있는 그대로 설치;
- 오래됨, 명백한 수정 가능 — 예: 인용된 파일 이름이 변경되었고 새 경로가 명확함(git log --follow 또는 고유한 검색 결과) → 메모리 본문을 업데이트한 후 설치;
- 오래됨, 명백한 수정 불가 — 폐기, 한 줄 이유 기록.

3. 설치

각 승인된 메모리를 현재 에이전트의 메모리 메커니즘(references/agent-memory.md 참고)을 통해 설치하며, 이식 가능한 메모리 내용은 그대로 유지하고 대상 에이전트가 요구하는 경우에만 저장소 래퍼/인덱스를 조정합니다.
기존 메모리와 슬러그 충돌: 덮어쓰지 마십시오. 충돌을 보고하고 사용자에게 어떤 것을 유지할지 물어보십시오.
대상 메모리 저장소에 인덱스 파일이 있으면 설치된 메모리당 한 줄의 인덱스를 추가합니다(없으면 생성). 현재 에이전트가 직접 메모리 쓰기를 금지하는 경우 대신 승인된 메모리 업데이트 아티팩트를 생성하거나 제시합니다.

4. 보고

다음 순서로 사용자에게 제시합니다:

전체 ONBOARDING.md 내용 (설계상 짧습니다).
가져오기 요약: 설치됨 / 업데이트됨 / 폐기됨, 각각 한 줄의 이유.
마무리 메모: 기술 질문은 이제 가져온 메모리에 기반할 수 있습니다.

에지 케이스

상황	동작
내보내기 시 메모리 없음	문서 전용 패키지; 명시적으로 알림.
프로젝트가 git 리포지토리가 아님	`commit` 없는 매니페스트; 가져오기 검증은 존재 여부 확인만 수행.
내보내기 시 `handover/` 존재	덮어쓰기 전에 물어봄.
가져오기 시 `handover/` 없음	떠나는 동료를 위한 지침과 함께 중지.
가져오기 시 슬러그 충돌	절대 덮어쓰지 않음; 표시하고 물어봄.
알 수 없는 `manifest.version`	중지; 사용자에게 스킬 업데이트 요청.

knowledge-transfer