김종권의 iOS 앱 개발 알아가기

[AI] 1. Claude Code 병렬 처리로 효율 극대화하기 - git worktree 기본 개념

jake-kim — Sun, 5 Jul 2026 17:26:31 +0900

1. [AI] Claude Code 병렬 처리로 효율 극대화하기 - git worktree 기본 개념

2. [AI] Claude Code 병렬 처리로 효율 극대화하기 (claude --worktree)

3. [AI] Claude Code 병렬 처리로 효율 극대화하기 - tmux 활용하기

4. [AI] Claude Code 병렬 처리로 효율 극대화하기 - git worktree 기본 개념

5. Claude Code 병렬 처리로 효율 극대화하기 - cmux, worktree, omc 병렬 처리하기 (.omc/handoffs, .omc/shared_memory.json)

worktree가 왜 중요한가

Claude Code나 GitHub Copilot CLI 같은 터미널 기반 AI 도구를 쓸 때 아쉬운 점이 있음.
AI에게 무거운 리팩토링이나 테스트 코드 작성을 시켜두면, 작업이 끝날 때까지 해당 브랜치에서 키보드를 놓고 대기해야 함. 중간에 브랜치를 바꾸면 코드가 뒤엉키기 때문
이러한 컨텍스트 스위칭 비용과 병목 현상을 해결해 주는 Git 기능이 바로 git worktree
Claude Code를 병렬로 띄워두고 멀티태스킹을 하기 위한 핵심 전제 조건인 Git Worktree의 개념과 기본 사용법을 정리

1. Git Worktree란?

일반적인 git clone 환경에서는 단 하나의 작업 디렉토리(Working Directory)만 존재
git checkout으로 브랜치를 바꾸면 하나의 폴더 안에서 파일이 순간적으로 바뀌므로, 동시에 펼쳐놓고 작업할 수 있는 브랜치는 늘 단 1개뿐
반면, Git Worktree는 하나의 Git 저장소(.git)를 공유하면서, 서로 다른 브랜치를 바라보는 '물리적인 폴더'를 여러 개 생성하는 기능

개념 구분하기: worktree와 branch 차이?

기존 브랜치 방식: main에서 파일 코드를 10줄쯤 고치던 중, 급하게 bugfix 브랜치로 넘어가야 하면 그냥 바꿀 수 없음. Git이 "작업 중인 파일이 있으니 커밋하거나 stash(임시 저장)하라"고 에러를 뱉음. 하던 맥락을 끊고 git stash를 한 뒤 넘어가야 함.
Worktree 방식: 폴더 자체가 분리되어 있으므로 하던 작업을 저장하거나 커밋할 필요가 없음. main 폴더에 작업 중인 코드를 그대로 켜둔 채로, 그냥 옆 폴더(bugfix)로 이동해서 바로 코딩하면 됨.

2. 왜 Claude Code와 함께 쓸 때 강력할까?

프로젝트 구조가 물리적으로 분리되기 때문에 완벽한 격리가 가능함.

인간과 AI의 작업 분리: 폴더 A(main 브랜치)에서는 내가 원래 하던 피처 개발을 진행하고, 동시에 폴더 B(feature 브랜치)를 새로 만들어 Claude Code에게 "이 폴더 버그 좀 잡아줘"라고 던져놓을 수 있음.
의존성 격리: Claude가 코드를 대대적으로 수정하면서 발생하는 빌드 깨짐이나 임시 파일들이 내 작업 공간에 전혀 영향을 주지 않음.

3. Git Worktree 핵심 명령어

① 새로운 워크트리 생성

현재 프로젝트 폴더의 상위 경로에 새로운 폴더를 만들고, 새 브랜치를 연결하는 명령어.

# 사용법: git worktree add [생성할 폴더 경로] -b [새 브랜치명]
$ git worktree add ../my-app-claude -b feature-claude-task

Preparing worktree (new branch 'feature-claude-task')
HEAD is now at a1b2c3d Initial commit

현재 폴더 바로 바깥에 my-app-claude라는 물리적인 폴더가 실제로 생겨남.
해당 폴더로 이동(cd ../my-app-claude)해 보면 브랜치가 자동으로 feature-claude-task로 전환되어 있음.

② 워크트리 목록 확인

현재 저장소에 연결된 워크트리 경로와 브랜치 목록을 확인

$ git worktree list

/Users/developer/Desktop/my-app         a1b2c3d [main]
/Users/developer/Desktop/my-app-claude  a1b2c3d [feature-claude-task]

③ 워크트리 삭제

AI가 작업을 끝내고 원격 저장소에 푸시(Push)까지 완료했다면 워크트리를 삭제함. (반드시 원래 메인 프로젝트 폴더로 돌아와서 수행)

# 메인 폴더로 이동 후 삭제
$ cd ../my-app
$ git worktree remove ../my-app-claude

연결이 해제되면서 상위에 생성되었던 my-app-claude 폴더도 자동으로 삭제됨.
.git 저장소 자체는 공유하고 있었기 때문에, 옆 폴더에서 작업하고 커밋했던 내역은 메인 폴더의 git log에서도 그대로 조회됨.

요약

git worktree는 하나의 저장소를 공유하며 여러 브랜치를 독립된 폴더로 동시에 펼쳐놓는 기능임.
브랜치를 전환할 때 작업 내역을 stash하거나 기다릴 필요가 없음.
이 격리 공간을 활용하면 인간과 AI(Claude Code)가 서로의 컨텍스트를 깨뜨리지 않고 완벽한 병렬 작업을 수행할 수 있음.

다음 글에서는 Claude Code의 내장 명령어(claude --worktree)를 활용해 이 과정을 한 줄로 자동화하는 방법을 알아볼 예정

[iOS - swift] 5. 애플페이 (Apply Pay) - PassKit을 사용하여 구현하기 (Green, Yellow, Orange 플로우)

jake-kim — Mon, 29 Jun 2026 00:34:45 +0900

Green, Yellow, Orange 플로우

흐름 (Flow)	진입 경로	리스크 수준	인증 절차	최종 상태
Green-Flow	발급사 인앱 (In-App)	Low	앱 로그인으로 대체	즉시 활성화
Yellow-Flow	Apple 월렛 직접 입력	Medium	발급사 앱 인증 / SMS / ARS	인증 후 활성화
Orange-Flow	의심 기기 / 분실 카드	High	없음 (거절 또는 강제 차단)	등록 실패

애플페이 (Issuer App 입장)의 기능

발급사(Issuer) 앱 관점에서 애플페이 대응을 할 때 핵심이 되는 개념은 크게 In-App Provisioning과 Verification 두 가지로 나뉨.

1) In-App Provisioning (인앱 프로비저닝)

개념: 사용자가 우리 앱 내부에서 "애플 월렛에 추가" 버튼을 눌렀을 때, 안전하게 카드 정보를 암호화하여 Apple Wallet에 카드를 밀어 넣어주는(발급하는) 기능
특징:
- 앱 내부에서 PKAddPaymentPassViewController라는 Apple 표준 시트를 띄워 처리하므로 화면 이탈 없이 매끄러운 UX를 제공. (Green-Flow)
- 앱이 카드 번호(PAN) 원장을 가공되지 않은 상태로 다루지 않고, 기기가 생성한 일회성 토큰(Nonce)을 기반으로 발급사 백엔드와 TSP(Visa, Mastercard 등)를 거쳐 암호화된 페이로드 형태로 Apple 서버에 패스스루(Pass-through)하는 구조.

2) Verification (신원 확인 및 인증)

개념: 반대로 사용자가 애플 월렛 앱 안에서 직접 카드를 추가하려고 할 때, "이 사람이 진짜 실소유주가 맞는지 확인해라"라며 월렛이 발급사 앱을 깨워 본인 인증을 요구하는 기능. (Yellow-Flow)
특징:
- Step-up Authentication이라고도 부르며, 유니버설 링크(Universal Link)를 통해 월렛 앱에서 우리 앱으로 사용자를 전환시킴.
- 우리 앱이 켜지면 Face ID나 간편비밀번호 등으로 본인 확인을 수행한 뒤, 발급사 백엔드를 통해 TSP에 "인증 완료" 신호를 쏘고 다시 shoebox:// 스킴을 통해 사용자를 월렛으로 안전하게 돌려보내 줌.

PassKit을 사용하여 구현하기

Step 0. 권한 설정

1) PKPassLibrary: 애플월렛관련 데이터를 가져오기 위한 라이브러리이고 애플 개발자 페이지의 capability에서 Wallet 활성화해야함
2) 애플 in-app provisioining 권한
- PKAddPaymentPassViewController를 사용하려면 애플 개발자 페이지 -> Capability -> In-App Provisioning 권한이 필요
- Xcode에서도 entitlements 파일에 아래 설정도 필요

// {your_app}.entitlements

<dict>
    <key>com.apple.developer.passkit.in-app-provisioning</key>
    <true/>
</dict>

Step 1. 권한 확인 및 Configuration 설정

가장 먼저 현재 디바이스가 카드 등록을 지원하는지 체크하고, 카드 소유자 이름 및 뒤 4자리 정보를 담은 설정을 빌드

*주의) PKAddPaymentPassViewController를 사용하려면 애플 개발자 페이지 -> Capability -> In-App Provisioning 권한이 필요

import PassKit

func startInAppProvisioning() {
    // 1. 디바이스가 인앱 프로비저닝을 지원하는지 체크
    guard PKAddPaymentPassViewController.canAddPaymentPass() else {
        print("이 디바이스는 카드 추가를 지원하지 않거나 제한된 계정임")
        return
    }
    
    // 2. 발급할 카드의 메타데이터 구성 (암호화 스킴은 보통 ECC_V2 또는 RSA_V2 사용)
    guard let configuration = PKAddPaymentPassRequestConfiguration(encryptionScheme: .ECC_V2) else {
        return
    }
    
    configuration.cardholderName = "홍길동"
    configuration.primaryAccountSuffix = "1234" // 카드 뒷 4자리
    configuration.localizedDescription = "내 발급사 대표 카드"
    
    // 3. VC 생성 및 델리게이트 위임
    guard let addPaymentPassVC = PKAddPaymentPassViewController(requestConfiguration: configuration, delegate: self) else {
        print("컨트롤러 생성 실패 - Entitlement 권한 확인 필요")
        return
    }
    
    // 4. Apple 표준 카드 등록 시트 모달 표시
    self.present(addPaymentPassVC, animated: true, completion: nil)
}

Step 2. PKAddPaymentPassViewControllerDelegate 구현

시트가 뜨면 Apple 서버-발급사 서버 간 암호화 핸드셰이크가 일어남. 이 구간이 구현의 핵심

extension CardManagementViewController: PKAddPaymentPassViewControllerDelegate {
    
    // Apple 이 인증서 체인과 Nonce 를 넘겨주며 암호화 데이터를 요청하는 메서드
    func addPaymentPassViewController(_ controller: PKAddPaymentPassViewController,
                                      generateRequestWithCertificateChain certificates: [Data],
                                      nonce: Data,
                                      nonceSignature: Data,
                                      completionHandler: @escaping (PKAddPaymentPassRequest) -> Void) {
        
        // 1. 수신한 certificates, nonce, nonceSignature 를 우리 백엔드 API 로 전송
        let requestModel = IssuerAmhohwaRequest(
            certificates: certificates,
            nonce: nonce,
            nonceSignature: nonceSignature
        )
        
        // 2. 백엔드 통신 (백엔드는 TSP 와 연동하여 암호화된 데이터를 내려줌)
        NetworkManager.shared.requestEncryptedPayload(requestModel) { result in
            switch result {
            case .success(let response):
                // 3. 백엔드가 준 데이터를 암호화 요청 객체에 매핑
                let addPassRequest = PKAddPaymentPassRequest()
                addPassRequest.encryptedPassData = response.encryptedPassData
                addPassRequest.activationData = response.activationData
                addPassRequest.ephemeralPublicKey = response.ephemeralPublicKey
                
                // 4. 완성된 request 를 completionHandler 에 담아 Apple SDK 에 반환
                completionHandler(addPassRequest)
                
            case .failure:
                // 에러 발생 시 빈 객체를 던져 실패 처리
                completionHandler(PKAddPaymentPassRequest())
            }
        }
    }
    
    // 프로세스가 완전히 끝났을 때 (성공 혹은 취소/실패) 호출되는 메서드
    func addPaymentPassViewController(_ controller: PKAddPaymentPassViewController,
                                      didFinishWith pass: PKPaymentPass?,
                                      error: Error?) {
        // 우선 띄웠던 모달을 닫아줌
        controller.dismiss(animated: true) {
            if let error = error {
                print("카드 등록 실패 혹은 유저 취소 발생: \(error.localizedDescription)")
                return
            }
            
            if let successfullyAddedPass = pass {
                print("카드 등록 최종 성공: \(successfullyAddedPass.primaryAccountNumberSuffix)")
                // UI 상의 '애플 월렛에 추가' 버튼을 숨기거나 완료 상태로 전환하는 비즈니스 로직 수행
            }
        }
    }
}

[iOS] 4. 애플페이 (Apply Pay) - 애플월렛과 앱에서 카드등록 개념

jake-kim — Wed, 17 Jun 2026 01:35:36 +0900

애플페이 관련 목차

전체 목차 링크

대응해야하는 영역

내앱에서 애플페이 결제는 지원하지 않고, 내앱에 있는 카드 정보를 애플월렛에 등록하여 애플월렛에서 결제하게끔 도와주는 방법을 대상으로 설명 예정 (Issuer App 관점)

1. 진입점이 애플월렛: 애플월렛 -> 내앱(Issuer App) -> 애플월렛

사용자가 애플월렛 앱에서 직접 카드를 추가(실물 카드 카메라 스캔 또는 번호 직접 입력)하는 도중, "이 사람이 진짜 카드 주인이 맞는지 발급사 앱에서 인증해라"라고 요청받아 넘어오는 플로우

핵심 메커니즘: 유니버설 링크를 통한 신원 확인 (Step-up Authentication)
흐름:
1. 애플월렛이 발급사의 유니버설 링크를 호출하여 발급사 앱을 강제로 깨움.
2. 발급사 앱이 켜지면서 URL에 담긴 토큰 정보를 파싱하고, 사용자에게 Face ID 또는 간편비밀번호 인증을 요구.
3. 인증이 성공하면 발급사 백엔드가 TSP(카드 브랜드사)에 "인증 완료" 신호를 보냄.
4. 앱이 shoebox:// 스킴을 호출하여 사용자를 다시 애플월렛으로 돌려보냄.
  * shoebox 앱스킴: Apple Wallet(애플월렛) 앱을 호출하기 위해 Apple이 전 세계 모든 개발사에게 공식적으로 지정해 둔 실제 프로덕션용 URL 스킴
특징: 앱과 앱 사이를 전환(애플월렛 ➔ 발급사 앱 ➔ 애플월렛)하며 흐름이 이어짐

2. 진입점이 내앱: 내앱(Issuer App) -> 애플월렛

발급사 앱 안에서 사용자가 "애플 월렛에 추가" 버튼을 눌러 카드를 등록
핵심 메커니즘: 암호화 데이터 토싱 (Pass-Through)
흐름
- 1. 앱에서 Apple 표준 등록 시트(PKAddPaymentPassViewController)를 띄움.
- 2. 기기가 생성한 일회성 암호화 키(Nonce)를 발급사 앱이 받아서 발급사 백엔드로 전달.
- 3. 백엔드가 카드 정보와 Nonce를 결합해 암호화된 페이로드(Payload)를 만들어 앱으로 반환.
- 4. 앱이 이 페이로드를 그대로 Apple 서버에 제출하면 카드 등록 완료.
특징: 화면 전환 없이 발급사 앱 안에서 모달 시트 형태로 매끄럽게 종료

두 방식의 차이

가장 큰 차이는 카드 정보(원장)의 출발지와 UI 주도권이 누구에게 있느냐

비교 항목	내 앱에서 시작 (Green-Flow)	애플월렛에서 시작 (Yellow-Flow)
주도권 (시작점)	Issuer App (발급사 앱)	Apple Wallet (애플월렛 앱)
카드 정보 입력	필요 없음 (앱 내부 카드 목록에서 선택)	필요함 (사용자가 직접 입력 또는 카메라 스캔)
핵심 기술 요소	PassKit 프레임워크 델리게이트 구현	Universal Link 및 URL Scheme (shoebox://)
보안 작업의 본질	안전하게 카드 정보를 암호화하여 Apple에 전달	사용자가 본인이 맞는지 생체인증 등으로 검증
화면 경험 (UX)	발급사 앱 내부에서 모달 창으로 해결	앱 간의 유기적인 스위칭 (App-to-App)

[iOS - swift] 애플페이 목차

jake-kim — Wed, 10 Jun 2026 01:29:29 +0900

3. 애플페이 (Apply Pay) - Xcode에 적용하기

4. 애플페이 (Apply Pay) - 애플월렛과 앱에서 카드등록 개념

5. 애플페이 (Apply Pay) - PassKit을 사용하여 구현하기

[iOS] 3. 애플페이 (Apply Pay) - Xcode에 적용하기

jake-kim — Wed, 10 Jun 2026 01:16:36 +0900

애플페이 관련 목차

전체 목차 링크

Xcode에 적용하기

Xcode > Project > Signing & Capabilities
- + Capability를 클릭

Apply Pay 검색

검색했을때 아무것도 안뜬다면, 애플 개발자 페이지에서 애플페이를 추가해줘야함
- 단 애플 개발자 구독 플랜이 되어있어야함 (연간 99$ 애플 구독)

애플 개발자 페이지에서 애플페이 활성화하기

Apple Developer 웹사이트 로그인: Apple Developer 계정 페이지에 로그인한 뒤, Certificates, Identifiers & Profiles 메뉴로 이동

Identifiers에서 앱 선택: 왼쪽 메뉴의 Identifiers를 누르고, 현재 작업 중인 프로젝트의 Bundle ID를 찾아 클릭
Apple Pay 기능 활성화: Capabilities 리스트 중에서 Apple Pay Payment Processing 항목을 찾아 체크박스를 선택(Enable)하고 Save를 눌러 저장

다시 XCode > Capability 눌러서 시도하면 Apple Pay가 보이는 것을 확인 가능

https://apnspush.com/integrate-apple-pay-into-ios-app

그럼 아래처럼 Merchant ID 입력 화면이 등장
- Merchant ID는 이전 글 참고 (단, 애플월렛에 단순히 카드등록만 하는 경우는 "Issuer App"이라 하며 Merchant ID는 필요없음.)

입력 시 아래처럼 merchant id들이 추가됨

이제 apple pay를 만들 준비가 끝났고, 다음 글에서 PassKit을 사용하여 애플페이 구현을 계속 수행

* 참고

- https://apnspush.com/integrate-apple-pay-into-ios-app

[iOS] 2. 애플페이 (Apply Pay) - 사전 설정 2단계 (앱 외적인 세팅)

jake-kim — Wed, 27 May 2026 01:08:49 +0900

애플페이 관련 목차

전체 목차 링크

사전 설정

Apple Pay 결제 데이터의 암호화 키체인을 구성

1단계) Merchant id 만들기

Merchant id (판매자 식별자)
- Merchant id는 Apple Pay에서 결제를 받을 수 있는 판매자임을 고유하게 식별하는 데 사용
- 판매자 식별자는 만료되지 않으며 여러 앱에서 동일한 식별자를 사용할 수 있음

인증서, 식별자 및 프로필 에서사이드바에서 '식별자'를 클릭한 다음 왼쪽 상단의 추가 버튼(+)을 클릭
판매자 ID를 선택한 다음 계속을 클릭
판매자 설명과 식별자 이름을 입력한 다음 계속을 클릭
설정을 검토한 후 등록을 클릭

2단계) payment processing certificate 만들기

payment processing certificate (결제 처리 인증서)
- 결제 처리 인증서는 판매자 식별자와 연결되어 있으며 결제 정보를 암호화하는 데 사용
- 결제 처리 인증서는 25개월마다 만료
- 인증서가 취소된 경우 재발급받을 수 있음

인증서, 식별자 및 프로필 에서 사이드바에서 '식별자'를 클릭
식별자 항목에서 오른쪽 상단의 필터를 사용하여 판매자 ID를 선택
오른쪽 에서 판매자 식별자를 선택
참고: 페이지 상단에 이용약관에 동의해야 한다는 배너가 표시되면 '이용약관 검토' 버튼을 클릭하고 안내에 따라 진행
Apple Pay 결제 처리 인증서 아래에서 인증서 생성을 클릭
Mac에서 인증서 서명 요청을 생성한 다음 계속을 클릭.
파일 선택을 클릭
나타나는 대화 상자에서 인증서 요청 파일(파일 확장자가 있는 파일 .certSigningRequest)을 선택한 다음 [선택]을 클릭
계속을 클릭
다운로드를 클릭
인증서 파일(파일 확장자가 있는 파일 .cer)이 Downloads폴더에 나타남

* 참고

- https://developer.apple.com/documentation/passkit/apple-pay

- https://developer.apple.com/help/account/capabilities/configure-apple-pay#create-a-merchant-identifier

- https://developer.apple.com/kr/apple-pay/implementation/

- https://developer.apple.com/documentation/passkit/setting-up-apple-pay

[iOS] 1. 애플페이 (Apply Pay) - 처리해야하는 전체 플로우

jake-kim — Wed, 20 May 2026 01:15:54 +0900

