Ask a group of Flutter engineers what systems design means, and most will describe server architecture: load balancers, databases, and microservices.

Ask them to design a distributed cache or sketch out a message queue, and they'll hesitate. Ask them to design the Flutter client for a social feed, and they'll open a new file and start writing widgets.

That's the gap. And it's closing fast.

As Flutter applications grow more complex with real-time features, offline support, multiple platform targets, and AI-generated code that still needs to be maintainable, the architectural decisions you make before writing a single widget become just as important as your backend architecture.

Senior Flutter interviews at product companies increasingly test this skill. The engineers who can clearly explain why they chose a particular architecture, the trade-offs they considered, and the problems they were optimizing for are the ones who get hired and promoted.

This article is structured in two halves. The first half explains what frontend systems design actually is and why it matters for Flutter engineers specifically in 2026. The second half works through a full mock interview answer for one of the most common scenario questions: designing the Flutter architecture for a social feed with infinite scroll, likes, comments, and real-time updates. We'll walk through the kind of answer that separates mid-level from senior in an interview room.

Prerequisites

This article assumes you're a working Flutter developer comfortable with state management (Riverpod, Bloc, or similar), REST APIs, and basic Dart. You don't need backend experience, but familiarity with concepts like caching, pagination, and WebSockets will help you follow the deeper sections.

No code setup is required. This is a thinking and architecture article, not a tutorial. Dart/Flutter snippets are used to ground abstract ideas in concrete implementation.

Table of Contents

• 1. What is Frontend Systems Design?

• 2. Why Flutter Engineers Can't Ignore It Anymore

• 3. The Interview Format: What to Expect

• 4. How to Structure Your Answer

• 5. Mock Interview: Design a Social Feed

• 6. Other Questions to Prepare For

• 7. Key Takeaways

1. What is Frontend Systems Design?

Systems design is the practice of making high-level decisions about how a software system is structured before implementation begins: how its components are divided, how they communicate, how it handles scale, failure, and change over time.

On the backend, this means deciding between microservices and a monolith, choosing a database, designing an API contract, and planning for horizontal scaling. The feedback loop is fast: a bad database schema causes slow queries within days, and a poorly designed API breaks clients immediately.

On the frontend, the consequences of bad design are slower and quieter. A 600-line screen widget still ships. A god-class repository with 40 methods still works. State leaks between sessions only surface after a frustrated user reports it.

Frontend systems design asks the same category of questions, applied to the client layer:

• How do you divide a large app into independently-buildable features?

• Where does business logic live, and what enforces that boundary?

• How does data flow from the network to the screen and back?

• What happens when the network fails, the API changes shape, or the user logs out mid-session?

• How do you design components that can be tested in isolation?

• How do you structure the app so a team of engineers can work on it without stepping on each other?

These aren't widget questions. They're architecture questions. And they have answers: principled ones, with real tradeoffs.

2. Why Flutter Engineers Can't Ignore It Anymore

Three forces are pushing systems design into the Flutter conversation in a way that simply didn't exist three years ago.

Flutter Apps Are No Longer Just UIs

With Serverpod and Dart Frog on the server, Jaspr on the web, and Flutter on mobile and desktop, Dart is now a genuinely full-stack language. Engineers making architecture decisions that span mobile, web, and server in the same codebase need systems thinking, not just widget composition skills.

When your Freezed model is shared between the Flutter client and the Dart backend, the boundary between "frontend" and "backend" design dissolves. You're designing a system.

AI Agents Expose Bad Architecture Immediately

This is the new pressure point. When Claude Code or any AI coding agent reads your project cold, it has no accumulated mental model to compensate for messiness. It reads files sequentially. It works within a limited context window. It makes decisions based on the patterns it sees.

A codebase with tangled dependencies, inconsistent naming, and business logic scattered across the widget tree produces unreliable AI output. This doesn't happen because the AI is wrong, but because the code doesn't communicate its own structure clearly enough to be navigated by something without human intuition.

Good systems design and AI-navigable architecture are almost identical. Feature-first structure, clear layer boundaries, consistent naming, small, focused files. These aren't just team hygiene practices anymore. They're what make AI-assisted development actually work at scale.

Senior Flutter Interviews Now Test it Explicitly

As Flutter matures and product companies build larger apps with larger teams, the interview bar has risen. A mid-level Flutter interview might test widget lifecycle and state management fundamentals. A senior interview tests your ability to design a system you've never seen before, live, under pressure, while explaining your thinking out loud.

If you haven't thought about this before walking into that room, you'll be caught off guard.

3. The Interview Format: What to Expect

Frontend systems design interviews at senior level typically run 45–60 minutes. You're given a vague scenario, like "design the Flutter client for a social feed", and you're expected to drive the conversation.

The interviewer isn't looking for a single correct answer. They're watching how you think:

• Do you clarify requirements before jumping to solutions?

• Do you identify the hard problems (real-time sync, optimistic UI, offline states) rather than the easy ones?

• Do you make tradeoffs explicitly rather than just picking the thing you know best?

• Can you go deep on any layer when pushed?

The biggest mistake candidates make is opening Xcode or a code file immediately and starting to build. Systems design interviews are whiteboard conversations, not implementation sessions. Draw boxes. Name the layers. Talk through the data flow before writing a single method signature.

4. How to Structure Your Answer

Use this framework for any frontend systems design question:

1. Clarify requirements (5 minutes) What platforms? How many users? Offline support? Real-time? Authentication? What's in scope for this conversation? Never assume.

