Logs Visualization教學手冊

Logs Visualization 教學手冊(ELK Stack) 文件資訊 項目 內容 文件版本 2.0 最後更新 2026-10-01 版本基準 Elastic Stack 9.5.4(2026-09-15 發佈):Elasticsearch/Logstash/Kibana 同版;相容說明涵蓋 8.19.x(支援至 2027-07-15) 文件定位 企業標準技術白皮書/內部標準教材:Logs 視覺化、查詢分析、告警與治理 適用對象 資深軟體工程師、系統架構師、SRE/DevOps 工程師、資安與稽核人員 前置知識 Linux 基礎、Java/Spring Boot 應用程式、JSON 與 HTTP API、基本的 Elasticsearch 概念 姊妹文件 《ELK Stack 教學手冊》v2.0:平台安裝、設定、升級、ECK、叢集維運 前一版本 1.0(2026-01-26,以 Elastic Stack 8.x 早期做法為主) Created by Eric Cheng 📌 v2.0 改版重點:全面對齊 Elastic Stack 9.5。索引設計從「每日 index + rollover alias」改為 Data Stream + ECS + LogsDB。Logstash 範例改用 ssl_enabled、API Key 與 data stream 輸出。修正 v1.0 中已失效或錯誤的設定,例如 ILM freeze、node.attr.data、Alerting 規則格式、grok 自訂 pattern 錯誤、萬用字元刪除 index、法規年限等。新增多個章節:ES|QL、Log 分析(Pattern/Rate/Change Point)、Dashboard as Code、Elastic AI(Agent Builder、MCP)、AI 治理、查詢問題排除、導入路線圖、上線審查清單。完整差異見 D.2 v1.0 → v2.0 更正對照表,查證依據見 附錄 E:查證紀錄。 ...

January 26, 2026 · 68 min · 14298 words · Eric Cheng

Metrics Visualization 教學手冊

Metrics Visualization 教學手冊(Prometheus + Grafana) 文件資訊 項目 內容 文件版本 2.0 最後更新 2026-10-01 版本基準 Prometheus 3.15.0(2026-09-24)、Prometheus LTS 3.13.x(支援至 2027-07-31)、Grafana 13.2.3(2026-09-29)、Alertmanager 0.34.1;完整矩陣見 1.3 版本基準與相容性矩陣 文件定位 企業標準技術白皮書/內部標準教材:指標設計、PromQL 分析、儀表板、告警與 SLO、架構決策與治理 適用對象 資深後端工程師、系統架構師、SRE/DevOps 工程師、技術主管、資安與稽核人員 前置知識 Linux 與容器、Kubernetes 基本概念、RESTful API、微服務架構、基本監控概念 姊妹文件 《Prometheus與Grafana教學手冊》:安裝、設定檔、維護、升級操作步驟;《OpenTelemetry教學手冊》:OTel SDK 與 Collector 前一版本 1.0(2026-01-26,以 Prometheus 2.x/Grafana 11 時期做法為主) Created by Eric Cheng 📌 v2.0 改版重點:全面對齊 Prometheus 3.x 與 Grafana 13。修正 v1.0 中無法執行或結果錯誤的範例,例如 relabel 位址改寫、predict_linear 子查詢語法、錯誤率告警百分比顯示、不存在的指標名稱 redis_keys_total、Pushgateway「TTL」說法、以「P99 達標時間比例」定義延遲 SLO 等。新增原生直方圖、OTLP 與 UTF-8、Kubernetes Operator、Alertmanager 設計、規則單元測試、Dynamic dashboards、Dashboard as Code(Git Sync)、Grafana Alerting、多視窗多燃燒率告警、SLO 工具鏈、Grafana Assistant 與 MCP、AI 治理,以及第 9 章「企業級部署、容量與治理」。完整差異見 D.2 v1.0 → v2.0 更正對照表,查證依據見 附錄 E:查證紀錄。 ...

January 26, 2026 · 64 min · 13522 words · Eric Cheng

微前端教學手冊

