最佳實踐

使用 OpenYida 和 AI 驅動應用生成的最佳實踐建議，涵蓋提示詞編寫、增量迭代、環境配置和協作開發等方面。

​

1. 編寫詳細提示詞

產生應用程式的品質與提示詞的詳細程度成正比。對比：

模糊（避免）

建立一個 CRM

---

​

2. 使用需求文件

複雜應用程式先寫 PRD，再交給 AI：

根據以下需求文件生成宜搭應用程式：

[貼上 PRD — 欄位名、類型、驗證規則、工作流程等]

這種方式比反覆提示詞產生更準確的結果。

---

​

3. 增量迭代

不要試圖在一個提示詞中建構所有內容。先建構核心結構，再逐步增加複雜度：

第 1 步：建立基礎員工資訊表單
第 2 步：新增關聯員工的請假申請表單
第 3 步：設定請假審批流程
第 4 步：新增顯示待審批的經理儀表板
第 5 步：發布儀表板為公開頁面

---

​

4. 資料操作前必須執行 get-schema

宜搭欄位 ID 由平台隨機生成（如 textField_eftt1aa5m），無法從欄位名稱猜測。在建立、更新或按欄位條件查詢資料前，務必先執行：

openyida get-schema <appType> <formUuid>

寫入資料後，查詢至少一筆記錄驗證結果：

openyida data query form <appType> <formUuid> --size 1

確認 formData 中欄位有實際值。若所有值為空，表示欄位 ID 有誤，需重新執行 get-schema 並修正。

---

​

5. 每步驗證

AI 建立每個元件後，讓它驗證：

顯示 [表單名] 表單的目前 Schema
檢查 [頁面名] 頁面是否已發布並可存取

及早發現問題，避免累積成大問題。

---

​

6. 複用專案工作目錄

每個專案只執行一次 openyida copy，不要每次工作階段都執行。project/config.json 檔案儲存 appId 和 corpId —— AI 用它知道目標應用。專案中途不要刪除此檔案。

---

​

7. 環境特定登入

不同 AI 工具需要不同登入方式：

AI 工具	登入指令
Claude Code、Cursor、VSCode	openyida login
悟空	openyida login
OpenCode、Aone Copilot	openyida login

切換工具時，先執行 openyida env 確認啟用環境。

---

​

8. 自訂頁面圖片使用 CDN

自訂頁面含圖片時，先上傳至 CDN 確保可靠渲染：

openyida cdn-config   # 設定阿里雲 OSS + CDN（一次性）
openyida cdn-upload ./my-image.png   # 取得穩定 CDN URL

然後在頁面提示詞中引用 CDN URL：

使用此 CDN URL 給登陸頁面新增首頁橫幅圖片：https://cdn.example.com/banner.png

---

​

9. 處理多組織設定

可存取多個宜搭組織時：

openyida org list          # 檢視所有可用組織
openyida org switch --corp-id <id>   # 切換到目標組織
openyida env               # 確認切換

建立應用程式前始終驗證啟用組織，避免在錯誤空間建構。

---

​

10. 除錯前先執行 Doctor

花時間除錯失敗指令前，先執行：

openyida doctor --fix

自動偵測並解決最常見問題：過期工作階段、缺失設定檔案、環境不匹配。

---

​

11. AI 輔助 PR 歡迎

向 OpenYida 本身貢獻時，完全接受 AI 產生的程式碼。在 PR 描述中註明使用的 AI 工具 —— 幫助維護者理解產生上下文，更高效地審查。