flutter-agentic-starter CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Role & Responsibilities

Your role is to analyze user requirements, delegate tasks to appropriate sub-agents, and ensure cohesive delivery of features that meet specifications and architectural standards.

Workflows

• Primary workflow: ./.claude/rules/primary-workflow.md
• Development rules: ./.claude/rules/development-rules.md
• Orchestration protocols: ./.claude/rules/orchestration-protocol.md
• Documentation management: ./.claude/rules/documentation-management.md
• And other workflows: ./.claude/rules/*

IMPORTANT: Analyze the skills catalog and activate the skills that are needed for the task during the process. IMPORTANT: You must follow strictly the development rules in ./.claude/rules/development-rules.md file. IMPORTANT: Before you plan or proceed any implementation, always read the ./README.md file first to get context. IMPORTANT: Sacrifice grammar for the sake of concision when writing reports. IMPORTANT: In reports, list any unresolved questions at the end, if any.

Karpathy Guidelines

Behavioral guidelines to reduce common LLM coding mistakes:

• Think before coding. State assumptions, surface tradeoffs, ask when unclear.
• Simplicity first. Minimum code that solves the requested behavior.
• Surgical changes. Touch only files/lines needed, match existing style, clean up only your own unused code.
• Goal-driven execution. Define success criteria and verify with concrete checks.

Hard Development Rules

• Minimal focused edits are mandatory. Touch only files and lines required for requested behavior.
• Do not rewrite, reformat, reorder, regenerate, or clean up unrelated code unless required.
• Never manually edit build_runner generated files, including *.g.dart, *.freezed.dart, *.config.dart, or files marked GENERATED CODE - DO NOT MODIFY BY HAND.
• For generated code changes, edit source files only, then run dart run build_runner build --delete-conflicting-outputs.
• Avoid primitive obsession. Prefer existing SDK/package types, enums/enhanced enums, sealed classes, or small value objects over raw String, raw int, raw bool, and magic constants for finite or high-risk domain concepts. Parse wire primitives at boundaries; keep raw primitives only for open user text, raw JSON/generated/localized output, and simple IDs/keys without behavior.
• Prefer maintained pub.dev packages before implementing reusable Flutter/Dart utilities, widgets, integrations, or helpers yourself.
• Custom Flutter/Dart implementation requires a documented reason when a maintained pub.dev package is not used.
• For Flutter source icons/images, find suitable existing internet assets instead of creating them yourself. Prefer SVG for icons/simple vectors, PNG/JPG for raster/photo use cases, and record source/license when adding assets.
• Keep ephemeral widget-only UI state local with StatefulWidget/setState; use injectable feature view models with private Signal fields and public ReadonlySignal views for shared, persisted, business-critical, or asynchronous state.
• Use SignalWidget for signal-driven screens and focused SignalBuilder boundaries when only a subtree should rebuild. Use AsyncState<T> for loading/data/error, computed for derived state, and batch when multiple writes must publish atomically.
• Keep navigation, dialogs, and snackbars at the widget boundary. Explicitly dispose every effect, signal subscription, stream connection, and lifecycle observer owned by a long-lived object. Do not use .watch(context) or SignalsMixin.
• Use SafeArea; honor text scaling and accessibility-aware MediaQuery.
• Use LayoutBuilder for parent constraints and MediaQuery.sizeOf(context) for app-window size; avoid orientation or hardware type checks for top-level layout decisions.
• On large screens, add useful panes/content instead of stretching widgets; center and constrain forms, text, and list rows with ConstrainedBox/max widths.
• Use lazy builders for long lists/grids. Use GridView.builder or SliverGridDelegateWithMaxCrossAxisExtent for large feeds instead of wider list rows; avoid intrinsic layout passes in large scrolling surfaces.
• Prefer width-adaptive navigation: compact NavigationBar/bottom nav, larger NavigationRail, drawer, or split shell.
• Prefer canonical large-screen layouts when they fit: list-detail, feed, and supporting pane. Preserve selection/pane state across resize, rotation, fold, and unfold; compact widths show one pane with back behavior, expanded widths show panes together.
• For foldables, do not lock orientation; use MediaQuery.displayFeatures/DisplayFeatureSubScreen when content must avoid hinges/folds. Use Flutter Display API only for the strict orientation-lock letterboxing exception.
• Preserve scroll position with PageStorageKey where list identity should survive rotation, fold, or resize.
• Custom controls need semantics, labels, focus traversal, keyboard activation, hover, and pointer support where relevant.
• Use isolates/compute only for measured UI jank or clearly heavy JSON, media, database, or list-processing work.
• Add restorationScopeId/restorationId for MaterialApp.router, GoRouter, and restorable pages when navigation state should survive OS process death.
• New production user-facing strings go through ARB/localization unless the surrounding file is intentionally demo-only.
• Prefer simple fakes over broad mocks; add widget/accessibility guideline tests for non-trivial UI.
• For large-screen/adaptive UI changes, verify resizing, both orientations, physical keyboard, mouse/trackpad, and fold/unfold scenarios where possible.
• Keep repo-owned source code files under 300 lines when practical; split focused concerns when it improves readability.