Agent Skills教學手冊

Agent Skills 教學手冊(企業級 SSDLC + GitHub Copilot + Claude Code) 版本:v1.4.0 更新日期:2026-06-30 適用對象:資深工程師、架構師、Tech Lead、DevSecOps 工程師 技術棧:Agent Skills 開放標準、GitHub Copilot Skills、Claude Code Skills、VS Code、Spring Boot、Vue 3 規範參考:Agent Skills Specification(開放標準 v1.0) 目錄 第 1 章:Agent Skills 概念與架構 1.1 什麼是 Agent Skills 1.2 與傳統 Prompt Engineering 的差異 1.3 Skills vs Prompt vs Tool vs Agent 比較 1.4 漸進式揭露(Progressive Disclosure)設計原則 1.5 Skills 組成結構 第 2 章:Skills 平台深度解析(GitHub Copilot + Claude Code) 2.1 多平台 Skills 架構 2.2 Skills 運作流程 2.3 Skills Metadata 設計(Frontmatter 完整參考) 2.3.1 開放標準欄位(agentskills.io Specification) 2.3.2 Claude Code 擴展欄位 2.3.3 字串替換(String Substitutions) 2.3.4 動態上下文注入(Dynamic Context Injection) 2.4 Claude Code 內建 Skills(Bundled Skills) 2.5 Skills 與 Agent 整合方式 2.6 Skills Repository 設計(企業級) 2.7 gh skill CLI(GitHub CLI 整合) 2.8 Skill 內容生命週期與 Token 預算 第 3 章:SSDLC × Skills(核心章節) 3.1 Requirements(需求階段) 3.2 Design(設計階段) 3.3 Development(開發階段) 3.4 Testing(測試階段) 3.5 Security(安全) 3.6 Deployment(部署) 3.7 Maintenance(維運) 第 4 章:Skills 設計最佳實務 4.1 高可重用性設計 4.2 低 Token 消耗策略 4.3 命名規範 4.4 模組化與版本控管 4.5 安全性與權限控管 4.6 社群設計模式參考(Community Patterns) 4.6.1 CONTEXT.md 共用語言模式 4.6.2 反合理化表格模式 4.6.3 Agent Personas 模式 4.6.4 生命週期導向組織模式 4.6.5 四大失敗模式框架 4.6.6 User-invoked vs Model-invoked 設計模式 4.6.7 自主執行模式 4.6.8 Skills 安裝器生態 第 5 章:Skills 實作教學(Hands-on) 5.1 範例 1:產生 API 設計文件 Skill 5.2 範例 2:程式碼審查 Skill 5.3 範例 3:Spring Boot 服務生成 Skill 第 6 章:企業級 Skills Repository 架構 6.1 建議 GitHub Repo 結構 6.2 Skills 分類策略 6.3 權限控管(RBAC) 6.4 與 CI/CD 整合 第 7 章:與開發工具整合 7.1 GitHub Copilot 整合 7.2 Claude Code 進階整合 7.3 VS Code 整合 7.4 CI/CD(GitHub Actions)整合 7.5 Issue / PR 流程整合 第 8 章:Skills 治理(Governance) 8.1 Skills 審核機制 8.2 品質控管(Quality Gate) 8.3 安全審查(Security Review) 8.4 使用追蹤與優化(Telemetry) 第 9 章:常見錯誤與反模式 9.1 過度設計 Skills 9.2 Token 爆炸問題 9.3 Skills 過於耦合 9.4 其他常見反模式 第 10 章:未來趨勢 10.1 Agentic Workflow 10.2 Multi-Agent Collaboration 10.3 Skills Marketplace 與開放生態 附錄 A:企業導入檢查清單 附錄 B:Prompt → Skill 轉換速查表 附錄 C:常用 Skills 清單 附錄 D:參考資源 第 1 章:Agent Skills 概念與架構 1.1 什麼是 Agent Skills 定義:Agent Skills 是一種基於 agentskills.io 開放標準的模組化、可重複使用「AI 能力包」(Capability Package),以資料夾形式存在,內含說明文件(SKILL.md)、腳本(Python / Bash / PowerShell)、範本(Templates)和參考資源(References)。 ...

April 1, 2026 · 82 min · 17388 words · Eric Cheng

使用 GitHub Copilot 進行逆向工程並產出需求規格書

