Add Framework

---
name: add-framework
description: Use when creating a new framework (module) in this project — 신규 프레임워크 신설의 엔드투엔드 절차. Tuist 매니페스트·Workspace 등록부터 스킴 하드코딩 동기화, child CLAUDE.md·rules paths 확인까지. Triggers on "프레임워크 추가하자", "새 모듈 만들자", "Scene 프레임워크 신설". Does NOT trigger on 기존 프레임워크에 파일 추가(add-file 스킬).
---

# Add Framework — 신규 프레임워크 신설

타겟·스킴은 tuist가 자동 생성하지만, **CI·스크립트의 스킴 목록은 전부 수동 하드코딩**이다. §3 체크리스트에서 하나라도 빠지면 신규 모듈 테스트가 CI에서 조용히 실행되지 않는다 (실사례: AIAgentScene 신설 때 run-tests 스킬 목록 누락).

## 1. 모듈 정의

- `<위치>/<Name>/Project.swift` — 팩토리 호출 (`Tuist/ProjectDescriptionHelpers/Project+Templates.swift`):
  - 테스트 있는 프레임워크: `Project.frameworkWithTest(name:destinations:iOSTargetVersion:dependencies:)` — 본체 + `<Name>Tests` 타겟 자동 생성, 테스트 의존성(UnitTestHelpKit·TestDoubles·Common3rdParty) 자동 주입 (Project.swift에 손으로 쓰지 않는다)
  - 테스트 없는 지원 모듈: `Project.framework(...)`
- `<위치>/<Name>/<Name>.h` — **모듈 루트에 헤더 파일 필수** (팩토리가 `Headers.headers(public:)`로 요구).
- `Sources/`, `Tests/` 디렉토리 생성. 테스트 배치는 testability §8.
- 의존성은 `.project(target:path: .relativeToRoot("<Layer>/<Module>"))` — 레포 루트 기준. **`.relativeToCurrentFile`은 쓰지 않는다** (#794): 직렬화된 매니페스트에 `#file` 절대경로가 `callerPath`로 실리는데, tuist의 전역 manifest 캐시 키에는 매니페스트 위치가 없어서 같은 레포의 다른 체크아웃(워크트리·self-hosted CI 러너)과 충돌하면 의존 경로가 남의 트리로 샌다. Presentation Scene 표준 세트: `Common3rdParty`·`CommonPresentation`·`Domain`·`Extensions`·`Scenes` (선례: `Presentations/AIAgentScene/Project.swift`).
- Service 프레임워크(Domain 프로토콜의 플랫폼·서드파티 SDK 결합 구현체): 위치 `Services/<Name>`, 네이밍 `XxxService`(여러 SDK를 묶는 성격이면 `XxxServices`), 의존 표준 세트 `Common3rdParty`·`Domain`·`Extensions` (선례: `Services/AuthService/Project.swift`). 분할 축은 의존 SDK 성격 — auth / MapKit(PlaceService) / AVFoundation(SpeechService) / 기타 1st party(FirstPartyServices) / 외부 서드파티(ExternalServices). 프로토콜은 Domain 잔류, 조립은 앱 타겟(ApplicationRootBuilder·Factories). 단일 소비자 SPM은 Common3rdParty가 아니라 해당 서비스가 `.external`로 직접 의존 (선례: ExternalServices ↔ SwiftLinkPreview).

## 2. 등록

- `Workspace.swift`의 `projects` 배열에 프로젝트 경로 추가 — **빠지면 tuist가 모듈을 인식하지 못한다.** 스킴은 `autogeneratedWorkspaceSchemes: .enabled()`로 자동 생성 (수동 .xcscheme 정의 불필요).
- `TodoCalendarApp/Project.swift`의 dependencies에 **기본으로 추가**하고 앱 타겟에서 임포트한다 — 앱이 의존해야 모듈이 앱 바이너리에 링크된다. 앱이 직접 안 쓰는 모듈(테스트 지원 등)만 예외.
- 다른 Presentation 모듈에서 참조할 Scene 프로토콜은 `Presentations/Scenes/Sources/Scenes+<Name>.swift`에 (presentations-rules §7).

## 3. 스킴 하드코딩 동기화 — 짝지어진 위치

새 스킴 이름을 아래 **전부**에 추가한다 (CLAUDE.md §1 '짝지어진 두 위치' 등재 항목):

- `.github/workflows/pr_test.yml` 3곳 — ① `ALL_SCHEMES` (+Presentation 모듈이면 `ALL_PRESENTATION`) ② detect-changes의 경로→스킴 매핑 블록 ③ test job의 `Test <Scheme>` 실행 step
- `scripts/run-all-tests.sh` — `ALL_SCHEMES` 배열
- `.claude/skills/implement/scripts/impact-check.sh` — `ALL_SCHEMES`/`ALL_PRESENTATION` 상수 + 경로→스킴 매핑 블록 + **이 프레임워크에 의존하는 상위 레이어(Domain 등) 블록에 새 스킴 파급 추가** + `impact-check.test.sh`의 배열·assertion 갱신
- `.claude/skills/run-tests/SKILL.md` — 스킴 목록과 개수 문구
- `CLAUDE.md` — §2 모듈 구조 (스킴 목록은 run-tests 스킬이 정본 — 위 항목이 커버)

## 4. 문서·rules

- **child CLAUDE.md** — 프레임워크 고유 규칙·도메인 맥락이 있으면 `<위치>/<Name>/CLAUDE.md` 작성 (선례: Domain·Repository·CalendarScenes·EventDetailScene·EventListScenes·MemberScenes·SettingScene).
- **rules paths 확인** — 새 모듈이 기존 rules의 paths 프리픽스(`Domain/**`·`Repository/**`·`Presentations/**`·`TodoCalendarApp/**`·`Supports/**`) 밖이면 해당 `.claude/rules/*.md` frontmatter에 경로를 추가해야 자동 로드된다.

## 5. 마무리 검증

- `mise exec -- tuist generate --no-open` 재실행 (`tuist install`은 SPM 의존성 변경 시에만).
- `bash .claude/skills/implement/scripts/impact-check.sh` — 새 모듈 경로가 새 스킴으로 매핑되는지 확인.
- 새 스킴 테스트 1회 실행: `./scripts/run-all-tests.sh <NewScheme>`.