微前端教學手冊 版本:1.0 最後更新:2026 年 1 月 適用對象:資深工程師 / Tech Lead / Architect 最後更新: 2026年1月23日 適用於: 微前端 Created by: Eric Cheng 微前端(Micro-Frontend)教學手冊 版本:1.0 適用對象:資深前端/全端工程師、Tech Lead、架構師 最後更新:2026 年 1 月 目錄 微前端的核心價值與真正要解決的問題 1.1 什麼是微前端? 1.2 微前端真正要解決的問題 1.3 什麼情況「不該用微前端」 1.4 微前端 vs 單體前端 vs Monorepo 1.5 本章實務案例 微前端主流架構模式比較 2.1 基座(Shell / Container)模式 2.2 Runtime Integration vs Build-time Integration 2.3 iframe / Web Components / Module Federation 比較 2.4 主流框架方案比較 2.5 本章實務案例 Module Federation 深度解析 ...

January 23, 2026 · 34 min · 7103 words · Eric Cheng

Claude Agent Skills教學手冊

Claude Agent Skills 使用教學手冊 版本:1.0 最後更新:2026 年 1 月 適用對象:新進軟體工程師、系統分析師、AI 導入成員 最後更新: 2026年1月8日 適用於: Claude Code Created by: Eric Cheng 目錄 前言 文件目的 適用對象 如何使用本手冊 第一章:Claude Agent 與 Agent Skills 基礎概念 1.1 什麼是 Claude Agent 1.2 什麼是 Agent Skills 1.3 Agent / Tool / Skill 的差異與關係 1.4 為什麼要使用 Agent Skills 第二章:Agent Skills 的設計理念 2.1 Skill 的責任邊界(Single Responsibility) 2.2 Skill 與 Prompt 的差異 2.3 Skill 是可重用、可組合的能力單元 2.4 官方 Skills Repo 的設計原則 第三章:官方 Skills Repository 結構說明 3.1 Skills GitHub 專案的目錄結構 3.2 Skill 的命名慣例 3.3 Skill 定義中的關鍵元素 第四章:Agent Skills 的使用方式 4.1 如何在 Agent 中呼叫 Skill 4.2 Skill 在任務流程中的角色 4.3 單一 Skill vs 多 Skill 組合 第五章:實務範例 5.1 需求文件產生 Skill 5.2 程式碼 Review / 重構 Skill 5.3 測試案例產生 Skill 第六章:新手常見錯誤與最佳實務 6.1 Skill 設計過大或過小的問題 6.2 把 Skill 當成一次性 Prompt 的錯誤用法 6.3 如何讓 Skill 更容易被重用 6.4 如何讓 Agent 行為更穩定 第七章:團隊導入建議 7.1 適合先從哪些類型的 Skill 開始 7.2 如何建立內部 Skill Library 7.3 與既有開發流程整合 7.4 導入成熟度階段建議 附錄:檢查清單(Checklist) Skill 建立前檢查 SKILL.md 撰寫檢查 Skill 發布前檢查 團隊導入檢查 參考資源 官方資源 延伸閱讀 前言 文件目的 本手冊旨在協助團隊成員快速理解並導入 Claude Agent Skills,透過系統化的教學內容,讓新進同仁能夠: ...

January 12, 2026 · 14 min · 2880 words · Eric Cheng

Anthropic Model Context Protocol (MCP) 教學手冊