使用 GitHub Copilot 進行逆向工程並產出需求規格書 版本:2.0 | 更新日期:2026-03-31 適用對象:資深工程師、系統分析師、架構師、PM 技術環境:VS Code + GitHub Copilot(含 Agent Mode、Coding Agent、MCP 整合) 產業適用:銀行、金融、保險等高合規性企業系統 AI 模型支援:GPT-5.4 / GPT-5.4 mini / GPT-5.3-Codex / Gemini 3.1 Pro / 自動模型選擇 目錄 第 1 章 逆向工程方法論 1.1 什麼是逆向工程 1.2 企業系統中的逆向工程應用場景 1.3 Code → Requirement 轉換模型 1.4 各層級程式碼的需求推導策略 1.5 逆向工程成熟度模型 第 2 章 GitHub Copilot 使用策略 2.1 Copilot 在逆向工程中的角色定位 2.1.1 GitHub Copilot 2026 功能架構全景 2.1.2 各功能在逆向工程中的定位 2.1.3 AI 模型選擇策略 2.2 Prompt Engineering 核心原則 2.2.1 角色設定(Role Setting) 2.2.2 結構化 Prompt 模板 2.2.3 五大 Prompt 策略 2.3 逐段分析程式碼的技巧 2.3.1 分段策略 2.3.2 VS Code 操作技巧 2.4 C# 程式碼解讀策略與 Prompt 範例 2.5 SQL / Stored Procedure 解讀策略與 Prompt 範例 2.6 Batch Job 解讀策略與 Prompt 範例 2.7 從技術描述轉換為商業需求描述 2.8 Before / After 完整範例 2.9 Agent Mode 與 Coding Agent 在逆向工程中的進階應用 2.9.1 使用 Agent Mode 進行跨檔案逆向分析 2.9.2 使用 Plan Agent 規劃逆向工程任務 2.9.3 使用 Copilot Coding Agent 進行自動化逆向分析 2.9.4 使用 MCP 擴展逆向工程能力 2.9.5 使用 Custom Agent 建立專用逆向工程分析師 2.9.6 使用 Copilot Memory 累積逆向工程知識 2.9.7 第三方 Coding Agent 與外部平台整合 2.9.8 使用背景代理進行非同步逆向分析 第 3 章 實戰流程(Step-by-Step) 3.1 Step 1 — 程式碼盤點 3.1.1 模組分類方法 3.1.2 使用 Copilot 快速摘要 3.1.3 自動化盤點腳本 3.2 Step 2 — 邏輯解析 3.2.1 API 邏輯分析 3.2.2 Batch Job 邏輯分析 3.2.3 DB 邏輯分析 3.3 Step 3 — 商業邏輯抽取 3.3.1 從技術邏輯到業務需求的轉換方法 3.3.2 商業規則分類框架 3.3.3 需求追溯矩陣 3.4 Step 4 — 文件產出 3.4.1 SRS 文件自動生成流程 3.4.2 文件品質檢查 3.5 端到端流程圖 第 4 章 SRS 文件標準格式 4.1 SRS 文件結構概覽 4.2 系統概述 4.3 Use Case 描述 4.4 功能需求(Functional Requirements) 4.5 非功能需求(Non-functional Requirements) 4.6 資料流程(DFD) 4.7 ER Model(資料結構) 4.8 Batch Flow 4.9 企業級 SRS 範本(完整) 第 5 章 完整實戰範例 5.1 範例一:C# API 控制器逆向分析 5.1.1 原始程式碼 5.1.2 Copilot 分析過程 5.1.3 推導出的需求 5.2 範例二:Stored Procedure 逆向分析 5.2.1 原始程式碼 5.2.2 Copilot 分析過程 5.2.3 推導出的需求 5.3 範例三:Batch Job 逆向分析 5.3.1 分析場景 5.3.2 Copilot 分析結果 5.4 最終 SRS 文件片段產出 第 6 章 企業最佳實務 6.1 避免誤判需求的策略 6.1.1 常見的誤判類型 6.1.2 防範策略 6.1.3 信心度評估框架 6.2 需求驗證流程 6.2.1 三層驗證機制 6.2.2 驗證會議範本 6.3 整合 SSDLC 6.4 搭配版本控制(Git) 6.4.1 SRS 文件的 Git 管理策略 6.4.2 Git Branching 策略 6.4.3 Commit 訊息規範 6.5 常見錯誤與修正策略 6.6 使用 Copilot Code Review 驗證 SRS 品質 6.6.1 設定 Copilot Code Review 規則 6.6.2 SRS Pull Request 審查流程 6.7 使用 Copilot Spaces 管理逆向工程上下文 第 7 章 架構延伸(進階) 7.1 從逆向結果到 Spring Boot API 設計 7.1.1 技術對照表 7.1.2 SRS → API 設計的轉換流程 7.1.3 範例:從 SRS 到 Spring Boot 7.2 微服務架構轉換 7.2.1 從單體到微服務的拆分策略 7.2.2 Stored Procedure 的遷移策略 7.3 Domain Modeling(DDD) 7.3.1 從逆向結果推導領域模型 7.3.2 統一語言表 7.4 Clean Architecture 對應 7.4.1 分層架構設計 7.4.2 Spring Boot 專案結構 7.5 使用 Copilot Coding Agent 自動化遷移工作 7.5.1 從 SRS 到 Spring Boot 骨架自動生成 7.5.2 SP 邏輯遷移自動化 7.5.3 Hooks 自動化品質檢查 第 8 章 Prompt 工程模板庫 8.1 程式碼摘要類 8.2 邏輯解析類 8.3 需求轉換類 8.4 文件產出類 8.5 驗證與審查類 第 9 章 自動化流程(AI + Script) 9.1 自動化盤點腳本 9.1.1 C# 專案自動盤點(PowerShell) 9.1.2 SQL Server Stored Procedure 盤點 9.2 批次分析流程 9.2.1 分析工作流程自動化 9.2.2 分析任務分配模板 9.3 SRS 自動組裝 9.3.1 SRS 組裝腳本(PowerShell) 9.3.2 SRS 品質檢查腳本 9.4 Copilot Coding Agent 端到端自動化流程 9.4.1 自動化流程架構 9.4.2 GitHub Actions 工作流配置 9.4.3 批次 Issue 建立腳本 9.4.4 追溯矩陣自動生成 附錄 A 檢查清單(Checklist) A.1 逆向工程啟動檢查清單 A.2 每日分析檢查清單 A.3 模組完成檢查清單 A.4 SRS 發佈前檢查清單 A.5 Copilot 使用安全檢查清單 A.6 Copilot Coding Agent 使用檢查清單 附錄 B 術語表 附錄 C 參考資源 C.1 工具 C.2 標準與規範 C.3 推薦閱讀 C.4 GitHub Copilot 相關資源 第 1 章 逆向工程方法論 1.1 什麼是逆向工程 逆向工程(Reverse Engineering) 是從既有系統的成品(程式碼、資料庫、設定檔等)出發,反推出系統的設計意圖、業務規則與需求規格的過程。 ...

March 31, 2026 · 49 min · 10428 words · Eric Cheng

企業級程式碼品質分析方法論教學手冊

