feat: scaffold C++ template with tooling helpers

README.md

@@ -1,2 +1,60 @@
 # cpp-template
 
+這個專案提供一個簡單的 C++ 樣板，包含基本的目錄結構、Makefile 與開發輔助工具，方便快速開始新專案。
+
+## 目錄結構
+- `src/`: 主要的 C++ 原始碼，目前包含 `main.cpp`。
+- `build/`: 由 Makefile 自動建立，用來存放編譯後的物件檔。
+- `utils/`: 收錄常用腳本，例如編譯、執行、清理以及格式化。
+- `.clang-format`: 定義 clang-format 的專案格式規則。
+- `.clang-tidy`: 定義 clang-tidy 的檢查設定。
+- `Makefile`: 管理編譯、執行、清理與格式化等命令。
+
+## 建置與執行
+若系統已安裝 `g++`，可使用以下命令：
+
+```bash
+# 編譯 (預設目標 app)
+make
+
+# 編譯並執行
+make run
+
+# 清理 build 及執行檔
+make clean
+```
+
+也可以透過 `utils/` 底下的腳本快速操作：
+
+```bash
+./utils/build.sh        # 執行 make，接受額外參數
+./utils/run.sh          # 編譯並執行
+./utils/clean.sh        # 移除 build/ 與 app
+./utils/format.sh       # 依據 .clang-format 重新排版 src/ 下的檔案
+```
+
+如需指定不同的目標或旗標，可直接傳入 `utils/build.sh`：
+
+```bash
+./utils/build.sh TARGET=my_app CXXFLAGS="-O3 -DNDEBUG"
+```
+
+## 程式碼格式化
+`utils/format.sh` 會檢查 `clang-format` 是否存在，並對 `src/` 目錄內的 `.cpp/.hpp/.h` 檔案進行格式化。專案提供的 `.clang-format` 以 LLVM 風格為基礎，並設定：
+- C++20 標準
+- 4 空格縮排，最大列寬 100
+- 自訂括號換行與 namespace 縮排規則
+
+## 靜態分析
+`.clang-tidy` 啟用了一些常用的檢查（`bugprone-*`、`clang-analyzer-*`、`modernize-*` 等）。要檢查特定檔案，可執行：
+
+```bash
+clang-tidy src/main.cpp --
+```
+
+可視需求調整 `Checks`、`HeaderFilterRegex` 或其他設定來符合專案需求。
+
+## 下一步
+- 在 `src/` 新增更多檔案與模組。
+- 依專案需求擴充 Makefile 或 utils 腳本。
+- 若需要不同的編碼規範或靜態分析工具，修改 `.clang-format` 與 `.clang-tidy` 即可。