Skip to content

CLAUDE.md

Latest commit

 

History

History
172 lines (135 loc) · 7.31 KB

CLAUDE.md

File metadata and controls

172 lines (135 loc) · 7.31 KB

CLAUDE.md

Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

  • State your assumptions explicitly. If uncertain, ask.
  • If multiple interpretations exist, present them - don't pick silently.
  • If a simpler approach exists, say so. Push back when warranted.
  • If something is unclear, stop. Name what's confusing. Ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

  • No features beyond what was asked.
  • No abstractions for single-use code.
  • No "flexibility" or "configurability" that wasn't requested.
  • No error handling for impossible scenarios.
  • If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

  • Don't "improve" adjacent code, comments, or formatting.
  • Don't refactor things that aren't broken.
  • Match existing style, even if you'd do it differently.
  • If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:

  • Remove imports/variables/functions that YOUR changes made unused.
  • Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

  • "Add validation" → "Write tests for invalid inputs, then make them pass"
  • "Fix the bug" → "Write a test that reproduces it, then make it pass"
  • "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

Runnect-iOS (프로젝트 specific)

프로젝트 개요

  • 앱 이름: Runnect (러넥트) — 러닝과 일상을 연결하는 달리기 앱
  • 플랫폼: iOS (UIKit)
  • 언어: Swift 5.9
  • 최소 타겟: iOS 17.0
  • Xcode: 16.0
  • 패키지 관리: Swift Package Manager (SPM) — v2.5.0에서 CocoaPods → SPM 마이그레이션 완료
  • 앱스토어: 배포 중

⚠️ 보안 — public GitHub 저장소

본 레포는 public 저장소. 아래 파일은 절대 commit / push 금지:

파일 포함 secret
Runnect-iOS/Network/Foundation/Config.swift 서버 baseURL, kakaoRestAPIKey, tmapAPIKey, kakaoNativeAppKey, naverMapClientId, 개발자 패스워드
Runnect-iOS/Network/Foundation/AdConfig.swift AdMob 광고 단위 ID
Runnect-iOS/GoogleService-Info.plist Firebase 설정

관리 흐름:

  • 위 파일 모두 .gitignore 등록 + 메인 레포에서 추적 해제됨
  • 실제 값은 별도 private 레포 thingineeer/thingineeer-env 의 Runnect-env/ 에서 관리
  • 신규 셋업: gh auth login 후 git root 에서 ./bin/setup 한 줄로 자동 배치
    • gh CLI 본인 계정 인증을 활용해 private 레포 접근. 권한 없는 계정은 자동 차단

작업 시 주의:

  • git status --ignored 가 아닌 일반 status 에는 안 보이지만, 실수로라도 git add -f / staged 처리 / commit 금지
  • 신규 secret 추가 시 위 패턴 따를 것 (gitignore 등록 + private 레포 보관)
  • AI 도구(Claude 등) 사용 시에도 이 규칙 적용 — Config/AdConfig 변경분이 PR diff 에 절대 포함되면 안 됨

주요 라이브러리 (SPM)

라이브러리 용도
Moya 네트워킹
SnapKit Auto Layout
Then UI 편의
Kingfisher 이미지 로딩
NMapsMap 네이버 지도 SDK
Google-Mobile-Ads-SDK AdMob 광고
FirebaseAnalytics 애널리틱스

의존성은 Runnect-iOS.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved 에서 관리. Xcode 가 자동 resolve.

브랜치 전략

  • 메인 브랜치: develop
  • Feature 브랜치: feature/v{버전}-{설명}
  • Fix 브랜치: fix/v{버전}-{설명}
  • Chore 브랜치: chore/v{버전}-{설명}
  • PR 대상: 본체 레포 Runnect/Runnect-iOS → develop
  • 포크: thingineeer/Runnect-iOS
  • 머지 후: 로컬 + 리모트 브랜치 삭제

커밋 컨벤션

  • 형식: <type>: <한국어 명사형 제목>
  • 타입: feat, fix, refactor, style, docs, chore, test
  • 제목: 한국어, 50자 이내, 명사형
  • 본문: - 불릿 포인트로 how 설명
  • Author: thingineeer <dlaudwls1203@gmail.com>
  • 금지: Co-Authored-By: Claude, Generated with Claude Code 등 AI 관련 표기 절대 금지

PR 컨벤션

  • 제목 형식: [Prefix] - 한국어 제목
  • Prefix: Feat, Fix, Refactor, Style, Docs, Chore, Test (첫글자 대문자)
  • 예시: [Feat] - 코스 발견 성능 최적화 및 UX 개선
  • Assignee: 항상 --assignee @me (thingineeer) 지정
  • 성과 기록: 빌드 시간 단축, 코드 라인 수 변화, 성능 수치 등 측정 가능한 데이터는 PR 본문에 반드시 포함
  • Labels: PR prefix에 맞는 라벨 + 명진😼 항상 추가 (Feat, Fix, Refactor, Chore, Del, UX, Setting, Docs 등)
  • 본문 템플릿 (.github/PULL_REQUEST_TEMPLATE.md):
    • 🌱 작업한 내용
    • 🌱 PR Point
    • 📸 스크린샷
    • 📮 관련 이슈

프로젝트 구조

Runnect-iOS/
├── Runnect-iOS/
│   ├── Presentation/          # 화면별 UI (VC, View, Cell)
│   │   ├── CourseDiscovery/   # 코스 발견
│   │   ├── CourseDrawing/     # 코스 그리기
│   │   ├── CourseStorage/     # 보관함
│   │   └── MyPage/           # 마이페이지
│   ├── Network/               # API 통신 (Moya)
│   ├── Global/                # 공통 유틸, 익스텐션
│   └── Resource/              # 에셋, 폰트
├── .github/                   # PR 템플릿, 워크플로우
├── bin/setup                  # 신규 클론 환경 자동 셋업 (secret 배치)
└── Runnect-iOS.xcodeproj      # SPM 의존성 포함

배포 (Fastlane)

  • fastlane release version:X.X.X — 빌드 + App Store 업로드
  • fastlane submit_review version:X.X.X — 심사 제출 (바이너리 업로드 없이)
  • fastlane update_metadata version:X.X.X — 메타데이터만 수정 (심사 중이면 자동 취소 후 재제출)
  • fastlane beta version:X.X.X — TestFlight 배포
  • 주의: bundle exec 사용 불가 (bundler 버전 이슈) → fastlane 직접 실행
  • 주의: fastlane/metadata/ 가 gitignored → git add -f 필요
  • 코드 서명: match 대신 자동 프로비저닝 (update_code_signing_settings) 사용

최신 릴리즈

  • 현재 버전: v2.5.0 (CocoaPods → SPM 마이그레이션, App Store 업로드)
  • iOS 버전 참고: iOS 18 다음이 iOS 26 (19~25 없음)