菜单
Pre-flight checklist of frequent agent mistakes. Use before writing or reviewing code.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Canonical rules — feature layers, domain purity, cubit vs widget roles, DI entrypoints, Freezed. Part of agents-canonical-rules split.
Scaffold or add a feature Cubit with Freezed state, tests, and repo-standard placement under presentation/cubit/.
Figma design-to-code for this repo (figma-sync assets, Flutter adaptation, MCP).
Dependency direction and feature composition. Use for shared package/app-shell changes, cross-feature deps, auth/theme contracts.
External references and key file paths for this repo. Use when locating theme, DI, lifecycle, sync, HTTP, or Supabase code.
Flutter BLoC app stack snapshot and lib/ layout. Use at task start or when adding features, routes, or shared code.
| name | agents-common-pitfalls |
| description | Pre-flight checklist of frequent agent mistakes. Use before writing or reviewing code. |
Pre-flight scan before first edit on non-trivial work. Owner register:
docs/ai/ai_failure_risks.md.
Full rules: agents-canonical-rules (+ matching agents-canonical-rules-*).
Table: docs/CODE_QUALITY.md.
| Pitfall | Risk ID | Prevention |
|---|---|---|
Flutter/UI imports in domain/ | RISK-ARCH-LAYER | agents-feature-delivery; check_clean_architecture_imports.sh |
Copy legacy cubit layout (cubits/, root cubits) | RISK-ARCH-LAYER | reference_features.md; presentation/cubit/ |
MVVM outside presentation (viewmodels/, repo in ViewModel folder) | RISK-ARCH-LAYER | clean_architecture.md § Architecture skeleton; feature_structure_contract.md |
context.read / BlocProvider.of | RISK-BLOC-DIVERGENCE | type-safe-bloc-access; context.cubit<T>() |
Emit after close() or leaked subscriptions | RISK-ASYNC-LIFECYCLE | agents-canonical-rules-async; cancel in close() |
context after await without mounted | RISK-ASYNC-LIFECYCLE | Guard mounted; keep side effects in Cubit |
| Remote fetch overwrites offline-pending local | RISK-OFFLINE-OVERWRITE | agents-shared-patterns; offline adoption guide |
| Skip DI / routes / l10n / codegen | RISK-INTEGRATION-SEAM | agents-feature-delivery wire-DI rule |
| Start feature without brief/tests | RISK-FEATURE-BRIEF-SKIP | scaffold_feature_contract.sh; feature brief |
| Claim done without focused tests | RISK-TEST-GAP | testing matrix; flutter test <paths> |
| Auth/PII/payments without security pass | RISK-SECURITY-GAP | review/security_checklist.md |
| Commit or print secrets | RISK-SECRET-LEAK | check_tracked_secret_literals.sh |
| Patch Flutter/Dart SDK or core framework files | RISK-FLUTTER-SDK-MUTATION | Treat /Users/ilkersevim/Flutter_SDK/flutter/** as read-only; fix repo code or upgrade toolchain via docs |
rm, deploy, or external mutation without ask | RISK-DESTRUCTIVE-SIDE-EFFECT | List affected items; current-turn confirm |
| Reuse stale checklist / partial proof | RISK-VALIDATION-SHORTCUT | --no-reuse; scorecard gates |
Direct Hive.openBox / ad-hoc Dio | RISK-ARCH-LAYER | DI entrypoints; agents-canonical-rules-platform |
print instead of AppLogger | RISK-UI-REGRESSION | logging standards |
| Hardcoded colors/strings | RISK-UI-REGRESSION | DESIGN.md; AppTheme / l10n |
| Page-only UI (no extractable leaf widget for preview/test) | RISK-UI-REGRESSION | design_system.md § Reusable widgets; word_card_test.dart pattern |
| Fixed width/height on reflowable UI (skip LayoutBuilder/MediaQuery/responsive helpers) | RISK-UI-REGRESSION | design_system.md § Responsive layout; ui_ux_responsive_review.md |
| UI change only tested on one platform/host | RISK-PLATFORM-SCOPE | tech_stack.md § Supported platforms; design_system.md § Cross-platform form factors; flutter-cross-platform-modern |
| Widget works on debug device only (tablet/web/desktop not considered) | RISK-PLATFORM-SCOPE | Mobile + wide widget tests; ui_ux_responsive_review.md § Cross-platform form factors |
| Guess pub API from model memory | RISK-STALE-API | package_docs_mcp.md; Context7 + read_package_uris |
After scan: map task to Minimum proof by task in ai_failure_risks.md.
