AGENTS.md

AGENTS.md is a plain markdown file that sits at the root of your Flutter project. AI coding agents such as Cursor, Claude Code, opencode and GitHub Copilot read it automatically before every task. It tells the agent how your project is structured, what conventions to follow and what patterns to use when generating code.

Without an AGENTS.md file, AI agents fall back to their own training defaults. They invent file structures, pick state management libraries you do not use and write code that fights your existing architecture. AGENTS.md replaces those defaults with your rules.

Flutter Agent Kit ships a production-tested AGENTS.md file that covers architecture, data layer, services, UI patterns, naming conventions, setup, git workflow and development process. It is the same file used to ship BitPong, a Flutter app with 1000+ active users on the App Store.

When you scaffold a new project with Flutter Agent Kit, the AGENTS.md file is placed at the project root. Every time you ask your AI agent to write code, the agent reads AGENTS.md first. It learns:

• The project uses Riverpod v3 for state management, not Bloc, not Provider, not GetX.
• Models are plain Dart classes with fromJson/toJson, not freezed or json_serializable.
• Files follow a feature-first directory structure, not a type-first one.
• HTTP calls go through service classes, not directly in widgets or providers.
• Naming conventions: snake_case for database fields, PascalCase for types, camelCase for variables.
• Imports are grouped: built-ins first, then third-party, then absolute aliases, then relative.
• No inline comments, no ternary operators, no useEffect patterns for initial state.

The agent applies these rules to every file it generates or edits. The result is code that looks like it was written by a human who knows your project.

The AGENTS.md file in Flutter Agent Kit is organized into eight sections, each covering a different aspect of the codebase:

• Architecture: App initialization, state management with Riverpod v3, feature-first directory layout and the role of each layer.
• Data: Model conventions, JSON serialization, repository pattern and storage layer rules.
• Services: HTTP service classes, error handling, interceptors and service registration.
• UI: Navigation with GoRouter, theming with the design token system, shared widget patterns and screen structure.
• Conventions: Naming rules, import ordering, file size limits, comment policy and code style enforcement.
• Setup: FVM configuration, dependency management, build targets and environment setup.
• Git: Branching strategy, commit message format, PR workflow and code review expectations.
• Process: Change tracking, task breakdown, testing requirements and development workflow.

Each section is concise enough for the agent to parse quickly but detailed enough to eliminate ambiguity. The file is designed to be read in under 30 seconds by an AI agent.

AI coding agents are powerful, but they are generalists. When you ask an agent to add a feature to a Flutter app, it reaches for patterns from its training data. Those patterns may use Bloc when your project uses Riverpod, or freezed when your models are plain Dart classes, or a type-first directory structure when your project is feature-first.

Every mismatch creates friction. You review the generated code, ask the agent to rewrite it, it makes different mistakes. The back and forth erodes the productivity gain that AI agents promise.

AGENTS.md eliminates that friction. It tells the agent exactly how to write code for your project. The first generation is closer to what you want. The agent spends less time guessing and more time shipping.

This is especially important for Flutter because the ecosystem has many valid approaches. Riverpod vs Bloc vs GetX. freezed vs json_serializable vs plain Dart. GoRouter vs Navigator 2.0. Without AGENTS.md, the agent picks one at random. With AGENTS.md, it picks the one you chose.

AGENTS.md is supported by every major AI coding tool. Flutter Agent Kit has been tested with:

• Cursor: Reads AGENTS.md from the project root and applies it to every chat and edit.
• Claude Code: Loads AGENTS.md as part of its system prompt for every task.
• opencode: Reads AGENTS.md from the project root and applies it to every task.
• GitHub Copilot: Uses AGENTS.md as workspace instructions for code generation.
• Gemini: Reads AGENTS.md when configured as a project context file.
• ChatGPT: Can be pointed to AGENTS.md as a reference document.
• Devin: Reads AGENTS.md from the repository root.

If your agent supports a project-level instructions file, it supports AGENTS.md. The format is plain markdown with no proprietary syntax.

Flutter Agent Kit includes the production-tested AGENTS.md file plus the scaffold command, the feature-first template, on-demand .ai docs and 18 feature skills. One-time purchase, lifetime access, all future updates included.