AGILAB 軟體開發手冊
歡迎加入 AGILAB！本手冊是你在實驗室開發研究專案的完整指南。
新生閱讀路線
第一次進實驗室？從這裡開始
依照下方步驟順序讀完，你就能獨立建立並管理一個符合實驗室規範的研究專案。
第一週必讀（專案啟動前完成）
| 步驟 | 章節 | 你會學到什麼 | 所需時間 |
|---|---|---|---|
| 1 | 快速啟動 | Clone 實驗室 repo、建立個人開發分支 | 15 分鐘 |
| 2 | 環境管理 | 如何用 Conda 建立可重現的開發環境 | 10 分鐘 |
| 3 | 模板結構說明 | 每個資料夾與設定檔的用途 | 10 分鐘 |
| 4 | Commit 規範 | 如何寫出讓隊友看懂的 Git commit 訊息 | 5 分鐘 |
日常開發（第一週後熟悉）
| 步驟 | 章節 | 你會學到什麼 | 所需時間 |
|---|---|---|---|
| 5 | 程式碼規範 | 風格規範、型別提示、Docstrings | 10 分鐘 |
| 6 | 日常 Git 操作 | 分支工作流、每日 commit 與 PR 流程 | 15 分鐘 |
| 7 | Logging 與除錯 | 用 logging 取代 print、讀懂錯誤訊息 | 10 分鐘 |
| 8 | 撰寫與執行測試 | 用 pytest 保護你的程式邏輯 | 15 分鐘 |
| 9 | 實驗管理 | 讓每次實驗結果都可追溯、可重現 | 10 分鐘 |
研究規範（開始跑實驗前閱讀）
| 步驟 | 章節 | 你會學到什麼 | 所需時間 |
|---|---|---|---|
| 10 | 研究可重現性 | 種子設定、決定性演算法、資料版本化 | 10 分鐘 |
| 11 | 專案生命週期 | 從開案到論文發表後的程式碼管理 SOP | 10 分鐘 |
📚 附錄知識庫
如果你在依照新生路線閱讀時，發現某些基礎工具不夠熟悉，或者在專案開發中遇到特定的進階部署與除錯需求，可以隨時查閱 附錄總覽。
我們將附錄內容整理為四個層級，方便你依照自身背景補齊知識：
- L1: 基礎工具與協作：Git 基礎與衝突處理解決。
- L2: 環境建置與相依性管理：Conda 進階設定、Editable 安裝、
pyproject.toml套件發布、Docker 部署與 tmux 管理。 - L3: 程式碼風格與型別安全：Google Python 規範、實用 Type Hinting（聯合型別與別名）、Google Style Docstrings 自動生成。
- L4: 進階工程與除錯技巧：pytest 測試與 Mock、console/file 雙輸出 Logging 配置。
基礎建設
- SoftwareTemplate: 所有研究專案的起點，內含標準目錄結構與自動化 Lint。
聯絡資訊
如果你對規範有任何建議，請聯繫閔傑老大或透過 Issue 提出討論。
下一步 → 快速啟動