企業級程式碼品質分析方法論教學手冊 版本:v2.0|日期:2026-03-30|適用對象:初階至資深工程師、Tech Lead、架構師 適用技術棧:Java / Spring Boot、Vue / TypeScript、微服務架構 適用產業:銀行、金融業、保險業等高穩定度 / 高安全系統 重要更新:OWASP Top 10: 2025 版、PMD 7.x、Checkstyle 13.x、SpotBugs 4.9.x、ESLint 9.x Flat Config 📋 目錄 第 1 章:程式碼品質概論 1.1 程式碼品質的定義 1.2 技術債(Technical Debt) 1.3 為什麼企業需要品質管理 1.4 品質管理全景圖 1.5 實務落地建議 第 2 章:程式碼品質模型(核心方法論) 2.1 品質模型總覽 2.2 可讀性(Readability) 2.3 可維護性(Maintainability) 2.4 可測試性(Testability) 2.5 效能(Performance) 2.6 安全性(Security) 2.7 可擴展性(Scalability) 2.8 實務落地建議 第 3 章:程式碼異味(Code Smells) 3.1 什麼是 Code Smell 3.2 常見 15+ 種 Code Smells 3.3 實務落地建議 第 4 章:靜態分析與工具 4.1 靜態分析概述 4.2 SonarQube 4.3 ESLint 4.4 PMD / Checkstyle 4.5 SpotBugs 4.6 工具功能比較 4.7 企業導入方式 4.8 實務落地建議 第 5 章:Code Review 方法論 5.1 Code Review 的價值 5.2 Review Checklist(企業版) 5.3 Pull Request 標準 5.4 Review 角色分工 5.5 常見錯誤 5.6 實務落地建議 第 6 章:CI/CD 與品質門檻(Quality Gate) 6.1 CI/CD 品質整合概述 6.2 Quality Gate 設計 6.3 Pipeline 品質檢查流程 6.4 Fail Pipeline 策略 6.5 實務落地建議 第 7 章:測試策略與品質關聯 7.1 測試金字塔 7.2 單元測試(Unit Test) 7.3 整合測試(Integration Test) 7.4 覆蓋率迷思 7.5 測試與品質的關係 7.6 實務落地建議 第 8 章:重構(Refactoring)策略 8.1 何時該重構 8.2 安全重構流程 8.3 常見重構技巧 8.4 實務落地建議 第 9 章:企業實務最佳實踐(Best Practices) 9.1 銀行 / 金融系統案例 9.2 微服務品質管理 9.3 DevSecOps 整合 9.4 實務落地建議 第 10 章:導入策略(企業落地) 10.1 推動步驟(Roadmap) 10.2 組織角色 10.3 KPI 指標 10.4 成熟度模型(Level 1~5) 10.5 實務落地建議 附錄 A:新進成員檢查清單(Checklist) 附錄 B:品質指標速查表 附錄 C:推薦學習資源 第 1 章:程式碼品質概論 1.1 程式碼品質的定義 程式碼品質不只是「能跑就好」,在企業級系統中,品質直接影響系統的穩定性、安全性與長期維護成本。 ...

March 30, 2026 · 31 min · 6462 words · Eric Cheng

軟體開發標準程序(Software Development Standard Process)教學手冊

軟體開發標準程序(Software Development Standard Process)教學手冊 項目 內容 版本 v2.1 最後更新 2026-10-06(v2.1:文件範本同步更新,見附錄 D.3;各標準版本查證日:2026-10-06,見附錄 E) 適用對象 軟體開發團隊全體成員:PM、BA/SA、架構師、開發、QA、DevOps/SRE、資安、稽核 文件性質 企業內部技術規範(白皮書等級)與教育訓練教材 閱讀方式 第一次閱讀請先看 1.4 如何使用本手冊;要驗證 AI 依本手冊產出的成果,請看各章最後一節「審查與驗證」與附錄 A.5 📋 目錄 第一章:前言與目的 1.1 為什麼需要軟體開發標準程序 1.2 對組織與工程師的價值 1.3 本手冊適用範圍 1.4 如何使用本手冊 1.5 AI 輔助開發的人機責任 1.6 參考標準與版本基準 第二章:軟體開發生命週期(SDLC)總覽 2.1 SDLC 各階段說明 2.2 與實務專案的關係 2.3 敏捷與瀑布的選擇 2.4 階段閘門(Stage Gate)與 DoR/DoD 2.5 專案裁剪(Tailoring) 2.6 AI 輔助 SDLC 的產出與審查點 2.7 審查與驗證 第三章:需求管理(Requirements Engineering) 3.1 需求來源與分類 3.2 功能性與非功能性需求 3.3 需求文件標準 3.4 PRD、SDD、TSD、程式規格書 四大文件體系 3.5 需求異動管理流程 3.6 需求品質檢核 3.7 需求追溯矩陣(RTM) 3.8 審查與驗證 第四章:系統分析與設計 4.1 系統架構設計原則 4.2 邏輯架構與實體架構 4.3 API 設計規範 4.4 資料庫設計與資料治理 4.5 非功能性設計 4.6 架構決策紀錄(ADR) 4.7 C4 Model 架構圖 4.8 審查與驗證 第五章:開發實作規範 5.1 程式碼風格與命名規範 5.2 架構分層原則 5.3 重用性與模組化 5.4 Secure Coding 基本原則 5.5 AI 生成程式碼審查 5.6 審查與驗證 第六章:測試策略與品質保證 6.1 測試類型與層級 6.2 測試責任分工 6.3 測試資料管理 6.4 缺陷(Bug)管理流程 6.5 測試進入與退出準則 6.6 效能測試 6.7 審查與驗證 第七章:版本控制與組態管理 7.1 Git 分支策略 7.2 版號管理原則 7.3 設定檔與環境管理 7.4 機密資訊(Secrets)防護 7.5 審查與驗證 第八章:CI/CD 與部署流程 8.1 自動化建置流程 8.2 部署策略 8.3 回滾與風險控管 8.4 Feature Flag 與漸進式交付 8.5 審查與驗證 第九章:資安與 SSDLC 9.1 安全需求納入時機 9.2 程式碼掃描與弱點管理 9.3 權限、稽核與日誌 9.4 軟體供應鏈安全 9.5 AI/LLM 應用安全 9.6 法規遵循重點(台灣) 9.7 審查與驗證 第十章:上線、維運與監控 10.1 上線檢核清單 10.2 監控與告警 10.3 問題處理與 RCA 10.4 審查與驗證 第十一章:文件化與知識交接 11.1 必備文件清單 11.2 文件維護責任 11.3 審查與驗證 第十二章:持續改善與流程治理 12.1 專案回顧(Post-mortem) 12.2 指標與成熟度模型 12.3 流程優化建議 12.4 審查與驗證 附錄 A:檢查清單(Checklist) A.1 開發階段檢查清單 A.2 部署階段檢查清單 A.3 Code Review 檢查清單 A.4 安全性檢查清單 A.5 AI 產出審查檢查清單 附錄 B:文件範本索引 需求分析階段(Requirements Phase) 系統設計階段(Design Phase) 測試驗證階段(Testing Phase) 部署上線階段(Deployment Phase) 維運監控階段(Operations Phase) 專案管理(Project Management) 附錄 C:術語對照表 附錄 D:修正紀錄 D.1 錯誤修正 D.2 新增內容 D.3 v2.1 文件範本更新 附錄 E:查證紀錄 E.1 待確認與後續更新事項 E.2 標準、法規與工具版本查證 E.3 範例實測紀錄 E.4 如何重做驗證 文件資訊 版本歷程 第一章:前言與目的 1.1 為什麼需要軟體開發標準程序 在企業軟體開發環境中,缺乏標準化流程將導致以下問題: ...