2. Define the data model (5–10 minutes) What are the core entities? What are their relationships? This anchors every architectural decision that follows.

3. Design the layer architecture (10 minutes) How is the app divided? What are the layers? What enforces the boundaries between them?

4. Solve the hard problems one by one (20–25 minutes) Pagination. Optimistic UI. Real-time sync. Offline. Performance. Go deep on each one, and name the tradeoffs.

5. Address failure states (5 minutes) What breaks? What's the user experience when it does? Senior answers always include error handling.

6. Summarise and invite questions (5 minutes) Recap the key decisions and the tradeoffs you made. Show you can hold the whole picture.

5. Mock Interview: Design a Social Feed

Interviewer: Design the Flutter client architecture for a social feed. Users can scroll through posts, like and comment on them, and receive real-time updates when new posts arrive.

This is the answer.

Step 1: Clarify Requirements

Before touching architecture, ask the questions that constrain your decisions.

"A few questions before I start. What platforms are we targeting? Mobile only, or web and desktop too? How many users are we designing for? Is this a startup MVP or an app at scale? Do we need offline support? How real-time does real-time need to be? Are we talking push notifications, or should the feed update while the user is looking at it? And what's the authentication model? Are users logged in, or is there a guest mode?"

For this walkthrough, assume:

• Mobile (iOS + Android), with web on the roadmap

• Tens of thousands of MAU. Not Twitter scale, but meaningful.

• Offline: show cached content, queue interactions

• Real-time: live feed updates while the screen is open (WebSocket)

• Auth: logged-in users only

These answers change every architectural decision that follows. Offline support means a local cache layer. Live updates while the screen is open means WebSockets, not polling. Web on the roadmap means avoiding anything mobile-only in the business logic layer.

Step 2: Define the Data Model

Start with the entities and their relationships. Draw these before writing any code.

// Core entities

@freezed
class Post with _$Post {
  const factory Post({
    required String id,
    required String authorId,
    required String authorName,
    required String authorAvatarUrl,
    required String content,
    String? imageUrl,
    required int likeCount,
    required int commentCount,
    required bool isLikedByMe,      // derived from current user context
    required DateTime createdAt,
  }) = _Post;
}

@freezed
class Comment with _$Comment {
  const factory Comment({
    required String id,
    required String postId,
    required String authorId,
    required String authorName,
    required String content,
    required DateTime createdAt,
  }) = _Comment;
}

@freezed
class FeedPage with _$FeedPage {
  const factory FeedPage({
    required List<Post> posts,
    required String? nextCursor,    // null = end of feed
  }) = _FeedPage;
}

A few design decisions embedded in this model are worth calling out explicitly in an interview:

isLikedByMe lives on the Post. You could derive this from a separate user-likes table, but embedding it in the post response is simpler and makes the UI stateless. The screen doesn't need to join two data sources to render a like button.

Cursor-based pagination, not offset. nextCursor rather than page: 2. Offset pagination breaks when new posts are inserted at the top. Item 20 on page 2 becomes item 21, and you either show a duplicate or skip an item. Cursors are stable.

likeCount and commentCount are integers, not arrays. You don't fetch all likers to render a post. You fetch the count and a flag. This is a deliberate API contract decision that prevents unbounded payload size.

Step 3: Design the Layer Architecture

A feed is a good test of layer discipline because data flows in multiple directions: down from the API, up from user interactions, and sideways from real-time events. A flat architecture collapses quickly.

Here's the structure:

lib/
├── core/
│   ├── network/          # Dio client, interceptors, token refresh
│   ├── cache/            # Local storage abstraction (Hive or Isar)
│   ├── realtime/         # WebSocket connection manager
│   └── errors/           # Typed error classes
└── features/
    └── feed/
        ├── data/
        │   ├── models/   # Post, Comment, FeedPage (Freezed)
        │   ├── sources/
        │   │   ├── feed_remote_source.dart   # API calls
        │   │   └── feed_local_source.dart    # Cache reads/writes
        │   └── repositories/
        │       └── feed_repository.dart      # Coordinates remote + local
        └── presentation/
            ├── screens/
            │   └── feed_screen.dart
            ├── widgets/
            │   ├── post_card.dart
            │   ├── like_button.dart
            │   └── comment_sheet.dart
            └── providers/
                ├── feed_provider.dart        # Paginated post list
                ├── like_provider.dart        # Like/unlike actions
                └── realtime_provider.dart    # WebSocket events → state

A couple things worth noting here:

First, the repository is the only component that talks to both the remote source and the local source. Providers call the repository. The repository decides whether to hit the network or return cached data. Screens never know the data came from cache.

Second, the real-time layer is separate from the data fetching layer. It's a common mistake to wire WebSocket events directly into the same provider that manages pagination, and it becomes impossible to test or reason about. The realtime_provider receives events and patches the feed state and the feed_provider manages the paginated list. They coordinate through Riverpod's ref, not through direct dependency.

Step 4: Pagination and Infinite Scroll

Infinite scroll is the first hard problem. The naïve implementation: a ListView that loads everything falls apart at a few hundred posts.

Here's a Riverpod AsyncNotifier that handles cursor-based pagination:

@riverpod
class FeedNotifier extends _$FeedNotifier {
  static const _pageSize = 20;
  String? _nextCursor;
  bool _isFetchingMore = false;

