Claude Code से Flutter/Dart विकास: प्रोजेक्ट मैप, स्टेट, टेस्ट और बिल्ड

Flutter/Dart प्रोजेक्ट में Claude Code सबसे उपयोगी तब होता है जब उसे सिर्फ widget generator नहीं, बल्कि प्रोजेक्ट समझने वाला coding partner बनाया जाए। असली बदलाव अक्सर lib/ से आगे जाता है: pubspec.yaml, assets, tests, Android/iOS config, Web limits, emulator और build commands तक। Widget को स्क्रीन का छोटा building block समझें, state वह data है जिससे UI बदलता है, और pubspec वह file है जिसमें dependencies, assets और SDK constraints लिखे जाते हैं।

इस guide में छोटा cart screen example है। यह flutter create से बने project में paste करने लायक है, लेकिन production जैसी गलतियां दिखाता है: build में state बनाना, बिना वजह package जोड़ना, widget test छोड़ना, और Android, iOS, Web को एक जैसा मान लेना। Official references के लिए Flutter CLI, Flutter testing, Widget testing, Flutter pubspec options, Dart pubspec, Platform channels और Claude Code common workflows देखें। Related reading: React Native guide, testing strategies और CLAUDE.md best practices।

पहले प्रोजेक्ट मैप बनवाएं

पहला prompt “cart screen बना दो” नहीं होना चाहिए। पहले Claude Code से read-only inspection कराएं। यही harness है, यानी agent के लिए सुरक्षित काम का ढांचा: कौन सी files छूनी हैं, क्या नहीं करना, कौन से commands चलाने हैं, और review कैसे होगा।

पहले इस Flutter project को पढ़ें।
अभी कोई file edit न करें।
Report करें:
1. pubspec.yaml में SDK constraints, dependencies और assets
2. lib/ के अंदर UI, state और data layer का structure
3. test/ और integration_test/ में existing test style
4. android/, ios/, web/, macos/, windows/, linux/ में active targets
5. flutter analyze, flutter test और build commands documented हैं या नहीं
अंत में safe-to-edit files और untouched रहने वाली files अलग-अलग बताएं।

क्षेत्र	Claude Code कर सकता है	इंसान तय करेगा
Project map	Structure, dependencies, tests पढ़ना	Edit boundary
Widget	UI component, accessibility, responsive details	Copy और design
State	setState, ChangeNotifier, Riverpod, Bloc या existing pattern follow करना	App-wide state strategy
pubspec	Dependency/assets proposal	New package approve करना
Platform	Android/iOS/Web/Desktop differences	Supported targets
Test/build	Widget test, integration test, commands	Merge और release decision

pubspec को सावधानी से बदलें

pubspec.yaml छोटा दिखता है, पर dependencies, assets, SDK और test packages इसी से चलते हैं। Claude Code को edit से पहले reason, alternatives, affected files और verification commands बताने को कहें।

name: cart_ai_demo
description: A small Flutter cart screen used to verify Claude Code prompts.
publish_to: "none"

environment:
  sdk: ">=3.4.0 <4.0.0"

dependencies:
  flutter:
    sdk: flutter

dev_dependencies:
  flutter_test:
    sdk: flutter
  integration_test:
    sdk: flutter
  flutter_lints: ^6.0.0

flutter:
  uses-material-design: true
  assets:
    - assets/images/

Fresh sandbox के लिए baseline commands:

flutter create cart_ai_demo
cd cart_ai_demo
flutter pub get
flutter analyze
flutter test

Common pitfalls: assets indentation खराब होना, pubspec.lock में unnecessary churn, और छोटी interaction के लिए नया state-management package जोड़ देना। Safer prompt:

pubspec.yaml inspect करें और बताएं कि cart change के लिए new dependency सच में चाहिए या नहीं।
Edit से पहले reason, alternatives, affected files और verification commands दें।
Approval से पहले pubspec.yaml या pubspec.lock modify न करें।

Widget और state को छोटा रखें

यह code fresh flutter create cart_ai_demo project के lib/main.dart में paste किया जा सकता है। यह सिर्फ Flutter SDK use करता है। CartController state change संभालता है और widget render करता है।

import 'package:flutter/material.dart';

void main() => runApp(const CartDemoApp());

class CartDemoApp extends StatelessWidget {
  const CartDemoApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Cart AI Demo',
      theme: ThemeData(colorSchemeSeed: Colors.teal, useMaterial3: true),
      home: const CartSummaryPage(),
    );
  }
}

class CartLine {
  const CartLine({required this.name, required this.price, required this.quantity});
  final String name;
  final int price;
  final int quantity;

  CartLine copyWith({int? quantity}) =>
      CartLine(name: name, price: price, quantity: quantity ?? this.quantity);
}

class CartController extends ChangeNotifier {
  final List<CartLine> _lines = const [
    CartLine(name: 'Dart notebook', price: 1800, quantity: 1),
    CartLine(name: 'Flutter sticker', price: 500, quantity: 2),
  ].toList();

  List<CartLine> get lines => List.unmodifiable(_lines);
  int get total => _lines.fold(0, (sum, line) => sum + line.price * line.quantity);

  void increment(int index) {
    final line = _lines[index];
    _lines[index] = line.copyWith(quantity: line.quantity + 1);
    notifyListeners();
  }

