From 524b91f454822337e13acd6fb18421309aea6679 Mon Sep 17 00:00:00 2001 From: qzl Date: Thu, 19 Mar 2026 18:43:23 +0800 Subject: [PATCH] docs: update AGENTS.md with new guidelines - Add ui-ux-pro-max skill reference - Add keyboard overlay behavior rules for Flutter - Update testing strategy to prioritize high-regression flows - Add copy priority rules for auth and form pages - Update minimal interface copy guidelines --- AGENTS.md | 1 + apps/AGENTS.md | 22 ++++++++++++++++++++-- backend/AGENTS.md | 14 ++++++++++++++ 3 files changed, 35 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 099485d..ea97a7c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -57,5 +57,6 @@ This ensures frontend and backend stay synchronized and prevents drift. - `ag-ui`: AG-UI protocol implementation guidance. - `agentscope-skill`: AgentScope framework guidance. +- `ui-ux-pro-max`: APP UI design guidelines. Skill invocation and process routing are governed by workspace runtime rules. diff --git a/apps/AGENTS.md b/apps/AGENTS.md index 480fbc8..52219d3 100644 --- a/apps/AGENTS.md +++ b/apps/AGENTS.md @@ -55,6 +55,14 @@ This document defines **hard constraints** for Flutter mobile development. Treat - If persistent header/footer regions exist, **MUST** center primary content within the remaining usable region. - **MUST** prioritize *visual centering* over purely geometric centering when they differ. +## 4.1) Keyboard Overlay Behavior (MUST) + +- For pages with text input, keyboard appearance **MUST** prefer overlay behavior and avoid reflowing the whole page. +- Input pages **MUST** avoid global layout jump when keyboard opens/closes (including subtle shifts caused by safe-area padding changes). +- Default strategy for full-screen pages with fixed hierarchy: `Scaffold.resizeToAvoidBottomInset = false`. +- If a page truly requires keyboard-driven scrolling to keep focused fields reachable, this must be an explicit opt-in and justified by page structure. +- When using `SafeArea` on keyboard-overlay pages, **MUST** stabilize bottom safe-area behavior (for example, maintain bottom view padding) to prevent center recalculation jitter. + ## 5) Testing Strategy (MUST) Follow lightweight testing strategy - prioritize value over coverage: @@ -62,10 +70,16 @@ Follow lightweight testing strategy - prioritize value over coverage: **Write tests for:** - Model / DTO parsing (json → model) - Service layer logic (business rules, API call handling) -- Complex custom widgets with rich interactions +- High-regression UI interaction flows only (multi-state/multi-step widgets, viewport/scroll decision logic, route return stability) -**Skip for:** +**Default skip for UI tests:** - Simple UI pages, regular buttons, basic layouts +- Pure visual structure/snapshot-like checks without behavior risk +- Low-risk styling and static rendering changes + +**UI test policy:** +- UI tests are opt-in, not default; only keep or add them when failure risk is high and there is clear regression value. +- If a UI test does not protect critical interaction behavior, remove it or avoid adding it. ## 6) UI Feedback System (MUST) @@ -110,6 +124,10 @@ All UI/UX work **MUST** follow the visual design language defined in `apps/rules - **MUST** achieve visual hierarchy through spacing, surface grouping, radius, depth, density, contrast, scale, and motion—not color alone. - **MUST** prioritize compact informational delivery in top bars: when the page purpose can be clearly expressed by a concise header title, avoid repeating equivalent explanatory hints in the body. - **MUST NOT** duplicate page identity text between header and first content block unless the repeated text introduces new decision-critical information. +- **MUST** keep interface copy minimal and action-oriented: every text node must justify its presence by either enabling a decision, reducing error risk, or satisfying compliance requirements. +- **MUST NOT** stack multiple instructional hints around the same control (for example title + subtitle + placeholder + helper text all repeating the same meaning). +- **MUST** follow copy priority for auth and form pages: `Primary action > Required input labels > Error/recovery > Compliance`. Secondary explanatory copy should be removed when users can complete the task without it. +- **MUST** ensure each form field has at most one primary hint source in normal state (prefer placeholder or label, not both with duplicated wording). - **MUST** follow the screen-level decision rules: 1. What is the primary focus? 2. What is the surface hierarchy? diff --git a/backend/AGENTS.md b/backend/AGENTS.md index 00ad71c..07a05db 100644 --- a/backend/AGENTS.md +++ b/backend/AGENTS.md @@ -164,6 +164,20 @@ Use `schemas / repository / service` pattern: - `service.py` — authorization + business logic + transaction boundary (must commit/rollback) - `dependencies.py` — DI (`get_db`, `get_current_user`) +### Schema-First and Strong Typing (Mandatory) + +**Data model constraints are the first priority. Define schemas before implementation.** + +- Any backend feature that introduces or changes data structures MUST define/update strong-typed schemas first. +- All request/response/domain/runtime contracts MUST use explicit Pydantic models or typed dataclasses. +- Prohibit weak typing in data contracts: `Any`, untyped `dict`, untyped `list`, `object` placeholders. +- Prohibit using raw `dict[str, object]` as the canonical contract for pipeline/stage/config/domain payloads. +- External library boundaries may accept weakly typed input only at adapter edges; data MUST be converted immediately into local strong-typed schemas before entering service/domain layers. +- New model placement rules: + - Cross-module runtime/domain contracts: `backend/src/schemas/**` + - HTTP request/response contracts: `backend/src/v1/**/schemas.py` + - ORM persistence models: `backend/src/models/**` + ### Auth & Data Access - Backend must verify JWT signature and expiration (not just decode)