  @override
  Future<List<Post>> build() async {
    // Load first page + seed from cache if available
    final cached = await ref.read(feedLocalSourceProvider).getCachedPosts();
    if (cached.isNotEmpty) {
      // Show cache immediately, refresh in background
      _refreshInBackground();
      return cached;
    }
    return _fetchPage(cursor: null);
  }

  Future<void> loadMore() async {
    if (_isFetchingMore || _nextCursor == null) return;
    _isFetchingMore = true;

    final currentPosts = state.valueOrNull ?? [];
    final page = await ref
        .read(feedRepositoryProvider)
        .getFeedPage(cursor: _nextCursor, limit: _pageSize);

    _nextCursor = page.nextCursor;
    state = AsyncData([...currentPosts, ...page.posts]);
    _isFetchingMore = false;
  }

  Future<List<Post>> _fetchPage({required String? cursor}) async {
    final page = await ref
        .read(feedRepositoryProvider)
        .getFeedPage(cursor: cursor, limit: _pageSize);
    _nextCursor = page.nextCursor;
    await ref.read(feedLocalSourceProvider).cachePosts(page.posts);
    return page.posts;
  }

  void _refreshInBackground() {
    Future.microtask(() async {
      final freshPosts = await _fetchPage(cursor: null);
      state = AsyncData(freshPosts);
    });
  }

  bool get hasMore => _nextCursor != null;
}

In the screen, trigger loadMore() before the user reaches the bottom, not at the last item, but a few items before it:

NotificationListener<ScrollNotification>(
  onNotification: (notification) {
    if (notification.metrics.pixels >
        notification.metrics.maxScrollExtent - 400) {
      ref.read(feedNotifierProvider.notifier).loadMore();
    }
    return false;
  },
  child: ListView.builder(
    itemCount: posts.length + (hasMore ? 1 : 0),
    itemBuilder: (context, index) {
      if (index == posts.length) return const FeedLoadingIndicator();
      return PostCard(post: posts[index]);
    },
  ),
)

The 400-pixel threshold means the next page starts loading before the user sees the end of the list. The experience feels seamless.

Step 5: Optimistic UI for Likes and Comments

Optimistic UI is the practice of updating the local state immediately when a user takes an action, before the server confirms it, then rolling back if the server rejects it. It's what makes a like button feel instant rather than laggy.

The pattern has three steps: apply the optimistic update, fire the network request, and roll back on failure.

@riverpod
class LikeNotifier extends _$LikeNotifier {
  @override
  void build() {}

  Future<void> toggleLike(String postId) async {
    final feedNotifier = ref.read(feedNotifierProvider.notifier);
    final currentPosts = ref.read(feedNotifierProvider).valueOrNull ?? [];

    // Find the post
    final postIndex = currentPosts.indexWhere((p) => p.id == postId);
    if (postIndex == -1) return;
    final post = currentPosts[postIndex];

    // Step 1: Apply optimistic update immediately
    final optimisticPost = post.copyWith(
      isLikedByMe: !post.isLikedByMe,
      likeCount: post.isLikedByMe ? post.likeCount - 1 : post.likeCount + 1,
    );
    feedNotifier.patchPost(postIndex, optimisticPost);

    // Step 2: Fire the network request
    try {
      await ref.read(feedRepositoryProvider).toggleLike(postId);
    } catch (e) {
      // Step 3: Roll back on failure
      feedNotifier.patchPost(postIndex, post);
      // Show a snackbar or error indicator
    }
  }
}

The patchPost method on FeedNotifier replaces a single post in the list without rebuilding the whole feed. This is an important performance detail when the list has hundreds of items.

The tradeoff to name explicitly in an interview: optimistic UI can produce an inconsistent state if the server is the source of truth for like counts. Two users liking simultaneously might both see their local count increment from 41 to 42, but the real count is 43. For a social app, this is usually acceptable. You show the user their action was registered, and the next feed refresh corrects the count. For financial transactions, an optimistic UI is inappropriate. Know where to draw the line.

Step 6: Real-Time Updates

Real-time feed updates and new posts appearing while the user is looking at the screen require a persistent connection. WebSocket is the right tool here. Server-Sent Events work too, but WebSocket is bidirectional, which matters if you later want to push events (typing indicators, presence).

Design the WebSocket layer as a singleton service, not inside the feed feature:

// core/realtime/realtime_service.dart

class RealtimeService {
  WebSocketChannel? _channel;
  final _controller = StreamController<RealtimeEvent>.broadcast();

  Stream<RealtimeEvent> get events => _controller.stream;

  Future<void> connect(String token) async {
    _channel = WebSocketChannel.connect(
      Uri.parse('wss://api.yourapp.com/ws?token=$token'),
    );

    _channel!.stream.listen(
      (data) {
        final event = RealtimeEvent.fromJson(jsonDecode(data as String));
        _controller.add(event);
      },
      onError: (_) => _scheduleReconnect(),
      onDone: () => _scheduleReconnect(),
    );
  }

  void _scheduleReconnect() {
    Future.delayed(const Duration(seconds: 3), connect);
  }

  void dispose() {
    _channel?.sink.close();
    _controller.close();
  }
}

Then in the feed layer, listen to the stream and patch state when new posts arrive:

@riverpod
class RealtimeFeedNotifier extends _$RealtimeFeedNotifier {
  StreamSubscription? _subscription;