애플페이 관련 목차

전체 목차 링크

애플페이을 준비하는 앱 개념

Issuer App vs Merchant App
- Issuer App: 단순히 특정 A앱에서 카드들을 애플월렛에 등록하는 역할 (provisioning 이라고 함)
- Merchant App: A앱에서 애플페이를 이용한 결제기능을 제공하는 역할
중요한 것
- Issuer App은 Apple Develop페이지에서 Pass Type ID 등록만하면 됨
- Merchant App은 Apple Develop페이지에서 Merchant ID 등록, CSR 업로드, App ID 등록을 해줘야함 (아래에서 소개 예정)

처리해야하는 전체 플로우

1단계: Apple Developer 인프라 설정

Apple Pay 결제 데이터의 암호화 키체인을 구성하는 단계

Merchant ID (판매자 식별자) 생성: 우리 앱이 Apple Pay 시스템에서 결제를 요청할 수 있는 고유한 상점 ID(merchant.com.domain...)를 등록하는 과정
Payment Processing Certificate (결제 처리 인증서) 생성: 사용자가 페이스 ID 등으로 인증하면 Apple 서버는 결제 정보를 암호화. 이때 암호화에 사용되는 공개키(Public Key)를 Apple에 등록하고, 이를 복호화할 수 있는 개인키(Private Key) 쌍을 만드는 과정

2단계: 결제 대행사(PG) 연동 및 환경 설정

Apple Pay 결제 데이터를 복호화하고 실제 원화(KRW) 결제 승인을 처리할 PG사 연동 단계

PG사 선정 및 계약: 토스페이먼츠, 포트원, NHN KCP, KG이니시스 등 Apple Pay 지원 국내 PG사 선택 및 가맹 계약 진행
인증서 업로드: 1단계에서 생성한 Payment Processing Certificate(.cer 파일)를 PG사 상점 관리자 콘솔에 등록
등록 이유: Apple 서버가 암호화하여 앱으로 전송한 결제 데이터(Token)를 PG사가 복호화할 수 있도록 권한을 위임하는 작업

3단계: Xcode 프로젝트 개발 환경 설정

생성한 Merchant ID를 Xcode 프로젝트와 동기화하여 앱에 Apple Pay 권한을 부여하는 단계

Apple Pay Capability 추가: Xcode 프로젝트의 Signing & Capabilities 탭에서 + Capability 버튼을 통해 Apple Pay 기능 추가
Merchant ID 매핑: 추가된 Apple Pay 섹션의 새로고침( ) 버튼을 클릭하여 생성해 둔 ID를 동기화하고 해당 체크박스 선택
- 완료 시 프로젝트 내 [프로젝트명].entitlements 파일이 자동 생성/업데이트되며 Apple Pay 권한이 명시됨

4단계: 앱 내 결제 로직 구현 (코드 작성)

사용자 결제 버튼 클릭부터 Apple Pay 시트 인증 및 최종 결제 완료까지의 클라이언트 코드 구현 단계 (PassKit 프레임워크 활용)

PG사 iOS SDK 설치: SPM 또는 CocoaPods를 통해 선택한 PG사의 최신 iOS SDK를 프로젝트에 추가
Apple Pay 전용 버튼 배치: Apple 디자인 가이드라인을 준수하는 내장 이니셜라이저 기반의 PKPaymentButton을 UI에 배치
결제 요청서(PKPaymentRequest) 정의: Merchant ID, 국가 코드(KR), 통화 코드(KRW), 지원 카드 브랜드 목록 지정 및 결제 금액 목록(PKPaymentSummaryItem) 구성 (배열의 마지막 아이템이 최종 결제 총액)
결제 시트 표시 및 델리게이트 구현: PKPaymentAuthorizationController를 통해 화면 하단에 Apple Pay 결제 시트 노출 및 사용자 인증 처리
토큰 추출 및 PG사 전달: didAuthorizePayment 콜백 메서드로 전달된 PKPayment 객체에서 암호화된 결제 데이터(payment.token.paymentData)를 추출하여 PG사 결제 승인 API로 전송
결제 결과 처리: PG사 서버의 최종 결제 승인 결과에 따라 Apple Pay 시트에 성공/실패 애니메이션을 표시하고 시트 종료(dismiss)

* 참고

- https://developer.apple.com/documentation/passkit/apple-pay

- https://developer.apple.com/help/account/capabilities/configure-apple-pay#create-a-merchant-identifier

- https://developer.apple.com/kr/apple-pay/implementation/

- https://developer.apple.com/documentation/passkit/setting-up-apple-pay

[AI] 클로드코드 사용 종류 (인증 방식, session key, API Key, Amazon Bedrock)

jake-kim — Wed, 13 May 2026 01:57:54 +0900

클로드코드 사용 종류

클로드코드를 사용할때 클로드코드에 비용을 지불하고 사용하는데 여러가지 방법이 있음
- session key - 개인이 가장 많이 사용 (구독해서 사용하는 것. 구체적인 건 아래에서 계속 설명)
- API key
- Amazon Bedrock

session key 방식

session key: 넷플릭스나 유튜브 프리미엄을 구독해서 쓰는 것과 비슷하게 claude auth login을 치고 웹브라우저에서 로그인
- 웹 세션 기반으로 로그인 유지 개념으로 사용하는 것
- 구독하여 사용하는 것이 session key 방식: ex) 월 $20 (Pro 구독)
클로드코드 설치하여 session key 방식 준비

curl -fsSL https://claude.ai/install.sh | bash

아래 명령어를 통해 웹사이트에 로그인 및 구독 플랜을 선택한 후 결제

claude auth login

잘 연결 되었는지 확인

claude auth status

API key 방식

Anthropic이 발행해준 고유한 문자열 코드를 사용하는 것
Anthropic Console에서 키를 생성하여 Claude Code에 claude auth apikey <내-키>를 입력해 등록
쓴만큼 결제하는 방식

Amazon Bedrock

클로드코드에 바로 접근해서 쓰는게 아니라, aws를 통해 사용하는방법
Bedrock은 Converse API가 아니라 Invoke API 경로를 사용
- => 표준화된 공통 문(Converse)이 아니라, Claude 모델 전용 문(Invoke)으로 직접 들어가서 대화
- 데이터 형식을 더 꼼꼼히 맞춰줘야 하지만, 모델이 가진 원래의 성능이나 특수한 기능을 더 정확하게 끌어낼 수 있다는 장점이 있음

ex) 각 모델마다 아래처럼 사용 방식이 다른데, Amazon Bedrock을 쓰면 aws에서 내부적으로 세팅하여, 사용자는 따로 신경쓰지 않아도됨

Claude (Anthropic 방식)

클로드에게 보낼 때는 messages라는 항목 안에 role과 content를 명확히 나누는 것을 선호

{
  "model": "claude-3-5-sonnet",
  "messages": [
    {"role": "user", "content": "안녕?"}
  ],
  "max_tokens": 1024
}

Llama 2 (기존 Meta/Invoke 방식)

어떤 모델들은 아예 복잡한 구분 없이 특정 기호([INST], <<SYS>>)를 섞은 긴 문장 하나로 보내달라고 요구

{
  "prompt": "[INST] 안녕? [/INST]",
  "temperature": 0.5
}

Titan (Amazon 방식)

아마존 자체 모델은 또 입력 텍스트를 inputText라는 이름의 상자에 담으라고 요구

{
  "inputText": "안녕?",
  "textGenerationConfig": { "maxTokenCount": 512 }
}

3가지 방법 비교

구분	Session Key (세션)	Anthropic API Key (직접)	Amazon Bedrock (클라우드)
핵심 개념	웹사이트 로그인 상태 공유	개발자 전용 '출입증' 발급	AWS 인프라 내 모델 호출
비용 체계	월 $20 (Pro 구독)	종량제 (쓴 만큼 결제)	종량제 (AWS 통합 청구)
설정 난이도	매우 쉬움 (로그인 방식)	쉬움 (키 복사/붙여넣기)	복잡 (IAM, 권한, 리전 설정)
안정성	보통 (주기적 재로그인 필요)	매우 높음 (키 만료 없음)	매우 높음 (기업용 인프라)
장점	추가 비용 없이 구독 혜택 활용	자동화/봇 운영에 최적화	최고 수준의 보안, AWS 크레딧 활용
단점	질문 횟수 제한(Quota) 공유	비용 관리 주의 (요금 폭탄 가능성)	Claude Code 직접 연동 불가 (MCP 필요)

* 참고

- https://aws.amazon.com/ko/blogs/tech/bedrock-with-claude-code/

- https://wikidocs.net/329810

[AI] claude code - hook, btw 명령어 (클로드코드 훅, by the way)

jake-kim — Wed, 6 May 2026 01:52:21 +0900

btw 명령어

btw는 by the way의 줄임말 ("그나저나")
- 메인 작업 흐름을 중단하거나 대화 기록(Context)을 오염시키지 않고, 샛길 질문(Side Question)을 빠르게 던질 수 있는 번들 스킬

ex) 게시판 웹 구현해달라고 할때, 도중에 클로드코드가 어떤 언어로 구현하는지 궁금한 경우, /btw로 물어볼 수 있음

게시판 웹 구현해달라고 클로드코드한테 작업 시킴

게시판을 구현하고 있는 도중에 어떤 언어로 구현중인지 물어봄

작업 도중에 토큰을 얼마나 쓸지도 물어볼 수 있음

Hook 기능

Hook은 Claude Code의 실행중에, 특정 이벤트가 발생하였을때 사용자가 정해 지정해놓은 Shell Command나, HTTP 요청 또는 프롬프트를 실행할 수 있는 기능
주요 Hook들
- Pre-execution Hooks: 클로드가 코드를 생성하거나 수정하기 직전에 실행 (예: 최신 API 문서 불러오기)
- Post-execution Hooks: 클로드가 작업을 마친 직후 실행 (예: 린트(Lint) 체크, 빌드 테스트)
- Context Hooks: 특정 파일이나 디렉토리에 접근할 때 자동으로 맥락 정보를 제공하도록 설정

ex)

일반적으로 프로젝트 루트에 있는 .claude/config.json 또는 클로드 전용 설정 파일 내에 훅을 정의

pre-apply: 클로드가 수정 사항을 파일에 적용하기 전에 실행할 명령어
post-apply: 수정 사항이 적용된 후 정상 작동 여부를 확인하기 위한 명령어
on-error: 작업 중 오류가 발생했을 때 진단을 위해 실행할 명령어

{
  "hooks": {
    "pre-apply": "npm run lint",
    "post-apply": "npm test",
    "on-error": "tail -n 20 error.log"
  }
}

또 다른 활용 케에스

-	설명
자동 테스트	클로드가 코드를 고친 후 자동으로 jest나 pytest를 돌려 회귀 버그를 방지
포맷팅 강제	수정한 코드가 프로젝트의 Prettier나 ESLint 규칙을 준수하도록 자동 교정
의존성 체크	package.json이 변경되면 자동으로 npm install을 수행하도록 설정
문서 동기화	코드가 변경될 때마다 관련 사양서(Swagger 등)를 최신화하는 스크립트를 연결

아래와 같은 Hook 타이밍이 있음
- (참고: https://code.claude.com/docs/en/hooks)

https://code.claude.com/docs/en/hooks

Event	When it fires (발생 시점)
SessionStart	Session이 시작되거나 재개될 때
UserPromptSubmit	프롬프트를 제출했고, Claude가 처리하기 전
PreToolUse	Tool 호출이 실행되기 전. (호출을 차단할 수 있음)
PermissionRequest	Permission 대화 상자가 나타날 때
PostToolUse	Tool 호출이 성공한 후
PostToolUseFailure	Tool 호출이 실패한 후
Notification	Claude Code가 알림을 보낼 때
SubagentStart	Subagent가 생성될 때
SubagentStop	Subagent가 완료될 때
Stop	Claude가 응답을 마쳤을 때
TeammateIdle	Agent team 동료가 유휴 상태가 되기 직전
TaskCompleted	Task가 완료로 표시될 때
InstructionsLoaded	CLAUDE.md 또는 .claude/rules/*.md 파일이 context에 로드될 때. Session 시작 시 및 Session 중 파일이 지연 로드될 때 발생
ConfigChange	Session 중 Configuration 파일이 변경될 때
WorktreeCreate	--worktree 또는 isolation: "worktree"를 통해 worktree가 생성될 때. 기본 git 동작을 대체함
WorktreeRemove	Session 종료 시 또는 Subagent가 완료될 때 worktree가 제거될 때
PreCompact	Context compaction 전
SessionEnd	Session이 종료될 때

* 참고

- https://code.claude.com/docs/en/hooks

- https://www.reddit.com/r/ClaudeCode/comments/1rqlry4/have_you_tried_the_new_btw_command/?tl=ko#:~:text=BTW%EB%8A%94%20subagent%EB%9E%91%20%EB%B0%98%EB%8C%80/%EC%97%AD%ED%95%A0%EC%9D%84%20%ED%95%98%EB%8A%94%20%EB%8B%A4%EB%A5%B8%20%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8%EC%9D%B8%EB%8D%B0%2C%20%ED%98%84%EC%9E%AC,%EB%A7%90%ED%95%9C%20%EA%B2%83%EC%B2%98%EB%9F%BC%2C%20%ED%9B%84%EC%86%8D%20%EC%A7%88%EB%AC%B8%20%EA%B0%99%EC%9D%80%20%EA%B1%B4%20%EC%97%86%EC%96%B4.

[AI] 클로드코드 claude opus 4.7 내용 (claude-opus-4.7)

jake-kim — Wed, 29 Apr 2026 01:25:00 +0900

1. 고해상도 이미지 지원 (Vision 성능 강화)

그동안 Claude 모델의 이미지 해상도 제한 때문에 문서나 스크린샷 분석 시 아쉬운 점이 있었는데, 이번 4.7 버전에서 해상도가 크게 개선

해상도 증가: 기존 1568px(1.15MP) → 최대 2576px(3.75MP)로 향상
1:1 픽셀 매핑: 모델의 좌표 시스템이 실제 픽셀과 1:1로 대응되어, 별도의 스케일 팩터 계산 없이도 정확한 좌표 추출이 가능해짐
활용: 복잡한 UI 스크린샷 분석, 아티팩트 이해, 이미지 내 텍스트 및 사물 감지(Localization) 성능이 강화됨

2. 새로운 'xhigh' Effort Level 도입

기존에는 low, medium, high, max 등의 단계가 있었는데, xhigh는 high보다는 똑똑하고 max보다는 빠른 것

Low/Medium: 단순 요약, 번역, 가벼운 질의응답
High: 일반적인 코딩 지원, 복잡한 지시사항 이행
xhigh (신규): 에이전트 기반 작업(Agentic workflows), 복합적인 버그 수정, 멀티 스텝 도구 사용
Max: 수학적 증명, 논문 수준의 고도의 추론 (시간이 가장 오래 걸림)

참고: Claude Code에서는 이미 모든 플랜의 기본 설정이 xhigh로 상향

3. 코딩 및 에이전트 성능 (State-of-the-Art)

SW-bench 72.5%: 복잡하고 긴 작업에서도 집중력을 잃지 않고 수천 단계의 과정을 지속적으로 수행할 수 있음
자기 수정(Self-correction): 코드를 짜다가 스스로 실수를 발견하고 수정하는 능력이 좋아져, 시니어 개발자가 난이도 높은 작업을 믿고 맡길 수 있는 수준(Confidently delegate)까지 올라옴
메모리 기능: 로컬 파일 액세스 권한을 주었을 때, '메모리 파일'을 직접 생성하고 유지하며 정보를 저장하는 능력이 매우 뛰어남

4. 가격 및 사용 방법

가격: 기존 Opus 4.6과 동일 (Input $5/1M, Output $25/1M)
플랫폼: Claude Pro, Team, Enterprise 요금제 사용자는 바로 사용 가능하며, API와 Amazon Bedrock, Google Vertex AI에서도 지원
모델명: claude-opus-4-7

* 참고

- https://www.anthropic.com/news/claude-opus-4-7

[AI] 클로드코드 서브 에이전트 사용 방법 (SubAgent, agents, ClaudeCode, 병렬 처리)

jake-kim — Wed, 22 Apr 2026 23:51:24 +0900

서브 에이전트란?

특정 작업 유형을 처리하기위해 클로드코드에서 사용할 수 있는 AI 어시스턴트
자주 쓰이는 툴이나, 프롬프트에 사용
- ex) 코드 리뷰, 성능 병목 지점 탐색, 단위 테스트 누락 확인

서브 에이전트가 필요한 이유

에이전트 없이 하나로만 AI를 사용한다면 context가 오염됨 (토큰 효율성 하락)
비슷한 작업에 관한 재사용에 용이
아래와 같이 병렬 작업이 가능

ex. 병렬작업 (https://tech.hyperithm.com/claude_code_guides_2)

에이전트 만드는 방법

(vscode 사용하여 설명)

클로드코드 > /agents 입력 후 엔터

terminal에서 사용할수 있기에 1번 선택된 상태로 엔터

기다리면 자동으로 터미널 명령어 창에 claude /agents가 입력됨

oh-my-claudecode를 사용하고 있어서 여러개가 나오는데, 새로 만들어볼 것이므로 선택되어 있는 Create new agent 선택 후 엔터
- oh-my-claudecode는 이전 포스팅 글 참고

설치 위치 선택 (자율이지만 간단히 보기 위해 1. Project 선택
- Project: 해당 프로젝트에만 반영
- Personal: 전역적으로 사용할 수 있도록 반영

1번 클로드코드로 생성 선택

설명을 입력
- 예시) "코드를 분석하여 사람이 이해할 수 있도록 쉽게 자연어로 알려주는 분석 에이전트"

툴 입력
- 사실상 에이전트에게 부여할 권한에 해당
- Read-only tools (읽기 전용 도구): 파일 내용을 읽거나 데이터를 조회하는 기능. 시스템을 변경하지 않고 정보를 가져오기만 하므로 안전
- Edit tools (편집 도구): 파일을 수정, 삭제하거나 코드를 변경하는 기능. 에이전트가 직접 결과물을 만들어내야 할 때 필수
- Execution tools (실행 도구): 작성한 코드를 실제로 실행하거나 터미널 명령어를 입력하는 기능. 프로그램의 동작 여부를 확인할 때 사용
- MCP tools (Model Context Protocol): 다양한 외부 서비스나 데이터베이스를 표준화된 방식으로 연결해주는 도구. (예: Google Drive, Slack, GitHub 연동 등)
- Other tools (기타 도구): 위 분류에 속하지 않는 웹 검색이나 특정 API 호출 기능 등이 포함

(편의상 선택되어 있는 All tools을 적용하여 Continue에 커서를 대고 엔터)

모델 선택 (디폴트 Sonnet)

에이전트가 사용할 색 선택

최종 리뷰 -> Enter 누르면 완성

최종 Agents목록에서 위에서 만든 "code-explainer" 생성된 것을 볼 수 있음

에이전트 사용 방법

클로드 챗에 골뱅이를 붙이고 이름을 입력하면 리스트에 등장

엔터를 누르면 적용됨

병렬로 진행되게끔 하는 방법
- 아래처럼 에이전트들을 부른 후 여러줄에 작성하면 사용이 가능

@.claude/agents/code-explainer.md: A부분 코드 분석해줘
@.claude/agents/create-flow-chart.md: B부분 플로우차트 그려줘

* 참고

- https://tech.hyperithm.com/claude_code_guides_2

[AI] 클로드코드 승인 요청 안물어보게 하는방법 (auto accept, bypass, vscode)

jake-kim — Wed, 15 Apr 2026 01:03:41 +0900

vscode에서 bypass하게 하는 설정

cmd + ,를 눌러서 `Claude Code: Allow Dangerously Skip Permissions` 검색
- 아래 항목에 체크

(체크완)

체크하고나면 클로드코드 채팅창 오른쪽에 Bypass permissions라는 옵션이 생성됨
- 이 옵션을 누르고 다시 vscode를 실행하면 매번 권한을 물어보지 않음

cf) 터미널에서 bypass 설정하는 방법

claude --dangerously-skip-permissions

mcp관련 권한도 bypass 시키는 방법

위에서 Bypass로 설정했음에도 불구하고 serena와 같은 mcp를 사용할때는 권한을 여전히 물어봄
mcp에 관한 권한도 bypass 설정이 가능
아래 설정 범위를 참고로하여 설정이 필요 (만약 글로벌, 로컬 중복된 내용이 있다면 로컬이 우선되어 적용됨)
- 글로벌 설정: ~/.claude/settings.json (모든 프로젝트 적용)
- 프로젝트 설정: <project>/.claude/settings.json (팀원과 공유됨)
- 개인 로컬 설정: <project>/.claude/settings.local.json (Git 제외 권장)
만약, 로컬 설정을 한다면 settings.local.json 파일을 열어서 `mcp__*` 라고 입력하여 모든 mcp에 관해 권한을 허용

{
  "permissions": {
    "allow": [
      "mcp__*"
    ]
  }
}

[AI] 클로드코드 유용한 기능 (analyze, fix, explain, compact, call)

jake-kim — Wed, 8 Apr 2026 01:41:03 +0900

유용한 기능

명령어	주요 목적	권장 사용 시점
/analyze	구조 파악 및 전략 수립	프로젝트 초기 진입, 대규모 변경 전
/fix	에러 해결 및 디버깅	빌드 에러 발생 시, 버그 리포트 접수 시
/explain	코드 이해 및 학습	모르는 로직 분석 시, 코드 리뷰 시
/compact	토큰 절약 및 성능 유지	대화가 너무 길어져 응답이 느려질 때
/call	전문 작업 위임	특정 규칙(Lint 등) 준수 여부 정밀 확인 시

/analyze (구조 파악 및 전략 수립)

프로젝트의 전체 아키텍처를 분석하여 개선 방향을 제시

Swift 상황: MVC에서 MVVM으로 전환하거나, 새로운 프레임워크 도입 전 사용
에이전트 액션: Target, Dependency, Folder Structure를 스캔

ex)

// 에이전트의 분석 결과 예시 (Summary)
/*
[Analysis Result]
- Project: SwiftUIMovieApp
- Architecture: Heavy View (MVC-like)
- Issues: 
  1. ContentListView.swift 내부에 네트워킹 로직이 포함됨 (150라인)
  2. 전역 싱글톤 NetworkManager 사용으로 테스트가 어려움
- Suggestion: ViewModel 도입 및 의존성 주입(DI) 패턴 적용 권장함
*/

/fix (에러 해결 및 디버깅)

빌드 에러나 런타임 크래시 로그를 바탕으로 코드를 즉시 수정함.

Swift 상황: SwiftUI에서 @State 변경 시 발생하는 스레드 에러나 문법 오류 발생 시 사용

ex)