February 5, 2026 · 82 min · 17402 words · Eric Cheng

系統資料轉置教學指引

系統資料轉置教學指引 版本:1.0 更新日期:2026-02-02 適用對象:系統分析師、資料工程師、後端開發人員 文件性質:內部教育訓練與專案執行標準參考文件 目錄 主要章節 章節 內容概述 第 1 章 資料轉置整體概念與常見失敗原因 第 2 章 舊系統分析(As-Is Analysis) 第 3 章 新系統設計(To-Be Design) 第 4 章 資料轉置策略與架構設計 第 5 章 資料轉置流程設計(ETL Flow) 第 6 章 資料驗證與比對機制 第 7 章 工具與技術選型建議 第 8 章 測試策略與上線前檢核 第 9 章 實務經驗與最佳實踐 附錄 A 資料轉置專案檢查清單 附錄 B 常用 SQL 範本 附錄 C 名詞解釋 詳細目錄 第 1 章:資料轉置整體概念與常見失敗原因 1.1 Data Migration vs Data Transformation 差異 1.2 為何資料轉置是高風險專案 1.3 常見失敗原因與風險分析 第 2 章:舊系統分析(As-Is Analysis) 2.1 資料來源盤點 2.2 資料結構分析 2.3 Key 與邏輯關聯分析 2.4 資料品質檢測 第 3 章:新系統設計(To-Be Design) 3.1 新系統資料模型設計原則 3.2 舊欄位到新欄位 Mapping 規則 3.3 Code / Enum / Reference Data 對應策略 3.4 歷史資料保留與否的決策考量 第 4 章:資料轉置策略與架構設計 4.1 一次性轉置 vs 分批轉置 4.2 Online vs Batch 4.3 Big Bang vs Parallel Run 4.4 Rollback 與 Re-run 設計 第 5 章:資料轉置流程設計(ETL Flow) 5.1 Extract(資料抽取) 5.2 Transform(資料轉換) 5.3 Load(資料載入) 5.4 Staging Table 設計 5.5 Error Handling 與 Retry 機制 第 6 章:資料驗證與比對機制 6.1 筆數驗證(Record Count) 6.2 金額 / 數值驗證(Sum / Balance Check) 6.3 Key-based 資料比對 6.4 抽樣驗證(Sampling) 6.5 自動化驗證報表設計 第 7 章:工具與技術選型建議 7.1 SQL / Stored Procedure 7.2 ETL 工具 7.3 程式語言選擇 7.4 檔案處理工具 7.5 驗證與測試輔助工具 第 8 章:測試策略與上線前檢核 8.1 Unit Test(轉換邏輯) 8.2 Integration Test(流程驗證) 8.3 UAT 驗證模式 8.4 上線前 Checklist 第 9 章:實務經驗與最佳實踐 9.1 常見踩雷案例 9.2 與業務單位的資料驗證合作方式 9.3 文件化、稽核與可追溯性設計 9.4 金融與核心系統常見合規考量 附錄 A:資料轉置專案檢查清單(Checklist) A.1 專案啟動階段 A.2 分析設計階段 A.3 開發測試階段 A.4 UAT 階段 A.5 上線階段 附錄 B:常用 SQL 範本 B.1 資料品質檢測 B.2 資料比對 B.3 轉置進度追蹤 附錄 C:名詞解釋 第 1 章:資料轉置整體概念與常見失敗原因 1.1 Data Migration vs Data Transformation 差異 在開始資料轉置專案前,必須先釐清兩個核心概念的差異: ...

February 2, 2026 · 45 min · 9454 words · Eric Cheng

12-Factor App 說明與對應解決方案

Codebase(單一程式碼庫,多個部署環境) 原則:一個應用程式應有單一程式碼庫,透過不同的部署(deploy)對應不同環境(dev/test/prod)。 解決方案: 使用 GitLab repository 管理專案。 每個環境使用不同 branch 或 tag(如 develop, release, main)。 CI/CD pipeline 進行自動化部署,避免分散程式碼庫。 Dependencies(明確宣告與隔離依賴) 原則:應用程式必須明確管理相依性,避免依賴系統環境。 解決方案: 後端:使用 Maven pom.xml 宣告所有 dependencies,不依賴本地安裝的 jar。 前端:使用 package.json 鎖定依賴版本。 建議使用 Docker 建立一致的 build/runtime 環境。 Config(將設定與程式碼分離) 原則:設定(如 DB 密碼、API key)不應寫死在程式碼中。 解決方案: Spring Boot 使用 application.yml + 外部設定檔 或 環境變數。 GitLab CI/CD 提供 Environment Variables 管理不同環境的設定。 建議搭配 Vault / AWS Secrets Manager / Kubernetes Secrets。 Backing Services(後端服務當作附加資源) 原則:資料庫、快取、MQ、外部 API 都應視為「可替換的資源」。 解決方案: DB(MySQL/DB2/PostgreSQL)、Redis、RabbitMQ 等連線資訊放在設定檔,不耦合程式。 測試環境可用輕量替代(如 testcontainers 啟動 DB/Redis)。 Build, Release, Run(明確分離建置、發佈、執行) 原則:建置(build)、發佈(release)、執行(run)必須分開,避免環境污染。 解決方案: ...

October 31, 2025 · 2 min · 292 words · Eric Cheng

code review 指引

