project/ ├── build/ # 編譯輸出（不入版本控制） │ ├── debug/ │ └── release/ ├── dist/ # 發布包（可執行文件+依賴+配置） ├── doc/ # 文檔：設計、API、用戶手冊 ├── include/ # 公共頭文件（按模塊劃分） │ ├── module1/ │ └── module2/ ├── lib/ # 第三方靜態/動態庫 ├── module1/ # 業務模塊1（源碼+私有頭文件+單元測試） │ ├── src/ │ ├── include/ │ └── test/ ├── module2/ # 業務模塊2 ├── res/ # 資源文件：圖標、配置模板、腳本 ├── samples/ # 示例程式 │ ├── sample1/ │ └── sample2/ ├── tools/ # 構建腳本、代碼生成器、部署工具 ├── copyleft # 版權/許可證文件 ├── Makefile # 構建入口（或 CMakeLists.txt） └── README.md # 專案說明：構建、運行、貢獻指南
| 目錄 | 用途 | 版本控制 | 備註 |
|---|---|---|---|
| build/ | 中間文件、目標文件、可執行文件 | 否 | .gitignore 忽略；CI 構建產物 |
| dist/ | 最終發布產物 | 否 | 打包發布；可作為 CI 產物上傳 |
| doc/ | 架構設計、接口文檔、變更日誌 | 是 | Markdown/AsciiDoc；配合 Doxygen |
| include/ | 對外公共 API 頭文件 | 是 | 安裝時複製至系統 include 路徑 |
| lib/ | 第三方預編譯庫 | 視情況 | 大二進制建議用包管理器 |
| module*/ | 核心業務邏輯（高內聚低耦合） | 是 | 每模塊獨立 src/include/test |
| res/ | 運行時只讀資源 | 是 | 打包進 dist/ |
| samples/ | API 使用演示、集成測試場景 | 是 | 新人上手參考 |
| tools/ | 內部工具鏈 | 是 | 代碼生成、數據遷移、壓測腳本 |
module1/
├── CMakeLists.txt # 模塊構建腳本
├── include/ # 模塊私有頭文件（不安裝）
│ └── module1/
│ ├── internal.h
│ └── public.h # 對外接口（也可放頂層 include/）
├── src/
│ ├── public.cpp
│ └── internal.cpp
└── test/
├── CMakeLists.txt
└── test_public.cpp
CMakeLists.txt 通過 add_subdirectory(module1) 聚合。install(FILES include/module1/public.h DESTINATION include)。Config.cmake 支持 find_package。apps/、libs/、services/ 分離。tests/ 頂層目錄，鏡像模塊結構。doc/adr/ 架構決策記錄，doc/api/ 自動生成。.github/workflows/ 或 .gitlab-ci.yml 放根目錄。「沒有銀彈，只有適合當前團隊規模、技術棧、交付節奏的結構。」小專案可精簡至 src/、include/、test/ 三目錄；大型專案必須強制模塊邊界、依賴方向（內層不依賴外層）、介面隔離。定期通過架構檢查工具 驗證依賴規則，防止「大泥球」退化。