文件版本:2.0 對應規範:MCP Specification 2026-07-28(正式版,2026-07-28 發布) 前一規範:2025-11-25(相容性內容仍保留於本文) 最後更新:2026 年 7 月 31 日 文件等級:企業標準技術白皮書 適用對象:資深軟體開發工程師、系統架構師、平台工程與資安治理人員 Created by:Eric Cheng Anthropic Model Context Protocol (MCP) 教學手冊 重大提醒:2026-07-28 是 MCP 自發布以來最大幅度的改版,包含破壞性變更(Breaking Changes)。 核心協議由「有狀態、雙向」轉為「無狀態、請求/回應」。initialize 交握、Mcp-Session-Id 與 SSE 續傳機制均已移除;Roots、Sampling、Logging 進入棄用(Deprecated)狀態。 詳見 版本更新摘要 與 第十一章。 目錄 版本更新摘要:2026-07-28 規範重點 0.1 一頁式變更總覽 0.2 破壞性變更清單 0.3 棄用功能與生命週期政策 0.4 本手冊改版說明 第一章:MCP 概述與核心概念 1.1 什麼是 MCP? 1.2 為什麼需要 MCP? 1.3 MCP 架構概覽 1.4 協議演進史與版本治理 第二章:MCP 技術架構深度解析 2.1 分層架構 2.2 資料層協議(Data Layer Protocol) 2.3 MCP 核心原語(Primitives) 2.4 通知機制與訂閱串流(Notifications & Subscriptions) 2.5 多輪往返請求(Multi Round-Trip Requests, MRTR) 第三章:傳輸層深度解析 3.1 STDIO Transport 3.2 Streamable HTTP Transport 3.3 標頭路由、快取與可觀測性 3.4 傳輸層相容性策略 第四章:實戰開發指南 4.1 開發環境設置 4.2 開發 MCP Server 4.3 開發 MCP Client 4.4 整合到 AI 應用 第五章:完整實戰範例 5.1 範例一:檔案系統 MCP Server 5.2 範例二:資料庫查詢 MCP Server 5.3 範例三:API 整合 MCP Server 第六章:最佳實踐與設計模式 6.1 MCP Server 設計原則 6.2 效能優化 6.3 安全性考量 6.4 測試策略 第七章:進階主題 7.1 Tasks 擴充(io.modelcontextprotocol/tasks) 7.2 自訂傳輸層 7.3 多語言 SDK 比較 7.4 偵錯與監控 第八章:疑難排解 8.1 常見錯誤與解決方案 8.2 除錯技巧 8.3 錯誤訊息參考 第九章:實際案例研究 9.1 案例一:企業知識庫 MCP Server 9.2 案例二:DevOps 整合 MCP Server 第十章:資源與參考 10.1 官方資源 10.2 社群資源 10.3 開發環境建議 10.4 版本相容性 10.5 快速參考 第十一章:2026-07-28 遷移指南 11.1 遷移總體策略 11.2 Server 端遷移步驟 11.3 Client 端遷移步驟 11.4 從 Session 到顯式握柄(Explicit Handle) 11.5 雙時代(Dual-era)相容部署 第十二章:擴充框架與官方擴充 12.1 擴充框架(Extensions Framework) 12.2 MCP Apps:伺服器渲染互動介面 12.3 Tasks 擴充深入解析 12.4 企業託管授權(EMA)與 OAuth 擴充 12.5 自建第三方擴充 第十三章:企業級部署與治理 13.1 無狀態水平擴展架構 13.2 API 閘道、WAF 與速率限制 13.3 授權硬化與身分治理 13.4 可觀測性與 OpenTelemetry 13.5 一致性驗證與 SDK 分級 附錄:檢查清單(Checklist) A. Server 開發檢查清單 B. 部署檢查清單 C. 程式碼審查檢查清單 D. 故障排除檢查清單 E. 2026-07-28 遷移檢查清單 結語 參考文獻與延伸閱讀 官方規範(2026-07-28) 治理與流程 官方擴充 官方部落格 社群分析 相關標準 主要 SEP 索引 版本更新摘要:2026-07-28 規範重點 0.1 一頁式變更總覽 2026-07-28 由六份以上的 SEP(Specification Enhancement Proposal)共同構成,將 MCP 從 「為單機 stdio 情境設計的有狀態雙向協議」重塑為「可在通用 HTTP 基礎設施上水平擴展的無狀態 請求/回應協議」。以下為與前一版 2025-11-25 的對照總覽。 ...

January 9, 2026 · 134 min · 28540 words · Eric Cheng

Claude Code生態圈教學手冊