Code Review 指引 企業標準技術白皮書|版本 v3.0|2026-10-08 適用範圍:使用 GitHub(github.com、GitHub Enterprise Cloud、GitHub Enterprise Server)或 GitLab(GitLab.com、Self-Managed、Dedicated)管理原始碼,以 Java/Spring Boot 為後端、以 Vue/TypeScript/Tailwind CSS 為前端、以關聯式資料庫為儲存的企業應用系統。本指引規範程式碼審查(Code Review)的流程、角色、審查重點、平台設定與度量方式:每一條規則都說明要做到什麼、附有正確與錯誤的範例,並說明審查者要用什麼工具或方法確認。 v3.0 全面改寫 v2.0:依 Google Engineering Practices、IEEE 1028-2008、ISO/IEC 20246:2017、NIST SP 800-218 SSDF、OWASP ASVS 5.0、OWASP Top 10:2025、SLSA v1.2 Source Track、ISO/IEC 27001:2022 與 DORA 2025 重新組織內容,並新增「AI 輔助審查與審查 AI 產出」一章。每條規則都附有範例與「驗證方式」,每節結尾都有「🔍 審查與驗證」,讓審查者能判斷 AI 或同事產出的程式碼與審查意見是否正確。範例均經工具實測(見 附錄 F)。各技術領域的完整寫作規範請見 程式寫作指引、安全程式碼指引 與 測試與品質保證指引;本文從「審查」的角度把它們串成一套可執行的流程。 目錄 0. 文件資訊 0.1 文件目的與讀者 0.2 技術基準版本 0.3 規範等級與規則格式 0.4 與其他指引的關係 0.5 如何閱讀本指引 0.6 例外與豁免流程 1. Code Review 的目的、治理與國際標準 1.1 為什麼要做程式碼審查 1.2 審查的類型與選擇 1.3 國際標準與法規對照 1.4 審查的範圍與限制 2. 角色與責任 2.1 角色定義與責任分工 2.2 審查者的資格與指派 3. 審查流程與服務水準 3.1 審查生命週期 3.2 回應時限與服務水準 3.3 審查輪次與核准失效 3.4 風險分級與核准人數 3.5 同步審查、走查與正式檢查 3.6 合併與合併後 4. 作者:準備可審查的變更 4.1 小而聚焦的變更 4.2 撰寫 PR/MR 描述 4.3 提交訊息 4.4 送審前的自我審查 4.5 草稿 PR 與堆疊 PR 4.6 回應審查意見 5. 審查者:如何審查 5.1 審查前的準備 5.2 閱讀順序 5.3 檢查什麼:依重要性排序 5.4 審查的節奏與時間 5.5 在本機驗證 5.6 核准標準 6. 審查意見的撰寫與溝通 6.1 意見分級:讓作者知道哪些必須處理 6.2 好意見的結構 6.3 語氣與溝通 6.4 意見的記錄與追蹤 7. 審查重點:設計與架構 7.1 設計審查與架構決策紀錄 7.2 職責與模組邊界 7.3 簡單與適度:避免過度設計與重複造輪子 7.4 一致性:遵循既有的慣例 8. 審查重點:功能正確性與錯誤處理 8.1 需求符合度與邊界條件 8.2 輸入契約 8.3 錯誤處理 8.4 空值與 Optional 8.5 併發與交易 8.6 資源管理 8.7 金額、時間與數值 9. 審查重點:可讀性與可維護性 9.1 命名 9.2 複雜度 9.3 重複程式碼 9.4 註解與文件 9.5 技術債與範圍控制 10. 審查重點:測試 10.1 測試是否存在、是否在正確的層級 10.2 測試的品質:程式壞掉時會失敗嗎 10.3 覆蓋率作為門檻,而不是目標 10.4 測試的穩定性與可維護性 11. 審查重點:安全 11.1 安全審查的範圍與方法 11.2 輸入驗證與輸出編碼 11.3 注入 11.4 身分驗證與授權 11.5 秘密、敏感資料與日誌 11.6 密碼學 11.7 OWASP Top 10:2025 審查對照 12. 審查重點:效能與資源 12.1 資料庫存取:N+1 與查詢次數 12.2 無上限的查詢與分頁 12.3 快取 12.4 外部呼叫:逾時與重試 12.5 效能宣稱需要證據 13. 審查重點:資料庫與資料遷移 13.1 遷移腳本的管理 13.2 向後相容:擴充與收縮 13.3 鎖與線上變更 13.4 新查詢與索引 14. 審查重點:前端、UI 與無障礙 14.1 TypeScript 與 lint 設定 14.2 元件設計、狀態與非同步 14.3 無障礙(WCAG 2.2) 14.4 前端測試 14.5 UI 變更的審查 15. 審查重點:設定、CI/CD 與相依套件 15.1 應用程式設定 15.2 相依套件 15.3 CI/CD 工作流程 15.4 容器與基礎設施即程式碼 16. 審查重點:API 相容性與文件 16.1 API 契約與破壞性變更 16.2 文件與變更紀錄 17. 自動化與品質閘門 17.1 品質閘門清單 17.2 GitHub Actions 範例 17.3 GitLab CI 範例 17.4 SonarQube 設定 17.5 工具警告的抑制 17.6 審查輔助工具 18. 平台設定:GitHub 與 GitLab 18.1 平台功能對照 18.2 GitHub:Rulesets 18.3 GitHub:CODEOWNERS 18.4 GitLab:核准設定與受保護分支 18.5 GitLab:CODEOWNERS 區段 18.6 範本與自動化設定 19. AI 輔助審查與審查 AI 產出 19.1 原則:人對合併負責 19.2 AI 審查工具的選擇 19.3 AI 審查工具的安全 19.4 處理 AI 審查意見 19.5 審查 AI 產生的程式碼 20. 特殊情境 20.1 緊急修正 20.2 大型重構 20.3 自動產生的程式碼與機器人 PR 20.4 第三方程式碼與授權 20.5 跨團隊變更 20.6 正式環境的資料修正 21. 意見衝突與團隊文化 21.1 意見分歧的處理 21.2 心理安全與行為準則 21.3 建立審查文化 22. 度量與持續改善 22.1 度量的原則 22.2 收集方式 22.3 回顧與改善 23. 培訓與導入 23.1 導入路線圖 23.2 審查者培訓 23.3 審查校準 附錄 A 規則總表 A.1 依領域統計 A.2 驗證方式與範例覆蓋 A.3 規則清單 附錄 B 檢查清單與範本 B.1 作者送審前自我檢查 B.2 審查者檢查清單 B.3 快速參考卡 B.4 IDE 設定 附錄 C 工具設定與腳本 C.1 CODEOWNERS 檢查腳本 C.2 審查度量報表 C.3 審查提醒 C.4 PR 衛生檢查 C.5 審查意見標籤統計 C.6 Checkstyle 與 PMD 設定 附錄 D 術語表與常用審查用語 D.1 術語表 D.2 常用英文審查用語 附錄 E 參考資料 E.1 標準與框架 E.2 業界實務與研究 E.3 平台與工具文件 E.4 延伸閱讀 附錄 F 修訂紀錄與查證紀錄 F.1 v2.0 與 v3.0 章節對照 F.2 v2.0 錯誤修正紀錄 F.3 查證紀錄 F.4 待查證與後續更新 F.5 版本紀錄 0. 文件資訊 0.1 文件目的與讀者 程式碼審查是軟體團隊最常執行、也最容易流於形式的品質活動。一個 Pull Request(GitHub)或 Merge Request(GitLab)被按下「Approve」,可能代表審查者逐行讀過、在本機執行過測試;也可能只代表審查者看了標題,覺得「應該沒問題」。兩者在平台上看起來完全一樣,差別要等到上線後才會顯現。 ...

