SKILL.md
Git 提交前工作流（編排器）
描述
協調多個 Skills 完成 Git 提交前的所有準備工作。 本專案同時使用 pre-commit framework 自動執行程式碼品質檢查，以及 AI orchestrator 處理文檔同步。
🔄 自演化循環 (Self-Evolution Cycle)
本專案的品質守門是一個自我演化的閉迴系統：
┌─────────────────────────────────────────────────────────────┐
│ 自演化循環 (Self-Evolution Cycle) │
├─────────────────────────────────────────────────────────────┤
│ │
│ ① Instructions (copilot-instructions.md) │
│ │ 定義規範、引導 AI 使用 Skills │
│ ▼ │
│ ② Skills (SKILL.md 檔案) │
│ │ 確保建構完整、創建新 Hook │
│ ▼ │
│ ③ Hooks (.pre-commit-config.yaml + scripts/hooks/) │
│ │ 自動執行檢查、自動修正 │
│ ▼ │
│ ④ Validate (check_evolution_cycle.py) │
│ │ 驗證 ①②③ 的一致性 │
│ ▼ │
│ ⑤ Feedback → 更新 Instructions & Skills │
│ │ 處理驗證失敗、補齊文檔、更新套件版本 │
│ └────→ 回到 ①（循環完成） │
│ │
└─────────────────────────────────────────────────────────────┘循環觸發時機
| 事件 | 觸發動作 |
|---|---|
| 新增 Hook | Skill 創建 hook → evolution-cycle 驗證文檔及 instruction 是否同步 |
| 修改 Instruction | evolution-cycle 驗證 skill/hook 是否仍一致 |
pre-commit autoupdate |
套件版本更新 → 自動演化 |
| 驗證失敗 | 報告不一致處，強制修復後才能 commit |
架構：雙層防護 + 自演化
┌─────────────────────────────────────────────────────────────┐
│ Git Commit 防護架構 │
├──────────────────────┬──────────────────────────────────────┤
│ Layer 1: 自動化 │ Layer 2: AI 編排器 │
│ (pre-commit hooks) │ (agent orchestrator) │
├──────────────────────┼──────────────────────────────────────┤
│ ✅ ruff + ruff-format│ ✅ Memory Bank 同步 │
│ ✅ bandit security │ ✅ CHANGELOG 更新 │
│ ✅ vulture deadcode │ ✅ ROADMAP 更新 │
│ ✅ deptry deps │ ✅ README 更新 │
│ ✅ file-hygiene │ ✅ 架構文檔檢查 │
│ ✅ commit-size-guard│ ✅ Commit 訊息建議 │
│ ✅ file-hygiene │ │
│ ✅ commit-size-guard│ │
│ ✅ async-test-checker│ │
│ ✅ tool-count-sync │ │
│ ✅ skills-frontmatter│ │
│ ✅ evolution-cycle │ │
│ ✅ future-annotations│ │
│ ✅ no-print-in-src │ │
│ ✅ ddd-layer-imports│ │
│ ✅ no-type-ignore-bare│ │
│ ✅ docstring-tools │ │
│ ✅ no-env-inner-layers│ │
│ ✅ tenant-scoped-storage│ │
│ ✅ source-counts-guard│ │
│ ✅ todo-scanner │ │
│ ✅ instruction-drift│ │
│ ✅ yaml/toml/json │ │
│ ✅ no large files │ │
│ ✅ no debug stmts │ │
│ ✅ no private keys │ │
│ ✅ BOM / symlinks │ │
│ ✅ case conflicts │ │
│ ✅ Windows names │ │
│ ✅ mixed line ending│ │
│ ✅ no-commit-to-branch│ │
│ ✅ name-tests-test │ │
│ ── Pre-push ──────── │ │
│ ✅ mypy (pre-push) │ │
│ ✅ semgrep (pre-push)│ │
│ ✅ pytest (pre-push) │ │
├──────────────────────┼──────────────────────────────────────┤
│ 🔧 自動修復： │ 🔧 自動修復： │
│ trailing whitespace │ tool-count-sync (auto-stage) │
│ end-of-file newline │ │
│ ruff --fix │ │
│ ruff format │ │
│ future-annotations │ │
└──────────────────────┴──────────────────────────────────────┘開發者設定 (一次性)
uv sync # 安裝所有依賴 (含 pre-commit)
uv run pre-commit install # 安裝 pre-commit hook
uv run pre-commit install --hook-type pre-push # 安裝 pre-push hook (跑測試)Hook 自動演化 (Auto-Evolution)
套件版本更新
uv run pre-commit autoupdate # 更新所有 hook 版本 (ruff, pre-commit-hooks 等)
uv run pre-commit run --all-files # 驗證更新後所有 hook 正常循環一致性驗證
uv run python scripts/hooks/check_evolution_cycle.py # 手動執行一致性檢查此腳本驗證：
- 所有 hook ID 都在 instruction 和 skill 中被文檔化
- 所有 hook 引用的腳本檔案都存在
- CONTRIBUTING.md 的 hook 表格與 .pre-commit-config.yaml 一致
- pyproject.toml 的 addopts 強制多核
- Skill 文檔引用了正確的 hook 基礎設施
新增 Hook 的完整流程
當需要新增一個 hook 時，必須完成整個循環：
- 創建 hook 腳本 →
scripts/hooks/<name>.py - 註冊到 .pre-commit-config.yaml → 加入 hook 定義
- 更新 copilot-instructions.md → Pre-commit Hooks 區塊
- 更新本 SKILL.md → 架構圖 Layer 1 列表
- 更新 CONTRIBUTING.md → hooks 表格
- 執行驗證 →
uv run python scripts/hooks/checkevolutioncycle.py - 確認通過 → evolution-cycle hook 自動在下次 commit 時檢查
⚠️ 如果只做了步驟 1-2 而沒有 3-5，evolution-cycle hook 會在 commit 時報錯。
💡 建議每月執行一次
autoupdate，自動取得最新的 ruff 規則、安全性檢查等。
觸發條件
- 「準備 commit」「要提交了」「git commit」
法規依據
- 憲法：CONSTITUTION.md 第三章
- 子法：.github/bylaws/git-workflow.md
AI 編排器執行流程
當 AI agent 被要求「準備 commit」時，執行以下額外步驟：
┌─────────────────────────────────────────────────┐
│ AI Pre-Commit Orchestrator │
├─────────────────────────────────────────────────┤
│ Step 1: memory-sync [必要] Memory Bank 同步 │
│ Step 2: pre-commit-run [必要] 執行所有 hooks │
│ Step 3: readme-update [可選] README 更新 │
│ Step 4: changelog-update[可選] CHANGELOG 更新 │
│ Step 5: roadmap-update [可選] ROADMAP 更新 │
│ Step 6: arch-check [條件] 架構文檔檢查 │
│ Step 7: commit-prepare [最終] 準備提交 │
└─────────────────────────────────────────────────┘Step 2 會執行
uv run pre-commit run --all-files，涵蓋 ruff、file hygiene、tool docs sync 等所有自動化檢查。mypy 和 semgrep 已移至 pre-push 階段以防 OOM。
必要步驟：MCP 工具數量同步
由 pre-commit hook tool-count-sync 自動處理。也可手動執行：
uv run python scripts/count_mcp_tools.py --update-docs此腳本會自動更新：
README.md- 工具數量README.zh-TW.md- 工具數量.github/copilot-instructions.md- 工具數量 + 完整列表src/.../TOOLS_INDEX.md- 完整工具索引
參數
| 參數 | 說明 | 預設 |
|---|---|---|
--skip-readme |
跳過 README 更新 | false |
--skip-changelog |
跳過 CHANGELOG 更新 | false |
--skip-roadmap |
跳過 ROADMAP 更新 | false |
--skip-hooks |
跳過 pre-commit hooks | false |
--dry-run |
只預覽不修改 | false |
--quick |
只執行必要步驟 (memory-sync + hooks) | false |
使用範例
「準備 commit」 # 完整流程
「快速 commit」 # 等同 --quick
「commit --skip-readme」 # 跳過 README跳過特定 Hook
SKIP=mypy git commit -m "quick fix" # 跳過 mypy (較慢)
git commit --no-verify -m "emergency" # 跳過所有 hooks (慎用!)輸出格式
🚀 Git Pre-Commit 工作流
[1/7] Memory Bank 同步 ✅
└─ progress.md: 更新 2 項
└─ activeContext.md: 已更新
[2/7] Pre-commit Hooks ✅
└─ ruff lint: passed (auto-fixed 3 issues)
└─ ruff format: passed
└─ mypy: passed
└─ file hygiene: passed
└─ tool docs sync: passed (2 files updated)
[3/7] README 更新 ✅
└─ 新增功能說明
[4/7] CHANGELOG 更新 ✅
└─ 添加 v0.2.0 條目
[5/7] ROADMAP 更新 ⏭️ (無變更)
[6/7] 架構文檔 ⏭️ (無結構性變更)
[7/7] Commit 準備 ✅
└─ 建議訊息：feat: 新增用戶認證模組
📋 Staged files:
- src/auth/...
- docs/...
準備好了！確認提交？Hook 設定檔案
| 檔案 | 用途 |
|---|---|
.pre-commit-config.yaml |
pre-commit hooks 定義 |
pyproject.toml [tool.ruff] |
ruff lint + format 規則 |
pyproject.toml [tool.mypy] |
mypy type check 規則 |
pyproject.toml [tool.pytest] addopts |
強制多核測試 |
pyproject.toml [tool.bandit] |
bandit 安全掃描規則 |
pyproject.toml [tool.deptry] |
deptry 依賴衛生規則 |
vulture_whitelist.py |
vulture 死碼掃描白名單 |
scripts/hooks/checkfilehygiene.py |
檔案衛生檢查 |
scripts/hooks/checktoolsync.py |
MCP 工具文檔同步 |
scripts/hooks/checkskillsfrontmatter.py |
.claude/skills YAML frontmatter 驗證 |
scripts/hooks/checkevolutioncycle.py |
自演化循環一致性驗證 |
scripts/hooks/checkcommitsize.py |
Commit 檔案數限制 (≤30) |
scripts/hooks/checkfutureannotations.py |
future annotations 強制 |
scripts/hooks/checknoprint.py |
禁止 src/ 使用 print() |
scripts/hooks/checkdddlayers.py |
DDD 層級依賴檢查 |
scripts/hooks/checktypeignore.py |
禁止裸 type: ignore |
scripts/hooks/checkdocstringtools.py |
MCP tool docstring 檢查 |
scripts/hooks/checkenvconfig.py |
禁止內層使用 os.environ |
scripts/hooks/checktenantscoped_storage.py |
presentation 層儲存路徑須經 tenantdatadir() |
scripts/hooks/checksourcecounts.py |
確保每來源 API 回傳量顯示 |
scripts/hooks/checktodoscanner.py |
TODO/FIXME 掃描 |
scripts/hooks/checkinstructiondrift.py |
工具 docstring 變更偵測 |
scripts/checkasynctests.py |
async/sync 測試一致性 |
Unicode Mojibake Hook
unicode-mojibakeusesscripts/hooks/checkunicodemojibake.pyto block newly staged corrupted emoji/UTF-8 artifacts while allowing valid emoji.