122 lines
6.5 KiB
Markdown
122 lines
6.5 KiB
Markdown
# Frontend Agent Guidelines
|
|
|
|
These instructions extend the repository-wide rules in the root `AGENTS.md`
|
|
and apply whenever a task adds or modifies Dart or Flutter code under
|
|
`frontend/`.
|
|
|
|
Before completing the task, review the entire frontend diff produced by the
|
|
current task, fix every in-scope issue found, and then perform the required
|
|
validation. Use the
|
|
[`$review-frontend-change`](../.agents/skills/review-frontend-change/SKILL.md)
|
|
skill to perform this completion workflow.
|
|
|
|
## Preserve the frontend architecture
|
|
|
|
This applies to `frontend/app`, every shared package and future web/mobile
|
|
clients, including in-memory stubs. Keep an explicit data model even when it
|
|
currently resembles the DTO; do not use a provider as a substitute for that model.
|
|
The UI depends on providers/models; providers depend on service contracts; service
|
|
implementations own DTO conversion through mappers. Replacing a service must not
|
|
require DTO or networking changes in widgets or providers.
|
|
|
|
- Strictly preserve the existing `dto` -> `mapper` -> `service` -> `model` ->
|
|
`provider` flow. Widgets consume models and provider state; they must not
|
|
bypass the flow by parsing transport data or calling backend APIs directly.
|
|
- Keep responsibilities separated:
|
|
- DTOs represent serialized transport contracts only.
|
|
- Mappers convert between DTOs and frontend domain models.
|
|
- Services own API and external I/O operations and return mapped models.
|
|
- Models express frontend domain and presentation data without transport or
|
|
provider lifecycle concerns.
|
|
- Providers coordinate services, state transitions, loading and error state,
|
|
and expose models to widgets.
|
|
- Extend the established layer for new behavior instead of introducing parallel
|
|
data paths, embedding mapping in services or providers, or moving business
|
|
state into widgets.
|
|
|
|
## Reuse definitions and avoid naming stutter
|
|
|
|
- Search existing DTOs, models, providers, widgets, and shared utilities before
|
|
introducing another representation of the same concept.
|
|
- Avoid stutter in type names, field names, parameters, nested access paths,
|
|
directories, and filenames. The surrounding package or directory already
|
|
provides context; each child name should add meaning instead of repeating it.
|
|
- Prefer concise access such as `payment.details.id` over
|
|
`payment.payment.paymentId`.
|
|
- Avoid repeating a parent directory in a filename. For example, prefer
|
|
`payment/widget.dart` over `payment/payment_widget.dart` and
|
|
`profile/header.dart` over `profile/profile_header.dart`.
|
|
- Keep architectural suffixes such as `DTO`, `Mapper`, `Service`, `Model`, and
|
|
`Provider` only where they clarify the layer; do not repeat the domain name
|
|
around them, such as `PaymentPaymentDTO`.
|
|
|
|
## Keep widgets structured and files focused
|
|
|
|
- Keep widgets declarative and focused on presentation, composition, and user
|
|
interaction. Move state orchestration and side effects into the established
|
|
provider, service, or controller layer.
|
|
- Review large `build` methods, deeply nested widget trees, and files containing
|
|
multiple responsibilities. Extract cohesive widgets or supporting files with
|
|
clear ownership before the code becomes difficult to scan or test.
|
|
- Prefer one primary public widget or feature concept per file. Small private
|
|
helpers may remain when they are tightly coupled and improve readability; do
|
|
not fragment code into trivial files mechanically.
|
|
- Treat reasonable file size as a cohesion and readability requirement rather
|
|
than a fixed line limit. Generated files are excluded from this review.
|
|
- Preserve lifecycle correctness when extracting widgets or providers,
|
|
including disposal, subscription cleanup, mounted checks, asynchronous race
|
|
handling, and minimal provider notifications.
|
|
|
|
## Maintain Dart header layout
|
|
|
|
- Keep hand-written imports ordered from generic to specific:
|
|
1. Dart SDK imports (`dart:`).
|
|
2. Flutter SDK packages.
|
|
3. Third-party packages.
|
|
4. Shared internal packages such as `pshared`.
|
|
5. The current application package, such as `pweb` or `backoffice`.
|
|
6. Relative imports, when they are necessary.
|
|
- Group imports from the same package together and sort their paths within the
|
|
group. Separate every distinct package group with one blank line.
|
|
- Place generated-code imports, including imports under a package's
|
|
`generated/` path, after all hand-written import groups. Group generated
|
|
imports by package and separate distinct generated package groups with one
|
|
blank line.
|
|
- Place `part` directives after all hand-written and generated import groups;
|
|
they are the final directives in the header. Sort multiple `part` directives
|
|
consistently. In a part file, keep the required `part of` directive first and
|
|
do not add imports that Dart forbids there.
|
|
- Separate the final header directive from the first declaration or annotation
|
|
with exactly one empty line, meaning two consecutive newline characters.
|
|
This is the layout produced by `dart format`.
|
|
- Verify header layout with `dart format` and `flutter analyze`. Do not change
|
|
lint configuration preemptively. If an analyzer rule actually conflicts with
|
|
this layout, adjust only the narrowest affected package configuration,
|
|
document why, and rerun the checks.
|
|
|
|
## Review implementation quality
|
|
|
|
- Review the current task's frontend contribution for correctness, readability,
|
|
maintainability, testability, accessibility, responsive behavior, and
|
|
consistency with surrounding code and architecture.
|
|
- Check loading, empty, success, and error states; nullability; asynchronous
|
|
behavior; provider update scope; navigation; and user-visible failure paths.
|
|
- Remove duplicated logic, dead code, unnecessary indirection, speculative
|
|
abstractions, and avoidable widget rebuilds introduced by the task.
|
|
- Add or update focused tests for changed widgets, DTO mapping, services,
|
|
models, providers, edge cases, and failure paths as applicable.
|
|
- Fix all findings caused by the current task before reporting completion.
|
|
|
|
## Required validation
|
|
|
|
- Run `dart format --output=none --set-exit-if-changed` for every changed Dart
|
|
file.
|
|
- Run `flutter analyze` from each affected frontend package directory.
|
|
- From the repository root, run `make test-frontend`, plus every applicable
|
|
command from the root `AGENTS.md` change-scoped security requirements, after
|
|
all review fixes are complete.
|
|
- All commands must succeed before the task is reported as complete. Do not
|
|
silently skip, suppress, or weaken checks. Report the commands and outcomes
|
|
in the final response, or report the exact environmental blocker without
|
|
claiming successful validation.
|