October 31, 2025 · 120 min · 25430 words · Eric Cheng

JdbcTemplate 安全 SQL 實作指引文件

以下是完整的 《JdbcTemplate 安全 SQL 實作指引文件》Markdown 版本,可直接放入你的 Git Repository(例如 /docs/security/jdbctemplate-sql-guideline.md),作為團隊安全規範或 Code Review checklist 使用。 # 🧭 JdbcTemplate 安全 SQL 實作指引文件 **版本:v1.0** **適用範圍:** Spring Boot 專案中使用 `JdbcTemplate` 或 `NamedParameterJdbcTemplate` 的資料存取層 **目的:** 防止 SQL Injection 攻擊與弱掃誤判 --- ## 1️⃣ 目的與原則 SQL Injection(SQL 注入)是 OWASP Top 10 的主要風險之一。 若在 API 中直接拼接 SQL 字串(尤其包含前端輸入),將導致弱掃報告出現 Injection 問題,甚至被惡意利用。 **安全實作原則:** 1. 所有 SQL 查詢必須採用 **參數化查詢(Parameterized Query)**。 2. 不可直接拼接使用者輸入字串到 SQL。 3. 動態欄位或排序需求必須使用 **白名單機制(Whitelist)**。 4. 禁止讓 client 直接傳入完整 SQL。 5. 所有 DB 帳號採用最小權限原則(Least Privilege)。 --- ## 2️⃣ 正確安全作法範例 ### ✅ 查詢範例 ```java String sql = "SELECT id, name, email FROM users WHERE email = ?"; return jdbcTemplate.query(sql, new Object[]{email}, new UserRowMapper()); ✅ 插入範例 String sql = "INSERT INTO users (name, email) VALUES (?, ?)"; jdbcTemplate.update(sql, name, email); ✅ 更新範例 String sql = "UPDATE users SET status = ? WHERE id = ?"; jdbcTemplate.update(sql, status, id); ✅ 刪除範例 String sql = "DELETE FROM users WHERE id = ?"; jdbcTemplate.update(sql, id); ✅ 動態查詢(條件可變) 重點:條件以程式判斷拼接,但參數仍使用 ? 綁定。 ...

October 31, 2025 · 3 min · 498 words · Eric Cheng

refactor 重構指引

