# AGENTS.md — 專案協作與工程化指引（v1.0 / 2026-03-28）

本文件為本庫的協作與工程化規範（適用於整個專案目錄）。目標：免費優先（Free-first）的 CI / Security / Review / 文件骨架，並避免動到既有業務邏輯。

## 原則
- 僅新增流程檔、文件檔與 PowerShell 腳本；不修改任何業務程式碼（除非另有明確要求）。
- 文件一律使用繁體中文；腳本使用 PowerShell（7+），CI 使用 GitHub Actions。
- 不要放入真實 Secrets；如需使用，請以 `${{ secrets.MY_SECRET }}` 之類 placeholder 表示，並於 Repo 設定中配置。
- 變更應最小、可回滾、可追溯；避免引入與需求無關的檔案。
- 若同目錄或子目錄存在更特定的 `AGENTS.md`，以「更近層級」的規範優先。

## 重要檔案
- `.github/workflows/ci.yml`：通用 CI（Ubuntu Runner + PowerShell），呼叫 `scripts/lint.ps1` / `scripts/test.ps1`。
- `.github/workflows/security.yml`：免費安全檢查（Semgrep、Gitleaks、Trivy FS），上傳 SARIF。
- `.github/dependabot.yml`：每週依賴更新（含 github-actions 與常見生態系）。
- `.github/pull_request_template.md`：PR 模板與自我檢查清單。
- `code_review.md`：程式碼審查清單與建議。
- `docs/engineering-workflow.md`：工程作業流程（分支、PR、CI、安全、依賴更新）。
- `scripts/lint.ps1`：跨語言的 Lint 腳本（盡量使用免費工具；若工具不存在則跳過或以輕量規則檢查）。
- `scripts/test.ps1`：跨語言的 Test 腳本（偵測可用測試框架；無測試則跳過並成功結束）。

## 本地常用指令
- 執行 Lint：`pwsh -File scripts/lint.ps1`
- 執行 Test：`pwsh -File scripts/test.ps1`

## 分支與提交
- 建議分支命名：`feature/*`、`fix/*`、`chore/*`、`docs/*`。
- 提交訊息建議遵循 Conventional Commits（例：`feat: 新增設定檔`、`fix: 修正 CI 條件`）。

## 禁止事項
- 提交任何敏感資訊（金鑰、密碼、私鑰、存取權杖等）。
- 在版本控制中新增編譯產物或大型二進位檔（除非經明確同意）。

---
文件維護者：工程化維運。更新日期：2026-03-28。