// 수정 전 (에러 발생: Mutable property cannot be settled in a view)
struct ProfileView: View {
    var name: String = "Gim" // 빌드 에러 발생함
    
    var body: some View {
        Button("Change") { name = "Jong-gwon" }
    }
}

// /fix 실행 후 에이전트가 수정한 코드
struct ProfileView: View {
    @State private var name: String = "Gim" // @State 추가하여 해결함
    
    var body: some View {
        Button("Change") { name = "Jong-gwon" }
    }
}

/explain (코드 이해 및 학습)

난해한 Combine 연산자나 복잡한 동시성 제어 코드를 설명함.

Swift 상황: TaskGroup이나 AsyncSequence 등 복잡한 비동기 로직 분석 시 사용

// 분석 대상 코드
func fetchAllData() async throws -> [Data] {
    try await withThrowingTaskGroup(of: Data.self) { group in
        for url in urls {
            group.addTask { try await fetchData(from: url) }
        }
        return try await group.reduce(into: []) { $0.append($1) }
    }
}

/* 
[Agent Explanation]
이 코드는 'Structured Concurrency'를 사용하여 여러 URL에서 데이터를 병렬로 가져옴.
1. withThrowingTaskGroup: 에러 처리가 가능한 병렬 작업 그룹을 생성함.
2. addTask: 각 URL마다 개별 자식 태스크를 생성하여 비동기로 실행함.
3. reduce: 모든 작업이 완료될 때까지 기다렸다가 결과를 하나의 배열로 합쳐서 반환함.
*/

/compact (토큰 절약 및 성능 유지)

긴 코딩 세션 중 핵심 컨텍스트만 남기고 메모리를 정리

Swift 상황: 대규모 리팩토링 중 파일 10개를 넘나들며 대화가 길어졌을 때 사용

ex)

// /compact 실행 시 내부 작동 방식
[System] 이전의 50개 대화 기록을 요약함.
[Current Context Summary]
- 현재 목표: 'NetworkModule'의 URLSession 설정을 에러 핸들링 로직과 함께 고도화 중임.
- 진행 상황: 'NetworkError.swift' 정의 완료, 'APIClient.swift' 수정 중임.
- 남은 작업: 단위 테스트(Unit Test) 작성 필요함.
(불필요한 이전 잡담 및 중복 코드 출력물 삭제 완료함)

/call (전문 작업 위임)

특정 규칙(Lint, Test 등)을 준수하는지 전문 에이전트에게 맡김

Swift 상황: SwiftLint 규칙 준수 여부나 Unit Test 케이스 생성을 전담

# bash

# 터미널 호출 예시
/call swift_test_agent "APIClient.swift 파일에 대한 성공/실패 테스트 케이스 5개 만들어줘"

// swift

// /call로 호출된 서브에이전트가 생성한 코드
final class APIClientTests: XCTestCase {
    func test_fetchData_success() async throws {
        // Mock 데이터를 활용한 성공 케이스 로직 작성함
    }
    
    func test_fetchData_invalidURL_failure() async {
        // 잘못된 URL 입력 시 에러 반환 여부 검증함
    }
}

[AI] 클로드코드 sub agent 개념 (claude code, 서브 에이전트)

jake-kim — Wed, 1 Apr 2026 01:13:46 +0900

sub agent란?

메인 에이전트가 복잡한 작업을 수행할 때, 특정 역할에 특화된 '가상의 전문가'를 별도의 세션으로 띄워 작업을 위임하는 기능
메인 세션의 컨텍스트(대화 기록)가 너무 무거워지는 것을 방지하고, 특정 도구나 지침에만 집중하게 할 때 사용
- 독립된 컨텍스트: 메인 대화와 분리된 깨끗한 창에서 작업하므로 토큰 소모가 효율적임
- 전문화된 지침: .agent 파일에 적힌 전용 시스템 프롬프트를 따름
- 도구 제한: 보안이나 정확도를 위해 특정 도구(예: 읽기 전용)만 사용하도록 제한 가능

사용방법

프로젝트 루트의 .claude/agents/ 디렉토리에 마크다운(.md) 파일을 만들어 에이전트를 정의

ex) 파일명: .claude/agents/swift-reviewer.md

---
name: swift-reviewer
description: Swift 및 SwiftUI 코드의 품질을 검토하고 성능 최적화 방안을 제시하는 전문 리뷰어
tools: [ls, read_file, grep]
---

# 시스템 프롬프트
너는 10년 차 시니어 iOS 개발자임. 다음 원칙을 준수하여 코드를 리뷰함:
1. 메모리 누수 방지를 위해 `[weak self]` 사용 여부를 철저히 검사함
2. SwiftUI View 내 비즈니스 로직은 ViewModel로 분리할 것을 권고함
3. 가독성을 위해 한 함수는 30줄을 넘지 않도록 제안함

호출 방법

1) 자동 호출
- 메인 에이전트에게 작업을 시키면, 에이전트가 판단하여 .agent 파일의 description과 일치하는 작업일 경우 서브에이전트를 생성함

"방금 수정한 LoginView.swift 파일을 swift-reviewer로 검토해줘"

2) 에이전트 관리 (/agents 커맨드)
- 터미널에 /agents를 입력하면 현재 사용 가능한 내장/커스텀 에이전트 목록을 확인하고, UI를 통해 새 에이전트를 생성하거나 편집할 수 있음

주의) Agent와 Skill 개념 구분

에이전트: "로그인 페이지의 버그를 고쳐줘"라는 요청을 받으면 '파일 검색 -> 코드 분석 -> 수정 -> 테스트'라는 전체 과정을 주도
스킬: 에이전트가 "파일을 읽어라"라고 시키면 수행하는 read_file이나, "테스트를 돌려라"라고 할 때 쓰는 run_terminal_command 같은 개별 함수

요약

.skill은 함수를 정의하고, .agent는 지능의 성격과 규칙을 정의
서브에이전트는 작업이 끝나면 결과를 메인 에이전트에게 보고하고 사라지는 일회성 분신임
팀 공통 규칙은 프로젝트 내 .claude/agents/에, 개인 선호 규칙은 ~/.claude/agents/에 저장하여 사용

* 참고

- https://code.claude.com/docs/ko/sub-agents

[AI] 클로드코드 코드 리뷰 기능 (claude code, /code-review)

jake-kim — Tue, 24 Mar 2026 22:25:29 +0900

/code-review 이란?

여러 명의 AI 전문가가 협업하는 멀티 에이전트 오케스트레이션 방식으로 작동하여 코드의 품질과 보안, 논리적 결함을 심층적으로 검토
- 자율적 분석: 변경된 코드만 보는 것이 아니라, 전체 프로젝트 맥락을 이해하고 리뷰를 수행함
- 높은 신뢰도: 여러 에이전트가 교차 검증하여 오탐을 줄이고 실질적인 개선안을 제시함

주요 작동 메커니즘 (Agent Teams)

리뷰 명령 시 각기 다른 전문성을 가진 에이전트들이 병렬로 투입됨

규정 준수 에이전트: CLAUDE.md에 정의된 스타일 가이드 및 아키텍처 규칙 준수 여부 확인
버그 탐지 에이전트: 논리적 오류, 엣지 케이스, 잠재적 메모리 누수 등 탐색
컨텍스트 분석 에이전트: git blame 및 히스토리 분석을 통해 과거 수정 의도와의 충돌 여부 검토
최종 검증 에이전트: 발견된 이슈들의 우선순위를 정하고 신뢰도가 높은 항목만 필터링하여 보고

주요 기능 및 활용 패턴

기능	상세 설명	비고
CLAUDE.md 연동	프로젝트 특유의 컨벤션을 학습하여 맞춤형 리뷰 수행	"Early return 사용" 등 명시 가능
인라인 피드백	--comment 플래그 사용 시 GitHub PR에 직접 댓글 작성	CI/CD 연동 가능
심층 로직 검토	단순 린터가 잡지 못하는 인증/인가 로직이나 성능 병목 파악	대규모 PR에서 높은 효율

컨텍스트 비용 및 효율화 (Context Management)

/code-review는 고성능 분석을 수행하므로 컨텍스트 소모와 비용 관리가 중요함

고비용 구조: 프로젝트 전체 정보를 로드하므로 대규모 코드베이스에서는 토큰 소모가 큼
최적화 팁: * CLAUDE.md 정제: 리뷰 지침을 핵심 위주로 요약하여 매 요청 시 소모되는 컨텍스트를 줄임
- 범위 지정: 전체 리뷰 대신 특정 디렉토리나 변경 파일 위주로 범위를 한정하여 실행
- Subagent 활용: 무거운 분석 작업은 별도 Subagent 루프로 분리하여 메인 세션의 메모리를 보호함

사용방법

프로젝트 폴더에 CLAUDE.md라는 파일 생성
내용 작성

ex)

"SwiftUI View는 200줄 이하 유지함", "강제 언래핑 금지함"

더욱 체계적으로는 아래처럼 작성

# CLAUDE.md

이 파일은 Claude Code가 프로젝트를 이해하고 코드 리뷰를 수행할 때 참고하는 지침 파일입니다.

## 프로젝트 개요

Swift로 작성된 간단한 유저 관리 모듈입니다.
Claude Code의 코드 리뷰 기능 데모를 위해 작성되었습니다.

## 코드 리뷰 기준

코드 리뷰 시 아래 항목을 반드시 점검하세요.

### 보안
- 비밀번호는 절대 평문으로 저장하거나 로그에 출력하지 않습니다.
- 하드코딩된 credentials(비밀번호, API 키 등)은 허용하지 않습니다.
- 민감한 정보는 Keychain 또는 환경변수를 통해 관리합니다.

### 안전성
- 배열 접근 시 반드시 범위(bounds) 체크를 수행합니다.
- 강제 언래핑(`!`)은 사용하지 않으며, `guard let` / `if let`을 사용합니다.
- 외부 입력값은 항상 검증합니다.

### Swift 코드 스타일
- 반복문보다 `filter`, `map`, `first(where:)` 등 고차 함수를 우선 사용합니다.
- `var`보다 `let`을 기본으로 사용합니다.
- 접근 제어자(`private`, `internal`)를 명시합니다.

### 일반 품질
- 함수는 단일 책임 원칙(SRP)을 따릅니다.
- 불필요한 `print` 디버그 로그는 제거합니다.
- 테스트 가능한 구조로 작성합니다.

## 리뷰 명령어

```
/review
```

위 명령어를 실행하면 Claude Code가 이 파일의 기준에 따라 코드를 리뷰합니다.

코드리뷰 대상 예제 코드 준비

// UserManager.swift

import Foundation

// 유저 모델
struct User {
    var id: Int
    var name: String
    var email: String
    var age: Int
    var password: String  // 평문 비밀번호 저장
}

class UserManager {
    var users: [User] = []
    var adminPassword = "admin1234"  // 하드코딩된 관리자 비밀번호

    // 유저 추가
    func addUser(id: Int, name: String, email: String, age: Int, password: String) {
        let user = User(id: id, name: name, email: email, age: age, password: password)
        users.append(user)
        print("Added user: \(name), password: \(password)")  // 비밀번호 로그 출력
    }

    // 이메일로 유저 검색
    func findUser(email: String) -> User? {
        for user in users {
            if user.email == email {
                return user
            }
        }
        return nil
    }

    // 나이로 필터링
    func getUsersByAge(minAge: Int, maxAge: Int) -> [User] {
        var result: [User] = []
        for user in users {
            if user.age >= minAge && user.age <= maxAge {
                result.append(user)
            }
        }
        return result
    }

    // 유저 삭제 (인덱스로)
    func deleteUser(at index: Int) {
        users.remove(at: index)  // 범위 체크 없음, 크래시 위험
    }

    // 전체 유저 출력
    func printAllUsers() {
        for i in 0..<users.count {
            print("[\(i)] \(users[i].name) - \(users[i].email) - pw: \(users[i].password)")
        }
    }

    // 유저 수 반환
    func count() -> Int {
        return users.count
    }
}

// 사용 예시
let manager = UserManager()
manager.addUser(id: 1, name: "Alice", email: "alice@example.com", age: 28, password: "secret123")
manager.addUser(id: 2, name: "Bob", email: "bob@example.com", age: 35, password: "qwerty!")
manager.printAllUsers()

let found = manager.findUser(email: "alice@example.com")
print("Found: \(found?.name ?? "없음")")

클로드코드에 `/code-review` 입력하면 아래처럼 분석 완료

* 참고

- https://code.claude.com/docs/ko/code-review

[AI] 클로드코드 개념 - 기본 개념(CLAUDE.md, skills, mcp, subagents, agent teams, hooks, plugins)

jake-kim — Wed, 18 Mar 2026 01:22:53 +0900

에이전틱 루프 (The Agentic Loop)

Claude Code는 스스로 계획을 세우고 실행하는 에이전트 방식으로 작동하며 아래 3단계 과정이 반복

컨텍스트 탐색: 문제 해결에 필요한 파일 시스템을 조사하고 코드를 읽음
액션 실행: 코드 수정, 파일 생성, 터미널 명령(Shell) 실행 등을 직접 수행
결과 검증: 변경 사항이 의도대로 반영되었는지 테스트를 돌려보고 결과를 분석

기본 개념들

CLAUDE.md: 모든 세션에서 유지되는 프로젝트 컨텍스트로 코딩 컨벤션이나 규칙을 명시
Skills: 재사용 가능한 지식 및 워크플로우로 필요할 때 호출하거나 자동 로드
Subagents: 독립된 루프를 실행하는 격리된 작업자로 무거운 작업을 수행하고 결과만 보고
MCP: Slack, DB 등 외부 서비스와 연결하여 데이터를 주고받는 통로 역할
Hooks: 파일 수정 등 특정 이벤트 발생 시 자동으로 실행되는 스크립트

상황별 예제

기능	주요 용도	예시
CLAUDE.md	상시 적용 규칙	"pnpm 사용", "커밋 전 빌드 필수"
Skill	특정 작업 지식	배포 체크리스트(/deploy), API 가이드
Subagent	맥락 격리/병렬 처리	수백 개의 파일 분석, 보안 취약점 조사
Hook	자동화 프로세스	코드 수정 후 자동 Lint/Format 실행

비용

모든 확장은 모델의 기억 공간을 소모하므로 효율적인 관리가 필요

고비용: CLAUDE.md와 MCP는 매 요청마다 많은 정보를 로드하므로 핵심 위주로 구성
저비용: Skills는 평소엔 요약본만 들고 있다가 필요할 때만 전체 내용을 로드
효율화: 무거운 작업은 Subagent로 넘겨 메인 세션의 컨텍스트 소모를 방지

즉, CLAUDE.md로 기본 틀을 잡고 반복 작업은 Skill로 정의하며 외부 연결은 MCP를 활용해 자율적인 개발 환경을 구축하는 것이 핵심

주요 기능 조합 패턴 (Combination Patterns)

각 확장 기능은 고유의 역할이 있으며 이를 조합해 시너지가 가능

Skill + MCP: MCP로 외부를 연결하고 Skill로 사용법을 가이드함 (예: DB 연결 + 쿼리 패턴 가이드)
Skill + Subagent: 하나의 Skill이 여러 Subagent를 생성해 병렬 작업을 수행함 (예: 보안/성능/스타일 동시 검토)
CLAUDE.md + Skills: 상시 규칙은 CLAUDE.md에, 방대한 참조 문서는 Skill에 넣어 필요할 때만 로드함
Hook + MCP: 이벤트 발생 시 외부로 알림을 보냄 (예: 코드 수정 후 Slack 알림 발송)

컨텍스트 비용 및 로드 전략 (Context Costs)

확장 기능을 많이 추가할수록 모델의 기억 공간(Context)을 소모하며 효율적인 관리가 필수

기능	로드 시점	로드 내용	컨텍스트 비용
CLAUDE.md	세션 시작 시	파일 전체 내용	매우 높음 (매 요청 포함)
Skills	시작 시 + 사용 시	요약 설명(시작), 전체(사용)	낮음 (설명만 상주)
MCP	세션 시작 시	도구 정의 및 스키마	높음 (매 요청 포함)
Subagents	생성 시	지정된 스킬 포함 새 컨텍스트	격리됨 (메인 세션 무관)
Hooks	트리거 시	없음 (외부 실행)	0

효율적인 운영 팁

CLAUDE.md 최적화: 500줄 이내로 유지하고 상세 내용은 Skill로 분리함
Skill 호출 제어: 직접 호출할 스킬은 disable-model-invocation: true 설정을 통해 평상시 비용을 제로로 유지함
작업 격리: 많은 파일을 읽어야 하는 조사는 Subagent를 활용해 메인 세션의 메모리를 아낌

요약하자면, 모든 기능을 무분별하게 활성화하기보다 CLAUDE.md는 최소화하고 무거운 작업은 Skill과 Subagent로 분산하여 모델의 추론 효율을 유지하는 것이 핵심

* 참고: https://code.claude.com/docs/en/features-overview

[AI] Oh My Claude Code (omc) 이해하기

jake-kim — Wed, 11 Mar 2026 01:41:17 +0900

oh my claude code의 컨셉

"설계/실행/QA/검증"을 적절한 모델로 알아서 잘 하게끔 AI한테 쉽게 명령어하는 것

Multi-agent orchestration for Claude Code. Zero learning curve.

여러가지의 agent들을 지휘하며, 하나의 곡을 완성한다는 의미로 orchestration이라고 함
oh my claude code의 역할
- oh my claude code 없이 내가 새롭게 구현하려는 기능이 있을때, claude code에게 "기능을 구현해줘" 한 후 "테스트 해줘"라고 두 번 말해야 함
- oh my claude code를 사용한다면, ralph모드를 사용하여 새로운 기능을 구현해주고 동시에 테스트까지 해주고, 복잡한 로직은 opus, 쉬운 작업은 haiku를 알아서 사용함

 ╔══════════════════════════════════════════════╗
 ║                                              ║
 ║       OH MY CLAUDE CODE                   ║
 ║                                              ║
 ║   ┌─────────┐                                ║
 ║   │CONDUCTOR│  ──→    architect (Opus)     ║
 ║   │ (Claude) │  ──→    executor (Sonnet)   ║
 ║   │         │  ──→    designer (Sonnet)    ║
 ║   │        │  ──→    debugger (Sonnet)   ║
 ║   └─────────┘  ──→    explore (Haiku)     ║
 ║                                              ║
 ║   "1명의 AI → 28인 전문가 팀으로"            ║
 ║                                              ║
 ╚══════════════════════════════════════════════╝

agents들의 메모리 공유 방식

oh my claude code를 사용하면 여러 agent들이 동시에 동작하는데, 내부적으로 효율적인 메모리 공유의 전략이 있음
메모리 공유 두 가지
- 모든 메모리가 공유되는 중앙 상태 관리: 현재 작업의 진행 상황, 발견된 버그, 수정된 파일 목록 등을 중앙에서 관리
- 공유 파일 (CLAUDE.md / MEMORY.md): 프로젝트의 전역 규칙(코딩 컨벤션, 아키텍처)을 모든 에이전트가 공유함
- Auto-Memory: 에이전트가 작업을 수행하며 새로 알게 된 사실(예: "이 프로젝트는 커스텀 에러 핸들러를 씀")을 ~/.claude/projects/.../memory/에 기록하고, 다른 에이전트가 이를 참조
- 컨텍스트 격리: 하위 에이전트가 수천 줄의 로그나 파일을 읽어도, 그 상세 내용은 메인 에이전트의 대화창을 오염시키지 않고 에이전트는 요약된 결과물만 메인에게 전달

병렬 처리