重構指引(Refactoring Guide) 企業標準技術白皮書|版本 v2.0|2026-10-08 適用範圍:以 Java(Java 25 LTS,相容 Java 21)/Spring Boot 4 為後端、以 Vue 3/TypeScript 為前端、以關聯式資料庫為儲存,並使用 GitHub 或 GitLab 管理原始碼的企業應用系統。本指引規範「在不改變外部行為的前提下改善程式結構」的方法、時機、流程、工具與驗證方式:每一條規則都說明要做到什麼、附有正確與錯誤的範例,並說明審查者要用什麼工具或方法確認。 v2.0 全面改寫 v1.0:以 Martin Fowler《Refactoring》第二版的重構目錄、Michael Feathers《Working Effectively with Legacy Code》、Kent Beck《Tidy First?》與 Fowler 的演進式設計模式(Strangler Fig、Branch by Abstraction、Parallel Change)為方法基礎;以 ISO/IEC 25010:2023、ISO/IEC/IEEE 14764:2022、ISO/IEC 5055:2021、ISO/IEC/IEEE 12207:2017 與 DORA 2025 報告為治理基礎重新組織內容。新增 Java 現代化、前端 TypeScript/Vue、架構層、資料庫與 API 演進、OpenRewrite 大規模自動化與「AI 輔助重構與審查 AI 產出」等章。每條規則都附有範例與「驗證方式」,每節結尾都有「🔍 審查與驗證」,讓審查者能判斷 AI 或同事產出的重構是否真的「沒有改變行為」。範例均經工具實測(見 附錄 F)。 目錄 0. 文件資訊 0.1 文件目的與讀者 0.2 技術基準版本 0.3 規範等級與規則格式 0.4 與其他指引的關係 0.5 如何閱讀本指引 0.6 例外與豁免流程 1. 重構的定義、目的與國際標準 1.1 什麼是重構 1.2 為什麼要重構:目的與經濟效益 1.3 國際標準與研究對照 1.4 重構的範圍與限制 2. 重構原則 2.1 小步前進,每一步都保持綠燈 2.2 優先使用工具化的重構 2.3 以簡單設計為方向 3. 重構時機與決策 3.1 重構的五種時機 3.2 決定「要不要重構」:紅黃綠燈 3.3 重構、重寫或汰換 4. 程式碼異味:找出需要重構的地方 4.1 異味目錄與偵測工具對照 4.2 門檻與「新程式碼」品質閘門 5. 安全網:重構前的測試 5.1 測試是重構的前提 5.2 特性測試:記錄現在的行為 5.3 黃金主檔與核准測試 5.4 覆蓋率與變異測試:測試夠強嗎 5.5 接縫:讓無法測試的程式碼可以被測試 6. 基本重構手法 6.1 提煉函式與內聯函式(Extract Function/Inline Function) 6.2 改名與提煉變數(Rename/Extract Variable) 6.3 改變函式宣告(Change Function Declaration) 6.4 封裝變數與集合(Encapsulate Variable/Encapsulate Collection) 6.5 拆分階段與合併函式(Split Phase/Combine Functions into Class) 6.6 移除死程式碼(Remove Dead Code) 7. 搬移特性與組織資料 7.1 搬移函式與搬移欄位(Move Function/Move Field) 7.2 提煉類別與內聯類別(Extract Class/Inline Class) 7.3 以物件取代基本型別:值物件(Replace Primitive with Object) 7.4 隱藏委託與移除中間人(Hide Delegate/Remove Middle Man) 8. 簡化條件邏輯 8.1 提早返回與分解條件(Guard Clauses/Decompose Conditional) 8.2 以多型取代條件式(Replace Conditional with Polymorphism) 8.3 引入特例(Introduce Special Case) 8.4 引入斷言與以預先檢查取代例外(Introduce Assertion/Replace Exception with Precheck) 9. API 與繼承重構 9.1 參數物件、保留完整物件與移除旗標參數 9.2 分離查詢與修改、移除設值方法、以工廠函式取代建構子 9.3 處理繼承:上移、下移、提煉父類別與摺疊階層 9.4 以委託取代繼承(Replace Subclass/Superclass with Delegate) 10. Java 現代化重構 10.1 以 record 取代資料類別 10.2 模式比對與 switch 運算式 10.3 Optional 與 null 10.4 以管線取代迴圈(Replace Loop with Pipeline) 10.5 建構子驗證與 Java 25 語言特性 10.6 虛擬執行緒與併發程式的現代化 11. 前端 TypeScript/Vue 重構 11.1 型別強化:讓編譯器幫你重構 11.2 元件重構:Options API 到 Composition API 與 composable 11.3 大規模前端重構:codemod 與未使用程式碼 12. 遺留系統重構 12.1 遺留程式碼的變更步驟 12.2 Sprout 與 Wrap:在無法測試的程式碼旁邊加新功能 12.3 Mikado 方法:處理相依關係不明的大型重構 12.4 Branch by Abstraction:在主幹上替換元件 12.5 Strangler Fig:漸進汰換整個系統 13. 架構層重構 13.1 以架構測試守護重構 13.2 模組化單體:Spring Modulith 13.3 從模組化單體拆分服務 14. 資料庫與 API 的演進式重構 14.1 Parallel Change:擴充—遷移—收縮 14.2 資料庫重構 14.3 REST API 的演進 14.4 事件與訊息格式的演進 15. 大規模自動化重構 15.1 選擇自動化工具 15.2 框架升級與語法現代化 16. 效能與重構 16.1 重構與效能的關係 16.2 資料存取與快取:最容易「重構出」效能問題的地方 17. 安全與重構 17.1 安全控制不得在重構中消失 17.2 查詢、日誌與序列化:重構時常見的安全退化 18. 流程、版本控管與審查 18.1 重構型 PR 的組成 18.2 分支策略與長期重構 18.3 守護測試:重構 PR 不得改變測試的預期值 18.4 如何審查重構型 PR 19. AI 輔助重構與審查 AI 產出 19.1 AI 在重構中的角色與風險 19.2 提示範本:讓 AI 產出可審查的重構 19.3 等價性驗證:證明 AI 的重構沒有改變行為 19.4 AI 代理的重構:指示檔與防護欄 19.5 AI 重構常見錯誤總表 20. 技術債管理與度量 20.1 技術債的分類與登錄 20.2 度量重構的成效 20.3 重構的投資與時間配置 21. 反模式與常見陷阱 21.1 流程與範圍的反模式 21.2 設計與實作的反模式 21.3 v1.0 範例中的反模式更正 22. 案例研究 22.1 遺留計費模組的漸進式重構(Java) 22.2 前端元件現代化(Vue/TypeScript) 23. 導入與培訓 23.1 分階段導入 23.2 培訓:以重構套路(kata)練習 附錄 A 規則總表 A.1 依領域統計 A.2 驗證方式與範例覆蓋 A.3 規則清單 附錄 B 檢核清單與範本 B.1 重構前檢核 B.2 重構中檢核 B.3 合併前檢核(作者) B.4 審查者檢核 B.5 AI 產出重構的審查檢核 B.6 重構提案範本 B.7 重構後追蹤 附錄 C 設定檔與腳本 C.1 Maven 驗證專案設定 C.2 OpenRewrite 設定 C.3 PMD 規則集 C.4 Checkstyle 設定 C.5 架構規則(ArchUnit、Spring Modulith) C.6 CI 工作流程 C.7 commitlint 設定 C.8 熱點分析腳本 C.9 測試守護腳本 C.10 前端設定 C.11 等價性檢查腳本 附錄 D 名詞對照 附錄 E 參考資料 E.1 書籍 E.2 國際標準與規範 E.3 研究報告 E.4 線上資源 附錄 F 修訂紀錄與查證紀錄 F.1 v1.0 章節對照 F.2 v1.0 內容更正紀錄 F.3 查證紀錄 F.4 待確認事項 F.5 技術版本紀錄 0. 文件資訊 0.1 文件目的與讀者 重構(refactoring)是「在不改變軟體可觀察行為的前提下,改善其內部結構」的一系列小步驟。它聽起來簡單,實務上卻最容易出錯:一次改太多、測試不足、把功能變更混在重構裡、或是把「重寫」誤稱為「重構」,都會讓原本可控的整理工作變成難以審查、難以回復的風險。生成式 AI 讓產生「看起來更乾淨」的程式碼變得非常容易,但 AI 產出的重構常常悄悄改變了邊界條件、例外型別或執行順序;判斷一次重構有沒有改變行為,仍然是人的責任。 ...

October 31, 2025 · 104 min · 22027 words · Eric Cheng

UIUX指引