Claude Code 生態圈教學手冊 📖 版本:v5.0(企業技術白皮書版) 📅 最後更新:2026 年 11 月 16 日 🔎 查證基準:Claude Code v2.1.325(2026-11-13),逐頁比對 code.claude.com 官方文件;範例以本機 Claude Code v2.1.325 實測 👥 目標讀者:資深軟體工程師、技術主管、架構師、平台/DevOps 工程師、資安與 IT 管理員 ✍️ Created by:Eric Cheng 文件資訊 適用範圍 本手冊涵蓋 Claude Code 在 Terminal CLI、VS Code/JetBrains、Desktop App、Web(claude.ai/code)、CI/CD 等介面上的使用方式,以及 Subagents、Agent Teams、Skills、Plugins、Hooks、MCP、Output Styles、排程任務、Remote Control、Channels 等擴充與協作機制,並提供企業部署、治理、成本與安全的實務建議。 閱讀指引 讀者 建議閱讀順序 第一次使用 第一部分 → 2.3 Skills → 2.5 Hooks → 3.7 疑難排解 技術主管 1.2 → 2.1/2.2 → 3.5 團隊協作 → 3.6 成本 → 4.2 CI/CD 平台/DevOps 3.3 Headless → 4.2 CI/CD → 2.4 Plugins → 2.6 MCP → 4.3 自訂開發 資安/IT 管理員 1.2.5 權限與沙箱 → 1.2.8 v5.0 權限變更 → 2.5.9 Hook 治理 → 2.6.5 MCP 管理 → 4.1 企業部署(含 4.1.9) → 附錄 B 從 v4.0 升級 1.2.8 → 3.3.5 → 2.4.9 → 4.1.9 → 附錄 I.3 更正清單 標示說明 標示 意義 🆕 v5.0 新增(舊版標為 v4.0、v3.x) 該版依官方文件新增或更新的內容 ⚠️ v5.0 更正(舊版標為 v4.0 更正) 舊版內容與官方文件或實測結果不符,已更正(原錯誤寫法會一併說明,方便團隊清查既有設定) 🧪 v5.0 實測(舊版標為 v4.0 實測) 本版在本機實際執行過的範例與其輸出(Claude Code v2.1.325、jq 1.8.1、PowerShell 7、Python 3.12) 審查與驗證清單 AI 依本手冊產出設定或程式後,人工審查要逐項確認的內容與驗證命令 🔐 安全與治理相關的重點 🏢/企業導入檢核要點 企業導入時的建議與檢核清單 修訂重點 🆕 v5.0(2026-11-16):以 v2.1.325 為基準,重新下載並比對使用者指定的 17 個官方頁面與約 95 個延伸頁面(官方 plugin 文件已拆成 plugins/* 子頁;新增 code-mode、advisor、debug-your-config、errors 等;完整清單見附錄 I)。 ...

January 9, 2026 · 248 min · 52730 words · Eric Cheng

Claude Code教學手冊(資深同仁版)

版本: 1.0 最後更新: 2026年1月9日 適用於: Claude Code Created by: Eric Cheng Claude Code 使用教學手冊(資深同仁版) 版本:1.0 適用對象:資深工程師 / Tech Lead / 系統分析師 / 架構師 最後更新:2026 年 1 月 目錄 第一章:Claude Code 是什麼?(給資深工程師的視角) 1.1 Claude Code 與傳統 Copilot / ChatGPT Coding 的差異 1.2 適合用來做什麼?不適合做什麼? 1.3 在企業環境中的合理定位 第二章:資深工程師使用 Claude Code 的正確心法 2.1 把 AI 當成「資深 Pair Programmer」而非新人工具 2.2 為什麼「規格比程式碼更重要」 2.3 Prompt 即設計文件的延伸 第三章:高品質 Prompt 設計原則 3.1 好 Prompt vs 壞 Prompt 對照 3.2 Prompt 必備元素 3.3 常見錯誤 Prompt 範例與改寫示範 第四章:Claude Code 在實務開發流程中的應用 4.1 需求釐清 / PRD 補強 4.2 架構設計與技術選型 4.3 程式碼生成與重構 4.4 測試案例補齊 4.5 技術文件與 README 生成 第五章:企業級實戰範例 5.1 範例一:協助重構 Legacy Code 5.2 範例二:根據規格產生模組骨架 5.3 範例三:產生測試與安全檢查建議 第六章:風險、限制與最佳實踐 6.1 AI 可能產生的風險 6.2 如何做 Code Review 與 AI Output Review 6.3 在銀行 / 企業內部的安全使用原則 第七章:團隊導入建議 7.1 適合哪些角色優先使用 7.2 與現有開發流程的整合方式 7.3 建議的內部使用規範 第八章:進階技巧與模式 8.1 Prompt Chain 設計模式 8.2 多輪對話策略 8.3 與 Spec-Driven Development 整合 附錄:檢查清單(Checklist) A. 使用前準備清單 B. Prompt 撰寫清單 C. 程式碼審查清單 D. 整合上線清單 E. 團隊導入清單 版本紀錄 參考資源 第一章:Claude Code 是什麼?(給資深工程師的視角) 1.1 Claude Code 與傳統 Copilot / ChatGPT Coding 的差異 作為資深工程師,您可能已經使用過多種 AI 編程輔助工具。以下是 Claude Code 與其他工具的核心差異: ...

January 9, 2026 · 19 min · 4023 words · Eric Cheng

Claude Code教學手冊(新手版)

版本: 1.0 最後更新: 2026年1月9日 適用於: Claude Code Created by: Eric Cheng Claude Code 使用教學手冊(新進同仁版) 版本:1.0 最後更新:2026 年 1 月 適用對象:新進軟體工程師(PG / SA / Tech Lead 初階) 先決條件:具備基本程式設計能力 目錄 第 1 章:Claude Code 是什麼? 1.1 Claude Code 的定位 1.2 與一般聊天式 AI 的差異 1.3 適合與不適合的使用情境 1.4 Claude Code 在企業開發流程中的角色 第 2 章:Claude Code 的基本操作觀念 2.1 Prompt ≠ 問問題 2.2 好 Prompt 的核心結構 2.3 單輪 vs 多輪對話策略 2.4 如何逐步收斂出可用結果 第 3 章:新進工程師必學的 Prompt 範本 3.1 程式碼解讀 Prompt 3.2 新功能開發 Prompt 3.3 舊系統重構 Prompt 3.4 Bug 分析 Prompt 3.5 單元測試產生 Prompt 3.6 Code Review Prompt 3.7 規格補齊 Prompt 第 4 章:Claude Code 在實務開發中的典型流程 4.1 從需求文字到程式碼 4.2 從舊程式碼到可維護設計 4.3 從「我看不懂」到「我能修改」 4.4 搭配 Git / PR / Review 的使用方式 第 5 章:常見錯誤與 Anti-Pattern 5.1 問太籠統 5.2 一次丟太多責任 5.3 沒有限制輸出格式 5.4 盲目相信 AI 結果 5.5 沒做人工驗證 第 6 章:Claude Code 使用最佳實務(Best Practices) 6.1 Prompt 模組化 6.2 對話紀錄如何保存 6.3 與團隊共用 Prompt 的方式 6.4 什麼情況不該用 Claude Code 第 7 章:企業內部使用注意事項 7.1 資安與機敏資料原則 7.2 原始碼與客戶資料保護 7.3 法遵與稽核觀點 7.4 AI 產出責任歸屬說明 第 8 章:進階應用(選讀) 8.1 Spec-Driven Development(SDD) 8.2 將 Claude Code 當成虛擬 Pair Programmer 8.3 長任務拆解技巧 8.4 Prompt Chain 與角色切換 附錄:新進同仁檢查清單(Checklist) 延伸閱讀與資源 前言:如何使用本手冊 本手冊專為「新進軟體工程師」設計,協助您快速掌握 Claude Code 的使用方式。 ...

January 9, 2026 · 21 min · 4267 words · Eric Cheng

Java25升版教學

Java25升版教學 版本: 1.0 最後更新: 2025年12月31日 適用於: java 25 Created by: Eric Cheng +++ Java 1.7 → Java 25 升版教學手冊 版本:1.0 最後更新:2025 年 12 月 適用對象:具備 Java 1.7~8 基礎的開發人員 目標:企業升版實務 + Java OCP 認證準備 📋 目錄 前言 第一章:Java 平台演進總覽(1.7 → 25) 1.1 Java 版本生命週期說明(LTS vs 非 LTS) 1.2 為何企業應升級至 Java 17 / 21 / 25 1.3 Java 設計哲學的重大轉變 1.4 Java 與 JVM、生態系的角色變化 第一章小結 第二章:Java 7 → Java 8(現代 Java 的分水嶺) 2.1 Lambda Expression 2.2 Functional Interface 2.3 Stream API 2.4 Optional 的正確使用方式 2.5 Default Method 2.6 實務對照:Java 7 vs Java 8 2.7 常見誤用與 OCP 考點 第二章小結 第三章:Java 9 ~ Java 11(模組化與平台重整) 3.1 Java Platform Module System(JPMS) 3.2 jlink / jdeps 工具 3.3 移除 Java EE 模組的影響 3.4 HTTP Client API 3.5 var(區域型別推斷) 3.6 TLS / Security 強化 3.7 升版衝擊與因應策略 第三章小結 第四章:Java 12 ~ Java 16(語言精煉期) 4.1 Switch Expression 4.2 Text Blocks 4.3 Records 4.4 Pattern Matching for instanceof 4.5 ZGC / Shenandoah 簡介 4.6 Preview Feature 使用與風險 第四章小結 第五章:Java 17(LTS,企業升版首選) 5.1 Java 17 作為企業基準版的理由 5.2 Sealed Class 5.3 強封裝(Strong Encapsulation) 5.4 移除與淘汰 API 清單 5.5 與 Spring Boot / Jakarta EE 的相容性 第五章小結 第六章:Java 18 ~ Java 20(為並行革命鋪路) 6.1 Foreign Function & Memory API 6.2 Vector API 6.3 JVM 效能最佳化重點 6.4 新 GC 行為觀察 第六章小結 第七章:Java 21(LTS,Virtual Thread 時代) 7.1 Virtual Thread(Project Loom) 7.2 Structured Concurrency 7.3 Scoped Value 7.4 傳統 Thread Pool vs Virtual Thread 7.5 對 Web / Batch / MQ 系統的影響 7.6 實務建議 第七章小結 第八章:Java 22 ~ Java 25(未來 Java 的樣貌) 8.1 Pattern Matching 完整體系 8.2 Record Pattern 8.3 Class File API 8.4 最新 GC / JVM 優化 8.5 Java 在 Cloud-Native、AI、High Concurrency 的定位 第八章小結 第九章:舊系統升版實務指南(企業必讀) 9.1 Java 1.7 → 17 / 21 / 25 升版路線圖 9.2 常見升版風險 9.2.1 Unsafe API 9.2.2 反射存取 9.2.3 ClassLoader 問題 9.2.4 編碼 / TLS / 加密 9.3 建議升版策略(分階段) 9.4 升版 Checklist 第九章小結 第十章:Java OCP 認證對照與準備建議 10.1 Java OCP(新版)考試範圍對照 10.2 必考語言特性整理 10.3 常見陷阱題解析方向 10.4 建議學習與實作順序 第十章小結 第十一章:總結與學習地圖 11.1 Java 現代化能力成熟度模型 11.2 從 Java 7 工程師 → Java 25 架構師 11.3 持續學習建議與官方資源 第十一章小結 附錄:升版檢查清單(Checklist) A. 完整升版檢查清單 B. 快速參考卡 結語 前言 為什麼需要這份手冊? Java 自 1995 年誕生以來,已經走過近 30 年的歷程。從 Java 1.7 到 Java 25,Java 經歷了翻天覆地的變化: ...

December 31, 2025 · 59 min · 12401 words · Eric Cheng

OpenSpec使用教學

OpenSpec 使用教學手冊 版本:8.0 更新日期:2026-10-30 適用版本:OpenSpec v1.15.0(2026-10-24 發布);指令、旗標、預設值與驗證規則以 v1.15.0 tag 的原始碼與官方 docs/ 為準 文件等級:企業標準技術白皮書 適用對象:軟體工程師、系統分析師、Tech Lead、負責審查 AI 產出的 Reviewer 官方網站:openspec.dev 原始碼:Fission-AI/OpenSpec 摘要 AI 編碼助手很有能力,但如果需求只存在於聊天紀錄裡,產出結果就難以預測。OpenSpec 是一個輕量的「規格層」:在寫任何程式碼之前,先讓人與 AI 對「要做什麼」達成書面共識。共識以純 Markdown 的 requirement(需求)+ scenario(情境) 呈現,並以 delta(差異) 的方式描述每次變更。變更完成後封存(archive),delta 會合併回「現況規格」,成為系統行為的單一事實來源。 本手冊以 v1.15.0 為基準重新撰寫,重點有三個: 把人教會:每個概念都附可直接套用的範例,並用同一個「帳戶餘額查詢」案例貫穿全書。 讓人能審查與驗證 AI 的產出:每一章都有「👀 審查與驗證」小節,說明要看什麼、用什麼指令驗證、什麼結果代表通過。 可查證:書中所有完整的 spec、delta、proposal、tasks 檔案範例,都以原檔嵌入,並經過離線檢查器 check_spec.py 實際驗證;另有 22 個反例。只示範單一需求的片段,則是說明用途。檢查器依 v1.15.0 validator 原始碼的規則撰寫,原始碼與測試結果收錄在附錄 B。 目錄 前言 這份手冊的定位與讀者 版本基準與查證方式 本手冊的貫穿範例 閱讀符號說明 與 v7.0 的章節對照 第一章:OpenSpec 概念與定位 1.1 為什麼需要規格層 1.2 四個設計原則 1.3 核心心智模型 1.4 與其他做法的比較 1.5 何時不該用 OpenSpec 1.6 👀 審查與驗證:判斷團隊是否適合導入 第二章:安裝、升級與 AI 工具整合 2.1 選擇安裝方式 2.2 初始化專案 2.3 兩個輸入位置:終端機與 AI 聊天 2.4 Profile、Delivery 與 Workflow 2.5 支援的 AI 工具與呼叫語法 2.6 升級與 openspec update 2.7 遙測、版本檢查與企業網路 第三章:目錄結構與 Artifact 3.1 openspec 目錄結構 3.2 主規格格式 3.3 Requirement 與 Scenario 的格式規則 3.4 Delta spec 的四種區段 3.5 proposal.md 3.6 design.md 3.7 tasks.md 3.8 .openspec.yaml 變更中繼資料 3.9 👀 審查與驗證:artifact 結構檢核表 第四章:OPSX 標準工作流程 4.1 工作流程全貌:動作而非階段 4.2 步驟 1:explore 釐清需求 4.3 步驟 2:propose 產生規劃 4.4 步驟 3:審查規劃(人工關卡) 4.5 步驟 4:update 修訂規劃 4.6 步驟 5:apply 實作 4.7 步驟 6:verify 驗證實作 4.8 步驟 7:sync 與 archive 4.9 擴展流程:new、continue、ff、bulk-archive、onboard 4.10 更新既有變更還是開新變更 4.11 情境範例:Bug 修復、純重構、能力汰除 第五章:撰寫好規格 5.1 規格是行為,不是程式碼 5.2 好的 Requirement 5.3 好的 Scenario 5.4 選對 delta 類型 5.5 適當切分變更 5.6 漸進式嚴謹度 5.7 引導 AI 產出好草稿 5.8 反模式對照表 第六章:審查與驗證 AI 產出 6.1 兩個審查時機 6.2 審查順序與每個檔案要回答的問題 6.3 CLI 驗證指令 6.4 strict 模式與 SHALL/MUST 的中文陷阱 6.5 離線檢查器 check_spec.py 6.6 封存預演:在合併前看見結果 6.7 反例集:AI 常犯的錯誤 6.8 審查紀錄範本 第七章:客製化 7.1 三個客製化層級 7.2 config.yaml 7.3 繁體中文設定 7.4 自訂 schema 7.5 社群 schema 7.6 👀 審查與驗證:設定是否生效 第八章:團隊協作與治理 8.1 唯一的原則:OpenSpec 不碰 git 8.2 分支與 PR 流程 8.3 何時封存 8.4 平行變更與衝突 8.5 CI 整合 8.6 Stores(Beta)跨 repo 規劃 8.7 doctor、context 與 workset 8.8 安全性考量 第九章:既有專案導入與遷移 9.1 只為要改的部分寫規格 9.2 第一個真實變更 9.3 既有的 PRD、SRS 怎麼處理 9.4 Monorepo 與能力的組織方式 9.5 從舊版工作流程遷移到 OPSX 9.6 導入路線圖 第十章:實戰案例:帳戶餘額查詢端到端 10.1 時間線 10.2 封存前的預演 10.3 封存後的主規格 10.4 後續變更一:純重構 10.5 後續變更二:汰除與更名 10.6 案例回顧 第十一章:FAQ、疑難排解與常見陷阱 11.1 常見問題(FAQ) 11.2 疑難排解 11.3 常見陷阱 11.4 業界獨立評測摘要 附錄 A:指令參考 A.1 Slash 指令(AI 聊天) A.2 CLI 指令 A.3 環境變數與結束碼 A.4 AI 工具 ID 與安裝路徑 附錄 B:審查清單與 check_spec.py B.1 審查清單 B.2 check_spec.py 原始碼 B.3 測試與執行結果 附錄 C:Prompt 範本 C.1 探索 C.2 提案 C.3 請 AI 自我審查規劃 C.4 修訂 C.5 實作 C.6 遷移 project.md 附錄 D:版本沿革 D.1 v1.10 至 v1.15(本版新增) D.2 v1.0 至 v1.9(摘要) 附錄 E:術語表與參考資源 E.1 術語表 E.2 官方資源 E.3 第三方資源 附錄 F:修正紀錄與驗證紀錄 F.1 本版修正(v7.0 到 v8.0) F.2 驗證方式與結果 F.3 待確認事項 文件資訊 前言 這份手冊的定位與讀者 這是一份導入與操作手冊,不是官方文件的翻譯。官方文件告訴你「指令做什麼」,本手冊要回答企業團隊真正卡住的三個問題: ...

December 31, 2025 · 65 min · 13759 words · Eric Cheng