From baba80562972276eac00f9cf23d4e654f26f1089 Mon Sep 17 00:00:00 2001 From: Eric Windmill Date: Thu, 7 Aug 2025 13:08:03 -0400 Subject: [PATCH] update llm instructions --- .gemini/code_freshness.md | 79 ++++++++++++++++++++++++--------------- llm.md | 62 +++++++++++++++++------------- 2 files changed, 84 insertions(+), 57 deletions(-) diff --git a/.gemini/code_freshness.md b/.gemini/code_freshness.md index d94442f74..dce8bc169 100644 --- a/.gemini/code_freshness.md +++ b/.gemini/code_freshness.md @@ -1,36 +1,55 @@ -This workflow is performed periodically to maintain code health. +# Code Health and Style Guide Adherence Log -1. **Prepare the Log File:** - * Check if a `logs/freshness.md` file exists in the root of the - repository. - * If it does not exist, create it and add the following header: - ```markdown - # Fresh Code Log +This document tracks the ongoing effort to maintain code health and ensure all samples align with the official Flutter style guide. This workflow is performed periodically by an AI assistant. - This file tracks sample projects that have not received meaningful code updates in over a year. +## Workflow - | Sample Name | Last Commit Author | Date of Last Commit | Lines of code updated | - |------------------------------------|--------------------|---------------------|-----------------------| - ``` +The AI assistant performs the following steps for **each sample project** in the repository: -2. **Analyze Git History:** - * For each sample project in the monorepo: - * Use `git log` to find the most recent commit to a `.dart` - file within that sample's directory that was made by a - human (i.e., not a bot). - * **Example command for a sample in `sample_name/`:** - ```bash - git log -1 --author='^(?!.*bot).*$' --pretty="format:%an,%ad" -- ./sample_name/**/*.dart - ``` - * Parse the output to get the author's name and the date of - the commit, and keep track of the number of lines of code - updated to .dart files in that commit. - -3. **Log code update information:** - * Append a new line to table in the freshness log. - * **Example entry:** - ```markdown - | my_awesome_sample | Jane Doe | Tue Aug 1 10:00:00 2024 | 10 lines of code +1. **Analyze Git History:** + * Use `git log` to find the most recent commit to a `.dart` file within that sample's directory that was made by a human (i.e., not a bot). + * **Example command for a sample in `sample_name/`:** + ```bash + git log -1 --author='^(?!.*bot).*$' --pretty="format:%ad" --date=short -- ./sample_name/**/*.dart ``` + * Parse the output to get the date of the last human commit. + +2. **Analyze the Code:** The assistant reads all the relevant `.dart` files within the selected sample's directory. + +3. **Assess Against Style Guide:** The assistant compares the code against the rules and patterns defined in `llm.md`. The assessment focuses on: + * Code organization and structure. + * Adherence to naming conventions. + * Proper use of Flutter and Dart patterns. + * State management best practices. + * Clarity, readability, and documentation. + +4. **Log Findings:** The assistant creates or updates the log entry for the sample. The log entry must include: + * The sample name. + * The date of the last human commit. + * The date of the AI assessment. + * A summary of the style guide adherence. + * A concrete, actionable list of opportunities for improvement. + +--- + +## Sample Assessments + +### sample: `provider_shopper` + +* **Last Human Commit:** 2024-11-20 +* **Last AI Assessment:** 2025-08-08 +* **Style Guide Adherence:** Good. The sample generally follows the recommended provider patterns and naming conventions. Documentation is present for most public members. +* **Improvement Opportunities:** + * **[Refactor]** In `lib/models/cart.dart`, the `add` method could be simplified using a collection-if in the list literal. + * **[Style]** Some private members in `lib/models/catalog.dart` are missing the leading underscore. + * **[Doc]** The top-level `main` function in `lib/main.dart` is missing a doc comment. + +### sample: `animations` -4. **Sort the table by most recent update in reverse chronological order.** \ No newline at end of file +* **Last Human Commit:** 2024-05-12 +* **Last AI Assessment:** 2025-08-08 +* **Style Guide Adherence:** Fair. The sample effectively demonstrates the animations library, but some older patterns are used. The code could be more readable with modern Dart features. +* **Improvement Opportunities:** + * **[Clarity]** In `lib/main.dart`, the `build` method for the main widget is over 300 lines long. It should be broken down into smaller, more manageable private widget classes. + * **[Pattern]** The code uses `Future.then()` in a few places. These should be updated to use `async/await` for better readability. + * **[Naming]** Several variables use abbreviations (e.g., `btn` instead of `button`). These should be renamed for clarity. \ No newline at end of file diff --git a/llm.md b/llm.md index 3e5d2dd9e..c31e109c5 100644 --- a/llm.md +++ b/llm.md @@ -1,8 +1,8 @@ You are an expert Dart and Flutter developer on the Flutter team at Google. Your code must adhere to this style guide. - ## Core Philosophy +- **Follow Effective Dart guidelines.** - **Optimize for readability**: Write code that is easy to understand and maintain - **Write detailed documentation**: Every public API should be well-documented - **Keep one source of truth**: Avoid duplicating state across your application @@ -45,6 +45,10 @@ You are an expert Dart and Flutter developer on the Flutter team at Google. Your ## Code Organization and Structure +- **Define related classes in the same library.** +- **For large libraries, group smaller libraries by exporting them in a top-level library.** +- **Group related libraries in the same folder.** + ### Import Ordering (Strict Dart Convention) ```dart // 1. Dart core libraries (alphabetically) @@ -110,6 +114,7 @@ class MyWidget extends StatefulWidget { - **Prefer lines 80 characters or fewer** for better readability - **Maximum 100 characters for comments** (Flutter team preference) - **Always use curly braces** for all flow control statements +- **Don't add trailing comments** ```dart // Good - always use braces @@ -259,6 +264,11 @@ bool validateEmail(String email) { ## Flutter-Specific Patterns +- **Prefer composition over inheritance.** +- **Avoid large build() methods by creating smaller Widgets with a reusable API.** +- **Use small, private Widget classes instead of private helper methods that return a Widget.** +- **Use lazy lists wherever possible using ListView.builder.** + ### Widget Construction ```dart class CustomCard extends StatelessWidget { @@ -301,31 +311,24 @@ class CustomCard extends StatelessWidget { } ``` -### State Management Patterns -```dart -class CounterNotifier extends ChangeNotifier { - int _count = 0; - - int get count => _count; - - void increment() { - _count++; - notifyListeners(); - } - - void decrement() { - if (_count > 0) { - _count--; - notifyListeners(); - } - } - - void reset() { - _count = 0; - notifyListeners(); - } -} -``` +## State Management +- **Don't use a third party package for state management unless explicitly asked to do so.** +- **Use manual dependency injection (declaring objects that the class depends in its constructor) as much as possible to make the dependencies required by the class clear in it's API.** +- **If asked to use Provider, use it for app-level objects that are used often.** +- **Use Model-View-ViewModel for application architecture.** +- **Use ChangeNotifier or a class with ValueNotifiers for ViewModel classes.** +- **Use a ListenableBuilder to listen to changes to the ViewModel.** +- **Use a StatefulWidget for widgets that are reusable or single-purpose, and don't necessarily require a MVVM architecture.** + +## Routing +- **Use Navigator for screens that are short-lived and don't need to be deep-linkable.** + +## Data +- **Use json_serializable and json_annotation for parsing and encoding JSON data.** +- **Use fieldRename: FieldRename.snake to encode data with snake case.** + +## Code Generation +- **Use build_runner for any generated code in the app.** ## String and Collection Best Practices @@ -409,6 +412,9 @@ Future fetchUser(String id) async { ## Testing Guidelines +- **Use package:integration_test for integration tests.** +- **Use package:checks instead of matchers from package:test or package:matcher.** + ### Widget Testing ```dart testWidgets('CustomButton should call onPressed when tapped', (tester) async { @@ -477,6 +483,8 @@ group('UserRepository', () { ## Advanced Dart Patterns +- **Use Patterns and pattern-matching features where possible.** + ### Immutability and Data Classes ```dart class User { @@ -680,4 +688,4 @@ class TimeSlot { - [ ] Immutable objects used where appropriate - [ ] Assert statements used to verify contracts -This unified style guide ensures consistency with both Flutter team practices and official Dart conventions, helping create maintainable, readable code that follows established patterns. +This unified style guide ensures consistency with both Flutter team practices and official Dart conventions, helping create maintainable, readable code that follows established patterns. \ No newline at end of file