UI/UX 開發指引 企業標準技術白皮書|版本 v3.0|2026-10-09 適用範圍:以 Vue 3/TypeScript/Tailwind CSS 開發的企業 Web 應用,特別是網路銀行、保險、證券等金融服務,以及其他需要處理交易、個資與法規要求的系統。本指引規範從使用者研究、資訊架構、互動與視覺設計、Design Token、元件、表單、無障礙、內容、國際化、狀態設計,到效能、實作與品質驗證的 UI/UX 要求:每一條規則都說明要做到什麼、附有正確與錯誤的範例,並說明要用什麼工具或方法確認。 v3.0 全面改寫 v2.1:依 ISO 9241-210/-110/-11、ISO/IEC 25010:2023、WCAG 2.2(ISO/IEC 40500:2025)、WAI-ARIA 與 APG、EN 301 549 V4.1.1、European Accessibility Act、數位發展部「網站無障礙規範」115.11 版、金管會「數位金融服務包容性指引」、Design Tokens Format Module 2025.10 與 Core Web Vitals 重新組織內容。所有規則都有編號(UX-*)、等級與驗證方式,每節結尾都有「🔍 審查與驗證」,讓審查者能判斷 AI 或同事產出的介面是否正確。範例均以工具實際執行驗證(見 附錄 F)。框架工程細節見 前端開發指引,審查流程見 code review 指引。 目錄 0. 文件資訊 0.1 文件目的與讀者 0.2 技術與標準基準版本 0.3 規範等級與規則格式 0.4 與其他指引的關係 0.5 如何閱讀與使用本指引 0.6 例外與豁免流程 1. UX 治理與國際標準 1.1 為什麼企業需要 UI/UX 指引 1.2 國際標準與法規對照 1.3 無障礙法規與合規義務 1.4 UX 治理組織與責任 2. 以使用者為中心的設計流程 2.1 人本設計流程(ISO 9241-210) 2.2 使用者研究方法 2.3 人物誌、旅程地圖與使用情境 2.4 可用性需求與驗收條件 3. 資訊架構與導覽 3.1 資訊架構 3.2 導覽模式 3.3 頁面結構與地標 3.4 麵包屑、頁籤標題與網址 4. 互動設計原則 4.1 ISO 9241-110 互動原則與尼爾森啟發式 4.2 系統狀態與回饋 4.3 防錯、確認與復原 4.4 一致性與慣例 4.5 鍵盤與指標操作 5. 視覺設計 5.1 排版與字型 5.2 色彩與對比 5.3 間距、格線與版面 5.4 圖示與圖片 5.5 動態與動畫 5.6 資料視覺化 6. Design Token 與設計系統 6.1 Design Token 的分層 6.2 DTCG 格式與 Style Dictionary 6.3 Tailwind CSS 4 整合 6.4 主題與深色模式 7. 元件設計規範 7.1 元件的通用要求 7.2 按鈕與連結 7.3 對話框 7.4 選單、頁籤與手風琴 7.5 資料表格 7.6 通知訊息與 Toast 7.7 分頁與無限捲動 8. 表單設計與驗證 8.1 欄位標籤與說明 8.2 輸入類型與自動完成 8.3 驗證時機 8.4 錯誤訊息與錯誤摘要 8.5 多步驟表單 9. 響應式與多裝置設計 9.1 斷點與行動優先 9.2 重排與文字縮放 9.3 觸控目標與手勢 9.4 螢幕方向與容器查詢 10. 無障礙設計 10.1 WCAG 2.2 AA 符合策略 10.2 語意化 HTML 與 ARIA 使用原則 10.3 鍵盤操作與焦點管理 10.4 螢幕閱讀器與動態內容 10.5 WCAG 2.2 新增成功準則 10.6 認知無障礙 10.7 無障礙聲明與回饋管道 11. 內容設計與 UX 寫作 11.1 語氣與用語 11.2 微文案 11.3 易讀性與白話文 12. 國際化與在地化 12.1 語系與語言標示 12.2 數字、金額與日期格式 12.3 文字長度與雙向文字 13. 狀態設計 13.1 載入狀態 13.2 空狀態 13.3 錯誤狀態 13.4 離線與逾時 14. 金融情境 UX 14.1 金額、帳號與數值顯示 14.2 交易流程與確認 14.3 敏感資料遮罩與隱私 14.4 身分驗證與工作階段逾時 14.5 詐騙防範與風險提示 14.6 包容性金融服務 15. 效能與使用者體驗 15.1 Core Web Vitals 15.2 感知效能 15.3 效能預算 16. Vue 3 與 Tailwind CSS 實作落地 16.1 元件 API 設計 16.2 無障礙元件實作模式 16.3 樣式撰寫規範 16.4 元件文件與 Storybook 17. UX 品質驗證 17.1 驗證策略與金字塔 17.2 自動化無障礙檢測 17.3 手動與輔助科技測試 17.4 視覺回歸測試 17.5 可用性測試與 UX 指標 18. 設計與開發協作 18.1 設計交付 18.2 設計審查 18.3 設計系統治理與版本 19. AI 與 UX 19.1 審查 AI 產出的介面 19.2 設計 AI 功能的使用體驗 19.3 以 AI 輔助 UX 工作 附錄 A 規則總表 附錄 B 檢查清單與範本 B.1 UI 變更的 PR/MR 審查清單 B.2 設計交付與設計審查清單 B.3 螢幕閱讀器測試紀錄範本 B.4 使用者研究同意書範本 B.5 第三方 UI 元件評估清單 附錄 C 工具設定與腳本 C.1 驗證專案的結構與指令 C.2 按鈕樣式 C.3 Stylelint 規則說明 C.4 axe 設定 C.5 Playwright 設定 C.6 Lighthouse CI C.7 GitHub Actions 工作流程 C.8 GitLab CI 對應設定 附錄 D 術語表 D.1 UI/UX 與無障礙術語 D.2 產品詞彙表格式 D.3 台灣用語對照(節錄) 附錄 E 參考資料 E.1 國際標準與規範 E.2 法規 E.3 設計方法與業界實務 E.4 工具文件 附錄 F 修訂紀錄與查證紀錄 F.1 v2.1 與 v3.0 章節對照 F.2 v2.1 的錯誤與修正 F.3 查證紀錄 F.4 待確認項目 F.5 版本紀錄 0. 文件資訊 0.1 文件目的與讀者 使用者對一套系統的評價,幾乎都來自介面:按鈕按下去有沒有反應、錯誤訊息看不看得懂、轉帳前能不能確認金額、用鍵盤或螢幕閱讀器能不能完成操作。這些問題很少在需求文件中被寫清楚,卻在上線後以客訴、客服電話、交易錯誤與法規風險的形式出現。 ...

October 31, 2025 · 117 min · 24753 words · Eric Cheng