oh my claude code에서 /ultrawork 하여 사용
아래와 같은 3가지 방법을 사용
1. 분산 워커 프로세스 (Worker Processes)
- 메인 에이전트가 작업을 쪼개면, 각 작업은 별도의 자식 프로세스에서 독립적으로 돌아감
- 이점: 한 에이전트가 무거운 연산을 해도 메인 인터페이스가 멈추지 않고, 각 프로세스는 할당된 메모리 범위 내에서만 자원을 사용함
2. 지능형 모델 라우팅
- 모든 작업에 비싼 모델(Claude 3.5 Sonnet 등)을 쓰지 않음
- 단순 파일 탐색은 가벼운 모델에게 맡기고, 복잡한 추론만 메인 모델이 처리하여 메모리 점유율과 비용을 동시에 최적화
3. 토큰 절약 모드
- 병렬 작업 시 중복되는 컨텍스트를 제거하고 여러 에이전트가 동일한 라이브러리 문서를 읽어야 한다면, 이를 캐싱하거나 공통 참조 포인트로 연결해 토큰 소비를 30~50% 줄임

* 참고

- https://memoryhub.tistory.com/entry/%F0%9F%8E%BC-Oh-My-Claude-Code-%EC%95%84%ED%82%A4%ED%85%8D%EC%B2%98%EB%B6%80%ED%84%B0-%EC%8B%A4%EC%A0%84%EA%B9%8C%EC%A7%80-%EC%99%84%EC%A0%84-%ED%95%B4%EB%B6%80

- https://github.com/Yeachan-Heo/oh-my-claudecode

[AI] oh-my-claude code 개념 (클로드코드, 클로드코드 플러그인, omc, oh my claude code)

jake-kim — Wed, 4 Mar 2026 01:39:15 +0900

oh-my-claude code란?

= omc(oh my claude code)라고 지칭
claude code를 위한 멀티 에이전트 오케스트레이션 플러그인
여러 명의 전문 AI 에이전트가 협업하여 복잡한 코딩 작업을 수행하도록 설계
claude code의 market이라는 오픈소스 마켓에 존재

핵심 기능

32개의 전문 에이전트: 아키텍처 설계(Architect), 코드 실행(Executor), 디자인(Designer), 테스트(Tester), 보안 리뷰(Security) 등 역할이 세분화된 에이전트들이 협업
자동 위임: 사용자가 명령을 내리면 시스템이 작업의 성격에 맞는 최적의 에이전트를 자동으로 선택하여 배정

설치 방법

vscode에서 클로드코드를 쓰고 있다면 클로드코드 챗에서 manage plugins 진입
- "/plugin" 입력

manage plugins가 뜨면 Marketplaces 탭 클릭

omc 레포 주소 입력 후 add 버튼 클릭

https://github.com/Yeachan-Heo/oh-my-claudecode

주의) 만약 xcode 관련 오류가 나오면 아래 명령어 실행

sudo xcodebuild -license accept

다시 Plugins 탭을 누르면 생성된 것을 확인 -> Install 버튼 클릭

설치와 활성화가 완료된것을 확인

주요 명령어

1. 자율 실행 모드 (Autonomous)

/autopilot: 아이디어 제시부터 최종 코드 완성까지 전 과정 자율 수행
- 예시: /autopilot 로그인 페이지에 소셜 로그인(Google, Apple) 기능을 추가해줘
/ralph: 아키텍트 검증 기반의 반복 최적화 루프 실행
- 예시: /ralph API 응답 시간을 50% 개선해줘. 프로파일링부터 최적화까지 진행해
/ultrawork: 대규모 다중 작업을 병렬로 고속 처리
- 예시: /ultrawork 모든 API 엔드포인트에 입력 검증 추가, 에러 핸들링 통일, 로깅 추가

2. 팀 및 병렬 실행 (Collaboration)

/team: 역할이 분담된 여러 에이전트 간의 협업 수행
- 예시: /team 프론트엔드 리팩토링과 백엔드 API 마이그레이션을 동시에 진행해줘
/omc-teams: Claude, Codex, Gemini 등 이기종 모델을 tmux에서 동시 실행
- 예시: /omc-teams claude로 테스트 작성, codex로 리팩토링, gemini로 문서 생성해줘
/ccg: 3개 모델(Claude, Codex, Gemini)을 동시에 활용한 오케스트레이션
- 예시: /ccg 사용자 대시보드 페이지를 만들어줘. 백엔드 API와 프론트 UI 모두 필요해

3. 계획 및 분석 (Planning)

/plan: 복잡한 아키텍처 전환 등 전략적 실행 계획 수립
- 예시: /plan 모놀리식 아키텍처를 마이크로서비스로 전환하려면 어떻게 해야 할까?
/analyze: 메모리 누수 등 심층적인 코드 베이스 조사
- 예시: /analyze 현재 프로젝트의 메모리 누수 원인을 찾아줘
/ralph-init: 요구사항 명세서(PRD) 및 문서 초기화
- 예시: /ralph-init 실시간 채팅 기능에 대한 요구사항 문서를 만들어줘

4. 코드 품질 및 검증 (Quality & QA)

/code-review: 코드 품질 및 보안 취약점 종합 점검
- 예시: /code-review 최근 커밋에서 변경된 파일들을 리뷰해줘
/security-review: 보안 취약점 집중 리뷰
- 예시: /security-review 인증/인가 관련 코드에 보안 취약점이 있는지 확인해줘
/simplify: 복잡한 코드를 클린 코드로 리팩토링
- 예시: /simplify 방금 작성한 코드를 더 깔끔하게 정리해줘
/build-fix: 빌드 에러 및 TypeScript 타입 오류 자동 수정
- 예시: /build-fix TypeScript 컴파일 에러 전부 고쳐줘
/tdd: 테스트 주도 개발 기반 기능 구현
- 예시: /tdd 장바구니 기능을 TDD 방식으로 구현해줘
/ultraqa: 테스트 → 검증 → 수정을 성공할 때까지 무한 반복
- 예시: /ultraqa 전체 테스트 스위트를 돌리고, 실패하는 것들을 모두 수정해줘

5. 유틸리티 및 설정 (Utility)

/note: 세션이 종료되어도 유지되는 중요 정보 메모
- 예시: /note DB 마이그레이션 시 반드시 백업 먼저 실행할 것
/deepinit: 프로젝트 구조 분석 및 가이드 문서(AGENTS.md) 자동 생성
- 예시: /deepinit 이 프로젝트의 구조를 분석하고 AGENTS.md를 생성해줘
/skill: 에이전트의 로컬 스킬 관리 (list, add, remove)
- 예시: /skill add # 새 스킬 추가
/external-context: 외부 공식 문서 등 외부 컨텍스트 조회
- 예시: /external-context SwiftUI의 최신 NavigationStack 사용법을 찾아줘
/omc-setup / /omc-doctor: 환경 설정 및 설치 문제 진단
- 예시: /omc-setup # 최초 설치 마법사 시작

✅ 권장 워크플로우

/omc-setup: 초기 환경 설정 수행
/plan: 구현 전 구체적인 작업 계획 수립
/autopilot: 세워진 계획에 따라 자율 구현 시작
/code-review: 최종 결과물의 품질 및 에러 확인

* 참고

- https://github.com/Yeachan-Heo/oh-my-claudecode

[AI] 오픈코드에서 클로드코드 사용 제한 이슈 (Claude code, opencode, anthropic, authorized)

jake-kim — Wed, 25 Feb 2026 01:03:15 +0900

클로드코드 사용시 에러

클로드코드를 사용하다가 아래와 같은 에러가 생기는 경우가 있는데, 클로드코드 회사 앤트로픽에서 계정을 정지한 사례가 있음
클로드코드를 opencode와 같이 다른 곳에서 사용 시 중지시키는 사례가 발생

이 자격 증명은 Claude Code에서만 사용하도록 승인되었으며 다른 API 요청에는 사용할 수 없습니다.

(This credential is only authorized for use with Claude Code and cannot

be used for other API requests.)

오픈코드 레포에 issue로 문의를 해도 github action으로 아래 케이스가 있는지 확인하라는 문의가 있음

https://github.com/anomalyco/opencode/issues/10956

오픈코드에서 클로드코드 사용을 금지한 코드

오픈코드 레포를 가보면 클로드코드 관련 설정을 지운 커밋이 존재

앤트로픽 관련 설명 파일에 금지한다는 내용도 존재

thdxr이라는 사람의 커밋이며, 2026년 2월 20일에 작성

이 글을 적는 시점인 2026년 2월 22일에는 비록 이 커밋이 릴리즈에 들어가지 않아서 적용되지는 않았지만, 커뮤니티를 보면 앤트로픽 회사에서 클로드코드 max모델을 사용하던 유저들의 계정을 정지시킨 흔적이 있음
raddit에서도 내용 확인이 가능

https://www.reddit.com/r/ClaudeAI/comments/1qa50sq/anthropic_banning_thirdparty_harnesses_while/

임시적 해결

위 에러를 config파일을 수정하여 임시적으로 해결할 수 있지만, 이렇게 해결하여 사용하면 토큰이 많이 쓴다는 의견도 존재

https://github.com/anomalyco/opencode/issues/7410

결론

opencode 의존성을 너무 맹신하지 말고, opencode로 클로드코드를 사용하다가 에러가 발생하면 명확한 해결책이 나오지 않는이상 클로드코드 네이티브로 사용을 권장

* 참고

- https://github.com/anomalyco/opencode/commit/973715f3da1839ef2eba62d4140fe7441d539411#diff-23c1b48647ee5935d7825f0f38195a8e018b726e1e331bcc0fcc8f8ce85e4c71L335

[AI] 클로드코드 스킬 개념 2 - 활용하기 (동적 문자열, 참조, 프론트매터, 자동화 패턴)

jake-kim — Wed, 18 Feb 2026 01:21:22 +0900

동적 문자열 사용 방법 (Variables)

기술 콘텐츠 내에 동적 값을 주입하여 유연한 대응 가능

$ARGUMENTS: 기술 호출 시 전달된 모든 인수값. (예: /fix-issue 123 실행 시 123을 데이터로 활용)
${CLAUDE_SESSION_ID}: 현재 세션의 고유 식별자. 로깅 및 세션별 파일 생성에 활용

ex) skill.md 정의 예시

---
name: session-logger
description: 이 세션에 대한 활동 로그
---

다음을 logs/${CLAUDE_SESSION_ID}.log에 로깅합니다:

$ARGUMENTS

skill에서 다른 파일 참조하기

SKILL.md는 핵심 요약에 집중하고, 상세 내용은 별도 파일로 분리하여 컨텍스트 효율화

SKILL.md: 필수 파일. 기술의 개요 및 탐색 가이드 포함 (500줄 이하 권장)
지원 파일: 상세 API 명세(reference.md), 사용 예제(examples.md), 유틸리티 스크립트(scripts/) 등으로 구성
참조 방식: 마크다운 링크를 통해 필요할 때만 해당 내용을 클로드가 로드하도록 유도

파일 구조)

my-skill/
├── SKILL.md (필수 - 개요 및 탐색)
├── reference.md (상세 API 문서 - 필요할 때 로드됨)
├── examples.md (사용 예제 - 필요할 때 로드됨)
└── scripts/
    └── helper.py (유틸리티 스크립트 - 실행됨, 로드되지 않음)

skill.md 파일)

## 추가 리소스

- 완전한 API 세부 정보는 [reference.md](reference.md) 참조
- 사용 예제는 [examples.md](examples.md) 참조

호출 및 권한 제어

프론트매터(Frontmatter) 설정을 통해 사용자 및 AI의 실행 권한 관리

설정 필드	사용자 호출	AI 자동 호출	주요 용도
기본 설정	가능	가능	일반적인 모든 작업
disable-model-invocation: true	가능	불가능	배포, 커밋 등 의도치 않은 실행 방지
user-invocable: false	불가능	가능	배경 지식, 레거시 컨텍스트 제공

ex) skill.md

---
name: deploy
description: 애플리케이션을 프로덕션에 배포합니다.
disable-model-invocation: true
---

$ARGUMENTS를 프로덕션에 배포합니다:

1. 테스트 스위트 실행
2. 애플리케이션 빌드
3. 배포 대상으로 푸시
4. 배포 성공 확인

도구 액세스 및 보안

allowed-tools: 기술 활성화 시 클로드가 사용할 수 있는 도구(Bash, Read, Write 등)를 특정하여 보안 및 오작동 방지
권한 규칙: /permissions 설정을 통해 특정 기술의 실행 권한을 전역적으로 허용하거나 거부 가능

ex) skill.md

---
name: safe-reader
description: 변경하지 않고 파일 읽기
allowed-tools: Read, Grep, Glob
---

고급 자동화 패턴

동적 컨텍스트 주입 (!command): 기술 실행 직전 셸 명령어를 수행하여 실시간 데이터를 프롬프트에 삽입 (예: GitHub CLI를 통한 실시간 PR 데이터 추출)
확장 사고 (Ultrathink): 기술 콘텐츠 내 ultrathink 단어 포함 시 클로드의 추론 능력 극대화
서브에이전트 활용 (context: fork): 현재 대화 맥락과 분리된 독립된 환경(Explore, Plan 등)에서 기술을 수행하여 결과만 수신

ex) skill.md

아래 내용: GitHub CLI를 사용하여 라이브 PR 데이터를 가져와 풀 요청을 요약합니다. !gh pr diff“ 및 기타 명령어가 먼저 실행되고 출력이 프롬프트에 삽입

---
name: pr-summary
description: 풀 요청의 변경 사항 요약
context: fork
agent: Explore
allowed-tools: Bash(gh:*)
---

## 풀 요청 컨텍스트
- PR diff: !`gh pr diff`
- PR 댓글: !`gh pr view --comments`
- 변경된 파일: !`gh pr diff --name-only`

## 작업
이 풀 요청을 요약합니다...

시각적 출력 생성 (Visual Output)

단순 텍스트 응답을 넘어 외부 스크립트와 결합해 시각화 결과물 도출

작동 방식: 기술 내부에 Python/JS 스크립트를 포함하고 클로드가 이를 실행하도록 지시
결과물 예시: 코드베이스 트리 구조 시각화, 테스트 커버리지 보고서, 데이터베이스 스키마 다이어그램 등 브라우저 기반 HTML 파일 생성

ex) skill.md

---
name: codebase-visualizer
description: 코드베이스의 대화형 축소 가능한 트리 시각화를 생성합니다. 새 리포지토리 탐색, 프로젝트 구조 이해 또는 큰 파일 식별 시 사용합니다.
allowed-tools: Bash(python:*)
---

# 코드베이스 시각화기

프로젝트의 파일 구조를 축소 가능한 디렉토리로 보여주는 대화형 HTML 트리 보기를 생성합니다.

## 사용법

프로젝트 루트에서 시각화 스크립트를 실행합니다:

```bash
python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .
```

이렇게 하면 현재 디렉토리에 `codebase-map.html`이 생성되고 기본 브라우저에서 열립니다.

## 시각화가 표시하는 것

- **축소 가능한 디렉토리**: 폴더를 클릭하여 확장/축소
- **파일 크기**: 각 파일 옆에 표시됨
- **색상**: 파일 유형별로 다른 색상
- **디렉토리 합계**: 각 폴더의 집계 크기 표시

skill이 너무 자주 트리거 될때 제어 방법

자동으로 skill을 내부적으로 호출될때가 있는데, 이럴땐 프론트 메타에 아래와 같이 해결이 가능

설명을 더 구체적으로 만들기
수동 호출만 원하면 disable-model-invocation: true를 추가하기

* 참고

https://code.claude.com/docs/ko/skills#claude%EA%B0%80-%EB%AA%A8%EB%93%A0-%EA%B8%B0%EC%88%A0%EC%9D%84-%EB%B3%B4%EC%A7%80-%EB%AA%BB%ED%95%A8

[AI] serena MCP 개념 및 설치 방법

jake-kim — Wed, 11 Feb 2026 00:36:07 +0900

serena MCP란?

Serena MCP(Model Context Protocol) 서버는 Oraios AI에서 개발 및 제공하는 오픈 소스 코딩 에이전트 툴킷
LSP(Language Server Protocol)을 활용하여 분석함
LSP는 원래 VSCode나 Xcode 같은 IDE가 언어별(Python, Go, TS 등) 분석 엔진과 소통하기 위해 만든 표준 규격
- 구문 분석: 단순 텍스트가 아니라 Class, Method, Variable 간의 관계를 트리 구조로 이해
- 심볼 추적: find_symbol을 통해 특정 함수가 정의된 위치와 사용된 위치(References)를 즉시 찾아냄
- 효율적인 컨텍스트: 수만 줄의 코드 중 LLM이 정말로 수정해야 할 정확한 지점만 집어내어 전달
- 전체 파일을 읽거나 `grep`과 같은 텍스트 기반 검색에 의존하는 대신, `find_symbol`이나 `insert_after_symbol`과 같은 정교한 도구를 사용하여 복잡한 프로젝트에서도 정확한 컨텍스트를 찾고 코드를 수정

serena 설치

uv 설치

brew install uv

serena 적용

# 프로젝트 디렉토리 이동
cd ~/work

# Serena 클론
git clone https://github.com/oraios/serena
cd serena

# serena 폴더 추가
mkdir -p ~/.serena

# 설정 파일 복사
cp src/serena/resources/serena_config.template.yml ~/.serena/serena_config.yml

클로드코드와 통합

mcp 서버 설정 (아래 명령어 입력 시 .claude.json에 자동으로 입력됨)

claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena-mcp-server --context ide-assistant --project $(pwd)

위에 까지 입력하고 ~/.serena.json 파일 확인
- 아래처럼 serena가 동일한 내용으로 채워져 있지 않다면 serena json부분을 지우고 다시 위 명령어를 실행

"mcpServers": {
  "serena": {
    "type": "stdio",
    "command": "uvx",
    "args": [
      "--from",
      "git+https://github.com/oraios/serena",
      "serena-mcp-server",
      "--context",
      "ide-assistant",
      "--project",
      "/Users/jake/Desktop/cobot"
    ],
    "env": {}
  }
},

mcp 서버 띄우기

uvx --from git+https://github.com/oraios/serena serena start-mcp-server

claude 코드 챗에 들어가서 /mcp 입력하여 연결된 것 확인

serena 관련 파일

프로젝트 루트에 생성된 .serena 폴더에 가면 아래와 같은 폴더와 파일이 생성됨 (이 부분은 클로드코드를 사용할때 자동으로 업데이트됨)
- cache: LSP 기반의 코드 심볼 및 인덱싱 정보를 임시 저장하여 분석 속도를 높이는 공간
- memories: 프로젝트의 고유 규칙, 아키텍처 맥락 등 AI가 학습한 장기 지식을 보관하는 곳
- project.yml: 관리 중인 프로젝트의 경로, 상태, 메타데이터를 기록한 통합 명세서 파일

* 참고

https://github.com/oraios/serena

[AI] 클로드코드 스킬 개념 1 (Claude Code, Skill.md, 필드)

jake-kim — Wed, 4 Feb 2026 01:21:30 +0900

스킬이란?

클로드코드를 사용할 때 skills 하위 폴더 안에 skill이름을 넣고 md파일을 작성하면 `하나의 기능`으로 사용할 수 있는 것
폴더 위치는 스콥에따라 3가지로 분류

개인	~/.claude/skills/<skill-name>/SKILL.md	모든 프로젝트
프로젝트	.claude/skills/<skill-name>/SKILL.md	이 프로젝트만
플러그인	<plugin>/skills/<skill-name>/SKILL.md	플러그인이 활성화된 위치

.claude/commands/ 안에 정의된 것들보다도 skill이 더욱 우선순위가 높음
클로드코드 쓰임 예시
- skill-name: gen-test-cases: 특정 컴포넌트나 함수에 대한 단위 테스트(Unit Test) 코드 자동 생성.
- write-read-me: 폴더 구조와 코드를 읽고 README.md 초안 작성.

실행 원리

저렇게 skill을 명시해놓으면 알아서 클로드코드가 찾아서 수행하기도 하고, 조금 더 명시적으로는 채팅창에 슬래시를 치고 이름을 검색하면됨

ex) /explain-code 스킬을 만들고 싶은 경우

스킬 폴더 하위에 디렉토리 생성

mkdir -p ~/.claude/skills/explain-code

skill.md 작성

~/.claude/skills/explain-code/SKILL.md

아래처럼 skill.md파일을 작성 (---를 기준으로 스킬에 대한 설정을 하고 그 하단에 내용을 적는 방식)
- name: 채팅창에서 /slash-command 로 사용
- description: Claude가 자동으로 로드할 시기를 결정

---
name: explain-code
description: 시각적 다이어그램과 유추를 사용하여 코드를 설명합니다. 코드가 어떻게 작동하는지 설명하거나, 코드베이스에 대해 가르치거나, 사용자가 "이것이 어떻게 작동하나요?"라고 물을 때 사용합니다.
---

코드를 설명할 때 항상 포함하세요:

1. **유추로 시작**: 코드를 일상 생활의 무언가와 비교합니다.
2. **다이어그램 그리기**: ASCII 아트를 사용하여 흐름, 구조 또는 관계를 표시합니다.
3. **코드 단계별 설명**: 무슨 일이 일어나는지 단계별로 설명합니다.
4. **주의할 점 강조**: 일반적인 실수나 오해는 무엇입니까?

설명을 대화체로 유지합니다. 복잡한 개념의 경우 여러 유추를 사용합니다.

저 스킬을 사용하려면 채팅창에서 /explain-code로 하거나, "이 코드가 어떻게 작동하나요?" 이렇게 사용

skill.md 필드

