diff --git a/CLAUDE.md b/CLAUDE.md index 883cbe35..40caf127 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,34 +15,76 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co - Search the codebase to find existing usages and implementations - Prefer following established patterns, styles, and practices for consistency +## Skills & Plugins + +Claude Code has access to specialized skills. Use them proactively based on context: + +**`/feature-dev:feature-dev`** — Guided Feature Development +- Use when: Planning or implementing new features, analyzing architecture, creating implementation blueprints +- Trigger phrases: "add a feature", "implement", "build", "create new functionality" + +**`/frontend-design:frontend-design`** — Production UI Components +- Use when: Creating or improving UI components, widgets, screens, or visual design +- Trigger phrases: "design", "build UI", "create a widget", "improve the interface" + +**`/code-review:code-review`** — Code Quality Review +- Use when: After writing or modifying code, before commits, reviewing changes +- Trigger phrases: "review my code", "check this", "is this good?" +- **Proactive**: Suggest after significant code modifications + +**`/pr-review-toolkit:review-pr`** — Comprehensive PR Review +- Use when: Before creating PRs, reviewing PR changes, final quality checks +- Trigger phrases: "review the PR", "check before merging", "PR ready?" + +### Automatic Triggers + +Claude should proactively suggest skills in these situations: + +| After This Action | Suggest This Skill | +|-------------------|-------------------| +| Writing/editing multiple files | `/code-review:code-review` | +| Completing a feature implementation | `/code-review:code-review` | +| User says "ready for PR" or "create PR" | `/pr-review-toolkit:review-pr` | +| Discussing new feature requirements | `/feature-dev:feature-dev` | +| Building UI components or screens | `/frontend-design:frontend-design` | + +### Specialized Subagents + +These are advanced capabilities Claude can use for deeper analysis (not slash commands, but can be requested): + +**Code Quality & Review:** +- **Silent Failure Hunter** — Finds silent failures, poor error handling, swallowed exceptions + - Trigger: "hunt for silent failures", "check error handling", "find swallowed errors" +- **Code Simplifier** — Simplifies code while preserving functionality + - Trigger: "simplify this code", "make this cleaner", "reduce complexity" +- **Comment Analyzer** — Checks comments for accuracy and technical debt + - Trigger: "review the comments", "check documentation accuracy" + +**Architecture & Types:** +- **Type Design Analyzer** — Analyzes type design, encapsulation, and invariants + - Trigger: "analyze type design", "review this type", "check encapsulation" +- **Code Architect** — Designs feature architectures with implementation blueprints + - Trigger: "design the architecture", "create implementation blueprint" +- **Code Explorer** — Deep analysis of existing features, traces execution paths + - Trigger: "trace this flow", "how does this work end-to-end", "analyze this feature" + +**Testing:** +- **PR Test Analyzer** — Reviews test coverage quality and identifies gaps + - Trigger: "analyze test coverage", "are tests thorough enough", "find test gaps" + ## Development Commands -**Build and Development** - +**Common Commands:** - `flutter pub get` - Install dependencies -- `flutter run` - Run the app on connected device/emulator -- `flutter build apk` - Build Android APK -- `flutter build ios` - Build iOS app +- `flutter run --dart-define=clientId=YOUR_CLIENT_ID --dart-define=secret=YOUR_CLIENT_SECRET` - Run with Twitch API credentials - `flutter analyze` - Run static analysis and lint checks -- `flutter test` - Run tests (note: no test suite currently exists) +- `flutter test` - Run all tests +- `flutter build apk` / `flutter build ios` - Build release binaries -**Code Generation (Required for MobX stores and JSON serialization)** - -- `flutter packages pub run build_runner build` - Generate code once -- `flutter packages pub run build_runner watch` - Watch and regenerate code on changes -- `flutter packages pub run build_runner build --delete-conflicting-outputs` - Force rebuild all generated files - -**Asset Generation** - -- `flutter pub run flutter_native_splash:create` - Generate native splash screens -- `flutter pub run flutter_launcher_icons:main` - Generate app launcher icons - -**Environment Variables** -Use `--dart-define` to set environment variables (required for Twitch API access): - -```bash -flutter run --dart-define=clientId=YOUR_TWITCH_CLIENT_ID --dart-define=secret=YOUR_TWITCH_CLIENT_SECRET -``` +**Code Generation** (required after changing MobX stores or `@JsonSerializable` models): +- `flutter packages pub run build_runner build` - Generate once +- `flutter packages pub run build_runner build --delete-conflicting-outputs` - Force rebuild all +- `flutter packages pub run build_runner watch` - Watch mode for development ## Architecture Overview @@ -67,25 +109,10 @@ flutter run --dart-define=clientId=YOUR_TWITCH_CLIENT_ID --dart-define=secret=YO **Global Stores** (provided at app root in `main.dart`): - `AuthStore` - Authentication state and token management -- `SettingsStore` - User preferences with automatic persistence +- `SettingsStore` - User preferences with automatic persistence via MobX `autorun()` +- `GlobalAssetsStore` - Shared cache for global emotes and badges across all chat tabs -## HTTP Client Architecture - -**Centralized Dio Setup**: All API services share a single Dio instance configured in `DioClient.createClient()` with connection pooling, keep-alive headers, and optimized timeouts (8s connect, 15s receive, 10s send). - -**Authentication Interceptor**: `TwitchAuthInterceptor` automatically injects auth headers for Twitch API URLs. Updates automatically when user authentication changes. - -**API Service Pattern**: All API services extend `BaseApiClient` for consistent error handling. Services: `TwitchApi`, `BTTVApi`, `FFZApi`, `SevenTVApi`. - -## Authentication & Token Management - -**Two-tier Token System**: - -- Default app token for unauthenticated requests -- Optional user token stored in Flutter Secure Storage -- Automatic token validation on startup with fallback - -**Secure Storage Cleanup**: First-run detection clears secure storage to handle Android/iOS uninstall scenarios where secure storage persists. +**HTTP & Auth**: Centralized Dio client (`DioClient.createClient()`) with connection pooling and optimized timeouts. `TwitchAuthInterceptor` auto-injects auth headers for Twitch API URLs. `UnauthorizedInterceptor` catches 401 errors for token refresh. Two-tier token system: default app token + optional user token in Flutter Secure Storage. ## MobX Store Implementation @@ -113,7 +140,14 @@ After any changes to MobX stores or `@JsonSerializable()` models, run the build_ - **Real-time IRC**: WebSocket connection to Twitch IRC with custom `IRCMessage` parsing - **Third-party Emotes**: Asynchronous loading of BTTV, FFZ, and 7TV assets via dedicated APIs - **Message Management**: 5000 message limit with 20% batch removal optimization -- **Assets Store**: Separate `ChatAssetsStore` manages emotes, badges, and chat-related data +- **Assets Store**: Separate `ChatAssetsStore` manages channel-specific emotes/badges; `GlobalAssetsStore` caches global assets + +## Deep Linking + +App supports Twitch channel deep links (e.g., `twitch.tv/channelname`). Deep link handling in `main.dart`: +- Uses `app_links` package for URI stream handling +- Resolves channel names via Twitch API before navigation +- Graceful fallback with in-app browser option on failure ## Code Style @@ -122,11 +156,14 @@ Analysis rules enforced via `analysis_options.yaml`: - `prefer_single_quotes` - Use single quotes for strings - `always_use_package_imports` - Package imports over relative imports - `require_trailing_commas` - Trailing commas on multi-line constructs -- `prefer_final_locals` - Final for local variables +- `prefer_final_locals`, `prefer_final_in_for_each` - Prefer final variables - `directives_ordering`, `avoid_void_async`, `always_declare_return_types` +- `avoid_redundant_argument_values`, `unnecessary_parenthesis` Generated `.g.dart` files are excluded from analysis but must be committed. +**Error Handling**: Use `Future.error()` for API failures rather than throwing exceptions. + ## Commit Convention Commits follow conventional format: `refactor:`, `feat:`, `fix:`, `format:`, etc. Keep commits tightly scoped. Include generated `.g.dart` outputs in the same commit as their source changes.