  void decrement(int index) {
    final line = _lines[index];
    if (line.quantity == 1) return;
    _lines[index] = line.copyWith(quantity: line.quantity - 1);
    notifyListeners();
  }
}

class CartSummaryPage extends StatefulWidget {
  const CartSummaryPage({super.key});

  @override
  State<CartSummaryPage> createState() => _CartSummaryPageState();
}

class _CartSummaryPageState extends State<CartSummaryPage> {
  late final CartController controller;

  @override
  void initState() {
    super.initState();
    controller = CartController();
  }

  @override
  void dispose() {
    controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Cart summary')),
      body: AnimatedBuilder(
        animation: controller,
        builder: (context, _) => ListView(
          padding: const EdgeInsets.all(16),
          children: [
            for (final entry in controller.lines.indexed)
              ListTile(
                title: Text(entry.$2.name),
                subtitle: Text('JPY ${entry.$2.price} x ${entry.$2.quantity}'),
                trailing: Wrap(
                  spacing: 8,
                  children: [
                    IconButton(
                      tooltip: 'Decrease ${entry.$2.name}',
                      onPressed: () => controller.decrement(entry.$1),
                      icon: const Icon(Icons.remove_circle_outline),
                    ),
                    IconButton(
                      tooltip: 'Increase ${entry.$2.name}',
                      onPressed: () => controller.increment(entry.$1),
                      icon: const Icon(Icons.add_circle_outline),
                    ),
                  ],
                ),
              ),
            const Divider(),
            Text('Total: JPY ${controller.total}',
                style: Theme.of(context).textTheme.headlineSmall),
          ],
        ),
      ),
    );
  }
}

Pitfalls: build में controller बनाना, notifyListeners() भूलना, total calculation widgets में फैला देना, और dispose न करना।

Test और device verification जोड़ें

Project name cart_ai_demo है तो यह test/cart_summary_test.dart में रखें।

import 'package:cart_ai_demo/main.dart';
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
  testWidgets('updates the cart total when quantity changes', (tester) async {
    await tester.pumpWidget(const CartDemoApp());
    expect(find.text('Total: JPY 2800'), findsOneWidget);

    await tester.tap(find.byIcon(Icons.add_circle_outline).first);
    await tester.pump();
    expect(find.text('Total: JPY 4600'), findsOneWidget);

    await tester.tap(find.byIcon(Icons.remove_circle_outline).first);
    await tester.pump();
    expect(find.text('Total: JPY 2800'), findsOneWidget);
  });
}

flutter analyze
flutter test

Emulator या real device के लिए integration test रखें:

import 'package:cart_ai_demo/main.dart';
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:integration_test/integration_test.dart';

void main() {
  IntegrationTestWidgetsFlutterBinding.ensureInitialized();

  testWidgets('cart can be changed on a real device', (tester) async {
    await tester.pumpWidget(const CartDemoApp());
    await tester.tap(find.byIcon(Icons.add_circle_outline).last);
    await tester.pumpAndSettle();
    expect(find.text('Total: JPY 3300'), findsOneWidget);
  });
}

flutter devices
flutter test integration_test -d <device_id>

Platform pitfalls और use cases

Use case 1: existing list में quantity, filter या sort state जोड़ना। Use case 2: pubspec.yaml और assets cleanup। Use case 3: सिर्फ Android, iOS या Web पर आने वाली issue, जैसे permissions, notifications, location या external links। Use case 4: legacy screen में regression tests जोड़ना। हर prompt में target files, expected command और failure reporting format लिखें।

Flutter Dart layer share करता है, लेकिन deployment rules अलग हैं। Android में manifest permission, iOS में Info.plist, CocoaPods और signing, Web में CORS या browser API, Desktop में file permission और native plugin behavior अलग से जांचना पड़ता है।

flutter analyze
flutter test
flutter build apk --debug
flutter build web --release

iOS release build के लिए macOS और Xcode चाहिए। Prompt में साफ लिखें कि कौन से checks इस machine पर चल सकते हैं और कौन से pending रहेंगे।

Safe prompts और field note

Investigation: lib/, test/, pubspec.yaml और platform folders पढ़ें। Edit न करें। Map और risks दें।
Implementation: सिर्फ lib/features/cart बदलें। Existing state style follow करें। Dependencies न जोड़ें।
pubspec: dependency चाहिए तो रुकें और reason, alternatives, impact, commands दिखाएं।
Verification: widget test जोड़ें। flutter analyze और flutter test चलाकर failures file names के साथ बताएं।
Review: dispose, async, build side effects, platform config, accessibility, package churn और missing tests जांचें।

Masa की practical note: Flutter में सबसे अच्छा result “पहले map, फिर छोटा diff, अंत में tests और build” से मिला। कमजोर prompt था “एक अच्छा Flutter screen बना दो”; UI ठीक दिखी, लेकिन build में state, extra package और platform review missing थे। Team adoption के लिए free cheatsheet और Claude Code training/consulting उपयोगी हैं। Repeatable guardrails के लिए harness engineering पढ़ें।

यह sample flutter create cart_ai_demo की standard structure के लिए लिखा गया है। इस writing environment में Flutter SDK installed नहीं है, इसलिए final verification real Flutter environment में flutter analyze, flutter test, target build और emulator/device test से करें।