My Claude Code Setup: Global Configuration for Software Development

# Python Development Standards

## Package Management
- Always use `uv` for package management (not pip, poetry, or conda)
- Create virtual environments local to the project directory using `uv`
- Never use global Python installations for project dependencies

## Project Setup
```bash
# Initialize a new Python project
uv init

# Create virtual environment in project directory
uv venv

# Install dependencies
uv pip install -r requirements.txt

# Add new dependencies
uv pip install package_name

Code Style and Standards

• Follow PEP 8 for code style
• Use type hints for all function signatures
• Prefer f-strings over .format() or % formatting
• Use pathlib for file operations instead of os.path
• Use dataclasses or Pydantic for data structures

Import Organization

# Standard library imports
import os
import sys
from pathlib import Path

# Third-party imports
import pandas as pd
import numpy as np

# Local application imports
from app.models import User
from app.utils import helpers

Testing

• Use pytest for testing framework
• Place tests in a tests/ directory
• Name test files with test_ prefix
• Use fixtures for common test setup
• Aim for high test coverage (>80%)

Async Programming

• Use asyncio for concurrent operations
• Prefer async/await over threading for I/O operations
• Use aiohttp for async HTTP requests
• Use asyncpg for async PostgreSQL operations

Error Handling

• Use specific exception types, not bare except
• Log errors appropriately
• Provide user-friendly error messages
• Use context managers for resource management

Documentation

• Use docstrings for all public functions and classes
• Follow Google or NumPy docstring style consistently
• Include type hints in function signatures
• Document complex algorithms and business logic

Common Libraries and Preferences

• Web Framework: FastAPI (preferred) or Flask
• ORM: SQLAlchemy or Tortoise-ORM for async
• Data Processing: pandas, numpy, polars
• HTTP Client: httpx (supports async) or requests
• Testing: pytest with pytest-asyncio for async tests
• Linting: ruff (preferred) or flake8 + black
• Type Checking: mypy or pyright

Project Structure

project_name/
├── src/
│   └── project_name/
│       ├── __init__.py
│       ├── main.py
│       ├── models/
│       ├── services/
│       └── utils/
├── tests/
│   ├── __init__.py
│   ├── test_models.py
│   └── test_services.py
├── pyproject.toml
├── requirements.txt
└── README.md

Performance Considerations

• Profile before optimizing
• Use generators for large datasets
• Consider using Cython or Numba for CPU-intensive operations
• Use connection pooling for database operations
• Implement caching where appropriate

Security

• Never hardcode secrets or API keys
• Use environment variables for configuration
• Validate all user inputs
• Use parameterized queries to prevent SQL injection
• Keep dependencies updated

</details>

### Swift & SwiftUI Standards

<details>
<summary><strong>View Swift development standards (~/.claude/docs/swift.md)</strong></summary>

```markdown
# Swift & SwiftUI Coding Standards

## Technology Stack Preferences
- **UI Framework**: SwiftUI (prefer over UIKit)
- **Data Persistence**: SwiftData for iOS 17+, Core Data for older versions
- **State Management**: SwiftUI native state management (@State, @StateObject, @Observable)
- **Testing**: Swift Testing framework (`@Test` macro) instead of XCTest
- **Concurrency**: Swift 6 with strict concurrency checking, async/await
- **Minimum iOS**: iOS 18.0 unless specified otherwise

## Dependency Injection Pattern

Always use **protocol-based dependency injection** for testability and maintainability:

### Core Principles
1. **Protocol-First Design**: All services (HealthKit, Audio, Networking, etc.) have protocols defining their interface
2. **Direct Injection**: Dependencies are passed explicitly through initializers, NOT through Environment
3. **Mock Support**: Each protocol has mock implementations for testing and preview implementations for SwiftUI previews

