VibeCoding System

# .cursorrules 文件：軟體開發與 AGI 融合指引 (Windows 環境優化版) 本文件旨在建立一套涵蓋軟體開發全流程與 AGI 輔助技術的整體指引，特別針對 **Windows 環境與 PowerShell** 進行優化，幫助團隊與個人達成快速原型 (POC) 開發、知識積累與持續優化。 ## 🖥️ Windows 環境特別說明 本指引特別針對 Windows 10/11 環境進行優化，包含： - **PowerShell 與 Linux 指令對照表** - **Windows 特有問題解決方案** - **跨平台開發最佳實踐** - **Windows 開發環境設定指引** 文件整合了以下各部分內容： - 與使用者互動及內部記錄的基本指示 - 開發過程中各角色的分工與職責 - 軟體開發流程與運算思維方法 - 快速 POC 開發的 SOP 指引 - 持續學習與自我優化的機制 - 套件與版本紀錄機制（含版本相依性守則） - 依賴查詢：透過官方文件 URL 搜尋套件相依性資訊 - **Windows 環境專用開發指引** ⭐ 新增 --- ## 一、基本指示 (Instructions) ### 🖥️ Windows 環境優先考量 - **指令使用**: 優先使用 PowerShell 指令，必要時提供 Linux 對照 - **路徑格式**: 使用 Windows 路徑格式 (`C:\path\to\file`)，但程式碼中使用跨平台寫法 - **權限管理**: 注意 PowerShell 執行政策與管理員權限需求 - **編碼問題**: 預設使用 UTF-8 without BOM 避免編碼問題 ### 📝 記錄與協作規則 - **可重用資訊記錄** 在與使用者互動過程中，若發現專案中可重用的資訊（例如函式庫版本、模型名稱、錯誤修正或收到的糾正），請立即記錄於本文件的 **Lessons** 區塊，避免日後重複相同錯誤。 **Windows 特別注意**: - 記錄 PowerShell 特有的解決方案 - 標註需要管理員權限的操作 - 記錄路徑相關的問題與解決方案 - **Scratchpad 作為思考與記錄工具** - 使用本文件作為 Scratchpad（工作筆記區），組織與記錄所有新任務的思考、規劃與進度。 - 開發流程規劃 - 任務內容 - 接到新任務時，首先回顧 Scratchpad 內容，若有與當前任務無關的舊任務，請先清除。 - 說明任務內容、規劃完成任務所需步驟，可使用 todo markers 表示進度，如： - [X] 任務 1 - [ ] 任務 2 - 完成子任務時更新進度，並於每個里程碑後反思與記錄，確保全局規劃與細節追蹤兼備。 **Windows 任務規劃特別事項**: - 標明需要管理員權限的任務 - 考慮 Windows Defender 或防毒軟體的影響 - 規劃跨平台相容性測試 --- ## 二、開發指引 development_guideline.md > 此區為根據 產品開發流程使用說明書.md 的指引，規劃整個系統的開發流程作為基本指示 (Instructions) 的 checklist。 --- ## 三、資料夾結構規劃 folder_structure.md > 此區為規劃整個系統的資料夾模組和套件的結構，詳細說明每個檔案的目的用途。 ### 資料夾規劃說明 1. **模組化結構**: - 依照課程六大模組建立對應資料夾 - 各模組下設立統一的子資料夾: data, exercises, notebooks, slides 2. **教材層次化**: - notebooks目錄下的教材依照課程內容進行編號 - 從基礎到進階的漸進式知識建構 3. **實務導向**: - 每個模組均包含exercises提供練習 - M6設置專案目錄用於整合性專題製作 4. **補充資源區**: - 提供參考資料、進階主題與通用資料集 - 常用函數模組化於common目錄下便於重複利用 5. **資料集管理**: - 各模組教學所需的資料集放在模組內的data目錄 - 通用大型資料集集中在supplementary/datasets目錄 --- ## 四、Scratchpad Scratchpad.md > 此區為內部記錄區，請在進行每項任務時依序記錄任務目標、規劃步驟、進度更新與反思筆記，確保能夠隨時回顧與調整作業策略。 --- ## 五、軟體開發公司的角色與職責 - **產品經理 / 業務分析師** - 負責收集需求、定義使用者故事、規劃功能與分析市場趨勢。 - **系統架構師** - 負責決策技術路線、系統架構設計及模組間協作，確保系統擴展性與安全性。 - **開發工程師** - 包括前端、後端及全端工程師，依據需求撰寫程式、進行模組整合及系統優化。 - **測試工程師 / QA** - 制定測試計劃、設計與執行測試用例，確保產品質量並協助修正缺陷。 - **DevOps / 基礎建設工程師** - 負責持續整合、部署自動化、系統監控及運維，確保產品順利上線。 - **UX/UI 設計師** - 負責設計使用者介面與體驗，提升產品易用性與視覺吸引力。 - **專案經理** - 規劃專案進度、調配資源、協調跨部門合作，確保專案按期、按質完成。 --- ## 六、軟體開發流程 1. **需求分析** - 收集使用者需求及市場資訊。 - 制定功能需求與技術規格。 - 與產品經理、業務分析師與設計師密切合作。 2. **系統設計** - 定義系統整體架構、資料流程及模組間的交互。 - 撰寫設計文件、介面規範與數據庫設計。 - 考慮系統安全、可擴展性與容錯機制。 3. **開發實作** - 撰寫前後端程式、進行單元測試。 - 進行代碼審查及版本控制管理（例如 Git）。 - 實施持續整合與自動化部署流程。 4. **測試驗收** - 執行功能、效能及壓力測試。 - 修正 Bug 並執行回歸測試。 - 進行用戶測試與驗收確認。 5. **部署上線** - 部署至正式環境，設定環境配置與監控機制。 - 監控系統運作，快速回應突發狀況。 6. **維運與改進** - 持續監控系統表現，收集用戶反饋。 - 定期進行功能更新與優化。 - 記錄學習與改進經驗，進行持續迭代。 --- ## 七、運算思維在開發流程中的應用 - **分解 (Decomposition)** - 將複雜問題拆解成更小、易解決的部分（例如：核心功能與輔助功能）。 - **抽象化 (Abstraction)** - 找出問題中的共通模式與本質，建立通用模組或解決方案，忽略不必要的細節。 - **模式識別 (Pattern Recognition)** - 從過往經驗中識別重複出現的問題與解決策略，快速制定最佳實踐。 - **演算法設計 (Algorithm Design)** - 根據需求設計高效演算法，並模擬、優化以提高系統效能與資源利用率。 --- ## 八、整合開發知識於 .cursorrules - **經驗教訓 (Lessons)** - 記錄每次專案或模組開發中的問題、解決方案與改進建議。 - 例如：建立標準化分支管理流程以處理版本控制衝突；強調單元測試在早期發現錯誤的重要性。 - **任務與進度管理 (Scratchpad)** - 使用 Scratchpad 作為內部記錄工具，詳細記錄任務目標、步驟與進度。 - 定期回顧並更新任務狀態，促進團隊知識共享與協同成長。 - **自我省思與持續改進** - 每個專案階段結束後進行反思會議，總結成功經驗與不足之處。 - 鼓勵創新思考，將可行方案記錄於本文件中，作為不斷迭代的知識庫。 --- ## 九、AI 快速 POC 開發指引 (附錄) 針對全球前 1% 頂尖碼農，但規劃能力較弱的情況，特別制定以下快速 POC 開發 SOP，融合大廠敏捷流程與快速驗證理念： 1. **問題定義與需求確認** - 明確核心目標，定義需驗證的假設。 - 整理所有關鍵需求與使用案例，限定 POC 範圍。 2. **技術選型與架構規劃** - 快速選擇適用技術棧（語言、框架、資料庫）。 - 繪製簡易架構圖，定義系統組件與 API 接口。 - 辨識技術風險，提前規劃應對措施。 - 構建開發資料夾結構。 3. **快速原型 (POC) 開發** - 建立最小可行產品 (MVP) 以展示核心功能。 - 採用短迭代週期（1-2 天），不斷交付與調整。 - 採用模組化設計，方便後續擴充與維護。 4. **測試與反饋驗證** - 撰寫單元與集成測試，驗證主要功能。 - 進行內部或用戶驗證，收集反饋並記錄改進建議。 - 建立基本監控與日志機制，追蹤原型表現。 5. **文件紀錄與知識分享** - 編寫簡明技術文檔與使用手冊，記錄設計與實作要點。 - 記錄開發過程中的學習與問題解決經驗，作為團隊知識庫。 - 定期舉辦內部技術分享，促進團隊共同成長。 6. **持續迭代與部署準備** - 根據反饋迅速修正與調整原型。 - 定期進行代碼審查，確保程式品質。 - 規劃初步部署流程與基本運維監控，確保系統穩定運行。 --- ## 十、套件與版本紀錄守則 - **版本資訊紀錄** - 每次導入新套件或更新現有套件時，請立即將套件名稱及其版本資訊記錄於本文件專門的套件清單區塊中。 - 建議建立一個獨立區塊或文件（例如 `package_versions.md`），並在 .cursorrules 中註明參考位置，以便於後續維運與排查。 - **持續更新** - 在每次進行環境建置、依賴管理或部署前，檢查並更新相關套件版本，確保所有版本資訊保持最新。 - 當系統規模擴大導致依賴關係複雜時，透過自動化工具（如 `pip freeze`、`npm list` 等）定期生成版本清單，並將結果納入版本控制系統。 - **跨團隊協作** - 所有團隊成員在引入或更新套件時，均應遵循此守則，並在提交說明中標明套件變更情況，方便 DevOps 及維運團隊追蹤歷史變更。 --- ## 十一、Windows 環境開發專用指引 ### Windows 系統特殊考量 - **路徑分隔符號**: Windows 使用反斜線 `\`，但在程式碼中建議使用正斜線 `/` 或 `os.path.join()` 確保跨平台相容性 - **環境變數設定**: 使用 `$env:VARIABLE_NAME` (PowerShell) 或 `%VARIABLE_NAME%` (CMD) - **權限管理**: 某些操作需要「以系統管理員身分執行」PowerShell - **檔案編碼**: 注意 UTF-8 BOM 問題，建議使用 UTF-8 without BOM ### PowerShell vs Linux 指令對照表 | 功能 | Linux/macOS | Windows PowerShell | 說明 | |------|-------------|-------------------|------| | **目錄操作** | | 列出檔案 | `ls -la` | `Get-ChildItem` 或 `dir` | PowerShell 別名：`ls`, `gci` | | 切換目錄 | `cd /path/to/dir` | `Set-Location C:\path\to\dir` | 別名：`cd`, `sl` | | 建立目錄 | `mkdir dirname` | `New-Item -ItemType Directory -Name dirname` | 別名：`mkdir`, `md` | | 刪除檔案 | `rm filename` | `Remove-Item filename` | 別名：`rm`, `del` | | 複製檔案 | `cp source dest` | `Copy-Item source dest` | 別名：`cp`, `copy` | | 移動檔案 | `mv source dest` | `Move-Item source dest` | 別名：`mv`, `move` | | **文件操作** | | 查看內容 | `cat filename` | `Get-Content filename` | 別名：`cat`, `gc` | | 編輯檔案 | `nano filename` | `notepad filename` | 或使用 `code filename` (VSCode) | | 搜尋文字 | `grep "pattern" file` | `Select-String "pattern" file` | 別名：`sls` | | **程序管理** | | 查看程序 | `ps aux` | `Get-Process` | 別名：`ps`, `gps` | | 終止程序 | `kill PID` | `Stop-Process -Id PID` | 別名：`kill`, `spps` | | **網路** | | 測試連線 | `ping hostname` | `Test-Connection hostname` | 或直接用 `ping` | | 下載檔案 | `wget URL` | `Invoke-WebRequest -Uri URL` | 別名：`wget`, `iwr` | | **環境變數** | | 設定變數 | `export VAR=value` | `$env:VAR = "value"` | 臨時設定 | | 查看變數 | `echo $VAR` | `$env:VAR` | 或 `Get-ChildItem Env:` | | **套件管理** | | Python 套件 | `pip install package` | `pip install package` | 相同，但注意路徑 | | Node.js 套件 | `npm install package` | `npm install package` | 相同 | | **權限** | | 執行權限 | `chmod +x script.sh` | `Set-ExecutionPolicy RemoteSigned` | PowerShell 執行政策 | ### Windows 開發環境設定指令 ```powershell # 設定 PowerShell 執行政策 (管理員權限) Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser # 安裝 Chocolatey (Windows 套件管理器) Set-ExecutionPolicy Bypass -Scope Process -Force [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072 iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1')) # 常用開發工具安裝 choco install git nodejs python vscode -y # Python 虛擬環境 (Windows) python -m venv venv .\venv\Scripts\Activate.ps1 # 啟動虛擬環境 deactivate # 停用虛擬環境 # Git 設定 (處理換行符號問題) git config --global core.autocrlf true git config --global core.safecrlf false ``` ### Windows 特有問題解決方案 1. **路徑長度限制** ```powershell # 啟用長路徑支援 (管理員權限) New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force ``` 2. **PowerShell 腳本執行問題** ```powershell # 臨時允許腳本執行 Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process # 永久設定 (當前用戶) Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser ``` 3. **檔案編碼問題** ```powershell # 設定 PowerShell 預設編碼為 UTF-8 $PSDefaultParameterValues['Out-File:Encoding'] = 'utf8' ``` ### Windows 開發最佳實踐 - **使用 WSL2**: 對於需要 Linux 環境的專案，建議安裝 WSL2 - **路徑處理**: 使用 `os.path.join()` 或 `pathlib.Path()` 處理路徑 - **環境變數**: 使用 `.env` 檔案管理環境變數 - **容器化**: 使用 Docker Desktop for Windows 確保環境一致性 ### VibeCoding Windows 專用指令 在 Windows PowerShell 環境下使用 VibeCoding 時的特殊注意事項： ```powershell # 建構所有服務 (Windows) npm run build # 測試 MCP 服務 (注意路徑格式) node "C:\path\to\your\vibeCoding-template\dist\vibe-services\context-manager\index.js" # 設定環境變數 (PowerShell) $env:ANTHROPIC_API_KEY = "your-api-key-here" $env:OPENAI_API_KEY = "your-api-key-here" # 檢查環境變數 Get-ChildItem Env: | Where-Object Name -like "*API*" # Windows 路徑在 mcp.json 中的格式 { "mcpServers": { "vibecoding-context-manager": { "command": "node", "args": ["C:\\Users\\YourName\\Projects\\vibeCoding-template\\dist\\vibe-services\\context-manager\\index.js"] } } } ``` ### Windows 常見問題與解決方案 1. **PowerShell 執行政策問題** ```powershell # 如果無法執行 .ps1 腳本 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser ``` 2. **路徑包含空格問題** ```powershell # 使用引號包圍路徑 node "C:\Program Files\vibeCoding-template\dist\vibe-services\context-manager\index.js" ``` 3. **Node.js 模組路徑問題** ```powershell # 確認 NODE_PATH 環境變數 $env:NODE_PATH = "C:\Users\YourName\AppData\Roaming\npm\node_modules" ``` 4. **防毒軟體干擾** ```powershell # 將專案目錄加入 Windows Defender 排除清單 Add-MpPreference -ExclusionPath "C:\path\to\your\vibeCoding-template" ``` ## 十二、版本相依性與官方文件查詢守則 - **版本相依性查詢** - 每次引入新套件或更新現有套件前，必須查閱該套件官方文件，確認相依性與版本要求。 - 利用 agent 機制自動搜尋並比對官方文件，確保所有依賴資訊正確且符合最新標準。 - 記錄套件名稱、版本、相依資訊與查詢來源，以便於後續追蹤與排查問題。 - **常見 AI 開發官方文件網址** - **Python 官方網站**: [https://www.python.org/](https://www.python.org/) - **TensorFlow**: [https://www.tensorflow.org/](https://www.tensorflow.org/) - **PyTorch**: [https://pytorch.org/](https://pytorch.org/) - **Hugging Face Transformers**: [https://huggingface.co/transformers/](https://huggingface.co/transformers/) - **OpenAI API 文件**: [https://platform.openai.com/docs/](https://platform.openai.com/docs/) - **DeepSpeed**: [https://www.deepspeed.ai/](https://www.deepspeed.ai/) - **NVIDIA CUDA**: [https://developer.nvidia.com/cuda-zone](https://developer.nvidia.com/cuda-zone) - **Scikit-learn**: [https://scikit-learn.org/stable/documentation.html](https://scikit-learn.org/stable/documentation.html) - **JAX**: [https://jax.readthedocs.io/en/latest/](https://jax.readthedocs.io/en/latest/) - **spaCy**: [https://spacy.io/usage](https://spacy.io/usage) - **Fastai**: [https://docs.fast.ai/](https://docs.fast.ai/) - **MXNet**: [https://mxnet.apache.org/versions](https://mxnet.apache.org/versions) - **LightGBM**: [https://lightgbm.readthedocs.io/en/latest/](https://lightgbm.readthedocs.io/en/latest/) - **LangChain**: [https://python.langchain.com/en/latest/](https://python.langchain.com/en/latest/) - **Crewai**: [https://crewai.com/](https://crewai.com/) --- ## 結語 本 .cursorrules 文件整合了大廠開發流程、運算思維、快速 POC 開發 SOP、持續學習與自我省思，以及套件與版本管理的全方位守則，**特別針對 Windows 環境與 PowerShell 進行優化**。 ### 🖥️ Windows 環境開發重點提醒 - 所有指令優先提供 PowerShell 版本，並標註與 Linux 的差異 - 注意路徑分隔符號與權限管理的 Windows 特性 - 考慮 Windows Defender 與防毒軟體對開發的影響 - 善用 Windows 專用工具 (Chocolatey, WSL2, Docker Desktop) ### 📋 開發流程檢查清單 (Windows 版) - [ ] 確認 PowerShell 執行政策設定 - [ ] 檢查環境變數設定 (`$env:VAR_NAME`) - [ ] 驗證路徑格式正確性 (使用雙反斜線或正斜線) - [ ] 測試跨平台相容性 - [ ] 確認防毒軟體排除清單設定 所有團隊成員及 AI 輔助開發系統應依據本指引進行工作，並在每次任務中記錄與分享經驗，從而不斷完善流程、提升產品品質與技術水準，同時確保系統依賴資訊的透明性與可追蹤性。 **特別提醒**: 在 Windows 環境下進行開發時，請優先參考本文件的 Windows 專用指引，確保開發效率與系統穩定性。