  @override
  void build() {
    _subscription = ref
        .read(realtimeServiceProvider)
        .events
        .where((e) => e.type == RealtimeEventType.newPost)
        .listen((event) {
      final newPost = Post.fromJson(event.payload);
      ref.read(feedNotifierProvider.notifier).prependPost(newPost);
    });

    ref.onDispose(() => _subscription?.cancel());
  }
}

The UX decision worth raising in an interview: do you silently prepend new posts to the top of the feed, or do you show a "3 new posts, tap to refresh" banner?

Silent prepend is jarring: the user is reading post 5, and suddenly they're reading post 8. The banner pattern (used by Twitter/X and LinkedIn) is almost always the better choice. It signals freshness without disrupting reading position.

Step 7: Offline and Error States

An offline-capable feed has two distinct requirements: show something useful when there's no connection, and queue interactions (likes, comments) so they fire when connectivity returns.

For showing cached content, the repository pattern handles this cleanly:

// feed_repository.dart

Future<List<Post>> getFeed({String? cursor}) async {
  try {
    final page = await _remoteSource.getFeedPage(cursor: cursor);
    await _localSource.cachePosts(page.posts);
    return page.posts;
  } on DioException catch (e) {
    if (e.type == DioExceptionType.connectionError) {
      // Network unavailable — return cache
      final cached = await _localSource.getCachedPosts();
      if (cached.isNotEmpty) return cached;
    }
    rethrow;
  }
}

For queuing interactions offline, keep a simple pending actions queue in local storage:

@freezed
class PendingAction with _$PendingAction {
  const factory PendingAction.like({
    required String postId,
    required bool isLike,
    required DateTime queuedAt,
  }) = PendingLike;

  const factory PendingAction.comment({
    required String postId,
    required String content,
    required DateTime queuedAt,
  }) = PendingComment;
}

When connectivity returns (detected via connectivity_plus), drain the queue and fire each action in order. If an action fails after retry, surface it to the user. Don't silently drop it.

Step 8: Performance Considerations

A feed is one of the most performance-sensitive screens in any app. There are a few non-negotiable practices:

First, use ListView.builder, never ListView with a children list. Builder renders only the items currently on screen. A children list renders all of them at once (which would be catastrophic for a feed of 200+ posts).

Second, keep PostCard build methods cheap. Every rebuild of a postcard is expensive at scale. Use const constructors everywhere possible. Avoid rebuilding the whole card when only the like count changes. Isolate the like button into its own Riverpod consumer.

// Bad — whole PostCard rebuilds when like changes
class PostCard extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final post = ref.watch(feedNotifierProvider)
        .valueOrNull
        ?.firstWhere((p) => p.id == postId);
    // ...
  }
}

// Good — only LikeButton rebuilds
class LikeButton extends ConsumerWidget {
  final String postId;
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final post = ref.watch(
      feedNotifierProvider.select(
        (state) => state.valueOrNull?.firstWhere((p) => p.id == postId),
      ),
    );
    // Only rebuilds when this specific post's like state changes
  }
}

Third, cache network images aggressively. Use cached_network_image with a memory cache limit. On a feed with avatars and post images, uncached network images are the single biggest source of jank.

And lastly, dispose WebSocket connections on screen exit. Don't keep a real-time connection alive when the user navigates away. Riverpod's ref.onDispose makes this straightforward, but it's easy to miss.

6. Other Questions to Prepare For

The social feed covers most of the hard architectural territory. These additional questions round out your preparation:

Architecture & structure:

• How would you structure a large Flutter app for a team of 10 engineers?

• How do you handle shared state between two features that shouldn't know about each other?

• Walk me through how you'd design the data layer for an offline-first app.

State management:

• Compare Riverpod, Bloc, and Redux from an architecture standpoint (not just API differences).

• How do you prevent the state from leaking between sessions after a user logs out?

Networking & data:

• How would you handle token refresh across concurrent requests?

• Walk me through optimistic UI for a financial transaction. How is it different from liking a post?

Performance:

• A screen has 10,000 items. How do you render it without jank?

• How do you design an image-loading system for a feed with mixed media types?

Multi-platform:

• How would you share models and business logic between a Flutter mobile app and a Dart backend?

• What changes about your architecture when you add a web as a target?

For each of these, use the same framework: clarify the constraints, define the data model, name the layers, solve the hard problems explicitly, and address failure states.

7. Key Takeaways

Systems design is not a backend discipline that Flutter engineers are exempt from. It's a way of thinking about software that becomes unavoidable as apps grow in complexity, teams grow in size, and AI agents become part of the development workflow.

The social feed scenario illustrates five principles that apply across every frontend systems design problem:

1. Layer Boundaries Are Load-bearing

The repository pattern, the separation of real-time from data fetching, and the isolation of pending actions aren't academic choices. They're what makes the system testable, navigable, and maintainable when requirements change.

2. The Data Model Anchors Everything

Decisions you make in the model (like cursor-based pagination, isLikedByMe on the post, and integer counts instead of arrays) ripple through every layer. Get the model right before designing anything else.

3. Optimistic UI is a UX Contract, Not Just a Pattern

When you apply an optimistic update, you're making a promise to the user. Know when that promise is appropriate (social interactions) and when it isn't (financial transactions).

4. Real-time is an Architecture Concern, Not a Feature

A WebSocket connection is a persistent resource that needs to be managed, connected when needed, disconnected when not, and reconnected on failure. Design it as infrastructure, not as part of a single screen.

5. Offline is a First-class State

Not an edge case, not a "nice to have." In markets with unreliable connectivity, which includes most of the world's fastest-growing mobile markets, an app that shows nothing when the network drops is a broken app.

