通用架構模組 Showcase

它如何協助建立 repo

1. 描述需求

填一份 project spec

描述專案名稱、repo slug（儲存庫代稱）、產品類型、隱私等級與文件深度。

{
  "project_name": "Account App",
  "project_slug": "account-app",
  "module_pack": "android-app",
  "privacy_level": "private",
  "docs_depth": "standard"
}

2. 產生骨架

用 generator 套用 base + pack

先跑 dry-run（試跑）看會建立哪些檔案，再正式寫入目標 repo。

python scripts\scaffold.py `
  --spec project-spec.json `
  --target D:\Codex\account-app `
  --dry-run

正式寫入時移除 --dry-run。

3. 交付結果

得到可延續的 repo 骨架

README 入口與 docs link（文件連結）
HTML showcase（HTML 展示頁）
PROJECT_STRUCTURE 與 ARCHITECTURE
scripts、tests、examples
private data boundary（私密資料邊界）

建立流程

判斷目標

是 new repo（新儲存庫）、new product（新產品）、new feature（新功能），或 retrofit existing repo（補強既有儲存庫）。

選 module pack

依型態選 `python-cli`、`python-api`、`android-app`、`knowledge-base` 或 `governance-docs`。

產生 spec

把專案名稱、runtime（執行環境）、privacy level（隱私等級）與 docs depth（文件深度）寫成 JSON。

dry-run 預覽

先列出將新增或提案的檔案；既有檔案不直接覆蓋，會輸出到 `_proposed/`。

寫入並驗證

確認後寫入目標 repo，跑 unit tests（單元測試）與 HTML preview（HTML 預覽）。

新 repo

從零建立

目標資料夾是空的時候，generator 會直接建立基礎目錄與 pack 專屬檔案。

`README.md`
`docs/showcase/index.html`
`docs/PROJECT_STRUCTURE.md`
`scripts/verify.ps1`

既有 repo

補強既有 repo

目標 repo 已有 README 或 docs 時，generator 不會直接覆蓋；它會把建議版本放到 `_proposed/` 讓你 review（審查）。

保留既有內容
標示可補強檔案
降低誤覆蓋風險

Agent（代理）使用

由 agent 調用

Codex 透過 `$universal-project-scaffold` skill（技能）調用；OpenClaw 與 Claude 可讀取 `docs/AGENT_USAGE.md` 後使用同一份 repo source of truth。

Codex：直接走 skill workflow（技能流程）
OpenClaw：偏 governance（治理）與架構路由
Claude：讀 repo 文件後執行 generator

目標 repo 會得到什麼

README.md

docs/showcase/index.html

docs/PROJECT_STRUCTURE.md

docs/ARCHITECTURE.md

docs/HTML_SHOWCASE_SOP.md

docs/PRIVATE_DATA_BOUNDARY.md

scripts/verify.ps1

tests/README.md

Module pack（模組包）會再追加專屬檔案，例如 Android Gradle skeleton（Gradle 骨架）、Python `pyproject.toml`、API `Dockerfile`、knowledge base（知識庫）目錄或 governance docs（治理文件）。

其他 repo 如何反過來優化這個 repo

這不是一次性的 template copy（模板複製）。每個目標 repo 在實作後會產生新的架構經驗，例如更好的 docs 結構、測試入口、Android 分層、API runtime（執行環境）、HTML showcase 版型或 private data rule（私密資料規則）。這些經驗經過 review（審查）後，回寫到 `universal-architecture-modules`，下一個 repo 就會直接受惠。

目標 repo 學習

在實際 repo 裡發現更好的架構

某個 feature 需要新的資料夾責任邊界
showcase 需要更清楚的使用者流程
測試或驗證方式應該變成預設
某種 repo 類型需要新的 module pack

通用 repo 更新

沉澱成可重用資產

更新 `templates/base/` 的共用骨架
更新 `templates/packs/` 的類型模板
更新 `schemas/project-spec.schema.json` 的輸入欄位
更新 `scripts/scaffold.py` 的產生規則

從其他 repo 學到什麼	回寫到 universal repo 哪裡	下一個 repo 如何受惠
新的文件章節或 README 入口	`templates/base/docs/`、`templates/base/README.md`	新 repo 建立時自動帶出一致文件結構。
更好的 HTML showcase 版型	`templates/base/docs/showcase/index.html`、`docs/HTML_SHOWCASE_SOP.md`	每個 repo 的靜態展示頁更容易說清楚產品、架構與驗證方式。
某類產品的專屬架構	`templates/packs/<pack-name>/`	同類型 repo 不用重新定義資料夾、測試與文件基線。
新的安全或私密資料規則	`docs/PRIVATE_DATA_BOUNDARY.md`、generator validation（產生器驗證）	新 repo 預設避開真實私密資料與危險覆寫流程。
建立流程需要更多輸入欄位	`schemas/project-spec.schema.json`、`examples/project-spec.example.json`	agent 或使用者在 scaffold 前能提供更精準的規格。

判斷標準：只有「可跨 repo 重複使用」且「不含專案私密資料」的做法才回寫到 universal repo；單一 repo 的產品細節留在該 repo 自己的 docs 或 showcase。

Showcase 品質門檻

新產生或補強的 `docs/showcase/index.html` 不能只是一組簡單文字卡。它必須讓人類 reviewer（審查者）在 60 秒內看懂 system architecture（系統架構）、user architecture（使用者架構）、 dynamic pipeline（水管線路圖）、verification（驗證方式）與 private data boundary（私密資料邊界）。

topbar（頂部導覽）

固定連到 README、Architecture、Private Boundary 與 Verification，讓 reviewer 不迷路。

brief panel（摘要面板）

首屏右側濃縮 module pack、runtime、privacy level 與驗證入口。

key facts（重點事實）

用四個短資訊塊說明 project purpose、system boundary、user workflow 與 private data safety。

SVG pipeline（水管流程圖）

預設採用可掃描的水管線路圖，而不是只有孤立節點的裝飾圖。

01 Project Frame 首屏說清楚 repo（儲存庫）用途、角色與不可越界資料。

02 System Architecture 架構圖要能對應到真實 folders（資料夾）、modules（模組）與 runtime（執行環境）。

03 User Architecture 描述 owner（擁有者）、operator（操作者）、reviewer（審查者）如何進出流程。

04 Dynamic Pipeline 水管圖要有方向、階段、input（輸入）、process（處理）、output（輸出）與責任邊界。

05 Verification Panel 列出可執行的 verify script（驗證腳本）、tests（測試）與 local preview（本機預覽）。

06 Human Review 最後由人檢查是否清楚、可掃描、responsive（響應式）且不讀取 private data（私密資料）。

不接受

只有 3-4 個靜態節點、無責任邊界、無 code path（程式路徑）對應。

必須具備

system（系統）、user（使用者）、pipeline（水管）、verification（驗證）、private boundary（私密邊界）。

不能越界

不得呼叫 API（介面）、讀取 `.env`、掃描本機資料或使用 browser storage（瀏覽器儲存）。

回流標準

若實作 repo 暴露新缺口，先更新 template（樣板）、SOP（標準作業程序）與 tests（測試）。

Module pack 選擇表

Pack	適合情境	會額外建立
`python-cli`	Python command line tool（命令列工具）、pipeline（管線）、批次處理工具。	`pyproject.toml`、`src/`、CLI test（命令列測試）。
`python-api`	API service（服務介面）、FastAPI service（FastAPI 服務）、Docker-first runtime（Docker 優先執行環境）。	`app/main.py`、`Dockerfile`、`docker-compose.yml`、`docs/API.md`。
`android-app`	Android native app（原生 Android 應用）、行動端產品骨架。	Gradle skeleton（Gradle 骨架）、`app/src/main/`、Android architecture docs（Android 架構文件）。
`knowledge-base`	知識庫、研究資料、prompt/evidence（提示與證據）整理。	`START_HERE.md`、`notes/`、`evidence/`、`prompts/`。
`governance-docs`	治理文件、policy（政策）、procedure（程序）、decision log（決策紀錄）。	`GOVERNANCE_OVERVIEW.md`、`DECISIONS.md`、`POLICY.md`。

手動使用

Copy-Item examples\project-spec.example.json project-spec.json

python scripts\scaffold.py `
  --spec project-spec.json `
  --target ..\example-product `
  --dry-run

python scripts\scaffold.py `
  --spec project-spec.json `
  --target ..\example-product

Codex skill 使用

請使用 $universal-project-scaffold
幫我建立一個 android-app repo：
- project_name: Account App
- project_slug: account-app
- privacy_level: private
請先 dry-run，再列出會產生的檔案。

安全邊界

不讀取私密資料

HTML showcase 是 static project showcase（靜態專案展示頁），不是 live dashboard（即時儀表板），不得連接真實私密資料。

不預設覆蓋

既有檔案預設走 `_proposed/`，只有明確使用 force（強制）策略時才覆蓋。

設計留在來源 repo

模板、規則與設計 decision（決策）留在本 repo；實際 showcase 產物寫到目標 repo，避免互相污染。

延伸文件： docs/USAGE.md、 docs/AGENT_USAGE.md、 docs/PROJECT_STRUCTURE.md。