### Example Implementation
```swift
// Protocol
protocol HealthKitManaging {
    func saveMeditationSession(startDate: Date, endDate: Date) async throws
}

// Concrete implementation
class HealthKitManager: HealthKitManaging {
    func saveMeditationSession(startDate: Date, endDate: Date) async throws {
        // Real implementation
    }
}

// ViewModel receives dependency
class MeditationTimerModel {
    private let healthKit: HealthKitManaging

    init(healthKit: HealthKitManaging) {
        self.healthKit = healthKit
    }
}

// In tests
let model = MeditationTimerModel(healthKit: MockHealthKitManager())

// In previews
#Preview {
    ContentView(healthKit: PreviewHealthKitManager())
}

Dependency Creation Rules

• App Level: Create concrete service implementations in App struct
• Views: Receive dependencies through init, never create them
• ViewModels: Receive dependencies through init, use protocols not concrete types
• Tests: Use mock implementations
• Previews: Use preview-specific lightweight implementations

Architecture Evolution Path

As apps grow, follow this progression:

1. Small (1-2 features): Direct protocol injection to ViewModels
2. Medium (3-4 features): Introduce feature-specific stores (MeditationStore, SettingsStore)
3. Large (5+ features): Consider unified AppStore that coordinates feature stores

State Management

SwiftUI State Best Practices

• Use @State for view-local state
• Use @StateObject or @Observable for shared state objects
• Use @Observable macro for complex state objects (iOS 17+)
• Prefer computed properties over redundant state
• Implement proper cancellation for async tasks
• Keep view models focused and testable

View State Pattern

Use enum-based state machines for complex view states to prevent invalid state combinations:

// ❌ Avoid: Multiple state variables that can conflict
@State private var isLoading = false
@State private var hasError = false
@State private var data: Data? = nil

// ✅ Prefer: Single enum representing all states
enum ViewState {
    case idle
    case loading
    case loaded(Data)
    case error(Error)
}
@State private var state: ViewState = .idle

Sheet Management Pattern

enum SheetType: Identifiable {
    case settings
    case profile(userId: String)
    case confirmation(action: () -> Void)

    var id: String {
        switch self {
        case .settings: return "settings"
        case .profile(let id): return "profile-\(id)"
        case .confirmation: return "confirmation"
        }
    }
}

// In your view:
@State private var activeSheet: SheetType?

// Single sheet modifier handles all cases
.sheet(item: $activeSheet) { sheetType in
    switch sheetType {
    case .settings: SettingsView()
    case .profile(let id): ProfileView(userId: id)
    case .confirmation(let action): ConfirmationView(action: action)
    }
}

This pattern is essential for:

• Sheet/alert presentation management
• Loading states with data
• Multi-step flows and wizards
• Any UI with mutually exclusive states

Benefits:

• Type Safety: Impossible to have conflicting states
• Clarity: Self-documenting state transitions
• Testability: Easy to test all state combinations
• SwiftUI Integration: Works perfectly with .sheet(item:) and similar modifiers

SwiftData Best Practices

• Models use the @Model macro
• Configure to persist to disk (not in-memory) for production
• Access context via @Environment(\.modelContext)
• Use @Query for fetching data in views
• Define clear relationships between models
• Use transactions for bulk operations

Feature Implementation Guidelines

When Adding New Features

1. Create a new folder for the feature under the main app folder
2. Define a protocol for any external dependencies
3. Implement view models using @Observable with injected dependencies
4. Create SwiftUI views that receive ViewModels through init
5. Add SwiftData models if persistence is needed
6. Write tests using Swift Testing framework with mock dependencies
7. Use enum-based view state pattern for complex UI states

Project Structure

AppName/
├── AppNameApp.swift           # App entry point with dependency setup
├── Features/
│   ├── FeatureName/
│   │   ├── Views/
│   │   ├── ViewModels/
│   │   └── Models/
│   └── Shared/
│       ├── Services/          # Protocol definitions and implementations
│       └── Components/        # Reusable UI components
├── AppNameTests/             # Test target using Swift Testing
└── AppNameUITests/           # UI test target

Testing Standards

Swift Testing Framework

• Use Swift Testing (@Test macro) for all new tests
• Use #expect() for assertions instead of XCTAssert
• Test view models in isolation with mock dependencies
• Mock all external dependencies using protocols
• Write tests before implementation (TDD approach)
• Test all edge cases and error conditions

Test Structure

@Test
func meditationTimerCountsDown() async {
    let mockHealthKit = MockHealthKitManager()
    let model = MeditationTimerModel(healthKit: mockHealthKit)

    await model.startMeditation(duration: 60)
    #expect(model.timeRemaining == 60)

    await Task.sleep(for: .seconds(1))
    #expect(model.timeRemaining == 59)
}

Code Organization

Import Statements

• Group imports logically (Foundation, SwiftUI, third-party)
• Remove unused imports
• Use @testable import only in test files

Access Control

• Mark properties and methods as private by default
• Use internal only when needed for testing
• Use public only for framework/package APIs
• Prefer private(set) for read-only properties

Naming Conventions

• Use descriptive, self-documenting names
• ViewModels: FeatureNameViewModel or FeatureNameModel
• Protocols: Use -ing or -able suffix (e.g., HealthKitManaging, Cacheable)
• Avoid abbreviations except for well-known terms (URL, ID)

SwiftUI Specific Guidelines

View Composition

• Keep views small and focused
• Extract complex views into separate components
• Use ViewBuilders for reusable view logic
• Prefer composition over inheritance
• Follow DRY for views - use shared components between platforms (iOS, watchOS, etc.)

Modifiers

• Order modifiers from specific to general
• Extract complex modifier chains into view extensions
• Use custom modifiers for repeated patterns

Performance

• Use @StateObject for expensive object creation
• Implement Equatable for complex state objects
• Use task modifier for async operations
• Avoid unnecessary re-renders with proper state scoping

Async/Await Best Practices

• Mark all async operations with async/await
• Use structured concurrency (TaskGroup, async let)
• Implement proper cancellation handling
• Avoid detached tasks unless necessary
• Use @MainActor for UI updates

Platform-Specific Considerations

iOS/iPadOS

• Follow Apple’s Human Interface Guidelines
• Support Dynamic Type for accessibility
• Implement proper keyboard avoidance
• Support both portrait and landscape when appropriate
• Handle safe area appropriately

watchOS Compatibility

• Design for small screens first
• Minimize text input
• Use Digital Crown for scrolling
• Keep interactions brief
• Share business logic but adapt UI

Important Notes

• Always handle errors gracefully with user-friendly messages

• Request permissions (HealthKit, Notifications, etc.) appropriately with clear explanations

• Ensure proper handling of background tasks

• Implement proper data validation

• Consider offline functionality where appropriate

• Version using YYYY.MM.release format (e.g., 2025.9.1)

• Never use polling loops to wait for async operations. Use the platform’s async coordination primitives: async/await for one-shot operations, onChange/@Observable for state changes, or continuations to bridge callback APIs.

  Code smell to detect:

  // If you see this pattern, refactor it: for/while { check_state sleep/wait }

Logging Pattern

Setup

// In ViewModels/Services
private let logger = AppLogger.ui  // or .network, .database, .sync, .auth, .general

// With dependency injection
init(logger: Logging = AppLogger(subsystem: .ui)) {
    self.logger = logger
}

Usage

// [Context] = feature/component name for log filtering
logger.debug("[PhotoPicker] Processing data")           // Verbose dev info
logger.info("[Wine] Saved with ID: \(id)")             // Important events
logger.warning("[Sync] Asset not found")                // Recoverable issues
logger.logError("[CoreData] Save failed", error: e)     // Handled failures
logger.logFault("[Firebase] Corruption", error: e)      // Critical failures

Rules

• Always prefix with [FeatureName] or [ComponentName] tag
• Never log sensitive data (passwords, tokens, PII)
• Use MockLogger in tests

</details>

### Source Control Standards

<details>
<summary><strong>View source control standards (~/.claude/docs/source-control.md)</strong></summary>

```markdown
# Git

- NEVER add Claude attribution to git commit messages

# GitLab Integration

- **ALWAYS use `glab` CLI for GitLab operations** instead of web interface or git commands
- Use `glab` for:
  - Creating and managing issues: `glab issue create`, `glab issue list`
  - Working with merge requests: `glab mr create`, `glab mr view`
  - Managing pipelines: `glab pipeline status`
  - Project operations: `glab project view`
- Never use GitHub CLI (`gh`) for GitLab projects - use `glab` exclusively