wiki-agents-md

# Repository Agent Instructions ## Build & Run - `npm run dev` — Start the Vite development server. - `npm run build` — Type-check with `tsc -b`, then create the Vite production build. - `npm run lint` — Run ESLint on `src/`. ## Testing - `npm test` — Run the Vitest test suite once. ## Project Structure - `src/` — TypeScript application source. - `tests/` — Vitest tests. - `public/` — Static assets served by Vite. ## Validation After making changes, run the relevant checks: ```sh npm run lint npm test npm run build ```

## 應建立的位置 - `apps/web/AGENTS.md` - `apps/api/AGENTS.md` - `packages/ui/AGENTS.md` - 根目錄 `AGENTS.md`：根目錄一律需要，但題目未說明它是否已存在；只有確認缺少時才建立，絕不可覆寫。 各巢狀檔案只描述該工作區的特定規則，不重複根目錄的全域內容。 ## 根目錄 `AGENTS.md` 必須收錄： - 整個 monorepo 的用途與各 workspace 的角色。 - 根目錄 `package.json` 中實際宣告的 workspace 設定。 - 根目錄 scripts、Makefile 或 CI 中可驗證的安裝、建置、測試、lint、格式化命令；Build & Run 應放在最前面。 - `apps/web`、`apps/api`、`packages/ui` 的實際依賴或呼叫關係。 - 有設定檔或原始碼佐證的全域程式風格、開發環境要求及 repository-wide boundaries。 - CI/CD 或 Git workflow 規則，但僅限 workflow、commitlint、PR template、CONTRIBUTING 等已有證據者。 不得臆測： - npm、Node.js 或 Python 的版本。 - 使用 npm、pnpm 或 Yarn 中的哪一個；須由 lockfile、`packageManager` 或文件確認。 - workspace 之間的依賴方向。 - CI 平台、部署流程、分支命名或 Conventional Commits。 - 未出現在 scripts、CI 或文件中的命令、參數、埠號與環境變數。 ## `apps/web/AGENTS.md` 必須收錄： - web workspace 的實際用途及其在整體系統中的角色。 - `apps/web/package.json` 內存在的 install、dev、build、test、lint 等 scripts。 - 經目錄與原始碼確認的入口檔、主要資料夾及新增功能的位置。 - 從現有程式碼辨識出的命名、import、元件組織與錯誤處理慣例，最好附一段真實範例。 - 前端特有且有專案證據的 boundaries，例如變更公開元件介面或設計系統前需先確認。 不得臆測： - React、Next.js、Vue、Vite、TypeScript、Tailwind 等框架或工具。 - dev server 埠號、瀏覽器支援範圍及部署平台。 - 測試框架、測試目錄、單檔測試命令或 coverage 命令。 - API URL、認證方式、環境變數名稱或 UI 設計規範。 - `package.json` 沒有宣告、CI 也未使用的 npm scripts。 ## `apps/api/AGENTS.md` 必須收錄： - API workspace 的實際用途。 - `pyproject.toml` 中可驗證的套件管理、專案 scripts、測試、lint、格式化及型別檢查設定。 - 實際入口點、套件結構、路由、模型、服務與測試所在位置。 - 從 3–5 個現有 Python 檔案確認的命名、型別註記、import、同步／非同步及錯誤處理慣例。 - 有證據支持的後端 boundaries，例如資料庫 schema、migration 或公開 API 契約變更需先確認。 不得臆測： - FastAPI、Django、Flask、Poetry、uv、pytest、Ruff、Black 或 mypy 的使用。 - Python 版本、啟動命令、host、port 與 worker 數量。 - 資料庫種類、ORM、migration 工具、認證方式或外部服務。 - 測試、coverage 或單一測試命令；若沒有相關設定或測試，應省略 Testing 區段。 - 尚未實際存在的 `src/`、`tests/`、`routes/` 等路徑。 ## `packages/ui/AGENTS.md` 必須收錄： - UI package 的用途、公開輸出及被哪些 workspace 使用；後兩者必須有 manifest 或程式碼佐證。 - `packages/ui/package.json` 中存在的 build、test、lint、storybook 或其他 scripts。 - 實際 source entry、exports、元件、樣式、測試及 story 的位置。 - 從既有元件確認的檔名、props、export、樣式與測試慣例，並使用真實程式碼範例。 - 有依據的 package-specific boundaries，例如公開 export、元件 API 或 design token 的 breaking change。 不得臆測： - React、Vue、Storybook、CSS Modules、Tailwind 或任何設計系統工具。 - 套件是否發布至 npm、套件可見性、版本策略或 release 流程。 - 元件命名規則、無障礙標準、瀏覽器支援及視覺測試工具。 - `apps/web` 必然使用此套件；必須由 workspace dependency 或 import 證實。 - manifest、現有路徑或工具設定無法支持的命令與慣例。 所有檔案都應省略無證據或不適用的區段，且不得包含密鑰、token、憑證、占位文字或泛用樣板內容。

採取的動作： - 保留根目錄與 `apps/web/AGENTS.md`，不覆寫或重新產生。 - 掃描 `apps/api/` 的設定、指令、測試及程式碼慣例，僅建立缺少的 `apps/api/AGENTS.md`。 - 若 `apps/api/CLAUDE.md` 也不存在，則一併建立；若已存在則跳過。 預期回報文字： ```text AGENTS.md already exists at ./AGENTS.md — skipping AGENTS.md already exists at apps/web/AGENTS.md — skipping Generated apps/api/AGENTS.md ``` 另依 `apps/api/CLAUDE.md` 的實際狀態回報： ```text Generated apps/api/CLAUDE.md ``` 或： ```text CLAUDE.md already exists at apps/api/CLAUDE.md — skipping ```