flutter-coding

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Flutter Coding

Flutter 编码

Điều kiện tiên quyết

前置条件

  • flutter/agent-plugins
    phải đã được cài trong project (
    npx skills add flutter/agent-plugins --skill '*'
    ). Nếu chưa thấy skill này available, báo cho user cài trước khi tiếp tục — không tự viết code theo "kinh nghiệm chung chung" thay thế.
  • Đã đọc
    architecture/SKILL.md
    design-system/SKILL.md
    trong lượt hiện tại.
  • 项目中必须已安装
    flutter/agent-plugins
    (执行命令
    npx skills add flutter/agent-plugins --skill '*'
    )。如果该技能不可用,请告知用户先进行安装,不要用“通用经验”替代编写代码。
  • 当前已阅读
    architecture/SKILL.md
    design-system/SKILL.md
    文档。

Thứ tự ưu tiên khi viết code

编写代码的优先级顺序

  1. Instruction từ
    flutter/agent-plugins
    (Material 3, Riverpod, GoRouter, JSON serialization...) là chuẩn cao nhất.
  2. Rule cứng từ
    architecture/SKILL.md
    (vị trí file, naming) không được vi phạm.
  3. Token từ
    design-system/SKILL.md
    cho mọi giá trị UI.
  4. Model/field phải khớp đúng với delta spec trong
    openspec/changes/<change-name>/specs/
    (đặc biệt sau khi qua
    schema-migration
    ).
  1. flutter/agent-plugins
    的指令(Material 3、Riverpod、GoRouter、JSON serialization...)为最高标准。
  2. architecture/SKILL.md
    中的硬性规则(文件位置、命名规范)不得违反。
  3. 所有UI值均使用
    design-system/SKILL.md
    中的Token。
  4. Model/字段必须与
    openspec/changes/<change-name>/specs/
    中的delta spec完全匹配(尤其是经过
    schema-migration
    之后)。

Quy trình viết 1 tính năng

单个功能的编写流程

  1. Đọc
    openspec/changes/<change-name>/{proposal.md, tasks.md, specs/}
    liên quan đến tính năng đang làm (dùng
    /opsx:continue
    nếu change đã tồn tại từ trước).
  2. Tạo/sửa file theo đúng cấu trúc
    feature/<ten_feature>/{data,domain,application,presentation}
    .
  3. Model dùng
    freezed
    +
    json_serializable
    nếu project đã dùng codegen, giữ nhất quán với các model khác trong project.
  4. Provider Riverpod dùng codegen (
    @riverpod
    ), đặt trong
    application/
    .
  5. Route mới đăng ký trong
    app/router/
    (GoRouter), không hard-code Navigator.push rời rạc.
  6. UI trong
    presentation/screens|widgets
    , ưu tiên tái sử dụng từ
    shared/widgets/
    .
  1. 阅读与当前开发功能相关的
    openspec/changes/<change-name>/{proposal.md, tasks.md, specs/}
    文档(若变更已存在,可使用
    /opsx:continue
    )。
  2. 按照
    feature/<功能名称>/{data,domain,application,presentation}
    的结构创建/修改文件。
  3. 如果项目已使用代码生成工具,Model需使用
    freezed
    +
    json_serializable
    ,与项目中其他Model保持一致。
  4. Riverpod Provider使用代码生成(
    @riverpod
    ),放置在
    application/
    目录下。
  5. 新路由在
    app/router/
    (GoRouter)中注册,不得零散硬编码Navigator.push。
  6. UI代码放在
    presentation/screens|widgets
    目录下,优先复用
    shared/widgets/
    中的组件。

Sau khi viết xong

代码编写完成后

  • KHÔNG dừng lại ở "code xong là done". Luôn chuyển sang
    mcp-loop/SKILL.md
    để build/chạy thử thật.
  • Nếu trong lúc code phát hiện cần package chưa có trong danh sách duyệt của
    architecture.md
    → dừng, hỏi xác nhận, không tự thêm.
  • 不要停留在“代码写完就结束”的阶段。务必切换到
    mcp-loop/SKILL.md
    进行实际构建/运行测试。
  • 如果编码过程中发现需要使用
    architecture.md
    白名单之外的包,请暂停操作,询问确认后再进行,不得自行添加。

Lỗi thường gặp cần tránh

需要避免的常见错误

  • Không tạo
    setState
    tùy tiện trong widget đã có provider quản lý state tương ứng.
  • Không tự đổi tên field model đã tồn tại nếu không đi qua
    schema-migration
    (sẽ vỡ data cũ).
  • Không copy nguyên văn code mẫu từ agent-plugins mà không áp token của design-system (dễ bị lệch theme).
  • 在已有provider管理对应状态的widget中,不要随意使用
    setState
  • 未经过
    schema-migration
    不得擅自修改已存在的model字段名称(会导致旧数据失效)。
  • 不要直接复制agent-plugins中的示例代码而不应用design-system的Token(容易导致主题不一致)。