위에서 살펴본 대로, --- 라는 기호로 스킬의 성격을 정의할 수 있는데 name과 description 말고도 다른 필드도 있음
- name: 채팅창에서 /slash-command 로 사용
- description: Claude가 자동으로 로드할 시기를 결정
- context: 배포, 커밋 또는 코드 생성과 같은 특정 작업에 대한 단계별 지침을 제공
- disable-model-invocation: Claude가 자동으로 트리거하는 것을 방지

---
name: deploy
description: 애플리케이션을 프로덕션에 배포합니다.
context: fork
disable-model-invocation: true
allowed-tools: Read, Grep
---

애플리케이션 배포:
1. 테스트 스위트 실행
2. 애플리케이션 빌드
3. 배포 대상으로 푸시

전체 필드 내용

필드	필수	설명
name	아니요	기술의 표시 이름입니다. 생략하면 디렉토리 이름을 사용. 소문자, 숫자 및 하이픈만 사용 가능(최대 64자).
description	권장	기술이 하는 것과 사용 시기. Claude는 이를 사용하여 기술을 적용할 시기를 결정. 생략하면 마크다운 콘텐츠의 첫 번째 단락을 사용.
argument-hint	아니요	자동 완성 중에 표시되는 힌트로 예상 인수를 나타냄. 예: [issue-number] 또는 [filename] [format].
disable-model-invocation	아니요	Claude가 이 기술을 자동으로 로드하는 것을 방지하려면 true로 설정. /name으로 수동으로 트리거하려는 워크플로우에 사용. 기본값: false.
user-invocable	아니요	/ 메뉴에서 숨기려면 false로 설정. 사용자가 직접 호출해서는 안 되는 배경 지식에 사용. 기본값: true.
allowed-tools	아니요	이 기술이 활성화되었을 때 Claude가 권한을 요청하지 않고 사용할 수 있는 도구.
model	아니요	이 기술이 활성화되었을 때 사용할 모델.
context	아니요	포크된 서브에이전트 컨텍스트에서 실행하려면 fork로 설정.
agent	아니요	context: fork가 설정되었을 때 사용할 서브에이전트 유형.
hooks	아니요	이 기술의 수명 주기로 범위가 지정된 훅입니다. 구성 형식은 Hooks를 참조.

(다음 포스팅 글에서 계속)

* 참고

- https://code.claude.com/docs/ko/skills

[AI] 클로드 코드 vs 깃헙 코파일럿 (claude code, github copilot)

jake-kim — Wed, 28 Jan 2026 01:01:53 +0900

클로드 코드 vs 깃헙 코파일럿

클로드 코드
- Anthropic은 2021년, OpenAI의 창립 멤버였던 `다리오 아모데이(Dario Amodei)`와 그 형제들이 설립
- OpenAI가 점점 상업화되고 AI 안전성(Safety)보다 성능 확장에만 치중하는 것에 반대하며 회사를 나옴
- Anthropic의 핵심 가치는 `안전하고 신뢰할 수 있는 AI`
깃헙 코파일럿
- GitHub은 원래 오픈소스 코드의 저장소였지만, MS 인수 후 `모든 개발 단계에 AI를 심겠다`는 전략을 세우며 2021년 출시된 GitHub Copilot
- MS는 특정 모델(OpenAI)에만 국한되지 않고 Claude나 Gemini 같은 경쟁사 모델도 Copilot 안에서 선택할 수 있게 개방하도록 수정 -> 플랫폼의 힘 강화

깃헙 코파일럿에서도 클로드 모델을 사용할 수 있는데 클로드 코드와 차이점은?

(깃헙 코파일럿에서 고를 수 있는 클로드 코드 모델들)

비유적으로 클로드 코드와 깃헙 코파일럿은 IDE라고 할 수 있고, 그 IDE에서 돌아가는 가는 model들이 claude sonnet과 같은 것들이라고 이해
하지만 클로드 코드와 깃헙 코파일럿은 model들을 사용할 때 그 model들의 결과물들을 얻어내는 과정이 다름

GitHub Copilot: 토큰 아끼는 것을 우선

전처리 방식: 개발자가 코드를 작성하는 흐름을 방해하지 않도록 속도와 효율에 최적화
알고리즘 특성: 깃헙만의 알고리즘이 개입하여, 현재 열려 있는 파일이나 최근 수정한 코드 중 관련이 높은 것들만 골라냄
토큰 관리: 전체를 다 보여주기보다는 불필요한 부분을 쳐내거나 요약하여 모델에게 전달. 이는 응답 속도를 높이고 토큰 비용을 아끼는 데 유리하지만, 가끔 아주 멀리 떨어진 파일 간의 복잡한 의존성을 놓칠 수 있다는 단점

Claude Code: 토큰을 아끼지 않고 파악이 우선

전처리 방식: 단순히 보여주는 정보를 수동적으로 받는 것이 아니라, AI가 직접 수사관 처럼 프로젝트를 파악
알고리즘 특성: 특정 파일을 읽으라는 명령이 없어도 스스로 grep(검색)이나 파일 시스템 읽기 도구를 사용해 코드 간의 연결 고리를 끝까지 추적
토큰 관리: 토큰 소모가 훨씬 크더라도 `정확한 맥락 파악`을 우선시. 요약된 정보가 아니라 코드의 원본 구조와 전체적인 의존성 그래프를 모델이 직접 보게 함으로써, 대규모 수정 작업 시 발생할 수 있는 부작용을 최소화

[AI] vscode에서 클로드코드 쓰기 - 유용한 기능, 단축키 (init, claude.md

jake-kim — Wed, 21 Jan 2026 01:27:44 +0900

단축키

cmd + esc: 포커싱 변경 (에디터 <-> 클로드코드 챗)
- 코드를 드래그하고 cmd + esc하면 클로드코드 채팅창에 해당 코드 위치 참고하게됨
드래그 상태에서도 단순히 포커싱만 변경만 원하는 경우, cmd+2 (클로드코드 챗이 2번째 탭에 있는 경우)
shift + tab: 에이전트 모드 바꾸기 (아래에서 소개 예정)

유용한 기능

cmd + esc로 클로드코드 포커싱하고 난 후 shift + tab하면 모드 변경이 가능
- Ask before Edit: 클로드가 코드를 변경하려고 할 때마다 사용자에게 변경 사항을 보여주고 승인을 요청
- Edit Automatically: 사용자의 개별 승인 없이 클로드가 직접 파일을 수정
- Plan mode: 코드를 직접 수정하기 전에, 클로드가 수행할 작업의 단계별 계획을 먼저 세우고 사용자에게 브리핑하는 단계

"/model" 입력 시 다른 모델 선택 가능
- 글을 작성하는 지금은 opus 모델이 가장 비싸고 좋은 모델
- tip) 복잡한 로직을 물어볼땐 Opus를 사용하고 구현같은 것을 할땐 claude-sonnet-4-5 같은 것 사용 추천

채팅창에 @를 입력하고 폴더나 파일을 입력하면, 그 위치가 입력되어 더욱 구체적이고 명확하게 참조가 가능
/init: 프로젝트 초기화 및 CLAUDE.md 가이드 생성 (프로젝트 규칙 정의)
- CLAUDE.md 파일을 작성하면 ai는 이 CLAUDE.md를 준수하여 작성함
- 또는 파일을 그냥 만들어 놓고 거기에 기준들을 작성해놓으면 자동으로 클로드코드가 파악

이렇게 `/init`으로 입력하면 클로드코드가 알아서 코드를 읽고 여기에 중요한 것을 적어줌.
이렇게 생긴 .CLAUDE.md는 클로드코드가 내부적으로 코드를 작성하거나 제안을 줄 때, 최우선 지침으로 보기때문에, 프로젝트 협업을 할때 커밋 규칙과 같은 것을 적어 둘 수 있음

클로드코드 지침의 종류

https://code.claude.com/docs/

* 참고

- https://code.claude.com/docs/

[AI] 클로드 코드 사용 방법 (vscode에서 클로드 코드 사용 방법)

jake-kim — Wed, 14 Jan 2026 01:26:07 +0900

클로드 코드 설치

npm install -g @anthropic-ai/claude-code

vscode 확장

vscode 오픈 > 확장 > Claude Code for VS Code 설치

IDE 오른쪽에서 생겨난 것을 확인 가능

단축키 cmd + esc로 오픈

위 화면에서 Claude.ai Subscription 클릭
- 클로드코드 사이트에서 pro plan 구독 버튼을 누르고 결제
- vscode로 돌아와서 다시 클로드 코드 사이트로 갈 수 있는 URL이 있는데 그걸 복사해서 클로드 코드로 가서 확인 누르면 아래처럼 토큰이 보이는 화면 등장
- 이 토큰을 복사하여 vscode에 떠있는 클로드 코드 chat 화면에 붙여넣기

vscode에서 클로드 코드 화면을 닫고 다시 열으면 사용할 수 있는 화면 등장

* 이어서 클로드 코드 유용한 기능, 단축키는 다음 포스팅 글 참고

* 참고

- https://code.claude.com/docs/ko/vs-code

[iOS - SwiftUI] 앱 아이콘과 리퀴드글래스 (#Icon Composer, foreground layer, background layer, .icon)

jake-kim — Wed, 7 Jan 2026 01:36:51 +0900

변경된 앱 아이콘 컨셉

예전에는 맥북, 아이폰, 애플워치 마다 같은 성격의 설정 앱이라도 이미지가 미세하게 달랐었음

하지만 이제는 매우 심플하게 처리
- 맥북, 아이폰: 네모난 배경
- 애플워치: 동그란 배경

이렇게 처리하게된 배경에는 `foreground layer`, `background layer`, `.icon`과 관련된 개념이 생겨나서 부터 확립

Icon Composer (layer와 .icon)

애플에서는 앱 아이콘을 정의할때 layer(*층)라는 것을 두어서 이것을 사용하여 앱 아이콘을 표현함
층을 두어서 입체적으로 표현하려는것이 목적
층(layer)들을 합쳐놓은(Composer)것을 Icon Composer라고 지칭

이 개념에 의해, 이제 여러가지의 앱 아이콘 제작이 없이, 단순히 각 layer를 표현하는 이미지만 애셋에 등록하는 형태

Icon Composer 적용방법

애플 developer 사이트 > 다운로드 > Icon Composer 검색
아래 파일 설치

오픈

layer를 쌓으려면 좌측하단 > 플러스 버튼을 눌러서 group 이나 image 추가

(이미지 추가 하면 위에 layer처럼 쌓임)

* 용어 참고 (https://developer.apple.com/documentation/Xcode/creating-your-app-icon-using-icon-composer)

저장 (cmd + s)

이 파일을 Xcode 프로젝트 폴더에다가 드래그 앤 드롭

주의) Assets 폴더 안에 넣는것이 아닌 그 밖에다 배치해야함
Xcode > Target > App Icon에 "myIcon" 입력하고 App Icons sources에 체크하면 완료

변경된 것 확인 완료

* 참고

- https://youtu.be/l-9tYm0U998

- https://developer.apple.com/kr/icon-composer/

[iOS - SwiftUI] Sticky Header 구현 방법 (Sticky 헤더, List 사용)

jake-kim — Wed, 31 Dec 2025 01:15:41 +0900

cf) LazyVStack해서 구현 방법 포스팅 글은 이 링크의 포스팅 글 참고: https://ios-development.tistory.com/1760

List로 구현한 Sticky Header

StickyHeader 구현 아이디어

StickyHeader를 순수 직접 구현하려면 많은 작업이 들겠지만, SwiftUI에서 List안에 Section(header:)를 이용하면, 스크롤 시 자동으로 위에 걸쳐지는 효과를 사용하면 구현하기가 매우 쉬움
단, List의 속성에 .listStyle(.plain)을 해줘야 section으로 넣었던 UI들이 sticky header로 동작함

구현

List 선언