The engineers who understand these principles and can articulate them out loud under interview pressure are the ones who get hired to build the systems that millions of people use.

We had tools like ChatGPT, Gemini, and Copilot, but they were mostly chat interfaces: you pasted code, got a response, and moved on.

During that time, my manager, who worked in AI/ML, told me that a day would come when developers would collaborate with AI agents and that learning how to write effective prompts would become a valuable skill.

I took that advice seriously. I spent countless nights experimenting with prompts, refining instructions, and learning how to communicate with AI systems effectively.

Today, while I still write code by hand and believe strongly in fundamentals, those early lessons have paid off. In an era where AI is embedded into the development workflow, I've been able to leverage it to significantly amplify my productivity as a software engineer.

You've probably seen all the excitement around AI coding assistants. But if you've tried using one on a real Flutter project, whether it's a fintech app, an e-commerce platform, or any application with a well-structured architecture, you've likely experienced the frustration, too.

The assistant generates a widget. You paste it in. It doesn't fit your architecture. It ignores your naming conventions. It recreates functionality that already exists somewhere else in your codebase. Before long, you've spent twenty minutes fixing code that was supposed to save you time.

The problem isn't the AI. The problem is that most developers still use AI as an advanced autocomplete tool when it can function as something much more powerful: a second engineer that understands your codebase, follows your conventions, and tackles parallel tasks while you focus on solving the hard problems.

In this article, I'll show you what has actually worked for me. We'll cover how to structure your Flutter projects so Claude Code can navigate them effectively and how to use skills, loops, and subagents to automate repetitive development tasks and dramatically increase your productivity.

Prerequisites

Before following along, you should be comfortable with the basics of Flutter development; building widgets, managing state, and running the app from the terminal. You don't need to be an expert.

On the tooling side, you'll need:

• Flutter SDK (3.x or later): the framework we're building with. Install it from flutter.dev.

• Claude Code: Anthropic's agentic coding tool that runs in your terminal alongside your editor. Install it with npm install -g @anthropic-ai/claude-code, then run claude in your project directory to start a session. You'll need an Anthropic account and API key.

• A code editor: VS Code or Android Studio both work well. Claude Code operates in the terminal and reads/writes files directly, so it works alongside whatever editor you use.

• Git: version control is assumed throughout. Claude Code integrates with Git for commits, diffs, and branch awareness.

Here's a quick overview of the Claude Code concepts we'll use throughout the article:

• CLAUDE.md: a markdown file at your project root that Claude reads at the start of every session. Think of it as a briefing document: your architecture, your conventions, your commands.

• Skills: reusable instruction packs stored in .claude/skills/. You define them once, and Claude invokes them automatically when the task matches, or you call them manually with /skillname.

• Subagents: isolated Claude instances that handle a focused task in their own context window, then return only a summary. Great for parallel work without polluting your main session.

• Hooks: shell commands or scripts that fire on lifecycle events (before a tool runs, after a turn completes, and so on). They bypass Claude's judgment entirely — useful for enforcing rules deterministically.

• /loop: a built-in skill that reruns a task repeatedly until a condition you define is met.

None of these require special configuration to unlock. They’re all available once you have Claude Code installed.

Table of Contents

• 1. Why Architecture Comes First

• 2. Setting Up Your CLAUDE.md

• 3. Feature-First Folder Structure — The Details

• 4. Writing Skills for Your Most Repeated Tasks

• 5. Using /loop for Self-Correcting Workflows

• 6. Subagents for Parallel Screen Development

• 7. Hooks — Enforcing Rules Deterministically

• 8. Putting It All Together: A Real Sprint Workflow

• Key Takeaways

1. Why Architecture Comes First

Before you write a single skill or configure a single hook, your folder structure needs to make sense to an AI reading it cold.

Claude Code reads your files to understand your project. If your code is scattered across a layer-first structure (lib/models/, lib/services/, lib/widgets/), Claude has to piece together what each feature does by jumping between folders. It makes mistakes. It creates files in the wrong place. It generates code that doesn't conform to the pattern used in the rest of the app.

The fix is a feature-first structure. Each feature is a self-contained module. Everything Claude needs to understand the transfer flow, for example, lives inside lib/features/transfer/.

lib/
├── core/
│   ├── constants/
│   ├── errors/
│   ├── router/
│   └── theme/
├── features/
│   ├── auth/
│   │   ├── data/
│   │   │   ├── models/         # Freezed models
│   │   │   └── repositories/
│   │   ├── presentation/
│   │   │   ├── screens/
│   │   │   ├── widgets/
│   │   │   └── providers/      # Riverpod providers
│   │   └── auth.dart           # barrel export
│   ├── transfer/
│   │   ├── data/
│   │   ├── presentation/
│   │   └── transfer.dart
│   └── wallet/
│       ├── data/
│       ├── presentation/
│       └── wallet.dart
└── main.dart

This structure tells Claude immediately: "Everything for the transfer feature is in lib/features/transfer/"When you ask it to 'add a beneficiary validation to the transfer flow,' it knows exactly where to look and where to create new files.

It also maps cleanly to Riverpod with code generation. Each feature's providers live close to the screens that use them, which means build_runner output lands in the right place, too.

2. Setting Up Your CLAUDE.md

CLAUDE.md is arguably the most important file in your Claude Code setup. It's loaded at the beginning of every session. It remains in context throughout the conversation, helping Claude stay aligned with your project's architecture, conventions, and development practices no matter how long the session becomes.

