moonbit-agent-guide

此技能作為開發者在使用 MoonBit 進行專案構建時的全面技術指南。它為從初始化新模組到維護穩健、可投入生產的程式碼庫提供了結構化的建議。無論您是在設定專案目錄、管理跨套件依賴，還是優化 MoonBit 特有的併發與安全性模式，此代理程式都能協助您完成配置、重構與除錯任務。

該代理程式專為需要遵循慣用專案佈局、確保型別安全並有效利用 moon 命令列介面的軟體工程師所設計。它擅長解釋如何從單個 .mbt 檔案過渡到有組織的套件，如何編寫黑箱與白箱測試，以及如何解讀編譯器產生的 .mbti 介面檔案。它還能幫助開發者避免常見的陷阱，例如錯誤處理可變紀錄欄位、不當的錯誤傳播或誤用已棄用的語法。

• 專案支架：為複雜的多套件儲存庫建立與管理 moon.mod.json 和 moon.pkg.json 設定。

• 工具自動化：執行與排除核心工作流程的問題，包括 moon build、moon check、moon test 和 moon doc。

• 重構支援：安全地在 .mbt 檔案間拆分、合併或重組宣告，且不破壞套件語意。

• 慣用語法：提供關於使用 mut 關鍵字、使用 get() 處理陣列邊界，以及採用最新語法而非棄用的 ! 或 ? 模式的指導。

• 測試框架：設定 *_test.mbt 黑箱測試以及整合式的 README.mbt.md 文件與測試週期。

• 請務必將套件定義在包含 moon.pkg.json 的目錄中，因為 moon 命令必須在根模組目錄中執行。

• 在程式碼審查期間，優先使用 .mbti 介面檔案來驗證公開 API 介面。

• 避免硬編碼路徑假設；依賴模組系統透過 @username/module_name/package_path 來引用程式碼。

• 當遇到編譯錯誤時，請確認函式是否正確加上 Type:: 前綴，並檢查變數命名是否符合 MoonBit 的駝峰式或底線命名規範。