struct ListStickyHeaderView: View {
    var body: some View {
        NavigationView {
            List {

sticky header 위쪽에 위치할 뷰를 넣어주기
- 아래 사진에서 Top Content 부분

VStack 안에 넣기

struct ListStickyHeaderView: View {
    var body: some View {
        NavigationView {
            List {
                // 1. 상단 콘텐츠 (Header가 고정되기 전 함께 스크롤됨)
                VStack {
                    Text("Top Content")
                        .font(.largeTitle)
                        .padding()
                        .background(Color.green)
                        .cornerRadius(10)
                }
                .frame(maxWidth: .infinity)
                .padding()
                .listRowSeparator(.hidden) // 구분선 제거
                .listRowInsets(EdgeInsets()) // 좌우 여백 제거

여기 아래에 Sticky Header가 붙어야 하므로 Section(header:)라는 것을 넣기

struct ListStickyHeaderView: View {
    var body: some View {
        NavigationView {
            List {
                // 상단 콘텐츠 (Header가 고정되기 전 함께 스크롤됨)
                VStack {
                    ...
                }

                // Sticky Header가 포함된 섹션1
                Section(header: MyStickyHeader()) {
                    ForEach(0..<50) { index in
                        Text("Item \(index)")
                            .padding()
                            .frame(maxWidth: .infinity)
                            .background(Color.blue.opacity(0.3))
                            .cornerRadius(10)
                    }
                    .listRowSeparator(.hidden)
                    .listRowInsets(EdgeInsets(top: 5, leading: 16, bottom: 5, trailing: 16))
                }

...

struct MyStickyHeader: View {
    var body: some View {
        Text("Sticky Header")
            .font(.largeTitle)
            .bold()
            .frame(maxWidth: .infinity)
            .background([Color.red, Color.blue, Color.green].randomElement()!)
            .foregroundColor(.white)
    }
}

여기까지 구현하면 StickyHeader 부분의 상단에 아래처럼 padding이 생기므로 이 패딩을 없애는 코드도 따로 처리가 필요

이것은 header 구현한 코드에 .listRowInsets(EdgeInsets())를 추가하여 해결 가능

struct MyStickyHeader: View {
    var body: some View {
        Text("Sticky Header")
            .font(.largeTitle)
            .bold()
            .frame(maxWidth: .infinity)
            .background([Color.red, Color.blue, Color.green].randomElement()!)
            .foregroundColor(.white)
            .listRowInsets(EdgeInsets()) // <- header의 padding 제거
    }
}

또 다른 sticky header를 넣고 싶다면 동일하게 넣기

struct ListStickyHeaderView: View {
    var body: some View {
        NavigationView {
            List {
                // 상단 콘텐츠 (Header가 고정되기 전 함께 스크롤됨)
                VStack {
                    ...
                }

                // Sticky Header가 포함된 섹션1
                Section(header: MyStickyHeader()) {
                    ForEach(0..<50) { index in
                        Text("Item \(index)")
                            .padding()
                            .frame(maxWidth: .infinity)
                            .background(Color.blue.opacity(0.3))
                            .cornerRadius(10)
                    }
                    .listRowSeparator(.hidden)
                    .listRowInsets(EdgeInsets(top: 5, leading: 16, bottom: 5, trailing: 16))
                }

                // Sticky Header가 포함된 섹션2
                Section(header: MyStickyHeader()) {
                    ForEach(0..<50) { index in
                        Text("Item \(index)")
                            .padding()
                            .frame(maxWidth: .infinity)
                            .background(Color.blue.opacity(0.3))
                            .cornerRadius(10)
                    }
                    .listRowSeparator(.hidden)
                    .listRowInsets(EdgeInsets(top: 5, leading: 16, bottom: 5, trailing: 16))
                }
...

여기까지 완성된 코드

struct ListStickyHeaderView: View {
    var body: some View {
        NavigationView {
            List {
                // 1. 상단 콘텐츠 (Header가 고정되기 전 함께 스크롤됨)
                VStack {
                    ...
                }

                // 2. Sticky Header가 포함된 섹션1
                Section(header: MyStickyHeader()) {
                    ...
                }
                
                // 2. Sticky Header가 포함된 섹션2
                Section(header: MyStickyHeader()) {
                    ...
                }
            }
            .listStyle(.plain) // 중요: Sticky 효과를 위한 스타일
        }
    }
}

여기까지 하고 실행시켜보면 navigation bar 부분이 투명해서 뒤에 셀이 보여짐

여기서 navigationBar가 항상 보여지게하고, Color를 white로 바꾸는 코드가 필요

struct ListStickyHeaderView: View {
    var body: some View {
        NavigationView {
            List {
                ...
            }
            .listStyle(.plain) // 중요: Sticky 효과를 위한 스타일
            .toolbarBackground(Color.white, for: .navigationBar) // 배경색 지정 (코드 없으면 스크롤 될 때 뒤의 셀들이 보임)
            .toolbarBackground(.visible, for: .navigationBar)   // 항상 보이게 설정 (코드 없으면 스크롤 될 때 뒤의 셀들이 보임)
        }
    }
}

(완성)

List로 구현한 Sticky Header

* 전체 코드

import SwiftUI

struct ContentView: View {
    var body: some View {
        VStack {
            ListStickyHeaderView()
        }
    }
}

struct ListStickyHeaderView: View {
    var body: some View {
        NavigationView {
            List {
                // 1. 상단 콘텐츠 (Header가 고정되기 전 함께 스크롤됨)
                VStack {
                    Text("Top Content")
                        .font(.largeTitle)
                        .padding()
                        .background(Color.green)
                        .cornerRadius(10)
                }
                .frame(maxWidth: .infinity)
                .padding()
                .listRowSeparator(.hidden) // 구분선 제거
                .listRowInsets(EdgeInsets()) // 좌우 여백 제거

                // 2. Sticky Header가 포함된 섹션1
                Section(header: MyStickyHeader()) {
                    ForEach(0..<50) { index in
                        Text("Item \(index)")
                            .padding()
                            .frame(maxWidth: .infinity)
                            .background(Color.blue.opacity(0.3))
                            .cornerRadius(10)
                    }
                    .listRowSeparator(.hidden)
                    .listRowInsets(EdgeInsets(top: 5, leading: 16, bottom: 5, trailing: 16))
                }
                
                // 2. Sticky Header가 포함된 섹션2
                Section(header: MyStickyHeader()) {
                    ForEach(0..<50) { index in
                        Text("Item \(index)")
                            .padding()
                            .frame(maxWidth: .infinity)
                            .background(Color.blue.opacity(0.3))
                            .cornerRadius(10)
                    }
                    .listRowSeparator(.hidden)
                    .listRowInsets(EdgeInsets(top: 5, leading: 16, bottom: 5, trailing: 16))
                }
            }
            .listStyle(.plain) // 중요: Sticky 효과를 위한 스타일
            .toolbarBackground(Color.white, for: .navigationBar) // 배경색 지정 (코드 없으면 스크롤 될 때 뒤의 셀들이 보임)
            .toolbarBackground(.visible, for: .navigationBar)   // 항상 보이게 설정 (코드 없으면 스크롤 될 때 뒤의 셀들이 보임)
        }
    }
}

struct MyStickyHeader: View {
    var body: some View {
        Text("Sticky Header")
            .font(.largeTitle)
            .bold()
            .frame(maxWidth: .infinity)
            .background([Color.red, Color.blue, Color.green].randomElement()!)
            .foregroundColor(.white)
            .listRowInsets(EdgeInsets()) // 3. header의 padding 제거
    }
}

[WWDC2025] SwiftUI 최적화 프로파일링 - Optimize SwiftUI performance with Instruments (5)

jake-kim — Wed, 24 Dec 2025 01:32:42 +0900

SwiftUI Instruments 에 중요한 것

SwiftUI Instruments를 보면 빨간선과 주황선이 보이는데, 이 정보들은 중요한 것임
- (아래 사진 관련 내용: https://ios-development.tistory.com/1815)

https://wwdcnotes.com/documentation/wwdcnotes/wwdc25-256-whats-new-in-swiftui/

빨간색 선 기준

기준: View의 body 계산 시간이 1.0ms를 초과할 때 표시
의미: 매우 심각한 성능 저하 상태
영향: 120Hz 디스플레이(ProMotion) 환경에서 프레임당 가용 시간은 약 8.3ms인데, 뷰 하나 그리는 데 1ms를 넘겨버리면 실제 렌더링 루틴 전체가 꼬이며 눈에 띄는 Hitch(버벅임)가 발생

주황색 선 기준

기준: View의 body 계산 시간이 0.5ms를 초과할 때 표시
의미: 성능 저하 주의 단계
영향: 당장 화면이 멈추지는 않더라도, 이런 뷰가 리스트(List/ScrollView) 내부에 많아지면 누적 연산 시간이 늘어나 프레임 드랍의 직접적인 원인이 됨

수치의 의미

SwiftUI의 Render Loop는 단순히 body만 읽고 끝나는 게 아님
Body 계산 → 레이아웃 결정 → 뷰 트리 비교(Diffing) → GPU Commit 과정을 한 프레임 안에 다 끝내야 하기 때문
즉, body 연산에서 이미 1ms를 써버리면 나머지 과정을 수행할 시간이 부족해 시스템 전체 성능에 과부하를 줌

과부하 예시)

리스트 누적 연산: 화면에 셀 10개가 보일 때 각 셀의 body가 1ms라면, 순수 연산만 10ms가 소요되어 ProMotion 기준(8.3ms)을 즉시 초과하고 스크롤 렉을 유발함
프레임 점유율: 120Hz 환경에서 뷰 하나가 1ms를 쓰면 전체 가용 시간의 12% 이상을 혼자 점유하게 되어, 레이아웃 및 GPU 렌더링 등 후속 공정의 시간을 뺏음
복합 계층의 위기: 상위 뷰 변경으로 하위 뷰들이 줄줄이 재계산될 때, 각 서브뷰가 0.5ms씩만 잡아먹어도 전체 렌더링 파이프라인이 금방 마비됨

[iOS - SwfitUI] 탭했을 때 키보드 내리는 법 (simultaneousGesture를 쓸때 주의할 점)

jake-kim — Wed, 17 Dec 2025 01:24:32 +0900

탭했을 때 키보드 내리기

다른 제스처도 동시에 동작하게끔 하기 위해 보통 아래처럼 simultaneousGesture를 사용하여 tapGesture 이벤트를 얻어서 isFocused = false로 처리

struct ContentView: View {
    @State private var text: String = ""
    @FocusState private var isFocused: Bool

    var body: some View {
        ScrollView {
            VStack(spacing: 16) {
                TextField("텍스트를 입력하세요", text: $text)
                    .textFieldStyle(.roundedBorder)
                    .focused($isFocused)

                ...
            }
            .padding()
        }
        .simultaneousGesture(
            TapGesture().onEnded {
                isFocused = false
            }
        )
        .simultaneousGesture(
            DragGesture().onChanged { _ in
                isFocused = false
            }
        )
    }
}

하지만 simultaneousGesture를 사용하면 아래처럼 자기 자신의 텍스트필드를 탭했을때도 키보드가 내려감

simultaneousGesture가 아니라 tapGesture를 사용하면 텍스트 필드 자기 자신을 탭해도 여전히 유지되어 원하는 동작이 가능

simultaneousGesture 사용과 onTapGesture 동작이 다른 이유?
- 우선순위가 다르기 때문

simultaneousGesture를 사용할 때 주의할 점

simultaneousGesture
- 자식과 병렬로 모두 인식 → 컨트롤 동작을 유지하면서 부모 처리도 가능
onTapGesture
- 자식 제스처와 경쟁하며 자식의 우선순위가 높음
때문에, simultaneousGesture를 사용하면 우선순위가 다 동일해지고, onTapGesture를 사용하면 자식의 우선순위가 높아진다는 것을 알 것

전체 코드

struct ContentView: View {
    @State private var text: String = ""
    @FocusState private var isFocused: Bool

    var body: some View {
        ScrollView {
            VStack(spacing: 16) {
                TextField("텍스트를 입력하세요", text: $text)
                    .textFieldStyle(.roundedBorder)
                    .focused($isFocused)

                ForEach(0..<20, id: \.self) { idx in
                    Text("Row \(idx)")
                        .frame(maxWidth: .infinity, alignment: .leading)
                        .padding(.vertical, 8)
                }
            }
            .padding()
        }
//        .simultaneousGesture(
//            TapGesture().onEnded {
//                isFocused = false
//            }
//        )
        .simultaneousGesture(
            DragGesture().onChanged { _ in
                isFocused = false
            }
        )
        .onTapGesture {
            isFocused = false
        }
    }
}

[iOS - swift] 전체빌드와 증분빌드 차이점

jake-kim — Wed, 10 Dec 2025 01:36:41 +0900

전체빌드 개념

단어 그대로 캐싱 없이, a부터 z까지 모든 파일을 빌드하는 것
cf) 빌드란?
- 소스 코드들을 실행 가능한 형태로 메모리에 올리는 것

https://ios-development.tistory.com/1336

증분빌드 개념

증분 빌드(Incremental Build)는 “변화가 영향을 미치는 범위만 찾아서 필요한 파일만 재컴파일”하는 방식
Xcode는 이를 위해 “의존성 그래프(Dependency Graph)”와 “인터페이스 파일(.swiftinterface / .dia)”을 사용

증분빌드 원리

빌드 시스템은 파일마다 해시(hash) 또는 timestamp를 기록해 두고 있다가 사용

FileA.swift → 해시값 0xA2B3 
FileB.swift → 해시값 0xC883

Swift는 모든 .swift 파일 내부의 타입, 프로토콜, extension 등을 분석해 파일 간의 의존성 그래프를 만듦
- User.swift를 변경하면 → ProfileView.swift, SettingsView.swift도 다시 빌드되어야 함
- 하지만 SettingsView 안에서 User를 쓰지 않으면 → 건드릴 필요 없음

User.swift ← ProfileView.swift ← SettingsView.swift

Swift 컴파일러는 각 파일의 인터페이스 파일을 생성

예) 인터페이스 파일 (인터페이스: Stored property, function signature, protocol 정의)

MyType.swift	MyType~partial.swiftmodule
외부 모듈	.swiftinterface

만약? 함수 내부(body)만 바뀌면?
- 인터페이스는 그대로 → 다른 파일은 영향 없음 → 증분 빌드 가능
stored property, public API 변경되면?
- 인터페이스가 바뀜 → 영향을 받는 모든 파일 재컴파일 → 증분 빌드 불가

전체 빌드로 되는 경우?

다음 중 하나라도 일어나면 전체빌드로 됨
- 이런 경우엔 “의존성 그래프” 자체가 다시 계산되기 때문

모듈 public interface 변경
struct stored property 변경
protocol 변경
extension에 public method 추가
Swift version 변경
optimization level 변경
Package / Pod 업데이트
DerivedData 삭제
Build setting 변경
bridging header(ObjC) 변경

증분빌드 되었는지 유무는 빌드를 끝내고 결과물이 나오는 xcresult 파일에서 확인 가능
- xcresult 파일 개념: https://ios-development.tistory.com/1827

ex) 증분빌드인지 알아내는 방법

xcresult 결과를 보면 핵심 파일인 ContentView.swift 파일이 있는데, 이 파일 이컴파일 될때 wasFetchedFromCache가 true인 것을 보면 캐싱되어서 증분빌드 되었다는 것을 추측 가능

[iOS - swift] 빌드 로그 json형태로 뽑아보기 (xcresult, xcactivitylog, XCLogParser)

jake-kim — Wed, 3 Dec 2025 01:42:41 +0900

xcactivitylog

Xcode가 빌드/테스트/아카이브할 때 생성되는 빌드 로그의 원본 파일
(= Xcode UI에서 보는 Build Log 화면(⌘ + 9)의 실제 데이터 파일)

바이너리 파일은 아래 경로에 위치
- ~/Library/Developer/Xcode/DerivedData/<Project>/Logs/Build/
얻어내는 법
- Xcode > Build > 오른쪽마우스 > Show in Finder 클릭

Show in Finder 클릭 시 Logs/Launch에 들어가게됨

여기서 Logs/Launch가 아닌, Logs/Build 경로에 가야하므로 Logs경로로 이동한 다음 Build 폴더로 이동
- 마침내 UUID.xcactivitylog 파일 획득이 가능

들어있는 정보들
- 전체 빌드 타임라인
- 각 빌드 단계별 duration
- 컴파일러가 어떤 파일을 빌드했는지
- Warning, Error 메시지
- SwiftCompile, Link, Run Script, Previews 등 모든 빌드 스텝
- Bitcode/LLVM 단계
- 인덱싱(indexing) 관련 시간
- Test 실행 로그
- 증분 빌드 캐시 사용 여부

xcactivitylog 파일 json 형태로 뽑아보기

XCLogParser를 사용하여 json으로 뽑기가 가능

brew install xclogparser

xcactivity 파일의 경로를 얻어오기위해 오른쪽 클릭 > "정보 가져오기" 클릭

위치 > path를 복사
- path를 복사한 다음 파일 이름도 복사
  `/Users/jake/Library/Developer/Xcode/DerivedData/Performance1-frzqzmwaccvbjdfswawhmgkwahke/Logs/Build/51597595-B89A-4E8E-BC1C-842C12F78CD8.xcactivitylog`

아래 명령어를 통해 json형태로 추출 가능

xclogparser parse --project Your.xcactivitylog --output output.json

ex)

xclogparser dump --file /Users/jake/Library/Developer/Xcode/DerivedData/Performance1-frzqzmwaccvbjdfswawhmgkwahke/Logs/Build/51597595-B89A-4E8E-BC1C-842C12F78CD8.xcactivitylog --output activity.json

생성된 activity.json을 열어보면 약 2000줄의 json 데이트 획득 가능

* XCLogParser git: https://github.com/MobileNativeFoundation/XCLogParser

[iOS - swift] Instrument 결과물 trace파일 분석, xml 파일로 추출 방법 (xctrace export)

jake-kim — Wed, 26 Nov 2025 01:47:48 +0900

.trace 파일

Instruments를 통해 나오는 .trace 파일은

자주쓰는 xctrace export 옵션

--list
- trace 파일 내부에 어떤 데이터들이 들어있는지 전체 목록을 보여줌 (schema 이름들을 확인이 가능)
- xctrace export --input test1.trace --list
예)
- time-sample
- signpost
- process
- thread-state
- system-calls
- memory
- call-tree
--toc
- Trace Table of Contents(Toc)를 XML로 바로 출력
- xctrace export --input test1.trace --toc 이걸 보면 전체 구조를 한눈에 확인 가능

--xpath
- 특정 부분만 필터링하기 위한 고급 옵션

ex)

signpost 데이터만 추출: --xpath '//table[@schema="point-of-interest"]'
특정 이벤트 이름 필터: --xpath '//event[@name="MyCustomSignpost"]'

Insturments의 time profiler에서 데이터 추출해보기

Insturments 실행
- Xcode 오픈 > cmd + I
Instruments의 time profiler 선택

좌측상단 녹화 버튼을 눌러서 실행

확인하고 싶은 부분을 테스트 폰에서 실행해본 후, instruments에서 중지 버튼 클릭 > instruments를 닫으면 test1으로 저장
이 test1을 가지고 time sample을 뽑아보기
- * time-sample: Time Profiler가 일정 간격으로 CPU 스택을 찍어서 만든 "Raw Samples" 데이터

# Time Profiler에서 수집된 "raw CPU 샘플(time-sample)" 데이터만 .trace 파일에서 추출해 XML로 저장하는 명령어
xctrace export --input test1.trace --xpath '/trace-toc/run/data/table[@schema="time-sample"]' --output time-sample.xml

추출된 time-sample.xml을 실행시켜보면 정보가 등장
- time sample 말 그대로, 시간별로 뽑은 것들의 결과값이 나옴

<?xml version="1.0"?>
<trace-query-result>
<node xpath='//trace-toc[1]/run[1]/data[1]/table[3]'><schema name="time-sample"><col><mnemonic>time</mnemonic><name>Timestamp</name><engineering-type>sample-time</engineering-type></col><col><mnemonic>thread</mnemonic><name>Thread</name><engineering-type>thread</engineering-type></col><col><mnemonic>core-index</mnemonic><name>Core Index</name><engineering-type>core</engineering-type></col><col><mnemonic>thread-state</mnemonic><name>Thread State</name><engineering-type>thread-state</engineering-type></col><col><mnemonic>cp-kernel-callstack</mnemonic><name>Kernel Callstack ID</name><engineering-type>kperf-bt</engineering-type></col><col><mnemonic>cp-user-callstack</mnemonic><name>User Callstack ID</name><engineering-type>kperf-bt</engineering-type></col><col><mnemonic>sample-type</mnemonic><name>Sample type</name><engineering-type>time-sample-kind</engineering-type></col></schema><row><sample-time id="1" fmt="00:00.372.885">372885208</sample-time><thread id="2" fmt="Main Thread 0xc229 (Performance1, pid: 2875)"><tid id="3" fmt="0xc229">49705</tid><process id="4" fmt="Performance1 (2875)"><pid id="5" fmt="2875">2875</pid><device-session id="6" fmt="TODO">TODO</device-session></process></thread><sentinel/><thread-state id="7" fmt="Blocked">Blocked</thread-state><sentinel/><kperf-bt id="8" fmt="PC:0x1052f47c0, 1 frames, 0 regs, pid: 2875"><text-addresses id="9" fmt="frag 799">4381951936</text-addresses><text-address id="10" fmt="0x1052f47c0">4381951936</text-address><process ref="4"/></kperf-bt><time-sample-kind id="11" fmt="Stackshot">3</time-sample-kind></row>
<row><sample-time ref="1"/><thread ref="2"/><sentinel/><thread-state ref="7"/><sentinel/><kperf-bt ref="8"/><time-sample-kind ref="11"/></row>
<row><sample-time id="12" fmt="00:00.413.780">413780375</sample-time><thread ref="2"/><core id="13" fmt="CPU 5">5</core><thread-state id="14" fmt="Running">Running</thread-state><sentinel/><kperf-bt id="15" fmt="PC:0x1052f2c04, 19 frames, 1 regs, pid: 2875"><text-addresses id="16" fmt="frag 5329">4378756604 4378696628 4378654252 4378651164 4378618192 4378650264 4378652064 4378683412 4378831396 4378824096 4378830696 4378682744 4378597104 4378596164 4381968536 4381963076 4381962712 4381961036 0</text-addresses><text-address id="17" fmt="0x1052f2c04">4381944836</text-address><process ref="4"/><register-content id="18" fmt="0x104ff4044">4378804292</register-content></kperf-bt><time-sample-kind id="19" fmt="Timer Fired">0</time-sample-kind></row>
...
<row><sample-time id="2409" fmt="00:03.943.780">3943780041</sample-time><thread ref="509"/><core ref="240"/><thread-state ref="14"/><sentinel/><kperf-bt ref="1926"/><time-sample-kind ref="19"/></row>
<row><sample-time id="2410" fmt="00:03.944.778">3944778916</sample-time><thread ref="509"/><core ref="240"/><thread-state ref="14"/><sentinel/><kperf-bt ref="2139"/><time-sample-kind ref="19"/></row>
<row><sample-time id="2411" fmt="00:03.945.780">3945780458</sample-time><thread ref="509"/><core ref="323"/><thread-state ref="14"/><sentinel/><kperf-bt ref="1926"/><time-sample-kind ref="19"/></row>
<row><sample-time id="2412" fmt="00:03.947.779">3947779250</sample-time><thread ref="509"/><core ref="13"/><thread-state ref="14"/><sentinel/><kperf-bt id="2413" fmt="PC:0x1970593f4, 11 frames, 1 regs, pid: 2875"><text-addresses ref="921"/><text-address ref="2146"/><process ref="4"/><register-content ref="2147"/></kperf-bt><time-sample-kind ref="19"/></row>
<row><sample-time id="2414" fmt="00:03.948.779">3948779458</sample-time><thread ref="509"/><core ref="13"/><thread-state ref="14"/><sentinel/><kperf-bt id="2415" fmt="PC:0x1970583a8, 16 frames, 1 regs, pid: 2875"><text-addresses ref="2387"/><text-address ref="391"/><process ref="4"/><register-content ref="387"/></kperf-bt><time-sample-kind ref="19"/></row>
<row><sample-time id="2416" fmt="00:03.949.779">3949779958</sample-time><thread ref="509"/><core ref="240"/><thread-state ref="14"/><sentinel/><kperf-bt id="2417" fmt="PC:0x197059278, 34 frames, 1 regs, pid: 2875"><text-addresses id="2418" fmt="frag 6876">6828688312 6828680388 6828336324 6828673252 6828665960 6828688100 6828679012 7578375508 7578378520 7578379392 7578375240 7578374900 7578283052 7578280924 7578378536 7578379392 7578375240 7578374900 7578283052 7578280924 7578378536 7578379392 7578375240 7578374900 7578283052 7578280924 7578378536 7578385764 6444364976 6444476452 6444334424 6444336400 4377979792 4377975180</text-addresses><text-address ref="951"/><process ref="4"/><register-content ref="387"/></kperf-bt><time-sample-kind ref="19"/></row>
<row><sample-time id="2419" fmt="00:07.247.782">7247782291</sample-time><thread ref="2"/><core ref="447"/><thread-state ref="14"/><sentinel/><kperf-bt id="2420" fmt="PC:0x1051c4b70, 34 frames, 1 regs, pid: 2875"><text-addresses id="2421" fmt="frag 8147">4380740648 4380708568 6443621400 6443619872 6443619304 6443366520 6444364976 6444276492 6444276100 6443364636 6443433384 6443431928 6443422148 6443435012 6543765396 6444364976 6444276492 6576072508 6576068460 6446961884 6446961700 6446959536 6446955908 6446935588 6749886908 6545603644 6545620580 7934333500 7934332804 7931750860 4377788496 4378596304 4381961112 0</text-addresses><text-address ref="381"/><process ref="4"/><register-content ref="382"/></kperf-bt><time-sample-kind ref="19"/></row>
<row><sample-time id="2422" fmt="00:28.042.779">28042779958</sample-time><thread ref="2"/><core ref="13"/><thread-state ref="14"/><sentinel/><kperf-bt id="2423" fmt="PC:0x1800aef68, 21 frames, 1 regs, pid: 2875"><text-addresses id="2424" fmt="frag 9467">6448065688 6447321988 6495968380 6444321556 6444364976 6444479648 6444319516 6444318316 6446960656 6446957032 6446935588 6749886908 6545603644 6545620580 7934333500 7934332804 7931750860 4377788496 4378596304 4381961112 0</text-addresses><text-address id="2425" fmt="0x1800aef68">6443167592</text-address><process ref="4"/><register-content id="2426" fmt="0x180091e14">6443048468</register-content></kperf-bt><time-sample-kind ref="19"/></row>
<row><sample-time id="2427" fmt="00:50.779.780">50779780083</sample-time><thread id="2428" fmt="Performance1 0xcbd4 (Performance1, pid: 2875)"><tid id="2429" fmt="0xcbd4">52180</tid><process ref="4"/></thread><core ref="240"/><thread-state ref="14"/><sentinel/><kperf-bt ref="419"/><time-sample-kind ref="19"/></row>
<row><sample-time id="2430" fmt="00:58.435.779">58435779958</sample-time><thread id="2431" fmt="Performance1 0xcd65 (Performance1, pid: 2875)"><tid id="2432" fmt="0xcd65">52581</tid><process ref="4"/></thread><core ref="126"/><thread-state ref="14"/><sentinel/><kperf-bt id="2433" fmt="PC:0x104f8876c, 12 frames, 1 regs, pid: 2875"><text-addresses id="2434" fmt="frag 10618">6446876424 6446876264 6448042820 6448062604 6444255144 6444364976 6444293160 6444295912 6444340532 6444338292 4377979852 4377975180</text-addresses><text-address ref="687"/><process ref="4"/><register-content id="2435" fmt="0x104f2916c">4377973100</register-content></kperf-bt><time-sample-kind ref="19"/></row>
<row><sample-time id="2436" fmt="02:17.107.781">137107781291</sample-time><thread id="2437" fmt="Performance1 0xd37a (Performance1, pid: 2875)"><tid id="2438" fmt="0xd37a">54138</tid><process ref="4"/></thread><core ref="126"/><thread-state ref="14"/><sentinel/><kperf-bt ref="419"/><time-sample-kind ref="19"/></row>
</node></trace-query-result>

row 하나 해석해보기
- kberf-bt가 중요한 데이터

<row><sample-time id="2410" fmt="00:03.944.778">3944778916</sample-time><thread ref="509"/><core ref="240"/><thread-state ref="14"/><sentinel/><kperf-bt ref="2139"/><time-sample-kind ref="19"/></row>

sample-time	3.944초 지점에서 찍힌 샘플
thread	thread 509가 실행 중
core	CPU 코어 4 (ref=240)
thread-state	Running
kperf-bt	이 순간의 콜스택 (핵심 데이터)
sample-kind	Timer Fired

즉)

앱이 실행된 지 약 3.944초가 지났을 때(Time Profiler 샘플링 순간),
스레드 509(아마 Main Thread 또는 Worker Thread)가
CPU 4번 코어에서 Running 상태였고,
그 시점의 콜스택은 Backtrace ID 2139에 기록됐다.
이 샘플은 Timer Fired 이벤트로 찍혔다.

이 데이터를 가지고 시간이 많이 걸린 부분을 유의미한 데이터 파악이 위해서 아래와 같은 과정이 필요
- time-sample 데이터를 읽어서, 같은 Backtrace(kperf-bt ID) 또는 같은 함수 주소(symbol)로 그룹화 → 샘플 개수를 세면 → 가장 많이 찍힌 함수 = 가장 오래 걸린 부분
가장 많이 찍힌 함수가 왜 가장 오래걸렸는지 파악할 수 있는지?
- Time Profiler는 함수가 “얼마나 오래 실행됐는지” 직접 측정하지 않음
- 대신, 일정한 시간 간격(예: 1ms)에 한 번씩 CPU의 현재 스택을 찍기 때문에 카운트를 통해 오래걸렸는지 파악이 가능

[iOS - swift] 4. VScode 단축키 모음 (+깃헙 코파일럿)

jake-kim — Wed, 19 Nov 2025 01:51:55 +0900

1. 검색 관련

* 파일 탐색: cmd + P
* 문자열 전체 탐색: cmd + shift + F
* 파일 내 검색: cmd + shift + O
* 다음/이전 검색 결과로 이동: cmd + G / shift + cmd + G
* 검색된 상태에서 아래로 내려가기: cmd + ↓
* 현재파일에서 바꾸기: opt + cmd + F
* 전체파일에서 바꾸기: shift + cmd + H
* 현재파일 심볼 이름 바꾸기: F2
* 해당 폴더 안에서 검색: option + shift + F

2. 포커싱/탐색

* 코파일럿 챗 오픈 & 포커싱: ctrl + cmd + i
* 코파일럿 챗 클로즈 / 오픈: option + cmd + B
* 코파일럿 챗 agent / ask 모드 선택: cmd + .
* 커밋 그래프로 포커싱: ctrl + shift + G
* 현재 파일로 Explorer 포커싱: cmd + shift + E
* 탐색기에서 파일 포커싱: cmd + ↓
* 이전/다음 위치로 커서 이동: ctrl + -
* 다음 라인으로 커서 이동: cmd + enter
* 소스 편집기로 바로 포커싱: cmd + 1~9

3. 창/탭 이동

* 탭 닫기: cmd + W
* 탭 다 닫기: cmd + K 누른 후 W
* 닫은 탭 다시 열기: cmd + shift + T
* 창분할: cmd + \
* 창이동: cmd + 1~9
* 탭이동: ctrl + 1~9

4. 기타

* 터미널 열기/닫기: cmd + J
* 정의된 부분으로 점프: F12 또는 ctrl + 클릭
* 빌드: cmd + shift + B
* 라인이동: ctrl + g
* 커밋 그래프로 이동: ctrl + shift + G
* 휠 처럼 스크롤: ctrl + fn + page up/down
* 사이드바 숨기기/보기: cmd + B
* 영역 접기/펴기: opt + cmd + [ 또는 opt + cmd + ] * 영역 접기/펴기: opt + cmd + [ or ]
* 단축키창 열기: cmd + K + S
* 워닝나는 곳 자동 수정: cmd + .
* 절대경로 복사: 폴더 클릭 + option + cmd + C
* 파이썬 실행 단축키 설정: 단축키창 오픈 > run python file 검색 > option + R
* 코드 위로 or 아래로 이동: option + 방향키 위아래

* 깃 그래프 열기: ctrl + shift + cmd + C (커스텀 -> cmd+K cmd+C -> git graph: View git ...)

5. 깃

* 커밋: 단축키창 오픈 > git commit 입력 > ctrl + shift + C
* 푸시: 단축키창 오픈 > git push 입력 > ctrl + shift + P

6. VScode 세팅

VScode > cmd + shift + P > "Open User Settings (JSON)" 클릭
- setting.json 파일이 열리는데, 이 파일은 VScode를 사용할때, preference 설정을 json의 key-value객체로 저장하여 이것만 복붙해서 사용하면, 환경이 변경되어도 동일하게 사용가능

{
    "workbench.colorTheme": "Atom One Light",
    "github.copilot.nextEditSuggestions.enabled": true,
    "makefile.configureOnOpen": true,
    "files.autoSave": "afterDelay",
    "workbench.editor.showTabs": "single",
    "editor.minimap.enabled": false,
    "editor.wordWrap": "on",
    "python.defaultInterpreterPath": "/usr/local/bin/python3",
    "explorer.confirmDelete": false,
    "containers.containerClient": "com.microsoft.visualstudio.containers.docker",
    "containers.orchestratorClient": "com.microsoft.visualstudio.orchestrators.dockercompose",
    "git.enableSmartCommit": true,
    "git.useEditorAsCommitInput": false,
    "claudeCode.preferredLocation": "panel",
    "claudeCode.selectedModel": "default",
    "chat.viewSessions.enabled": false,
    "editor.find.seedSearchStringFromSelection": "never",
    "claudeCode.allowDangerouslySkipPermissions": true,
    "chat.tools.global.autoApprove": true
}

[iOS - swift] 3. VScode에 깃헙 코파일럿 활용 방법 (github copilot, 지침, 프롬프트, instruction, prompt)

jake-kim — Wed, 12 Nov 2025 01:11:41 +0900

<목차>

1. VScode에 깃헙 코파일럿 세팅 방법 (github copilot)

2. VScode에 깃헙 코파일럿 활용 방법 (github copilot, Ask, Agent, Edit)

3. VScode에 깃헙 코파일럿 활용 방법 (github copilot, 지침, 프롬프트)

지침 (Instruction)

“사전 정의된 규칙”이나 “코딩 컨벤션”, “프로젝트의 스타일 가이드” 등의 형태로 Copilot에게 알려줄 수 있는 정보
- ex) “모든 파일은 더블 쿼트(“”)를 사용하고, 탭으로 들여쓰기 한다”는 지침을 설정해두고, 나중에 프롬프트로 “이 함수 리팩토링해주세요” 했을 때 Copilot이 자동으로 해당 스타일을 반영해서 코드를 생성
적용하려는 폴더에 .github/copilot-instructions.md 파일을 생성
- 파일 이름은 "instructions.md"로만 끝나면 알아서 찾아서 해줌
- 여기에 지침을 적어서 AI에게 알려주는 형태

지침 적용 방법

프로젝트 루트에서 .github 폴더 생성 후 여기에 instructions.md 형태의 이름으로 작성

파일 생성

지침 적용하기
- 챗에 커서를 두고 `cmd + /` 단축키 > 지침 이름을 선택

챗을 확인해보면 my-instructions.md가 들어가있음
- 이제 여기에 어떤 요청을 하면 이 지침을 따라서 적용됨

프롬프트 (prompt)

마크다운 형식으로 작성된 재사용 가능한 프롬프트 템플릿
- 즉, 개발자가 자주 사용하는 프롬프트(예: 코드 생성 지시, 리팩토링 요청, 리뷰 요청 등)를 미리 정의해 놓고 필요할 때 꺼내 써서 일관된 형태로 GitHub Copilot에게 요청할 수 있게 해주는 기능

프롬프트 사용방법

./github/my-prompt.md 생성

아래와 같이 작성

my-prompt.md

[상황]
현재 이 ViewModel은 completion handler 기반으로 네트워크 요청을 수행합니다.
async/await 문법으로 바꾸고 싶습니다.

[명령]
fetchData() 함수를 async/await 구조로 리팩토링해주세요.

[조건]
에러 처리는 Result 타입 대신 do-catch로 해주세요.
Swift 5.9 문법 사용.

[출력]
주석 포함한 코드로 보여주세요.

이 프롬프트를 수행하고 싶은 경우, 지침과 동일하게 채팅 > `cmd + /` 누르고 적용

여기에 챗으로 요청하면 프롬프트에 내용에 맞게 답변을하거나 코드를 작성해줌

전역적으로 지침 적용하기

위에서 알아본건 `cmd + /`하여 지침을 따로 선택해야했지만, settings.json 파일을 만들어서 여기에 따로 선택 안하고 적용되도록 할 수 있음
- 루트 경로에 .github/settings.json 파일 생성

아래처럼 작성
- `github.copilot.chat.codeGeneration.instructions`를 키값으로하고, 배열로 text에 넣어주면 됨
- 이렇게하면 별도로 지침을 선택하면서 매번 적용하지 않아도됨

{
  "github.copilot.chat.codeGeneration.instructions": [
    {
      "text": "모든 코드는 한글로 주석을 작성해줘"
    }
  ],
}

* 참고

- https://docs.github.com/ko/copilot/how-tos/configure-custom-instructions/add-repository-instructions

- https://copilot-instructions.md/?utm_source=chatgpt.com

[iOS - swift] 2. VScode로 깃헙 코파일럿 기능 활용 방법 (github copilot, Ask, Agent, Edit)

jake-kim — Wed, 5 Nov 2025 01:10:30 +0900

<목차>

1. VScode에 깃헙 코파일럿 세팅 방법 (github copilot)

2. VScode에 깃헙 코파일럿 활용 방법 (github copilot, Ask, Agent, Edit)

3. VScode에 깃헙 코파일럿 활용 방법 (github copilot, 지침, 프롬프트)

깃헙 코파일럿 기능 - context단위로 물어보기

만약 mongodb 폴더에 관해 궁금한 경우?

폴더 오른쪽 마우스 클릭 > Add Folder to Chat 클릭

그럼 채팅에 mongosh 폴더 context가 들어가고 질문하면 완료

코드 editor에서 수정요청 하기

단축키 cmd + I 입력 > 인라인 채팅창이 보이면 여기에 필요한 요청을 적기

결과)
- 초록색으로 AI가 응답해주고, Accept을 누르면 적용됨

코드 적용하기

채팅에서 AI가 알려준 코드 부분에 마우스를 갖다대면 버튼들이 보여지는데, 이 버튼들은 코드에 적용시킬 수 있는 기능

여기서 앞 두 가지 버튼은 유용하게 쓸 수 있음

첫번째 버튼은 알아서 코드에 적용시켜달라는 것이고, 두번쨰 버튼은 코드부분에 있는 내 커서에 해당 코드를 적용시키라는 의미

채팅 타입 - Ask, Agent, Edit

vscode > chat 부분에 Ask로 되어있는 부분을 선택하면 3가지 옵션이 존재
- Ask: 질문-답변형 지원으로, 코드 변경 없이 “지식이나 설명이 필요할 때” 사용하기 좋음
  - “이 함수가 무슨 역할을 하나요?”
  - “이 라이브러리에서 어떤 패턴을 써야 하나요?”
  - “이 코드의 버그 원인은 뭘까요?”
- Edit: 코드 변경을 지시하고 직접 수정 제안을 받아보는 모드
  - “이 함수에서 async/await 방식으로 바꿔 주세요.”
  - “에러 핸들링을 추가해 주세요.”
  - “이 파일들에 null 체크를 넣어 주세요.”
- Agent: 가장 강력하고 “AI에게 큰 작업을 위임”하는 것
  - “이 앱에 인증 기능을 추가하고 테스트도 만들어 주세요.”
  - “이 코드베이스 전체를 최신 스타일로 리팩토링하고, 빌드/테스트까지 자동으로 돌려 주세요.”

모드	사용 상황	변경 가능성	AI 기여
Ask	개념 설명, 코드 이해, 빠른 질문	없음	낮음
Edit	특정 파일/구역에 대한 수정 지시	있음	중간 (사용자가 승인)
Agent	프로젝트 전체 또는 다파일 작업 위임 (오래걸림)	있음, 광범위한 변경 가능	높음 (AI 주도, 사용자가 검토)

사용 Tip
- 모르는 것이 있을 때 → Ask 모드
- 어떤 수정을 해야 할지 알고 있지만 직접 코딩은 피하고 싶을 때 → Edit 모드
- 큰 기능을 추가하거나 리팩토링/자동화 작업을 하고 싶을 때 → Agent 모드

[iOS - swift] 1. VScode에 깃헙 코파일럿 세팅 방법 (github copilot)

jake-kim — Wed, 29 Oct 2025 01:43:35 +0900

<목차>

1. VScode에 깃헙 코파일럿 세팅 방법 (github copilot)

2. VScode에 깃헙 코파일럿 활용 방법 (github copilot)

3. VScode에 깃헙 코파일럿 활용 방법 (github copilot, 지침, 프롬프트)

github copilot 개념

GitHub Copilot은 GitHub과 OpenAI가 공동 개발한 AI 프로그래밍 도우미
IDE에서 gpt5, claude code와 같은 것들을 사용할 수 있게 제공해주는것

github copilot의 기능

자동 코드 완성
- 주석이나 함수 이름만 써도 나머지 코드를 자동으로 제안
자연어 설명 기반 코드 생성
- “사용자 로그인 화면 만들기”처럼 자연어로 설명을 쓰면,
  그 설명에 맞는 코드를 자동으로 생성
다양한 언어 지원
- Swift, Python, JavaScript, TypeScript, C++, Go, Rust 등 거의 모든 주요 언어를 지원
IDE 통합
- vscode, Xcode와 같은 IDE에 통합되어 코드맥락을 더욱 잘 파악하며 답변해줄수있음

사용방법

github 로그인 > 프로필 클릭 > Copilot > Features 클릭

Start Using Copilot Free 선택

사용할수 있게 되었으므로 준비 완료
- 이제 남은것은 IDE에서 사용하는 것

vscode 에서 사용하는 방법

vscode > Extensions을 누르고, 검색창에 `github copilot` 입력
- 두 개 설치 (GitHub Copilot, GitHub Copilot Chat)
- `GitHub Copilot`하나만 설치하면 밑에껏도 자동으로 설치됨

설치하면 signin하라는 `Sign in with GitHub to use GitHub Copilot` 알림이 뜨는데 수행하기

만약 알림이 안보이면?
- cmd + shift + P 명령 팔레트 > github copilot을 검색하고 sign in 선택

연동 완료
- 오른쪽이 chat을 사용할수 있는 창
- cmd + option + B로 열고 닫을 수 있음

활용하기

ai 모델 변경하기
- 챗 아래쪽 모델 선택

여러가지 모델 확인 가능

[iOS - swift] 최적화 - 성능 모니터링 시스템 구축 사례 XCMetrics (스포티파이, XCMetrics 오픈소스)

jake-kim — Wed, 22 Oct 2025 01:06:26 +0900

XCMetrics 오픈소스

XCMetrics를 통해 성능 관련 내용들을 시각화

오픈소스
- github: https://github.com/spotify/XCMetrics
- 스포티파이가 만든 오픈소스이며, 성능에 관해 실시간으로 모니터링 할 수 있는 시스템
- xcactivitylog 형식으로 저장된 Xcode 및 xcodebuild 로그를 파싱할 수 있는 도구인 XCLogParser를 기반으로 구축
- Spotify iOS 앱에서 약 100만 개의 빌드와 100억 개 이상의 단계를 수집했고, 이를 통해 프로젝트 구조 및 아키텍처와 관련하여 중요하고 정보에 기반한 결정을 내릴 수 있음
이점
- xcactivitylog 파일에서 데이터를 추출하여 빌드 시간, 경고, 오류 및 기타 메타데이터를 원하는 방식으로 볼 수 있음
  - 정렬, 검색이 가능하여, 어떤 부분이 빌드 시간이 오래걸리고 언제부터 문제가 있었는지 파악이 가능

xcmetrics 콘솔

XCMetrics의 원리

Xcode는 테스트, 프로덕션 환경 모두 xcodebuild는 xcactivitylog라는 로그 파일을 생성함
xcactivitylog라는 로그 파일을 보면, 경고, 오류, 빌드 시간 등 유용한 성능에 관한 정보를 얻을 수 있음

XCMetrics 구조

백엔드쪽은 Swift로 작성되어있고, multipart request를 통해 메타데이터를 첨부
데이터베이스는 ProgresSQL이 사용되어 있으며, 데이터가 날짜별로 분기되어있음

https://engineering.atspotify.com/2021/1/introducing-xcmetrics-our-all-in-one-tool-for-tracking-xcode-build-metrics

스포티파이와 XCMetrics

스포티파이는 아래 사진과 같이 코드베이스와 상태를 모니터링하기 위해 매일 사용되는 데이터 파이프라인과 대시보드가 존재
- XCMetrics를 통해 로그를 파악하면서 프로젝트 구조에 대해서 많은 개선을 시도함
- 빌드 숫자, 코드 커버리지, 통계, 용량, warnings, errors 등 파악에 용이

* 참고

- https://github.com/spotify/XCMetrics

- https://engineering.atspotify.com/2021/1/introducing-xcmetrics-our-all-in-one-tool-for-tracking-xcode-build-metrics

[iOS - swift] 최적화 - Instruments로 행 분석하는 방법 (Analyze hangs with Instruments)

jake-kim — Wed, 15 Oct 2025 01:10:34 +0900

행이란?

사용자가 앱을 쓸 때 지연된다고 느껴지는 것
- 예) 사용자가 버튼을 누른 경우, 조금 있다가 반응한다는 느낌을 주는 것
애플에서 제공하는 가이드)

https://developer.apple.com/videos/play/wwdc2023/10248/

의미

Instant	즉각적인	반응이 바로 느껴질 정도로 빠름 (~100ms 이내)
Circumstantial	상황에 따라 달라지는, 약간 느리지만 용인됨	약간의 지연(~250ms)은 사용자가 느끼지만 불편하지 않음
Microhang	미세한 멈춤	눈에 띄는 짧은 멈춤 (~500ms 미만)
Hang	완전한 멈춤(먹통)	반응이 끊기거나 멈춘 듯한 상태 (~500ms 이상)

즉, 즉각적이려면 100ms 이내로 동작하게끔해야함
또 행의 기준은 500ms 이상 걸리는 동작을 의미함

행 파악하는 방법

위에서 알아본대로 500ms 이상 걸리는 작업을 행이라고 정의
이 행은 Instruments의 Time Profiler에서 확인이 가능
- Time Profiler 관련 기초 내용은 이전 포스팅 글 참고

(Instruemtns > Time Profiler 중 Hangs 부분)

https://developer.apple.com/videos/play/wwdc2023/10248/

여기서 보여지는 Severe Hang은 3.44초가 걸렸는데 단순히 오래걸린다는 의미에는 Too long 말고도 Too often도 존재

Main Thread가 바쁜 경우

3.44초가 걸린 행을 분석할때는 세 가지 관점으로 먼저 생각 필요
- 오래 걸림 (Too long)
- 자주 불림 (Too often)
- 메인스레드가 blocked 됨

이것을 어떻게 구분할 것인가?
- 우선 메인 스레드가 block된지 유무는 쉽게 파악이 가능
- hangs 부분의 하위의 Main Thread의 그래프를 보면 hang 시점에 그래프가 들쑥날쑥 보이는 것과 아예 그래프가 없는 것으로 확인이 가능

오래 걸림 vs 자주 불림 구분 방법

	오래 걸림 (Too long)	자주 불림 (Too often)
Flame Graph	가로로 긴 막대, 길게 이어짐	짧은 막대가 반복적으로 여러 곳에 흩어짐
Call Tree	Calls 적음, Self Time 높음	Calls 많음, Avg Time 낮음
Timeline	굵은 덩어리 하나로 CPU 점유	얇은 점들이 계속 반복, 일정한 패턴

코드 확인하는 방법: Time Profiler의 CPU Usage와 동일 (이전 포스팅 글 참고)

* 참고

- https://green1229.tistory.com/509

- https://developer.apple.com/videos/play/wwdc2023/10248/

[iOS - swift] 최적화 - Instrument의 Time Profiler

jake-kim — Wed, 8 Oct 2025 21:04:07 +0900

Time Profiler

Xcode > Cmd + I로 Instrument 실행 > Time Profiler 선택

창이 뜨면 Record 버튼을 눌러서 앱을 실행

중지 버튼을 눌러서 분석 중지

그래프를 보면 삐쭉 튀어나와있는 부분에 커서를 대면 시간이 얼마나 걸렸는지 알 수 있음

그 부분을 왼쪽마우스로 클릭하고 아래 로그를 보면 어떤 부분에서 시간이 걸렸는지 확인이 가능

더 구체적으로 확인 방법

위에 까지 알아본 방법은 대충 어떤 함수가 많이 걸리는지 알려주는데 더욱 구체적인 back trace를 보고싶은 경우는 아래처럼 처리가 필요
Samples를 클릭

Profile 클릭

하단 로그를 보면 아래처럼 누적값으로 Weight가 표시되는데 가장 큰 weight가 증가한 start부분을 펼치기

option + 왼쪽마우스 클릭하면 다 펼쳐짐

여기서 증가량이 많은 해당 부분을 클릭

또 펼쳐서 계속 확인해보면 마침내 어디에서부터 시작되었는지와 이 이후에 어떤것들이 불렸는지 알 수 있음

호출 순서: 빨간 화살표
- Example1.heavyWork()가 호출되고나서 forEach 그다음 heavyWork() 그다음 fib() 순서로 파악이 가능하고 마침내 fib()에서 시간이 많이 걸렸다는 의미

[iOS - SwiftUI] 헷갈리기 쉬운 frame(maxWidth: .infinity) 이해하기 (#Rounded 처리)

jake-kim — Wed, 1 Oct 2025 00:35:37 +0900

frame(maxWidth: .infinity)의 의미

"부모가 줄 수 있는 만큼 가로폭을 가득 채워라" 란 의미
- frame(maxWidth: .infinity)는 최대 크기를 제한 한다는 느낌을 주는데 이 의미가 아님
다른 예제)
- 아래처럼 텍스트가 좌우 24 패딩을 갖는 뷰 구현?

여기도 frame(maxWidth: .infinity)를 추가하여 구현

struct Example1: View {
    var body: some View {
        VStack {
            Text("Hello")
                .frame(maxWidth: .infinity) // <-
                .background(Color.red)
                .padding(.horizontal, 24)
            
            Text("World")
                .frame(maxWidth: .infinity)
                .background(Color.blue)
                .padding(.horizontal, 24)
        }
    }
}

Rounded 처리 방법

보통 외부 마진을 주고 버튼이 수평으로 쫙 펼친 아래와 같은 것을 요건이 있는 경우?

구현하다보면 아래처럼 내부 콘텐츠에 fit하게 작성되는 경우가 존재

코드

struct ContentView: View {
    var body: some View {
        VStack(spacing: 0) {
            Text("title")
                .font(.title)

            Spacer()
                .frame(height: 8)

            Text("desc")
        }
        .padding(.horizontal, 15)
        .padding(.vertical, 20)
        .background(Color.blue)
        .clipShape(RoundedRectangle(cornerRadius: 16))
        .padding(.horizontal, 45)
    }
}

이럴땐 frame(maxWidth: .infinity)를 추가하여 해결이 가능
- frame(maxWidth: .infinity)는 최대 크기를 고정한다는 느낌을 주는데 이 의미가 아님을 주의

struct ContentView: View {
    var body: some View {
        VStack(spacing: 0) {
            Text("title")
                .font(.title)

            Spacer()
                .frame(height: 8)

            Text("desc")
        }
        .padding(.horizontal, 15)
        .padding(.vertical, 20)
        .frame(maxWidth: .infinity) //<-
        .background(Color.blue)
        .clipShape(RoundedRectangle(cornerRadius: 16))
        .padding(.horizontal, 45)
    }
}

[iOS - Swift] SwiftUI - Environmnet로 인터페이스 제공 방법 (#링크 텍스트)

jake-kim — Wed, 24 Sep 2025 01:47:54 +0900

인터페이스 제공 방법

만약 링크 터치 이벤트를 처리하는 LinkDetectionText를 만들고 싶은 경우, LinkDetectionText 내부에서 해당 프로퍼티를 사용
- \.openURL의 정체: SwiftUI가 미리 정의한 EnvironmentKey

@Environment(\.openURL) private var openURL

아래처럼 openURL 프로퍼티를 선언한 후 이 프로퍼티를 마치 클로저처럼 실행시키면, 외부에서 사용이 가능

struct LinkDetectingText: View {
    @Environment(\.openURL) private var openURL // <-
    let text: String
    
    var body: some View {
        Text(makeAttributedString(from: text))
            .onOpenURL { url in
                openURL(url) // <-
            }
            .padding()
    }
    
    private func makeAttributedString(from string: String) -> AttributedString {
        ...
    }
}

외부에서는 openURL 키를 가지고 envionment 함수의 클로저에서 이벤트 핸들링이 가능

ContentView()
    .environment(\.openURL, OpenURLAction { url in
        print("링크 클릭됨:", url)
        return .handled
    })
    .padding()

openURL뿐만이 아닌 EnvironmentKey를 따로 정의하여 외부에 인터페이스 제공이 가능

완성)

전체코드)

import SwiftUI

@main
struct CounterDemoApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(\.openURL, OpenURLAction { url in
                    print("링크 클릭됨:", url)
                    return .handled
                })
                .padding()
        }
    }
}

struct LinkDetectingText: View {
    @Environment(\.openURL) private var openURL
    let text: String
    