Create it at the root of your project:

touch CLAUDE.md

Here's a template shaped for a Flutter/Riverpod project:

# My Flutter App

## Commands
- `flutter pub get` — install dependencies
- `dart run build_runner build --delete-conflicting-outputs` — generate code
- `flutter analyze` — run linter
- `flutter test` — run tests
- `flutter run` — start dev build

## Architecture
Feature-first folder structure. Each feature lives in lib/features/<name>/.
State management: Riverpod with @riverpod code generation (AsyncNotifier pattern).
HTTP: Dio with interceptors in lib/core/network/.
Navigation: GoRouter with named routes defined in lib/core/router/.
Models: Freezed + JsonSerializable. Run build_runner after any model change.

## Conventions
- All monetary amounts in the smallest unit (e.g. kobo for NGN), stored as int — never use doubles for money
- Use ref.invalidate() not ref.refresh()
- No business logic in widgets — all logic goes in notifiers or repositories
- Widget files contain only one public widget per file
- Barrel exports via feature.dart in each feature root
- Prefix private widgets with an underscore

## What NOT to do
- Do not add new packages without asking first
- Do not modify *.g.dart or *.freezed.dart files directly — regenerate with build_runner
- Do not put API calls directly in notifiers — always go through the repository layer

A few things to note about this file:

Keep it honest: If your conventions don't match what's actually in the codebase, Claude will get confused. The CLAUDE.md should reflect how the code actually works today, not aspirationally.

The "What NOT to do" section matters: AI assistants are optimistic. They'll solve the problem in front of them without thinking about side effects. Explicitly telling Claude what to avoid saves a lot of cleanup.

Don't make it too long: Every line in CLAUDE.md costs tokens on every single turn of every session. Put team-wide, always-relevant rules here. Everything else should be a skill (covered next).

3. Feature-First Folder Structure — The Details

Let's look inside a feature in more detail, using a wallet feature as an example:

lib/features/wallet/
├── data/
│   ├── models/
│   │   ├── wallet.dart             # Freezed model
│   │   ├── wallet.freezed.dart     # Generated
│   │   ├── wallet.g.dart           # Generated
│   │   └── transaction.dart
│   └── repositories/
│       ├── wallet_repository.dart  # Abstract class
│       └── wallet_repository_impl.dart
├── presentation/
│   ├── screens/
│   │   ├── wallet_screen.dart
│   │   └── transaction_history_screen.dart
│   ├── widgets/
│   │   ├── balance_card.dart
│   │   └── transaction_tile.dart
│   └── providers/
│       ├── wallet_provider.dart
│       └── wallet_provider.g.dart  # Generated
└── wallet.dart                     # Barrel export

And here's what a clean Riverpod provider looks like in this structure:

// lib/features/wallet/presentation/providers/wallet_provider.dart

import 'package:riverpod_annotation/riverpod_annotation.dart';
import '../../data/models/wallet.dart';
import '../../data/repositories/wallet_repository.dart';

part 'wallet_provider.g.dart';

@riverpod
class WalletNotifier extends _$WalletNotifier {
  @override
  Future<Wallet> build() async {
    return ref.watch(walletRepositoryProvider).getWallet();
  }

  Future<void> refreshBalance() async {
    state = const AsyncValue.loading();
    state = await AsyncValue.guard(
      () => ref.read(walletRepositoryProvider).getWallet(),
    );
  }
}

When Claude Code sees this pattern repeated across multiple features, it learns to replicate it. The more consistent your structure, the better Claude's output matches what you'd write yourself.

4. Writing Skills for Your Most Repeated Tasks

Skills are reusable instruction packs that Claude Code loads when they're relevant. They live in .claude/skills/<name>/SKILL.md and can be invoked manually with /skillname or triggered automatically when Claude recognises the right context.

A simple way to think about a Skill is as a specialist on your team. Imagine working with a designer, a QA engineer, and a security expert. You don't explain their entire job every time you need their help. Each person already knows their responsibilities and follows a defined process.

Skills work the same way. Instead of repeatedly telling Claude how to generate Riverpod providers, write tests, or review security concerns, you package those instructions into a Skill and let Claude load them whenever they're needed.

Think of a Skill as a saved recipe. Instead of writing out the ingredients and cooking steps every time you want to make a meal, you keep the recipe in one place and reuse it whenever needed.

Skills do the same thing for development workflows. They allow you to save a set of instructions once and have Claude follow them consistently every time a similar task comes up.

The key thing to understand is that the description field is what triggers a skill. Claude evaluates it on every turn and decides whether the current task matches. Because of this, you should describe it using the same verbs that developers actually type in real workflows, like build, commit, release, or fix lint, instead of documentation-style language.

Creating Your First Skill

Before you write a skill, think about the tasks you perform over and over again. A good skill captures a workflow you already know by heart. If you find yourself giving Claude the same instructions every session, such as "run flutter analyze, then run build_runner, then execute the tests," that's a good candidate for a skill.

Start with one task. Keep the steps in the exact order you expect Claude to follow, and clearly define what a successful outcome looks like. Don't try to cover every possible edge case. The goal is to automate your normal workflow so Claude can handle the repetitive work consistently, while you step in only when something unexpected happens.

mkdir -p .claude/skills/flutter-release
touch .claude/skills/flutter-release/SKILL.md

---
name: flutter-release
description: |
  Use this skill when building a release APK or preparing the app for deployment.
  Triggers on: "build release", "generate apk", "prepare release", "release build".
