Eve 教學手冊

Eve 教學手冊 Vercel Eve Agent Framework × PM Skills 企業整合架構完整指南 適用對象:資深工程師、AI Agent 平台團隊、架構師、DevOps / SSDLC 負責人 文件性質:企業內部 AI Agent 平台導入與培訓教材 目錄 第 1 章 Eve 是什麼 第 2 章 Eve 核心設計理念 第 3 章 Eve 系統架構解析 第 4 章 Eve 目錄結構 第 5 章 Eve 核心元件 第 6 章 Eve 執行流程 第 7 章 Eve 安裝教學 第 8 章 建立第一個 Eve Agent 第 9 章 Agent 開發實戰 第 10 章 Skills 開發教學 第 11 章 PM Skills 與 Eve 整合 第 12 章 使用 Eve 開發 Web Application 第 13 章 使用 Eve 執行 Reverse Engineering 第 14 章 使用 Eve 執行 Framework Upgrade 第 15 章 Subagents 設計模式 第 16 章 Human Approval 設計 第 17 章 Eve 與 MCP 整合 第 18 章 Eve 與 Claude Code 整合 第 19 章 Eve 與 GitHub Copilot 整合 第 20 章 Eve 與企業 SSDLC 整合 第 21 章 Eve 生產環境部署 第 22 章 Eve 可觀測性 第 23 章 Eve 安全設計 第 24 章 Eve 效能優化 第 25 章 Eve 開發規範 第 26 章 Eve 常見問題 FAQ 第 27 章 Eve 最佳實務 第 28 章 Eve 常見反模式 第 29 章 Eve Roadmap 分析 第 30 章 結論 附錄 A 完整 Weather Agent 範例 附錄 B PM Skills + Eve 整合範本 附錄 C Mermaid 圖總覽索引 附錄 D 檢查清單(Checklist) 第 1 章 Eve 是什麼 本章小節導覽:1.1 Eve 誕生背景 · 1.2 為何 Vercel 開發 Eve · 1.3 Agent Framework 發展歷史 · 1.4 與 LangGraph 的差異 · 1.5 與 CrewAI 的差異 · 1.6 與 OpenAI Agents SDK 的差異 · 1.7 與 AutoGen 的差異 · 1.8 與 Semantic Kernel 的差異 · 1.9 與 Mastra 的差異 · 1.10 與 PydanticAI 的差異 · 1.11 為何 Eve 被稱為「Agent 世界的 Next.js」 ...

June 24, 2026 · 44 min · 9280 words · Eric Cheng

Pm Skills教學手冊

