vibe-coding-tw: Instructions file for Codex

Repository Guidelines

Project Structure & Module Organization

• 根目錄：README.md 給出全貌，Makefile 封裝日常命令，CONTRIBUTING.md 說明貢獻流程，LICENSE 載明協議。保持根目錄扁平，避免巨石檔案。
• 文件庫：documents/ 彙總流程、架構與實踐（如 程式碼組織.md、通用專案架構模板.md、開發經驗.md），是理解方法論與協作規則的首選入口。新增流程文件時優先放此處並在 README 連結。
• 提示詞資產：prompts/ 按角色拆分（system / assistant / coding / user），libs/external/prompts-library/ 提供 Excel ↔ Markdown 互轉工具與指令碼目錄，便於批次維護提示詞，適合作為“單一真實來源”。
• 程式碼與整合：libs/ 預留核心實現骨架，common/、database/、external/ 分別對應通用模型、儲存適配與外部依賴登記；新增模組需保持分層邊界與單一職責，避免跨層呼叫。
• 備份：backups/ 內含 一鍵備份.sh 與 快速備份.py，用於本地快照或同步，請先在隔離目錄試跑，確認輸出路徑與許可權。

Build, Test, and Development Commands

• make help：列出所有 Make 目標，是新人快速上手的入口。
• make lint：使用 markdownlint-cli 校驗全倉庫 Markdown，一旦新增文件請先跑通（需本地 Node/npm 環境，可用 npm install -g markdownlint-cli 安裝）。
• make build / make test / make clean：目前為佔位，落地具體實現後務必更新指令碼和說明；建議在 Makefile 旁補充註釋並保持冪等，避免修改全域性狀態。
• 提示詞轉換：進入 prompts/prompts-library/ 後執行 python main.py 按互動提示進行轉換，執行前請確認虛擬環境、依賴與輸出目錄，並在完成後檢查生成 Markdown 是否符合 lint 規則。

Coding Style & Naming Conventions

• 文字層：文件、註釋、日誌使用中文；程式碼符號（函式 / 變數 / 模組）統一英文且語義直白，避免晦澀縮寫。
• 縮排與排版：全倉保持空格縮排（2 或 4 空格任選其一但不得混用）；Markdown 列表、程式碼塊與表格對齊清晰，行寬控制在 120 列內。Git diff 可讀性優先。
• 設計品味：優先消除分支與重複；函式力求單一職責且短小；命名遵循小寫加中劃線或下劃線，不使用空格與特殊字元；跨模組介面保持穩定簽名。
• 依賴管理：新增工具或庫時記錄安裝方式、最小版本與來源，必要時在 documents/工具集.md 或 README 中補充，並說明為何需要它（效能、相容、功能）。

Testing Guidelines

• 當前無實測用例；引入程式碼時請至少提供最小可復現測試。推薦 Python 使用 pytest，檔案命名 test_*.py，夾具精簡可讀，遵循 red-green-refactor 迴圈。
• 文件與提示詞改動：提交前執行 make lint；如轉換指令碼涉及資料，附帶示例輸入 / 輸出說明或最小資料樣例，確保可重複。
• 覆蓋率基線由模組維護者設定；若暫無標準，確保主流程和邊界條件均可被測試驗證，必要時在 PR 描述中寫明未覆蓋的風險，並建議後續補測計劃。

Commit & Pull Request Guidelines

• Commit 建議遵循簡化 Conventional Commits：feat|fix|docs|chore|refactor|test: scope – summary，一句話說明行為與範圍；避免籠統的 “update”。
• PR 必填：變更摘要、動機或關聯 Issue、測試與驗證步驟（列出執行的命令與結果概覽）；涉及文件 / UI 的修改應附對比截圖或連結，方便 reviewer 快速複核。
• 提交前清單：跑通 make lint；若新增指令碼 / 依賴，更新對應文件與 Makefile 目標；確認不攜帶臨時檔案或機密資料，並在描述中註明潛在風險或需要 reviewer 特別關注的點。