allowed-tools: Bash Read
---

# Flutter release checklist

Run these steps in order. Do not skip any step.

1. Run `flutter pub get`
2. Run `dart run build_runner build --delete-conflicting-outputs`
3. Run `flutter analyze` — fix every error before proceeding. Do not continue with warnings treated as errors.
4. Run `flutter test` — if any test fails, fix it before continuing
5. Run `flutter build apk --release`
6. Confirm build output at `build/app/outputs/flutter-apk/app-release.apk`
7. Create a git commit: `chore: release build vX.X.X`

If any step fails, stop and report the error clearly. Do not skip ahead.

Now, whenever you type "prepare a release" or "build the apk"Claude follows this checklist without you having to remind it of the steps.

A Skill For Conventional Commits

mkdir -p .claude/skills/commit
touch .claude/skills/commit/SKILL.md

---
name: commit
description: |
  Use when committing changes or writing a commit message.
  Triggers on: "commit", "git commit", "commit changes", "write a commit message".
---

Follow Conventional Commits format:

Types: feat | fix | chore | refactor | docs | test | perf

Format: `type(scope): short imperative summary`

Rules:
- Subject line max 72 characters
- Imperative mood — "add" not "added", "fix" not "fixed"
- Scope = the feature name (auth, transfer, wallet, cards)

Examples:
- `feat(transfer): add beneficiary validation on amount input`
- `fix(wallet): correct kobo-to-naira display conversion`
- `chore(deps): upgrade riverpod to 2.6.1`

Always run `flutter analyze` before committing. Never commit with lint errors.

Dynamic Context Injection

Skills support a powerful trick: you can inject live shell output directly into the skill body using !`command` syntax. Claude receives the output as part of the skill, not as a separate step.

For example, you could embed something like !git status inside a skill, so Claude always sees the current state of your repository when applying that skill. In a Flutter workflow, you could also use something like !flutter test so the skill dynamically includes the latest test results before Claude suggests fixes or improvements.

---
name: sprint-status
description: |
  Use when asked about current status, what's left to do, or what changed.
---

## Current git status
!`git status --short`

## Uncommitted changes
!`git diff --stat HEAD`

## Recent commits
!`git log --oneline -10`

## Lint status
!`flutter analyze 2>&1 | tail -20`

Review the above and give a concise summary of: what's done, what's broken, and what needs attention before the next commit.

Type /sprint-status and Claude gets a live snapshot of your project state before responding.

5. Using /loop for Self-Correcting Workflows

/loop is a built-in Claude Code skill that reruns a task repeatedly until a condition is met. It's the difference between "fix this lint error" (one shot) and "fix all lint errors" (autonomous loop).

For example, instead of running a one-time prompt like “fix this lint error,” you would use /loop fix lint errors in this Flutter project until there are no warnings left. Claude will then repeatedly check the output, apply fixes, and recheck until the condition is satisfied.

A more realistic Flutter workflow could look like /loop run flutter analyze and fix all reported issues until analysis passes clean. In this case, Claude keeps running analyses, fixing issues, and revalidating until the project reaches a clean state.

It's worthy of note here that a/loop and a Skill solve two different problems, and it helps to think of them like this:

• A Skill is knowledge.

• A Loop is behavior over time.

The pattern is always the same: tell Claude what to run, what to check, and when to stop.

Fix Until Clean

/loop
Run flutter analyze.
If there are any errors or warnings, read each one carefully and fix it.
Run flutter analyze again.
Continue until flutter analyze reports zero issues.
Do not move on while there are errors remaining.

TDD Loop

/loop
Run: flutter test --name "WalletNotifier"
If the test fails, read the failure output carefully.
Make the minimal code change required to fix the failure.
Do not change the test itself.
Run the test again.
Stop when the test passes with no errors.

Build a Screen, Check it, Iterate

/loop
Look at the Figma spec notes in CLAUDE.md under "Remaining screens".
Pick the next incomplete screen.
Build the screen following the architecture pattern in lib/features/wallet/presentation/.
After building, run flutter analyze and fix any issues.
Add a comment `// DONE` at the top of the completed screen file.
Move to the next screen.
Stop after completing 3 screens.

A word of caution: /loop is powerful, but give Claude a clear stop condition. "Keep going until it's perfect" is not a stop condition. "Stop when flutter analyze and flutter test both pass with zero issues." is.

6. Subagents for Parallel Screen Development

Subagents are isolated Claude instances that run a task in their own context window and then return only a summary to the main session. This changes how you think about working with Claude Code on a multi-screen project.

A simple way to understand it is to imagine building a full Flutter app with multiple screens. Without subagents, you would design the home screen, then the profile screen, then settings, all in one long conversation. Over time, the context gets heavier, and Claude starts losing focus on earlier decisions.

With subagents, it's like giving each screen to a different engineer. One works on the home screen, another builds the profile screen, and another handles settings. Each one works independently, follows the same project rules, and reports back only when the screen is ready. You then combine their output into the main project without losing clarity or consistency.

Setting Up a Screen-Builder Subagent

Create a file at .claude/agents/screen-builder.md:

---
name: screen-builder
description: Builds a single Flutter screen following the app's feature-first Riverpod architecture
model: claude-sonnet-4-6
tools: [Read, Write, Bash, Glob]
---

You are a Flutter engineer building a screen for a fintech app.