    var body: some View {
        Text(makeAttributedString(from: text))
            .onOpenURL { url in
                openURL(url)
            }
            .padding()
    }
    
    private func makeAttributedString(from string: String) -> AttributedString {
        var attributed = AttributedString(string)
        if let detector = try? NSDataDetector(types: NSTextCheckingResult.CheckingType.link.rawValue) {
            let matches = detector.matches(in: string, options: [], range: NSRange(location: 0, length: (string as NSString).length))
            for match in matches {
                if let range = Range(match.range, in: string),
                   let url = match.url {
                    let linkRange = attributed.range(of: String(string[range]))!
                    attributed[linkRange].link = url
                    attributed[linkRange].foregroundColor = .blue
                    attributed[linkRange].underlineStyle = .single
                }
            }
        }
        return attributed
    }
}

struct ContentView: View {
    var body: some View {
        VStack(spacing: 20) {
            LinkDetectingText(text: "이건 그냥 텍스트고 https://apple.com 은 링크야.")
            LinkDetectingText(text: "여기서도 https://google.com 클릭 가능")
        }
    }
}

[WWDC2025] SwiftUI 최적화 프로파일링 - Optimize SwiftUI performance with Instruments (4, Render Loop 개념, 업데이트 빈도수 파악하기)

jake-kim — Wed, 17 Sep 2025 01:24:13 +0900

View 업데이트 빈도수 파악하기

View의 body부분에서 업데이트가 너무 많게되면 아래 사진처럼 데드라인을 넘게되는 경우가 존재
- -> hitch가 발생

업데이트 수 프로파일링 방법

View Body Updates 하위 트랙 선택

빨간선 or 주황선 부분을 드래그하여 영역 선택

LandmarkListItemView에 Update Count가 30으로 찍혀있음

View코드를 작성할 때 이 부분을 확인해보면 내가 의도된 업데이트 카운트로 구현했는지 알 수 있음
- 만약, List와 Row가 있는 뷰를 구현할 때 Row에 state하나만 바꿨을때, List전체가 업데이트 되었는지 파악하는 용도로도 사용이 가능

* 참고

- https://developer.apple.com/videos/play/wwdc2025/306/

[WWDC2025] SwiftUI 최적화 프로파일링 - Optimize SwiftUI performance with Instruments (3, Render Loop 개념, 화면이 끊기는 원리, hitch)

jake-kim — Wed, 10 Sep 2025 01:35:08 +0900

프레임 드랍(Hitch)이 일어나는 과정 (Render Loop)

앱은 특정 싸이클마다 깨어나면서 이벤트를 처리
- 아래처럼 싸이클마다 클릭 이벤트를 인식하고 UI를 업데이트
- 이때 변경된 SwiftUI View의 body 프로퍼티를 실행함

이 UI를 업데이트 하는 과정들은 각 주기 프레임 데드라인전에 완료되어야함
- 즉 데드라인 전에 UI가 업데이트 되는 것
- 렌더링 된 출력은 해당 데드라인 직후에 화면에 표출됨 (주의: 첫번째 프레임에서 내부적인 UI 관련 업데이트를 하고 화면에 보이는 것은 다음 프레임에서 수행)

아래와 같은 프레임 드랍 케이스의 Render Loop는?
- UI 업데이트 부분이 프레임 데드라인 후에 실행되었음
- 이미 두 번째 프레임에서는 첫번째 UI 업데이트를 썼으므로 다음 업데이트는 3번째 프레임에서 시작해야함

아래 화면과 같이 2번째 loop에서 `Nothing to render!`됨
- 주의) 첫번째 프레임에서 내부적인 UI 관련 업데이트를 하고 화면에 보이는 것은 다음 프레임에서 수행하기 때문에 두번째 프레임에서 화면에 아무것도 업데이트가 안되는것

