API Learn

api-learn

프로젝트에서 사용하는 라이브러리/프레임워크의 공식 문서를 수집·정제하여 프로젝트 내부에 참조 문서로 저장합니다.

Workflow

Phase 0 — Apple 플랫폼 감지

수집 시작 전, 대상 라이브러리가 Apple 자체 프레임워크인지 판별합니다.

Apple 프레임워크 판별 기준:

• 라이브러리 이름이 Apple 공식 프레임워크와 일치 (SwiftUI, UIKit, AppKit, Foundation, SwiftData, MapKit, StoreKit, WebKit, WidgetKit, CoreData, CoreML, ARKit, RealityKit, HealthKit, CloudKit, GameKit, AVFoundation, CoreBluetooth, CoreLocation, AlarmKit, FoundationModels, AppIntents 등)
• 또는 프로젝트에 Package.swift, Podfile, *.xcodeproj, *.xcworkspace가 존재하여 Apple 프로젝트로 판별됨

결과에 따라:

• Apple 프레임워크 → Phase 1에서 Step 0 + Step 0.5를 추가 실행 후 기존 Step 1~3 진행
• Apple 프로젝트의 서드파티 라이브러리 → 기존 3단 전략, Step 3에서 Objective-C 패턴도 포함
• 비-Apple 프로젝트 → 기존 3단 전략 그대로

Phase 1 — 수집 (복합 전략)

인자로 받은 <library-name>에 대해 순차 실행:

Step 0: Xcode Documentation 조회 (Apple 프레임워크만)

Phase 0에서 Apple 프레임워크로 판별된 경우에만 실행합니다.

1. mcp__xcode__DocumentationSearch로 {library} 공식 문서 검색
2. 주요 타입, 프로토콜, 메서드의 시그니처와 설명 수집
3. Getting Started / Overview 문서가 있으면 함께 수집
4. Xcode MCP 미연결 시 건너뛰고 Step 0.5로 진행

Step 0.5: apple-craft 참조 문서 확인 (Apple 프레임워크만)

Phase 0에서 Apple 프레임워크로 판별된 경우에만 실행합니다.

1. Glob으로 **/apple-craft/skills/apple-craft/references/_index.md 검색
2. 발견 시 _index.md를 Read하여 대상 라이브러리 관련 참조 파일 확인
3. 관련 참조 있으면 Read하여 수집 데이터에 추가 (출처: apple-craft reference)
4. common-mistakes.md도 Read하여 해당 라이브러리 안티패턴 정보 수집
5. apple-craft 미설치(Glob 결과 없음) 시 조용히 건너뛰기

Step 1: context7 조회

1. resolve-library-id로 라이브러리 ID 해석
2. query-docs로 핵심 문서 조회 (topic: 주요 API별, tokens: 최대)
3. 조회 실패 시 건너뛰고 Step 2로 진행

Step 2: 웹 검색 보충

1. WebSearch로 "{library} official documentation site" 검색
2. 공식 문서 URL 식별 후 WebFetch로 다음 페이지 수집:
   • Getting Started / Quick Start
   • API Reference (핵심 API들)
   • Migration Guide (있는 경우)
   • Examples / Recipes
3. context7에서 이미 수집된 내용과 중복되는 부분은 제거

Step 3: 프로젝트 코드 분석

1. Grep으로 프로젝트 내 import/require 패턴 검색:
   • JavaScript/TypeScript: import.*from.*{library} 또는 require.*{library}
   • Swift: import {library}
   • Objective-C: #import <{library}/ 또는 @import {library}
   • Python: import {library} / from {library}
   • Kotlin/Java: import.*{library}
2. 사용 중인 API 목록 추출 (함수명, 클래스명, 훅 이름 등)
3. 사용 빈도 집계 — 빈도 높은 API에 더 상세한 문서 수집

Phase 2 — 정제·저장

수집된 원시 데이터를 아래 포맷의 단일 마크다운 파일로 정제합니다.

출력 파일: {project}/.claude/references/{library}.md

---
library: {library-name}
version: {detected-version}
collected: "{YYYY-MM-DD}"
sources:
  - xcode-docs  (Apple 프레임워크, DocumentationSearch 사용된 경우)
  - apple-craft-ref: "{참조파일명}"  (apple-craft 참조 사용된 경우)
  - context7  (사용된 경우)
  - web: "{공식문서URL}"  (사용된 경우)
  - code: {N} usages found  (사용된 경우)
---

# {Library Display Name}

## Overview
[라이브러리 소개: 목적, 핵심 컨셉, 언제 사용하는지]

## Core APIs
### {API 1}
**시그니처:**
[함수/클래스/훅 시그니처]

**파라미터:**
[각 파라미터 설명]

**반환값:**
[반환 타입 및 설명]

**예제:**
[공식 문서 예제 코드]

### {API 2}
[동일 구조 반복]

## Project Usage Patterns
프로젝트에서 실제 사용 중인 패턴:

[Grep으로 발견한 실제 사용 코드를 파일 경로와 함께 인용]

## Common Pitfalls & Migration Notes
[주의사항, 흔한 실수, 버전별 주요 변경점]

## Source URLs
- [각 출처 URL 나열]

수집 깊이: 포괄적 — 파일당 500~2000줄 목표. 공식 문서의 핵심 내용을 빠짐없이 포함.

버전 감지: 프로젝트 의존성 파일(package.json, Podfile, requirements.txt 등)에서 버전 추출. Apple 자체 프레임워크의 경우 최소 배포 타겟 또는 Xcode 버전을 기록 (예: "iOS 18+", "Xcode 26"). 감지 불가 시 "unknown"으로 기록.

_index.md 업데이트

.claude/references/_index.md가 없으면 새로 생성, 있으면 해당 라이브러리 행을 추가/갱신합니다:

---
project: {project-name from nearest package.json/Package.swift/etc or directory name}
scan_date: "{YYYY-MM-DD}"
doc_count: {총 문서 수}
---

# API References Index

| Library | Version | Collected | Lines | Sources |
|---------|---------|-----------|-------|---------|
| {library} | {version} | {date} | {lines} | {sources} |

Phase 3 — CLAUDE.md 등록

프로젝트 루트의 CLAUDE.md를 확인합니다:

1. CLAUDE.md가 없는 경우: 새로 생성하되 API References 블록만 포함
2. CLAUDE.md가 있고 API References 블록이 없는 경우: 파일 끝에 블록 추가
3. CLAUDE.md가 있고 API References 블록이 이미 있는 경우: 아무것도 하지 않음 (스킵)

추가할 블록:

## API References (.claude/references/)

아래 라이브러리 작업 시 해당 참조 문서를 학습 데이터보다 우선하세요.
목록: .claude/references/_index.md 참조

- 모르는 API → 참조 문서에서 먼저 검색
- 참조 문서와 학습 데이터 충돌 시 → 참조 문서 우선
- 참조 문서에 없는 경우 → context7 또는 웹 검색 폴백

갱신 모드

이미 .claude/references/{library}.md가 존재하는 경우:

• 사용자에게 "이미 내재화된 문서가 있습니다. 갱신하시겠습니까?" 확인
• 승인 시 기존 파일 덮어쓰기, _index.md 날짜/줄수 갱신
• CLAUDE.md 블록은 이미 있으므로 건드리지 않음

완료 보고

수집 완료 후 다음을 보고합니다:

• 저장 경로
• 수집 소스 (xcode-docs/apple-craft-ref/context7/web/code 중 어떤 것이 사용됐는지)
• 총 줄 수
• 감지된 프로젝트 사용 패턴 수
• CLAUDE.md 등록 여부