Before building anything:
1. Read lib/features/wallet/presentation/screens/wallet_screen.dart to understand the existing screen pattern
2. Read CLAUDE.md for conventions and architecture rules
3. Read the feature's existing providers in the presentation/providers/ folder

When building the screen:
- Follow the exact same structure as the existing screens
- Use AsyncValue pattern for loading/error/data states
- No business logic in the widget — all state goes through the provider
- Every monetary amount displayed in naira but stored in kobo (divide by 100 for display)
- Use GoRouter for navigation, not Navigator.push

After building:
- Run flutter analyze on the file
- Fix any errors
- Return a summary: file path created, provider used, any decisions made

Using it

In your main session, you can now say:

Use the screen-builder subagent to build the Transaction History screen.
The screen should show a list of transactions from the WalletNotifier provider.
Each item should display: amount (formatted), description, date, and status badge.

Claude dispatches the subagent, which reads your existing code for context, builds the screen following your patterns, fixes any lint errors, and returns a clean summary, without cluttering your main thread with every intermediate step.

You can also run multiple subagents simultaneously for truly parallel work:

Dispatch three screen-builder subagents in parallel:
1. Transaction History screen (list of transactions)
2. Send Money screen (amount input + recipient selection)
3. Wallet Top-Up screen (amount input + payment method)

Each should follow the existing wallet feature patterns.
Report back when all three are complete.

7. Hooks — Enforcing Rules Deterministically

Skills and subagents influence how Claude thinks and plans, but hooks are different. Hooks are deterministic. They run automatically at specific lifecycle events, no matter what Claude decides to do. This makes them useful for enforcing hard rules in your workflow.

A simple way to understand it is to think of hooks as guards in a real engineering pipeline. For example, before any code is committed, a PreToolUse hook can run to check formatting or block unsafe changes. After a tool runs, a PostToolUse hook can validate the output. When a session ends, a Stop hook can trigger cleanup tasks or logging. Other events, like SessionStart, PreCompact help you initialize context or manage memory before Claude continues working.

In practice, hooks are how you enforce consistency. While Skills and subagents guide Claude’s behavior, hooks ensure certain actions always happen at the right moment, without relying on Claude to “remember” or “decide.”

Block Edits to Generated Files

Generated files like *.g.dart and *.freezed.dart should never be edited manually — they get overwritten by build_runner. This hook blocks Claude from writing to them:

Create .claude/hooks.json:

{
  "PreToolUse": [
    {
      "matcher": "Write|Edit",
      "command": "bash -c 'if [[ \"\(CLAUDE_TOOL_INPUT_PATH\" == *.g.dart ]] || [[ \"\)CLAUDE_TOOL_INPUT_PATH\" == *.freezed.dart ]]; then echo \"Blocked: Do not edit generated files. Run build_runner instead.\"; exit 1; fi'"
    }
  ]
}

Run Analyze Before Every Stop

This hook runs flutter analyze before Claude considers its turn complete, catching lint errors before they accumulate:

{
  "Stop": [
    {
      "command": "bash -c 'result=\((flutter analyze 2>&1); if echo \"\)result\" | grep -q \"error •\"; then echo \"Flutter analyze found errors. Fix before stopping:\"; echo \"$result\"; exit 1; fi'"
    }
  ]
}

Now Claude can't finish a turn if there are lint errors. It gets blocked and has to fix them first.

8. Putting It All Together: A Real Sprint Workflow

Here's what a typical feature development session looks like when all of this is configured:

Morning: Check Project State

/sprint-status

Claude reads live Git status, recent commits, and current lint output, then summarises what needs attention.

Start a New Feature

I need to build the beneficiary management feature. 
Users should be able to save, view, and delete beneficiaries for the transfer flow.
Start with the data layer — Freezed model and repository interface.

Claude reads your CLAUDE.md and existing feature patterns, then builds the model and repository in the right place, following your conventions.

Generate All the Screens in Parallel

Use the screen-builder subagent to build:
1. BeneficiaryListScreen — shows saved beneficiaries with search
2. AddBeneficiaryScreen — form with account number and bank selection
3. BeneficiaryDetailScreen — shows details with delete option

Fix Everything Until it's Clean

/loop
Run flutter analyze.
Fix all errors.
Run flutter test.
Fix any test failures.
Stop when both pass with zero issues.

Commit Cleanly

Commit the beneficiary feature

The commit skill triggers, runs analyze one more time, and creates a correctly-formatted conventional commit message.

Key Takeaways

If there's one key takeaway from all of this, it's that Claude Code isn't just about prompting. It's about setup. The quality of its output is shaped far more by what you define about your project upfront than by what you type in the moment.

This is also what separates vibe coding from real AI-assisted engineering. Without structure, you end up guessing and reacting, which feels fast but breaks down quickly.

With the right setup, Claude becomes a pair programming partner that follows your conventions and handles execution while you focus on decisions that actually require engineering judgment. That shift is what lets you spend less time fixing generated code and more time solving the problems that matter.

The payoff compounds. A CLAUDE.md takes 20 minutes to write. A skill for your release flow takes 10 minutes. But both of those pay for themselves the first time Claude correctly follows your process without you having to walk it through every step.

Start small: write your CLAUDE.md this week. Add one skill for the task you repeat most — committing, releasing, or running lint. Then, when you're comfortable, try a /loop on your next test-fixing session. The rest follows naturally.

The goal isn't to let AI write all your code. It's to stop spending your limited engineering time on the parts that don't require your judgment, and to spend more of it on the parts that do.