그럼 늦게 UI Update된 프레임은 화면에 언제 그려지는 걸까?
- 3번째 프레임도 아님: 3번째 프레임에서는 Render 하는것에 자원을 사용하므로 결국 4번째 프레임에 그려짐

SwiftUI의 뷰 업데이트

위에서 알아본대로 Render Loop를 이해하여 SwiftUI의 Body부분에서 View Updates가 많이 일어나면 끊김 현상이 발생할 수 있다는 것을 이해
Instrument를 통해 이런 부분을 발견하고 개선하는것이 필요

(... View Update Count를 보고 업데이트가 많이 일어나는 부분을 분석하는 내용은 다음 글에서 계속)

* 참고

- https://developer.apple.com/videos/play/wwdc2025/306/

[WWDC2025] SwiftUI 최적화 프로파일링 - Optimize SwiftUI performance with Instruments (2)

jake-kim — Wed, 3 Sep 2025 01:47:47 +0900

SwiftUI 프로파일링

Instrument > SwiftUI 선택하고 프로파일 수행
- 먼저 SwiftUI 로 되어있는 꺽쇠를 클릭 > View Body Updates > 영역을 드래그하여 지정한 후 해당 영역 set Inspection Range And Zooms 클릭 > Time Profiler 클릭
  - 이전 포스팅 글 참고: https://ios-development.tistory.com/1812

Time Profiler는 정기적으로 샘플을 추출하여 현재 실행중인 함수에 대한 분석을 시도
- 뒤에서 나올 예제는 body가 실행되는 동안 프로파일링

WWDC 영상처럼 호출 스택이 여러가지가 표출됨
이 중에서 살펴볼 것은 LandmarkListItemView이므로 command + F를 하여 검색

왼쪽을 보면 각 call stack안에 해당하는 프레임에 대한 소요 시간을 의미
- 여기서 가중치가 높은 프레임을 찾아서 그 코드를 파악하기가 가능
- 그 중에서 body부분이 관심이 있으므로 여기를 클릭해서 확인

프로파일링하기
- 왼쪽을 더 보면, 아래와 위가 차이가 많이 나는 구간을 파악이 가능
- 첫번째: 58.9%에서 73.7로 간 부분
- 두번째: 31.6%에서 57.9%로 간 부분

클릭하면 해당 부분의 코드가 표출

프로파일링 결과 NSMeasurementFormatter 부분으로 확인
- 코드에서 이 부분을 확인

body에서 이 distance 변수를 뷰가 업데이트 될때마다 호출하고 있음

프로파일링을 하면 시간이 ms 단위로 적게 느껴지지만 이 시간들이 누적이 되면 사용성에 영향을 줄 수 있으므로 개선이 필요

(SwiftUI가 body를 실행하는데 걸리는 시간을 이해하는데 먼저 render loop 개념이 필요한데, 이 개념은 다음 글에서 계속..)

* 참고

- https://developer.apple.com/videos/play/wwdc2025/306/

[WWDC2025] SwiftUI 최적화 프로파일링 - Optimize SwiftUI performance with Instruments (1)

jake-kim — Wed, 27 Aug 2025 01:46:31 +0900

SwiftUI 최적화 방향

SwiftUI 코드가 병목 현상인 시점을 식별 할 수 있는 방법을 중점으로 두고 SwiftUI가 효율적으로 작동하는 방법을 알아보는 것이 목적
- 병목 현상) 애니메이션이 일시 중지되거나, 점프되거나 스크롤이 지연되는 경우
성능 문제를 식별하는 가장 좋은 방법은 Xcode Instrument를 사용하여 앱을 프로파일링하는 것
XCode 26부터 SwiftUI 프로파일링 할 수 있는 방법이 등장
- Instrument > SwiftUI 메뉴

프로파일링에서 볼 수 있는 것
- Long View Body Updates: body 프로퍼티를 실행하는데 너무 오래 걸릴때 표시가 됨
- Long Representable Updates: View와 ViewController가 너무 오래 걸릴때 표시가 됨
- Other Long Updates: 모든 유형의 긴 update가 너무 오래 걸릴때 보여줌
- (주황색과 빨간색으로 표시됨)

프로파일링에서 볼 수 있는 것 - Time Profiler
- 앱이 시간이 지남에 따라 CPU에서 수행하는 작업 샘플을 보여줌

SwiftUI Instrument requiremens

Xcode 26 다운로드
Xcode 열기 > Command I로 instrument 실행
특정앱을 프로파일링하면, Long View Body Updates에서 주황색 선이 보여짐

View Body Updates 부분을 클릭하면, 아래처럼 데이터가 보임

Summary: View Body Updates 부분을 누르면 아래처럼 세분화하여 보기 가능

긴 업데이트가 표시되는 부분을 확인 가능

`->` 오른쪽 화살표를 누르면 더 세분화하여 볼 수 있음

오른쪽 마우스 클릭 > `Set Inspection Range and Zoom` 클릭

Instrument 그래프에 해당 부분으로 펼쳐서 보여짐

(다음 글에서 계속..)

* 참고

- https://developer.apple.com/videos/play/wwdc2025/306/

[iOS - swift] 디스플레이 확대/축소, 화면 확대 모드 감지 방법 (더 큰 텍스트, UIScreen.main.scale, UIScreen.main.nativeScale)

jake-kim — Wed, 20 Aug 2025 01:22:39 +0900

더 큰 텍스트 효과란?

더 큰 텍스트 효과 사용 시, 시스템 전체에 영향이 가서 아래처럼 UILabel같은 컴포넌트들이 커짐
- 더 큰 텍스트 효과 적용 방법은 아래에서 설명

앱 뿐만이 아닌 시스템 앱에도 영향

설정 > 디스플레이 및 밝기 > 디스플레이 확대/축소 >

더 큰 텍스트 선택 시, 적용됨

코드에서 확대/축소 감지 방법

UIScreen.main.nativeScale 사용
- 하드웨어 디스플레이가 렌더링하는 원래 배율을 의미
- 디스플레이 확대/축소에서 확대 옵션을 켜면 3.0이 3.65625으로 나옴
cf) 일반적으로 많이 아는 UIScreen.main.scale은 UIKit이 사용하는 기본 좌표계(points)와 실제 픽셀(pixels)의 배율을 의미
- 일반 Retina 디스플레이: scale = 2.0
- Super Retina (iPhone X 이후): scale = 3.0
아래와같이 UIScreen의 확장으로 구현

extension UIScreen {
    static var isDisplayZoomed: Bool {
        let screen = UIScreen.main
        return abs(screen.nativeScale - screen.scale) > .ulpOfOne
    }
}

`ulpOfOne`은 0에 가까운 값이며 부동소수점 오차가 있을 수 있기에 이 것을 사용한 것
예) 3.0 - 2.9999999999999996 → 사람이 보기엔 같지만, 기계적으로는 차이가 존재
이런 미세한 차이를 "사실상 0" 으로 처리하기 위해 ulpOfOne 을 임계값으로 둔 것
- 차이가 ulpOfOne 이하 → 사실상 같은 값 (확대 모드 아님)
- 차이가 ulpOfOne 초과 → 의미 있는 차이 (확대 모드임)

[iOS - swift] WWDC2025 정리 - 백그라운드에서 작업하는 방법 4 (Request background runtime, beginBackgroundTask)

jake-kim — Wed, 13 Aug 2025 01:08:00 +0900

iOS 26의 BGContinuedProcessingTask

백그라운드에서 지속적으로 처리가 필요한 작업들에 사용
앱은 백그라운드 진입 후에도 시스템은 UI를 통해 진행 상황을 표시

ex) 앱에서 내보내기 설정 > 백그라운드 진입 시 상단에 진행 상태 표시해주는 `Journal` 앱

백그라운드에서 언제든 작업을 취소할 수도 있음

BGContinuedProcessingTask의 특징

명확한 사용자 행동으로 시작 (버튼, 클릭 등)
- 예) 파일 추출, sns 업로드
사용자는 작업이 자동으로 시작되리라 기대하지 않음
- BGContinuedProcessingTask으로 안되는 예) 백업, 사진 동기화
즉 예상하지 못하는 작업을 이 API에는 사용하면 안됨

BGContinuedProcessingTask 사용 방법

1. info.plist에서 작업 식별자를 추가
- Permitted background task scheduler identifiers 키 값으로 value에는 앱 bundle id로 추가

2. BGTaskScheduler를 사용하고 클로저 안에서 수행
- 만료되었을때 처리도 필요하여(아래에서 나올 예정) 아래처럼 shouldContinue라는 플래그를 사용

만료되었을때 처리인 setTaskCompleted(success:)를 반드시 호출해주어야함

3. UI 띄우기
- BGContinueProcessingTaskRequest 인스턴스의 파라미터에 id에는 info.plist에 입력한 bundle id 입력
- 백그라운드에서 사용자가 볼 제목인 title, subtitle을 입력

처리 전략 설정하고 BGTaskScheduler에 submit하면 완료

백그라운드 GPU

백그라운드에서도 GPU를 사용할 수 있는데 이것은 Xcode 프로젝트 설정에서 백그라운드 GPU 기능을 추가해주어야함

코드 레벨에서는 supportedResource로 체크한 후 reqruiedResources에 .gpu할당하여 사용

* 참고

- https://developer.apple.com/kr/videos/play/wwdc2025/227/

[iOS - swift] WWDC2025 정리 - 백그라운드에서 작업하는 방법 3 (Request background runtime, beginBackgroundTask)

jake-kim — Wed, 6 Aug 2025 01:59:50 +0900

Request background runtime

백그라운드에서 특정 처리를 하고싶은 경우 사용
- 백그라운드에서 생성된 데이터를 바탕으로 ML을 생성하는 등의 처리를 하고 싶은 경우 사용
- 백그라운드에서 DB를 클리어하고싶은 경우 사용

등록 방법
- AppDelegate에서 forTaskWithIDentifier로 등록

closure부분에 런타임에 호출할 내용만 작성해주면 완료

아래처럼 request를 만들고 submit하면 동작이됨
- 배터리 소모를 최소화하고 앱의 배터리 사용량도 줄어들게 하고싶은 경우?
- 아래처럼 requiresNetworkConnectivity나 requiresExternalPower 파라미터에 값을 세팅하여 섬세한 처리가 가능
- ex) 작업이 지연에 민감하지 않은 경우? > 충전 중이면서 네트워크에 연결됐을 때만 작업이 실행되도록 설정

beginBackgroundTask

백그라운드 작업 시작 및 종료 API
백그라운드로 전환되었을때 복구가 어려운 작업을 마무리할 수 있게 도와주는 것

ex) DB에 관한 처리를 진행하다가 작업이 중단되면 파일을 닫는 처리가 누락될 수 있는데 이 API를 통해서 닫는 처리를 수월하게 할 수 있음

만약 아래처럼 export.saveState()로 상태를 안전하게 저장해야하는경우?

아래처럼 beginBackgroundTask로 감싸면 시스템에 중요한 작업이 진행 중임을 알릴 수 있고 중단을 피할 수 있음

* 참고

- https://developer.apple.com/kr/videos/play/wwdc2025/227/

[iOS - swift] WWDC2025 정리 - 백그라운드에서 작업하는 방법 2 (background)

jake-kim — Wed, 30 Jul 2025 01:20:15 +0900

백그라운드 처리를 할때 고려하는것

백그라운드에서 처리할 때 프로세스 입장에서 고려하는 것들
- 배터리 생명주기
- 공유 자원 (Memory, CPU, 네트워크 대역폭, 저전력 모드, 적은 데이터 모드)

ex) 공유 자원 예시 - 포그라운드 관점

백그라운드에 너무 많은 자원을 사용하면 비효율적으로 처리가 될 뿐 아니라 포그라운드 경험과도 충돌되므로 백그라운드에 있는것들 종료할 수 있음
때문에 백그라운드 작업을 최소화하여 메모리 사용량을 줄여야함
또한 사용자가 저전력 모드를 키는 성격을 고려하여 사용자 관점에서 생각하며 설계해야함

애플에서 권고하는 백그라운드 처리 방향

효율성, 최소성, 탄력성, 신중함, 적응성

백그라운드 작업을 한다는 것은 런타임 기회가 생길 때마다 점진적 진행이 가능해야함
(시스템 조건과 우선순위를 이해하고 적응할수록 작업 성공률은 더욱 높아짐)
작업은 작고 가볍게 유지할 것
필요 사항은 명확히 전달해야할 것

백그라운드 작업을 할 때 체크리스트

이 작업은 누가 시작했는가?
명시적으로 시작된 작업인가? 아니면 나중에 실행해도 되는 선택적 작업인가?
작업 소요 시간은 얼마나 되는가?
작업은 앱 상태나 최신도에 중요한가?
이 작업은 사용자의 동의나 입력이 필요한가? (필요하면 백그라운드 런타임은 적절하지 않음)

Background API 1) BGAppRefreshTask - 새로고침에 사용

BGAppRefreshTask API
- 새로고침에 사용 > 서버에서 조용히 콘텐츠를 불러오는 용도
- 자주 사용하는 앱 일수록 작업이 예약될 확률이 높아짐 (시스템에서 빈도수가 많은 앱 위주로 우선순위를 정함)

SwiftUI 코드: .backgroundTask를 사용하여 실행
- 앱이 백그라운드일 때 시스템은 해당 클로저를 호출함

Background API 2) Background Push Notification

서버에서 새 콘텐츠 알림을 보낼때, 시스템이 적절한 시점에 앱을 깨워 콘텐츠를 가져오게함
- BGAppRefreshTask와는 다르게 데이터를 직접 요청하는 게 아니라 업데이트가 푸시되는 형식
새로운 원격 콘텐츠가 있다는 신호로 씀
- 1) 새로운 원격 콘텐츠가 있다는 신호
- 2) 낮은 우선순위 작업이므로 과부하와 배터리 소모를 최소화함
- 3) 사용자가 앱을 종료하면 시스템은 그 의도를 존중하여 앱이 다시 실행되기 전까지는 알림을 전달하지 않음

* 참고

- https://developer.apple.com/kr/videos/play/wwdc2025/227/

[iOS - swift] WWDC2025 정리 - 백그라운드에서 작업하는 방법 1 (background)

jake-kim — Wed, 23 Jul 2025 01:51:53 +0900

백그라운드 작업이란?

사용자가 앱을 나가고도 프로세스가 살아 있으면 앱은 백그라운드로 전환됨
앱은 일시중단되며,"Suspended" CPU를 사용하지 않게됨
- 배터리를 보호하고 개인 정보를 지키는 역할
- 포그라운드 앱에 리소스를 확보해 줌
- (앱은 일시중단 전 작업을 마무리할 수 있도록 백그라운드 실행 시간을 요청할 수 있음)

위처럼 백그라운드 상태를 잘 사용하려면 시스템이 리소스를 어떻게 우선순위화하고 관리하는지, 앱 안에서 무엇을 할 수 있는지 이해하는것이 좋음

백그라운드를 이해하는 핵심

애플이 백그라운드 상태를 만드는 목적의 핵심은 `배터리 수명`을 보호하고 `성능을 최적화`하여 부드럽고 반응성 있는 사용 경험을 유지하는 것
- 때문에 백그라운드 실행은 보장되지 않음
- 기회가 있을 때만 허용되고 대부분은 재량에 따라 엄격히 관리됨

시스템과 협력하는 방향

가장 기본적인 제약은 에너지
- ex 에너지) 모든 작업, CPU 사이클, GPU 렌더링, 네트워크 요청
백그라운드 런타임은 제한적이므로 할 일은 작고 명확한 개별 작업으로 구성해야 함
각 작업은 시스템의 우선순위와 제약을 고려해 효율적으로 하나의 일을 처리해야 함
cf) 아이폰에서 백그라운드 작업의 상태를 보려면 설정 > 배터리에서 볼 수 있음

다음 포스팅 글에서 계속..

* 참고

- https://developer.apple.com/kr/videos/play/wwdc2025/227/