PM Skills 教學手冊 以 phuryn/pm-skills 建立可審查、可驗證的企業級 AI 產品管理與交付流程 項目 說明 文件版本 v2.0.0 更新日期 2026-10-20 文件等級 企業標準技術白皮書 查證基準 phuryn/pm-skills v2.2.0(2026-10-10 發佈,commit c68487d;9 個 Plugin、69 個 Skill、42 個 Command);另含 main 分支上尚未發版的 Cursor 原生 manifest(PR #72,2026-10-16) 對照環境 Claude Code 2.1.303、Python 3.12.8、PowerShell 7.6.7、Node.js 24.16.0、Git 2.45.2、Hugo 0.151.0 適用對象 產品經理、Tech Lead、資深工程師、架構師、SSDLC/DevSecOps 負責人、AI 導入推動者、稽核與法遵人員 前置知識 至少使用過一種 AI 工具(Claude Code、Cowork、Codex、Cursor 等);了解 PRD、使用者故事、OKR 等基本概念 資料來源 phuryn/pm-skills(MIT License,由 The Product Compass 作者 Paweł Huryn 維護)、Agent Skills 規格、Claude Code/Codex/Cursor 官方文件;本手冊是消化後的重新撰寫,不是上游文件的轉貼 v2.0.0 改版重點:(1)查證基準由上游 v2.0.0 升到 v2.2.0,Skill 由 68 增為 69(新增 code-review);(2)create-prd 與 /write-prd 在 v2.2.0 改為精簡預設(1–2 頁)、價值主張改用 6 段 JTBD 模板;(3)pm-ai-shipping 新增正確性審查、獨立第二模型審查、OWASP 覆蓋回扣、check 檢查模式與 git range 稽核;(4)上游 main 新增 Cursor 原生 manifest;(5)全面重組為 25 章+附錄 A–H,69 個 Skill 與 42 個 Command 逐一涵蓋;(6)每章附「本章審查與驗證清單」,所有示意產出皆有正反例並經 149 個案例的檢查器驗證;(7)新增證據索引(SSDLC)、估點校準(Agile)、Plugin 差異審查(治理)、預埋缺陷與召回率(驗證方法論)。 ...

June 23, 2026 · 224 min · 47558 words · Eric Cheng

SkillSpector 教學手冊

SkillSpector 教學手冊 版本:v1.1(2026-06-22) 適用對象:AI Security Specialist、AI Agent 架構師、DevSecOps 工程師、軟體架構師、全端工程師、逆向工程專家、CI/CD 與 GitHub Security 工程師 內容定位:本手冊聚焦於 NVIDIA 開源專案 SkillSpector(github.com/NVIDIA/SkillSpector)——一套在 AI Agent Skill/MCP Server 安裝前進行安全掃描的工具——的核心理念、系統架構、安裝設定、掃描實戰,並延伸至企業級 DevSecOps 導入(CI/CD Gate、SARIF、治理藍圖、產業導入建議) 重要聲明:本手冊第 1~8、12 章之工具行為描述(CLI 指令、設定項、64 項檢測規則 16 大類別、風險評分公式、SARIF 輸出、架構模組名稱)基於 SkillSpector 官方 GitHub Repository 原始碼與 README.md、Makefile、pyproject.toml 逐項核對後整理改寫而成,並非逐字翻譯;少數官方來源未能逐項驗證的細節(如 LLM 階段精確度量化數字、model_registry.yaml 機制、OPENAI_BASE_URL 變數)已在對應段落明確標註「待以實際版本驗證」,不作斷言。第 1.1、1.3、2.0 節額外引用之外部研究與公告(arXiv:2601.10338、arXiv:2602.06547、Anthropic Agent Skills 官方公告、Snyk/Datadog/Repello 等資安社群報導)均為可公開查證之獨立來源,用於補強背景論述深度,非 SkillSpector 官方數據。第 9~11、13~20 章(GitLab CI/Jenkins/Azure DevOps 範例、企業導入架構、產業導入建議、治理藍圖、FAQ、Troubleshooting)為「企業實務延伸」內容,是顧問觀點下將 SkillSpector 套用於企業 DevSecOps 流程的建議做法,並非 NVIDIA 官方功能宣稱或官方範例,文中會明確標註。GitHub 社群數據(Star/Fork 數)反映查詢當下時間點,會隨時間持續變動,實際導入前請以官方 Repository 當下版本為準。 授權:內部教育訓練使用 如何使用本手冊 SkillSpector 解決的是一個正在快速擴大的問題:AI Coding Agent(Claude Code、GitHub Copilot、Gemini CLI、Cursor、Codex 等)的「Skill/Plugin/Extension」生態系正在爆炸性成長,但這些第三方 Skill 以 Agent 的完整權限執行,卻幾乎沒有安全審查機制。NVIDIA 針對 42,447 個公開 Skill 的研究顯示,26.1% 含有至少一項漏洞,5.2% 疑似具惡意意圖。SkillSpector 就是為了在「安裝 Skill」與「執行 Skill」之間,插入一道自動化的安全關卡。 ...

June 22, 2026 · 23 min · 4728 words · Eric Cheng

Ponytail 教學手冊

Ponytail 教學手冊 版本:v1.1(2026-06-22,已對照官方 Repository 原始檔案逐章核實修訂) 適用對象:系統分析師、軟體架構師、後端工程師、前端工程師、DevOps工程師、SRE工程師、AI工程師、企業資訊部門、Framework維護團隊、Legacy System維護團隊 內容定位:本手冊聚焦於開源 AI Agent 精簡化技能(Skill)Ponytail 的理念、架構、安裝設定、與主流 AI Coding Agent(Claude Code / GitHub Copilot / Cursor / Codex / Gemini CLI 等共 14 個受支援平台)的整合方式,並延伸至企業級開發流程(SSDLC、多 Agent 團隊協作、Legacy 逆向工程、Framework 升級)的實務導入 重要聲明:本手冊第 1~12、15 章內容基於 Ponytail 官方 GitHub Repository(DietrichGebert/ponytail)之 README.md、AGENTS.md、skills/ponytail/SKILL.md、skills/ponytail-review/SKILL.md、docs/agent-portability.md、docs/platform-native.md 等公開資料,逐項核對原文後整理改寫而成(非逐字抄錄);第 13、14、16、20 章為「企業實務延伸」章節,是顧問觀點下將 Ponytail 精簡哲學套用於企業開發治理的建議做法,並非 Ponytail 官方功能宣稱,文中會明確標註。GitHub 社群數據(Star/Fork/Issue 數)反映查詢當下時間點,會隨時間持續變動 授權:內部教育訓練使用 如何使用本手冊 Ponytail 不是一個框架,也不是一個 IDE,而是一套注入到 AI Coding Agent 的行為準則(Skill / Plugin)。它的任務很單純:在 AI Agent 動手寫程式之前,先逼它像一個「已經看過太多過度設計專案、留著馬尾、戴著圓框眼鏡的資深工程師」一樣,先問一句「這真的需要寫嗎?」。本手冊依角色整理出建議閱讀路徑: 角色 建議優先閱讀章節 新進工程師 第1、3、5、6章 後端/前端工程師 第7、8、9、10章 架構師/系統分析師 第2、4、11、12章 DevOps/SRE 第6、7、19章 AI Coding Agent 重度使用者 第4、5、15、17、18章 企業資訊部門主管 第13、14、16、20章 Legacy System維護團隊 第11、12章 Code Review/品質把關者 第9、17、18章 目錄 第 1 章 Ponytail 概述 1.1 專案背景 1.2 作者介紹 1.3 發展歷程與版本里程碑 1.4 GitHub 社群狀況 1.5 為何爆紅 1.6 解決哪些問題 第 2 章 AI Coding Agent 常見問題 2.1 Over Engineering 2.2 Reinvent The Wheel 2.3 Token Waste 2.4 Context Pollution 2.5 Hallucination Driven Design 2.6 Framework Ignorance 2.7 Existing Code Ignorance 2.8 Legacy System Rewrite Syndrome 2.9 案例分析總表 第 3 章 Ponytail 核心理念 3.1 Lazy Senior Developer Mindset 3.2 Less Code Principle 3.3 Existing Solution First 3.4 Delete Before Build 3.5 Native Feature First 3.6 Library Before Custom Code 3.7 Configuration Before Programming 3.8 Simplicity First 3.9 Maintainability First 3.10 Cost Awareness 第 4 章 Ponytail 系統架構 4.1 Architecture Overview 4.2 Skill Architecture 4.3 Agent Workflow 4.4 Review Loop 4.5 Self Critique Loop 4.6 Decision Flow 4.7 Prompt Enhancement Flow 4.8 Integration Flow 第 5 章 Ponytail 工作原理 5.1 第一階:這個功能真的需要存在嗎(YAGNI) 5.2 第二階:標準函式庫能解決嗎 5.3 第三階:平台原生功能能解決嗎 5.4 第四階:已安裝的相依套件能解決嗎 5.5 第五階:能用一行寫完嗎 5.6 第六階:只寫最小可行實作 5.7 企業實務延伸:刪除與精簡思維(呼應 ponytail-review) 5.8 內部思考流程整合範例 第 6 章 安裝與部署 6.1 Claude Code 6.2 GitHub Copilot 6.3 Cursor 6.4 OpenAI Codex/Agent 6.5 Gemini CLI 6.6 VS Code 整合 6.7 JetBrains 整合 6.8 Pi Agent Harness 6.9 OpenCode 6.10 CodeWhale 6.11 OpenClaw 6.12 Kiro 6.13 系統需求 第 7 章 Ponytail 設定說明 7.1 Agent Configuration 7.2 Rules 7.3 Skills 7.4 Context 7.5 Hooks 7.6 Templates 7.7 Review Policies 7.8 Team Standards 第 8 章 與 Claude Code 整合 8.1 Agent Skill 8.2 Custom Instructions 8.3 Commands 8.4 Workflows 8.5 Best Practices 8.6 Enterprise Standards 第 9 章 與 GitHub Copilot 整合 9.1 Copilot Agent 9.2 Copilot Coding Agent 9.3 Repository Instructions 9.4 Prompt Files 9.5 Agent Files 9.6 Skills 9.7 完整範例 第 10 章 Web Application 開發實戰 10.1 技術棧總覽 10.2 API 開發 10.3 CRUD 開發 10.4 Batch 開發 10.5 Security 開發 10.6 Integration 開發 10.7 Ponytail 如何減少程式碼 第 11 章 Legacy System Reverse Engineering 11.1 Mainframe 11.2 COBOL 11.3 Lotus Domino 11.4 Struts 11.5 JSF 11.6 舊版 Spring 11.7 WebSphere 11.8 WebLogic 11.9 Ponytail 在逆向工程中的角色與限制 第 12 章 Framework Upgrade 實戰 12.1 Spring Boot 2 到 3 12.2 Java 8 到 21 12.3 Vue2 到 Vue3 12.4 Jakarta Migration 12.5 JDK Upgrade 12.6 Dependency Upgrade 12.7 降低升級成本的具體做法 第 13 章 與 SSDLC 整合(企業實務延伸) 13.1 定位澄清:Ponytail 不是安全工具 13.2 Threat Modeling 13.3 SAST 13.4 DAST 13.5 Dependency Check 13.6 Secret Detection 13.7 Secure Coding 13.8 Compliance 13.9 Audit 第 14 章 與 AI Agent 團隊整合(企業實務延伸) 14.1 多 Agent 團隊架構總覽 14.2 Planner Agent 14.3 Architect Agent 14.4 Developer Agent 14.5 Reviewer Agent 14.6 Security Agent 14.7 QA Agent 14.8 Release Agent 14.9 Ponytail 在團隊中的角色 第 15 章 Token Optimization 15.1 Token Reduction 15.2 Context Reduction 15.3 Prompt Compression 15.4 Reuse Existing Logic 15.5 Knowledge Reuse 15.6 Memory Optimization 15.7 實際數據案例 第 16 章 企業導入指南(企業實務延伸) 16.1 Governance 16.2 Standards 16.3 Team Adoption 16.4 Change Management 16.5 Training Plan 16.6 KPI 16.7 ROI 第 17 章 最佳實務 第 18 章 常見錯誤 第 19 章 維運與升級 19.1 Version Upgrade 19.2 Skill Upgrade 19.3 Agent Upgrade 19.4 Prompt Upgrade 19.5 Governance Upgrade 第 20 章 完整企業導入範例(企業實務延伸) 20.1 案例背景:大型銀行共用平台 20.2 開發流程 20.3 Code Review 20.4 SSDLC 20.5 Release Flow 20.6 Production Support 附錄:新進成員快速 Checklist 第 1 章 Ponytail 概述 1.1 專案背景 Ponytail 是一套開源的 AI Agent 行為準則(Skill / Plugin),目標只有一個:讓 AI Coding Agent 在動手寫程式前,先經過「這真的有必要嗎」的層層質疑,而不是看到需求就立刻開始搭框架、拉套件、寫一堆「以後可能用得到」的抽象層。 ...

June 22, 2026 · 24 min · 4962 words · Eric Cheng

12 Factor Agents教學手冊

12-Factor Agents 教學手冊 版本:v1.1 | 更新日期:2026-06-19 | 適用對象:資深工程師、架構師、AI Agent Architect、技術主管 變更紀錄(v1.0 → v1.1) 對照原始來源 humanlayer/12-factor-agents 重新逐章核對內容準確度與時效性 第一章 1.1/1.5 補上原文「How We Got Here」中 DAG Orchestrator(Airflow/Prefect/Dagster)的歷史脈絡,使 Agent 工程演進敘事更完整 第三章新增 Factor 13(榮譽提及):Pre-fetch All the Context You Might Need,補齊原文十二大原則之外的延伸原則 第五章新增 5.8(Context Rot 與「啞區 Dumb Zone」現象)、5.9(Research-Plan-Implement, RPI 框架),收錄 HumanLayer 團隊基於十萬餘筆開發者 Session 分析的最新實證研究 新增附錄 H 參考資料,補上原始出處與延伸閱讀連結,提升內容可追溯性 校對全文標題層級、目錄錨點、code fence 配對,確認與本文一致且無格式錯位 文件說明 本手冊以 HumanLayer 團隊提出的《12-Factor Agents》原則為核心骨幹,延伸至企業實際導入 AI Coding Agent(Claude Code、GitHub Copilot Agent Mode 等)的完整工程實務。內容定位為企業內部培訓教材,同時也是架構設計手冊與開發實戰手冊,目標讀者涵蓋初級工程師到 AI Agent Architect 各個層級。 ...

June 19, 2026 · 34 min · 7137 words · Eric Cheng

Claude Code Cli 教學手冊

Claude Code CLI 教學手冊 版本:v3.0(2026-11-18) 適用對象:系統分析師、軟體架構師、後端工程師、前端工程師、DevOps工程師、SRE工程師、AI工程師、企業資訊部門、Framework維護團隊、Legacy System維護團隊 內容定位:本手冊聚焦於 Claude Code CLI 層級的安裝、設定、指令、Agent 架構、MCP 整合與企業導入實務,以「企業標準技術白皮書」等級撰寫:每一條規範都附範例,並說明人工如何審查與驗證 AI 依規範產出的結果。可與專案內其他 Claude Code 相關手冊(生態圈版、資深同仁版等)並行參考 對齊基準:官方文件 code.claude.com/docs(2026-11-18 下載 llms.txt 所列全部 205 頁原始 Markdown,逐章對照)與 Changelog 至 Claude Code v2.1.327(2026-11-17);指令旗標以本機 Claude Code v2.1.327 的 --help(含 21 個子指令)逐一比對;設定/Hook/MCP/Subagent/Skill 範例皆經第30章的檢查工具實際執行,另以 claude -p --model haiku 實測 8 項關鍵行為(第29.8章),細節見附錄H(v3.0)與附錄G(v2.0) 授權:內部教育訓練使用 如何使用本手冊 Claude Code CLI 是一套以終端機(Terminal)為主要操作介面的 AI 編碼代理人(Coding Agent)。它不像傳統 IDE 外掛只做行內自動完成,而是能夠自主規劃、呼叫工具、跨檔案修改、執行測試、操作 Git,甚至協調多個子 Agent 完成大型任務。本手冊依角色整理出建議閱讀路徑: 角色 建議優先閱讀章節 新進工程師 第1、3、4、6、7、11、32章 後端/前端工程師 第8、9、14、17、18章 架構師/系統分析師 第2、13、15、16、26、31章 DevOps/SRE 第5、12、19、20、28、29、32、33章 企業資訊部門主管 第21、25、28、33章、附錄H Legacy System維護團隊 第15、16章 平台/AI賦能團隊 第9、10、26、27、29、30、31、33章 資安/稽核人員 第6.6、12、19、28、30、31章 本手冊每一章的結構固定為:本章目標 → 概念與規範 → 範例 → 實務建議/注意 → 本章審查與驗證清單。「本章審查與驗證清單」是 v2.0 新增的固定段落,列出 AI 依本章規範產出內容時最常見的錯誤、正確寫法,以及人工可執行的驗證方式;第30章則把這些驗證方式整理成可直接放進 CI 的檢查工具。 ...

June 18, 2026 · 152 min · 32173 words · Eric Cheng

Loop Engineering 教學手冊

Loop Engineering 教學手冊 版本:v1.2 | 更新日期:2026-07-20 | 適用對象:資深工程師、架構師、技術主管 變更紀錄(v1.1 → v1.2) 新增「第十五章 Skill Library」:依 4.3.1 節目錄結構,實作 26 個技能檔案(coding/architecture/testing/security/migration 五大分類,Skill-01~Skill-26) 原第十五~十八章(最佳實務 Top 50、常見錯誤 Top 50、導入策略、未來發展)依序遞移為第十六~十九章,並同步更新目錄與全文交叉引用 變更紀錄(v1.0 → v1.1) 修復巢狀 code fence 連鎖錯位問題(曾導致第十五、十六章在嚴格 CommonMark 渲染器下被誤判為單一程式碼區塊)與其他 Markdown 格式問題 簡化附錄 I/J/K 標題格式並補上目錄連結,修正目錄與本文不一致之處 新增 1.6(演進脈絡與業界共識)、1.7(風險與限制:企業治理視角) 新增 2.10(Anthropic 六大 Agent 工作流模式對照)、2.11(Graph Harness 排程理論觀點)、2.12(Ralph Wiggum Technique) 擴充第十一章 Evals 設計方法論:新增 11.6~11.10,補齊術語體系、評分器類型、Pass@k/Pass^k、8 步驟落地路線圖、Swiss Cheese Model、業界標竿與工具 擴充第十八章導入策略:新增 18.4~18.6,補齊單一迴圈自主程度模型、七種生產級 Loop 模式目錄、loop-audit/loop-cost 自我檢測 新增 18.5(下一代執行引擎:Graph Harness 的展望) 目錄 第一章 Loop Engineering 概論 第二章 Loop Engineering 核心理論 第三章 Loop Engineering 系統架構 第四章 六大核心元件 第五章 Claude Code 中的 Loop Engineering 第六章 GitHub Copilot 中的 Loop Engineering 第七章 建立企業級 Loop Engineering 平台 第八章 Web Application 開發實戰 第九章 Legacy System 逆向工程 第十章 Framework 升級實戰 第十一章 Evals 設計 第十二章 AI Agent Team 設計 第十三章 SSDLC 與 Loop Engineering 第十四章 Prompt Library 第十五章 Skill Library 第十六章 最佳實務 Top 50 第十七章 常見錯誤 Top 50 Anti-patterns 第十八章 導入策略 第十九章 未來發展 附錄 A Loop Engineering Checklist 附錄 B Project Structure 附錄 C Skill Library Template 附錄 D Memory Template 附錄 E Evaluation Template 附錄 F Claude Code Setup 附錄 G GitHub Copilot Setup 附錄 H 企業導入路線圖 附錄 I 補充 Prompt Library 附錄 J 補充 SOP 集合 附錄 K 補充 Mermaid 架構圖集 第一章 Loop Engineering 概論 1.1 Loop Engineering 的起源 Loop Engineering 這個概念由 Google Chrome 工程師 Addy Osmani 在 2024-2025 年間系統化提出,並在其 Substack 文章《Loop Engineering》中首次完整闡述。這個概念的誕生並非偶然,而是對 AI 輔助開發演進路徑的自然延伸。 ...

June 17, 2026 · 97 min · 20591 words · Eric Cheng

Headroom 教學手冊

Headroom 教學手冊 版本:基於 Headroom v0.25.0(2026-06-12) 適用對象:資深工程師、AI Agent 開發團隊、DevOps 工程師 授權:Apache 2.0 專案規模:GitHub ⭐ 24.1K|Contributors 83+|Releases 155+ 官方資源:GitHub | 文件站 | PyPI | npm | llms.txt | Enterprise 目錄 第一章 Headroom 簡介 1.1 Headroom 是什麼 1.2 為何需要 Headroom 1.3 Headroom 與 RTK 差異 第二章 Headroom 系統架構 2.1 整體架構圖 2.2 三階段壓縮管線 2.3 ContentRouter 2.4 SmartCrusher 2.5 CodeCompressor 2.6 Kompress-base 2.7 CacheAligner 2.8 CCR(可逆壓縮) 2.9 TOIN 學習網路 2.10 Read Lifecycle Management 2.11 壓縮安全護欄 第三章 安裝與部署 3.1 系統需求 3.2 Python 安裝 3.3 Node.js 安裝 3.4 Docker 部署 3.5 Podman 部署 3.6 企業 SSL 環境處理 3.7 驗證安裝 第四章 使用模式 4.1 Library Mode 4.2 Proxy Mode 4.3 Agent Wrap 4.4 MCP Server 第五章 與 RTK 整合 5.1 為何同時使用 5.2 整合架構 5.3 實戰情境最佳實務 第六章 大型 Web Application 實戰 6.1 專案 Context 管理 6.2 Claude Code 最佳化 6.3 GitHub Copilot Agent 最佳化 6.4 Codex CLI 最佳化 6.5 Gemini CLI 最佳化 6.6 其他 Agent 整合 第七章 Token Optimization 策略 7.1 壓縮方案比較 7.2 依 Context 大小的壓縮策略 7.3 CacheAligner 策略 7.4 複合節省計算 第八章 團隊導入指南 8.1 導入流程 8.2 開發規範範本 8.3 團隊教育訓練 第九章 系統維護 9.1 日常維護 9.2 Log 分析 9.3 Cache 管理 9.4 CCR 管理 9.5 環境變數總覽 9.6 升級策略 9.7 備份策略 第十章 Troubleshooting 第十一章 最佳實務總結 11.1 Do — 建議做法 11.2 Don’t — 避免做法 11.3 Architecture Guideline 11.4 Security Guideline 11.5 Performance Guideline 11.6 Cost Optimization Guideline 附錄 A. Headroom 指令速查表 B. MCP 設定範例 C. Docker Compose D. Podman Compose E. Claude Code 整合範例 F. GitHub Copilot 整合範例 G. Codex CLI 整合範例 H. Gemini CLI 整合範例 I. RTK + Headroom 整合範例 J. 其他 Agent 整合範例 K. 檢查清單(Checklist) 第一章 Headroom 簡介 1.1 Headroom 是什麼 Headroom 是一套開源的 AI Agent 上下文壓縮層(Context Compression Layer),專門在資料送入大型語言模型(LLM)之前,對工具輸出、日誌、RAG 檢索結果、原始碼檔案及對話歷史進行智慧壓縮。其核心承諾是: ...

June 12, 2026 · 32 min · 6629 words · Eric Cheng

Codegraph教學手冊

CodeGraph 減少 Token 使用教學手冊 版本:v1.0(2026-05-31) 適用 CodeGraph 版本:v0.9.7+ 適用對象:資深工程師、架構師、AI Agent 開發團隊 授權:內部教育訓練使用 目錄 第 1 章 CodeGraph 概述 1.1 什麼是 CodeGraph 1.2 為何出現 — AI Agent 的 Token 困境 1.3 解決的核心問題 1.4 與傳統 RAG 的差異 1.5 Symbol Graph、Knowledge Graph 與 MCP 的關係 第 2 章 CodeGraph 架構 2.1 Tree-sitter AST 解析層 2.2 Symbol 與 Edge 提取 2.3 Resolution 層 2.4 SQLite 存儲層(FTS5) 2.5 Auto-Sync 檔案監視層 2.6 MCP Server 層 第 3 章 AI 為何浪費大量 Token 3.1 Agent 探索模式分析 3.2 Context 爆炸問題 3.3 Tool Call 爆炸問題 3.4 大型專案規模影響 第 4 章 CodeGraph 如何降低 Token 4.1 預建索引 vs 即時掃描 4.2 精準查詢 vs 全域搜尋 4.3 結構化上下文 vs 原始檔案 4.4 官方 Benchmark 數據分析 第 5 章 安裝與設定 5.1 系統需求 5.2 Windows 安裝 5.3 macOS / Linux 安裝 5.4 npm 安裝方式 5.5 Agent 自動設定 5.6 專案初始化 5.7 驗證與狀態檢查 5.8 解除安裝 第 6 章 MCP 工具詳解 6.1 codegraph_search 6.2 codegraph_context 6.3 codegraph_trace 6.4 codegraph_callers 6.5 codegraph_callees 6.6 codegraph_impact 6.7 codegraph_node 6.8 codegraph_explore 6.9 codegraph_files 6.10 codegraph_status 第 7 章 Claude Code 最佳實踐 7.1 MCP + CodeGraph 設定 7.2 Architecture Analysis 7.3 Bug Analysis 7.4 Refactoring 7.5 Feature Development 7.6 CLAUDE.md 配置建議 第 8 章 GitHub Copilot 最佳實踐 8.1 Copilot Agent Mode + CodeGraph 8.2 Symbol Search 優先策略 8.3 Impact Analysis 工作流 8.4 避免 Full Repository Scan 8.5 copilot-instructions.md 配置 第 9 章 Reverse Engineering 最佳實踐 9.1 場景:接手 20 年 Legacy 系統 9.2 Call Graph 快速理解架構 9.3 Dependency Graph 分析模組關係 9.4 Route Graph 理解 API 端點 9.5 逆向工程完整工作流 第 10 章 Framework 升級最佳實踐 10.1 Impact Analysis 找出受影響模組 10.2 案例:Spring Boot 2 → 4 10.3 案例:Java 17 → 25 10.4 案例:Vue 2 → Vue 3 10.5 案例:AngularJS → Angular 10.6 codegraph affected 整合 CI/CD 第 11 章 SSDLC 整合 11.1 SSDLC 與 CodeGraph 11.2 Threat Modeling 階段 11.3 Code Review 階段 11.4 Incident Response 階段 11.5 Dependency Audit 第 12 章 Token 優化五級策略 12.1 五級優化模型 12.2 Level 1:基礎安裝 12.3 Level 2:工具優先 12.4 Level 3:Prompt 工程 12.5 Level 4:工作流整合 12.6 Level 5:全面治理 第 13 章 企業級實踐 13.1 大規模專案的 CodeGraph 部署 13.2 多語言專案 13.3 團隊協作模式 13.4 安全考量 13.5 效能調優 13.6 程式庫使用(Library API) 第 14 章 團隊 AI 開發規範 14.1 AI Coding Standard(團隊範本) 14.2 Prompt Library(團隊 Prompt 庫) 14.3 Code Review Checklist(AI 產生程式碼) 14.4 onboarding 流程(AI 工具) 第 15 章 20 個常見錯誤與解決方案 15.1 安裝與設定類(錯誤 1-5) 15.2 使用模式類(錯誤 6-10) 15.3 Prompt 設計類(錯誤 11-15) 15.4 進階使用類(錯誤 16-20) 第 16 章 AI Agent 工作流與 KGDD 16.1 Knowledge-Graph-Driven Development (KGDD) 16.2 Agent 工作流設計模式 16.3 Multi-Agent 協作與 CodeGraph 16.4 Agentic Workflow 成熟度模型 第 17 章 總結與展望 17.1 核心要點回顧 17.2 採用路線圖 17.3 未來展望 17.4 行動建議 附錄 A:Claude Code 50%+ Token 削減實戰 附錄 B:GitHub Copilot 50%+ Token 削減實戰 附錄 C:知識圖譜成本削減計算 附錄 D:Enterprise AI Coding Standard 附錄 E:Enterprise MCP Standard 附錄 F:Enterprise KG Platform 藍圖 附錄 G:Checklist 第 1 章 CodeGraph 概述 1.1 什麼是 CodeGraph CodeGraph 是一個開源的本地端程式碼知識圖譜工具(MIT License,GitHub 34.9k+ stars),專為 AI 編碼代理(Coding Agent)設計。它利用 Tree-sitter 解析器將程式碼庫轉換為結構化的符號關係圖譜,儲存於本地 SQLite 資料庫,並透過 MCP(Model Context Protocol)Server 將圖譜能力暴露給 AI Agent 使用。 ...

May 31, 2026 · 40 min · 8448 words · Eric Cheng

Copilot CLI教學手冊

GitHub Copilot CLI 教學手冊 文件版本:v2.0(2026-10-14,全面重新編排) 對應產品版本:GitHub Copilot CLI v1.0.97(2026-10-13 發佈的最新穩定版),旗標與設定鍵以本機 v1.0.97 的 copilot --help、copilot help config|environment|commands|permissions|sandbox 輸出逐一核對 文件等級:企業標準技術白皮書(Enterprise Technical Whitepaper) 適用對象:資深工程師、DevOps/平台工程師、架構師、資安與治理人員 技術情境:企業級 Web 應用(Java 21/Spring Boot 3.5、Vue 3、微服務、GitHub Enterprise Cloud) 適用方案:Copilot Free/Student/Pro/Pro+/Max/Business/Enterprise(全面採用 AI Credits 用量計費,詳見第 17 章) 查證紀錄:所有更正、已執行的驗證與尚待確認的項目,集中記錄於附錄 H 如何使用本手冊 本手冊的目標不是「列出所有功能」,而是讓讀者學會正確使用 Copilot CLI,並有能力審查 AI 產出的結果。因此每一章都遵循相同結構: 區塊 內容 讀者要做的事 本章目標 讀完後應具備的能力 讀完後自我檢核 概念與原理 功能是什麼、為什麼這樣設計、限制在哪裡 理解,而不是背指令 操作範例 可直接複製的指令、設定檔與腳本(皆已在本機驗證,見附錄 H.3) 動手做一次 ❌/✅ 對照 常見的錯誤寫法與正確寫法 用來審查 AI 或同事的產出 本章審查與驗證清單 AI 產出項目、錯誤示範、正確做法、人工如何驗證 落地成團隊的 Review Checklist 💡 給審查者的提示:本手冊中的設定檔(hooks、MCP、custom agent、skill、settings)都可以用第 21 章提供的 check_config.py 檢查;所有 copilot 旗標與 slash 指令都可以用 check_flags.py 對照本機版本確認是否存在。 ...

May 29, 2026 · 95 min · 20162 words · Eric Cheng