Skip to content

AGENTS.md

Latest commit

 

History

History
52 lines (39 loc) · 3.4 KB

AGENTS.md

File metadata and controls

52 lines (39 loc) · 3.4 KB

DevTools Repo Guidelines for AI Assistants

Follow these rules when working in this repository.

Repository Rules

Dependencies

  • packages/devtools_shared: Never introduce a Flutter dependency or a dependency on web-only Dart libraries.
  • Imports: Never import packages/devtools_app/lib/devtools_app.dart in code under packages/devtools_app/lib/src/. It is acceptable in test code.

Published Packages (packages/devtools_shared, packages/devtools_app_shared, packages/devtools_extensions)

  • Document file changes in the respective CHANGELOG.md files.
  • Ensure version numbers in pubspec.yaml are updated accordingly for required changes.
  • Ensure no breaking changes are introduced. If introduced, they must be intentional and documented.
  • The published packages should not depend on unpublished packages like packages/devtools_app and packages/devtools_test.

Code Style

  • Style Guide: Follow the DevTools style guide in STYLE.md.
  • Formatting & Analysis: Always ensure code is formatted properly and has no analysis errors or warnings before completing a task.

Code Quality & Maintainability

  • DRY (Don't Repeat Yourself): Identify blocks of code that are 90%+ identical to existing utility methods in this repo and flag them for duplication.
  • Meaningful Naming: Variables should describe their intent (e.g., timeoutInMs instead of t).
  • Descriptive Pull Request: Contributors should include the information recommended in the pull request template (in .github/PULL_REQUEST_TEMPLATE.md).

Documentation

  • All public members should have documentation.
  • Answer your own questions: If you have a question, find the answer, and then document it where you first looked.
  • Documentation should be useful: Explain the why and the how.
  • Introduce terms: Assume the reader does not know everything. Link to definitions.
  • Use /// for public-quality documentation, even on private members.

Running Tests

  • Standard Packages: Run unit and widget tests with flutter test.
  • packages/devtools_shared: Run tests with dart test.
  • Integration Tests: Refer to the Integration Test README for instructions on running integration tests.

UI Development Guidelines

Constants and Magic Values

  • Avoid Raw Values: Avoid using raw strings or numbers in UI code. Use named constants instead.

Themes and Styles

  • Use Existing Themes: Use existing theme values and text styles from packages/devtools_app_shared/lib/src/ui/theme/theme.dart (e.g., Theme.of(context).regularTextStyle).
  • Reuse Patterns: Reuse common patterns and styles used in other UI code in the repository.

Code Reuse

  • Use Shared Components & Utils: Prefer using reusable components from shared/ui/ (such as packages/devtools_app/lib/src/shared/ui/common_widgets.dart), primitives from shared/primitives/, and utilities from shared/utils/ rather than creating things from scratch.

Helper Widgets and Methods

  • Avoid Long Build Methods: Use separate helper widgets instead of writing excessively long build methods to keep the structure clear.
  • Prefer Widgets Over Methods: Create small, composable helper widgets rather than helper methods that return a widget at build time. This improves readability and allows Flutter to optimize tree updates better.