分類: AI 職場超神助手

由於一場災難(詳見: 我的AI寫程式慘痛經驗)，我閱讀了這一篇論文，在此整理成一篇文章來做分享

The Impact of AI-Generated Solutions on Software Architecture and Productivity: Results from a Survey Study

AI 開發的雙面刃—機遇與挑戰並存

根據 Stack Overflow 2024 年的調查數據，超過 76% 的開發者正在使用或計劃使用 AI 工具，這明確揭示了 AI 技術在軟體工程領域已成為不可逆轉的主流趨勢。然而，這股浪潮也帶來了一個核心議題：AI 工具在顯著提升開發效率、縮短交付週期的同時，是否會以犧牲軟體品質為代價？對於追求長期價值的軟體架構師與工程師而言，這是一個必須審慎思考的問題。若未經深思熟慮地整合 AI 生成的程式碼，可能對系統的可維護性、可擴展性與整體架構穩健性構成潛在的長期風險。

如何在生產力與品質之間取得精準的平衡，是成為高效率 AI 時代工程師的第一步。接下來，我們將首先深入探討 AI 工具所帶來的具體生產力效益。

以數字來分析 AI 工具的實際影響

調查結果顯示，AI 工具對生產力的提升效果極其顯著。約 45% 的受訪者回報了「高於」或「遠高於」35% 的生產力提升，而若包含回報「約 35%」提升的群體，則總數高達 79%。

這項數據強烈暗示，AI 工具已成為提升開發效能的關鍵槓桿。在當前的技術環境下，不採用 AI 工具的工程師或團隊，可能面臨因生產力落差而導致的競爭力下降風險。值得注意的是，所有資歷少於三年的初階工程師都表示 AI 工具提升了他們的生產力，這暗示 AI 在弭平經驗差距上可能扮演著重要角色。

剖析效益最顯著的開發階段

AI 工具的效益在專案的早期階段最為突出，例如快速生成應用程式骨架 (skeleton code) 或樣板程式碼 (boilerplate)。這些任務通常重複性高且模式固定，恰好是 AI 發揮效率優勢的最佳場域。

工程師最常使用 AI 處理的任務以降序排列如下：

• 生成小型程式碼片段 (38 位參與者)
• 修改現有程式碼 (26 位參與者)
• 修復錯誤 (19 位參與者)
• 生成測試 (17 位參與者)

除了直接的編碼任務，AI 在多種輔助性工作中也展現出巨大的價值，這些「隱藏」的生產力增益同樣不容忽視：

• 加速技術研究：快速總結前沿研究論文，幫助團隊更快地將新技術應用於實踐。
• 優化資訊檢索：在內部設計文件或龐大的知識庫中快速查找資訊，遠比傳統搜尋更高效。
• 輔助創意發想：作為一個技術顧問進行頭腦風暴，探索解決方案的可能性。
• 簡化學習曲線：提供特定函式庫的實現範例，比直接閱讀官方文件更為快捷。

架構師的兩難：駕馭 AI 對程式碼品質的影響

軟體開發的成功不僅取決於開發速度，更仰賴於長期的架構穩健性與可維護性。一個看似高效的工具，若其產出會侵蝕系統的架構品質，那麼短期的生產力提升將會被長期的維護災難所抵銷。

其根本原因在於 AI 缺乏對系統全局上下文（global context）的理解，導致其在生成大型模組時無法做出符合整體架構的設計決策，從而破壞了內聚性與模組邊界。

除了結構品質外，功能正確性是另一個關鍵考量。調查數據顯示，AI 並非萬無一失。超過 65% 的參與者指出，AI 生成的程式碼很少能在第一次嘗試時就完全滿足功能需求。開發者通常需要透過反覆調整提示詞 (prompt) 才能獲得期望的結果，這也意味著對 AI 產出的盲目信任是極其危險的。

綜上所述，AI 對程式碼品質的影響呈現出明顯的兩面性，其關鍵分野在於「問題的規模」。這直接引導出下一章節將要介紹的核心策略——如何透過有效的問題拆解來趨利避害。

黃金法則：戰略性問題拆解是成功的關鍵

架構師的核心方法論：「拆解-委派-整合」循環

最大化 AI 生產力同時規避品質風險的最有效方法是採納一種系統性的工作流程：將一個大型、複雜的問題，戰略性地拆解成一系列小型、定義明確的子問題（拆解），再交由 AI 逐一實現（委派），最後由工程師負責審查、測試與智慧地組裝這些成果（整合）。

為了最大限度地提高生產力，工程師的技能（特別是架構技能）仍然很重要

• 拆解問題為最佳方式： 絕大多數受訪者同意，使用 AI 工具提高生產力的最佳方式是將問題分解成小塊，然後要求 AI 進行實作。
• 針對性提問： 針對小型、集中的問題尋求 AI 協助，可以最大限度地提高生產力。提問的技巧 (Prompting skill) 是提高生產力的關鍵驅動因素。

分析問題拆解的具體效益

• 提升結果品質：小型、範圍明確的提示詞能讓 AI 更準確地理解開發者的意圖，從而生成更高品質、更易於整合的程式碼。這避免了因問題描述模糊或複雜而導致的「猜測式」輸出。
• 降低風險：在大型、既有的程式庫中進行修改時，風險控管至關重要。超過 67% 的受訪者認為，程式碼規模越大，AI 越容易破壞現有功能。將修改任務拆解成針對小範圍的精準操作，可以顯著降低引入新錯誤的風險。
• 提高效率：40% 的受訪者觀察到，隨著輸入程式碼規模的增大，AI 的處理時間會顯著增加。將大問題拆解成小任務，可以讓 AI 快速響應，避免因等待 AI 處理而中斷開發心流，從而維持流程的順暢。

重新定義工程師的角色

在 AI 時代，軟體工程師的價值並未減少，而是發生了深刻的轉變。因此，工程師的價值核心必須從「程式碼的生產者」轉變為「複雜問題的分解者」與「高品質方案的整合者」。這意味著，軟體架構設計、系統性思維與判斷力等高階技能，變得前所未有的重要。

擁抱人機協作，成為 AI 增強型工程師

AI 工具是強大的生產力倍增器，能夠為工程師帶來超過 35% 的顯著效率提升，但它絕非能夠取代工程師專業判斷的「銀彈」。其核心局限性在於：

• 缺乏高層次理解力：AI 難以掌握複雜問題的整體脈絡與高層次的系統架構。
• 修改效率瓶頸：在大型、複雜的程式庫中進行修改和除錯時，其效率和可靠性通常不如經驗豐富的人類工程師。
• 測試可靠性不足：AI 生成的測試往往較為表面，可能缺乏對邊界條件和核心業務邏輯的深入驗證。

面對 AI 的優勢與局限，軟體工程師成功的關鍵在於「揚長避短」，建立一種高效的人機協作模式。

提高效率的應用場景（揚長）

• 早期實作與樣板代碼 (Early Implementation & Boilerplate)：利用 AI 在專案初期生成骨架程式 (skeleton code)、基本功能或樣板代碼。
• 研究與概念性工作 (Research & Conceptual Work)：讓 AI 快速總結最新研究、整理設計文件、搜尋公司內部資源。也可用來集思廣益，或查詢特定函式庫的使用範例，減少查文件的時間。
• 輔助與支援任務 (Support Tasks)：AI 可生成小型程式碼片段，或幫忙產生測試案例（但要注意 AI 測試常流於表面，缺乏邊界案例覆蓋）。

工程師必須採取一些緩解措施，避免引入新的技術債（避短）

• 預期並管理迭代 (Expect Rework)：AI 很少一次就能產出正確解法，通常需要 2–3 輪提示調整。
• 人工合成與架構整合 (Human Synthesis & Integration)：工程師必須將 AI 生成的片段整合到一個結構良好的系統裡，不能盲目照單全收。
• 預留整合時間 (Allocate Manual Integration Time)：常見手動工作包括：調整命名、修改函式簽名、適應既有模組介面，確保與現有代碼的一致性。

將 AI 用於其擅長的、範圍明確的任務（如生成程式碼片段、樣板代碼、輔助文檔查詢、腦力激盪），並將人類的智慧和經驗聚焦於 AI 的弱項（如系統架構設計、複雜問題拆解、關鍵模組整合與嚴謹的程式碼審查）。

Anthropic 選擇 打造 CLI 而非 IDE Plugin，其背後原因包括：

• 使用者偏好多樣性：CLI 可跨 VSCode、JetBrains、Vim、Emacs、終端機
• AI 模型主導決策流程：未來開發流程將由 AI 針對上下文自動驅動，IDE 的 GUI 操作權重會降低
• CLI 可自動串接 CI/CD / bash / SDK 工具，易於組成 AI-driven pipeline

鍵盤操作快捷指令

Claude Code 的 CLI 介面不只是輸入文字而已，它提供一整套鍵盤操作邏輯、bash 整合與 SDK 工具，讓你不需切換視窗，就能完成從 prompt 到自動化處理的流程。

建議在日常開發時養成 # 標記習慣，例如：
# 我們的 staging deploy 用的是 deploy-stg.sh，不要混用 prod
Claude 會將這段筆記納入後續 decision making 參考。

Bash 模式 × CLI 操作整合

直接在 CLI 輸入 !npm run lint，Claude 會：

• 執行指令
• 把 stdout 結果顯示在對話中
• 根據結果提供後續建議（例如修正 lint 錯誤）

支援 CLAUDE.md 中事先宣告的別名指令，例如：

## Custom Commands
!test-api: curl http://localhost:3000/test

Claude Code SDK的應用

• 傳入 prompt 並指定使用工具（如 bash, format, test）
• 輸出結果為 JSON、Markdown、或純文字
• 指定存取的 context 限制，控制 Claude 的「記憶範圍」

Claude Code SDK 支援的功能與整合應用：

多重 Session 操作

熟練使用者往往會搭配下列方式開啟多個 Claude session，以強化平行工作效率：

• 在 SSH session 中同時開啟 Quad CLI
• 使用 tmux / byobu / screen 分割畫面，一邊進行 API 實作，一邊讓 Claude 處理測試或 log 分析
• 每個 session 可以有不同的 prompt log 與 context，互不干擾

Bash 指令安全

Claude 能執行 bash 指令（如 !rm -rf），但若沒安全機制，可能造成災難性後果。設好安全機制與允許清單，讓 Claude 可以自動處理例行指令又不會誤殺系統

• 分層許可制度（Tiered Permission）：
  • 預設只允許「只讀類」指令（如 cat, ls, git status）
  • 寫入類或系統操作指令，需經過人工確認或提前白名單設定
• 靜態分析與模式識別：
  • Claude 會對複合指令進行分析，例如 curl + | bash，視為高風險行為自動暫停

也可以透過 Cloude.md 定義哪些指令允許自動執行、哪些需要人工審核。

多模態輸入支援

Claude CLI 不只能處理文字 prompt，還支援：

• 拖曳圖片 進 CLI，做 OCR 或 UI 檢查
• 貼上路徑（如：/tmp/screenshot.png），Claude 會載入該檔案進行處理
• 檔案上傳分析，如 log 檔、test output、build summary 等

例如:

• 拖進 error.png → Claude 判斷是 layout shift bug
• 拖進 test-results.json → Claude 根據失敗測試自動找錯

與Github連結

gh 是 GitHub CLI 工具，用於在命令列中與 GitHub 互動。

winget install --id GitHub.cli --accept-source-agreements

接著就是認證GitHub CLI，打開瀏覽器至：https://github.com/login/device

輸入代碼完成認證

GitHub CLI常用指令：

• gh repo clone – 複製倉庫
• gh pr create – 建立 Pull Request
• gh pr list – 列出 PR
• gh issue create – 建立 Issue
• gh auth login – 登入 GitHub 需要先安裝並認證才能使用。

使用Github CLI請Claude幫忙修Issue

接著就可以透過Github CLI請Claude自動幫忙修BUG了!

建立 ~/.claude/commands/fix-github-issue.md 這個檔案，內容就是你想讓 Claude Code 幫你「自動處理 GitHub Issue」的完整流程。這個檔案就像是你寫給 Claude 的任務腳本，它會當作「自定義指令」使用。

以下為一個範例內容

# Fix GitHub Issue

## 目標
修復 GitHub 上指定 issue 的 bug，並提交一個 Pull Request。

## 步驟

1. 使用 `gh issue view {input}` 指令讀取 Issue 編號為 `{input}` 的描述內容。
2. 分析問題並找出最可能相關的程式碼區段與檔案。
3. 編寫修正該 bug 的程式碼（請先顯示變更建議讓我確認）。
4. 編寫對應的測試案例來覆蓋此次修正。
5. 若我確認沒問題，請進行 commit，訊息為 `fix: resolve issue #{input}`。
6. 提交 PR，標題為 `Fix for issue #{input}`，描述為修正內容與測試方式。

只要你寫好後，在 Claude 裡輸入：

/project:fix-github-issue 1234

它就會根據那個 markdown 檔案的內容，自動幫你處理 Issue #1234。

功能介紹

Framelink Figma MCP 伺服器是一個專為 AI 程式碼工具（例如 Cursor）設計的橋接工具，它讓您的代理（agent）能夠直接存取 Figma 設計檔案，並將其轉譯為程式碼。這比單純貼上螢幕截圖等方式更準確、更高效。

透過 MCP（Model Context Protocol）伺服器，Cursor 能從 Figma 取得簡化後的設計元數據，例如版面配置與樣式，並生成對應的程式碼。這不僅大幅提升 AI 模型的準確度，也提升了回應的關聯性與品質。

• 一次性完成設計實作：可直接在任意框架中生成可用 UI 元件。
• 無需手動轉譯設計：省去工程師對設計稿「讀圖寫碼」的時間。
• 多語言支援：支援 English、韓文、日文、簡體中文等語系。
• MIT 授權：自由使用與修改。
• 社群支援：可加入 Discord 討論、追蹤 Twitter。

設定及安裝

步驟一：取得 Figma 存取權杖（Access Token）

在開始使用 MCP 前，您需要先產生一組 Figma API 權杖：

1. 開啟 Figma 首頁，點選左上角個人頭像，選擇「Settings」。
2. 點選「Security」分頁。
3. 捲動到「Personal access tokens」區塊，點選「Generate new token」。
4. 為此權杖命名，並確保您啟用「File content」與「Dev resources」的讀取權限。
5. 點選「Generate token」，將出現的 token 儲存下來。

詳細教學可參考 Figma Access Token 說明

步驟二：在 IDE 中加入 Framelink Figma MCP 設定

大多數現代 IDE 都支援以 JSON 格式設定 MCP 伺服器。以下提供適用於 macOS/Linux 與 Windows 的設定範例：

macOS / Linux

{
  "mcpServers": {
    "Framelink Figma MCP": {
      "command": "npx",
      "args": [
        "-y",
        "figma-developer-mcp",
        "--figma-api-key=YOUR-KEY",
        "--stdio"
      ]
    }
  }
}

Windows

{
  "mcpServers": {
    "Framelink Figma MCP": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "figma-developer-mcp",
        "--figma-api-key=YOUR-KEY",
        "--stdio"
      ]
    }
  }
}

記得將 "YOUR-KEY" 替換為您剛才產生的 Figma API token。

步驟三：實作您的第一個設計

複製 Figma 框架或群組的連結

由於 Figma 設計檔案的資料量龐大，MCP 伺服器會自動壓縮資料，減少約 90%。即便如此，建議您一次實作「一個區塊」，確保輸出品質最佳。

在 Figma 中：

1. 右鍵點選您要實作的 Frame 或 Group。
2. 選擇「Copy/Paste as → Copy link to selection」。

在 IDE 中貼上連結並發送請求

將上述連結貼到 IDE 的對話介面中（如 Cursor 的 Agent 模式），輸入簡單請求：

實作這個 Figma frame。

系統會呼叫 MCP 的 get_figma_data 函式，取得設計資料並自動產出對應的程式碼。

補充上下文說明（如：使用目的、期望技術堆疊等）有助於提升輸出品質。

最佳實踐指南

雖然 MCP 伺服器能大幅簡化從設計到程式碼的轉換流程，但 Figma 的檔案結構與命名方式仍會直接影響 AI 的理解效果。

請遵循以下設計原則：

• 使用 Auto Layout（自動排版）：
  MCP 尚未完全支援浮動（floating）或絕對定位（absolute positioning）元素，使用 Auto Layout 可讓排版更清楚易讀。
• 為 Frame 與 Group 命名：
  有意義的命名可幫助 AI 建立語意上的對應，避免出現一堆 div-123 或 group-456 的結構。
• 專業小技巧：
  Figma 內建 AI 命名工具可快速為元件自動命名，請善加利用！

在編輯器中的操作技巧

即使 MCP 幫你處理了設計資料的轉換，你仍需提供足夠的上下文，才能讓 AI 模型生成最符合需求的程式碼。

編輯器端的提示最佳化方式：

• 說明你在使用什麼技術堆疊：
  讓 AI 知道是否要使用 Tailwind CSS、React、Vue 等。
• 引用程式碼中的關鍵檔案：
  例如：「請依照 Button.tsx 的風格來實作這個 UI」，有助於維持一致性。
• 除了貼 Figma 連結，也加上文字描述：
  描述這個區塊的功能、使用者互動方式、期望行為等，可提升準確性。
• 管理上下文大小：
  與其貼整份 Figma 檔案，建議只貼 Frame 或 Group 的連結，避免 AI 過載無關資訊。

應用建議總結

Claude Code MCP 允許你依據用途與共享需求，將伺服器設定在不同範圍（scope）中，分為：

• Local（本地）
• Project（專案）
• User（用戶）

這三種範圍有明確的優先順序與用途，可靈活應對個人實驗、團隊共享、跨專案使用等情境。

Local Scope（本地範圍）

• 儲存位置：專案內使用者本機設定
• 權限：僅限你自己使用，不會被版本控制
• 適合：個人實驗伺服器、敏感金鑰（如 API key）、測試中的功能

claude mcp add my-private-server /path/to/server
# 或指定為 local
claude mcp add my-private-server -s local /path/to/server

Project Scope（專案範圍）

• 儲存位置：.mcp.json 檔案，放在專案根目錄
• 權限：團隊共享，可加入版本控制
• 適合：團隊共用伺服器、CI 工具、共用資料庫

claude mcp add shared-server -s project /path/to/server

.mcp.json 標準格式如下：

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

出於安全考量，Claude Code 啟用 .mcp.json 內容前會要求你手動批准
（重設批准選項用：claude mcp reset-project-choices）

User Scope（用戶範圍）

• 儲存位置：用戶本機設定檔（跨專案有效）
• 權限：只有你自己能用，但所有專案都能存取
• 適合：你常用的工具伺服器、通用開發服務

claude mcp add my-user-server -s user /path/to/server

其他規則

當多個範圍定義了同名伺服器，系統會依下列順序選擇：

1. Local 本地（最高優先）
2. Project 專案
3. User 用戶（最低優先）

這表示你可以用 local 設定暫時覆蓋 project/user 設定，不怕被共享配置干擾。

可以在 .mcp.json 中使用以下格式插入環境變數：

適用位置包含：

• command：可執行檔路徑
• args：執行參數
• env：環境變數本身
• url：遠端伺服器網址
• headers：身份驗證 token 等

{
  "mcpServers": {
    "api-server": {
      "type": "sse",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

若未設 API_KEY 也沒指定 default，Claude Code 啟動時會報錯。

遠端伺服器身份驗證（OAuth 支援）

若你連接的 MCP Server 需要 OAuth 驗證，例如 GitHub API：

新增伺服器

claude mcp add --transport sse github-server https://api.github.com/mcp

使用 /mcp 指令開啟互動選單，完成登入驗證

/mcp

瀏覽器會跳出 OAuth 流程，完成授權後即可連線

• Token 會安全儲存並自動刷新
• 也可手動用 /mcp 清除驗證

PostgreSQL MCP 伺服器連線

若你想讓 Claude 幫你查詢資料庫結構，可這樣啟用：

claude mcp add postgres-server /path/to/postgres-mcp-server \
  --connection-string "postgresql://user:pass@localhost:5432/mydb"

然後直接對 Claude 下指令：

> describe the schema of our users table
> what are the most recent orders?

Claude 會進行唯讀存取，幫你檢查欄位、關聯、資料內容，非常適合熟悉新專案資料庫。

參考實作伺服器

這些是官方驗證過、最值得嘗試的範例：

• Filesystem：安全操作檔案，支援讀寫控制
• Fetch：從網頁擷取內容並轉成 LLM 可讀格式
• Memory：提供持久記憶能力（知識圖譜）
• Sequential Thinking：讓模型用步驟式思考解題

適合在 coding 流程中使用的:

• Git -用於讀取、搜索和作 Git 儲存庫的工具
• GitHub – 倉庫管理、檔作和 GitHub API 集成
• GitLab – GitLab API 集成，支持專案管理
• Sentry – 從 Sentry.io 中檢索和分析問題

瀏覽器自動化

• Brave Search – 使用 Brave 的搜索 API 進行 Web 和本地搜索
• Puppeteer – 瀏覽器自動化和網頁抓取功能

更多官方推薦的MCP列表

https://github.com/modelcontextprotocol/servers?tab=readme-ov-file#%EF%B8%8F-official-integrations

安裝開發工具uv

# WinGet（Windows）
winget install astral-sh.uv
# Homebrew（macOS）
brew install uv
#PyPI
pip install uv

初始化MCP SERVER

這邊有很多不同語言的MCP範例：https://github.com/modelcontextprotocol

• specification – 協議規範和文檔
• typescript-sdk – TypeScript 實現
• python-sdk – Python 實現
• java-sdk – Java 實現
• kotlin-sdk – Kotlin 實現
• csharp-sdk – C# 實現
• docs – 使用者文件和指南

這邊為python實現的一個簡單範例

uv venv --python cpython-3.11.13-windows-x86_64-none
.\.venv\Scripts\activate
uv pip install "mcp[cli]"

設定main.py的內容如下

"""
FastMCP quickstart example.

cd to the `examples/snippets/clients` directory and run:
    uv run server fastmcp_quickstart stdio
"""

from mcp.server.fastmcp import FastMCP

# Create an MCP server
mcp = FastMCP("Demo")


# Add an addition tool
@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b


# Add a dynamic greeting resource
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Get a personalized greeting"""
    return f"Hello, {name}!"


# Add a prompt
@mcp.prompt()
def greet_user(name: str, style: str = "friendly") -> str:
    """Generate a greeting prompt"""
    styles = {
        "friendly": "Please write a warm, friendly greeting",
        "formal": "Please write a formal, professional greeting",
        "casual": "Please write a casual, relaxed greeting",
    }

    return f"{styles.get(style, styles['friendly'])} for someone named {name}."
    
if __name__ == "__main__":
    mcp.run(transport="stdio")

啟動MCP

uv run main.py

如何測試MCP？用 MCP Inspector！

npx -y @modelcontextprotocol/inspector@latest

在Transport Type選擇STDIO，然後command輸入uv run server.py

就可以從Resource、Prompts、Tools去測試剛剛設定的MCP了

將自己撰寫的工具加到Claude Code

claude mcp add my-mcp-server uv run main.py
claude mcp list

出現以下字樣代表成功

Checking MCP server health...

firecrawl-mcp: cmd /c npx -y firecrawl-mcp - ✓ Connected
my-mcp-server: uv run main.py - ✓ Connected

MCP 為什麼重要

現有的 LLM 模型像 GPT-4 或 Claude 雖然很強，但常見限制包括：

• 無法即時查資料（知識截止）
• 無法串接你用的工具（ERP、CI/CD）
• 整合要自己 hardcode，沒標準

MCP 正是為了解決這些問題：

MCP 架構核心概念

MCP 架構中有三個主要角色：

支援兩種通訊協定：

• stdio：用於本地執行程式
• http + SSE：用於網路 API、第三方系統

精選 MCP Server 實例

配置 MCP 伺服器

添加 MCP stdio 伺服器

# Basic syntax
claude mcp add <name> <command> [args...]

# Example: Adding a local server
claude mcp add my-server -e API_KEY=123 -- /path/to/server arg1 arg2
# This creates: command="/path/to/server", args=["arg1", "arg2"]

添加 MCP SSE 伺服器

# Basic syntax
claude mcp add --transport sse <name> <url>

# Example: Adding an SSE server
claude mcp add --transport sse sse-server https://example.com/sse-endpoint

# Example: Adding an SSE server with custom headers
claude mcp add --transport sse api-server https://api.example.com/mcp --header "X-API-Key: your-key"

添加 MCP HTTP 伺服器

# Basic syntax
claude mcp add --transport http <name> <url>

# Example: Adding a streamable HTTP server
claude mcp add --transport http http-server https://example.com/mcp

# Example: Adding an HTTP server with authentication header
claude mcp add --transport http secure-server https://api.example.com/mcp --header "Authorization: Bearer your-token"

管理您的 MCP 伺服器

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get my-server

# Remove a server
claude mcp remove my-server

在Claude Code新增Firecrawl的功能

在本機 Windows（非 WSL）上，使用 npx 的本地 MCP 伺服器需要 cmd /c 包裝器來確保正確執行。

https://github.com/mendableai/firecrawl-mcp-server

安裝方式

1. 到https://www.firecrawl.dev/app/api-keys申請API KEY

2. 設定環境變數FIRECRAWL_API_KEY，值為剛剛申請的API KEY

3. 安裝firecrawl-mcp

npm install -g firecrawl-mcp

4. 設定MCP

claude mcp add firecrawl-mcp -- cmd /c npx -y firecrawl-mcp

5. 確認有連接上

claude mcp list

出現Connected代表成功連接

接著就可以打開Claude Code使用firecrawl來抓取網頁了!

Claude Code + GitHub Actions的功能

• 立即產生 PR、補 bug 或實作功能：只要在 issue 或 PR 留言 @claude implement ...，Claude 就會自動完成工作，並提交 PR 。
• 自動代碼審查：PR 中問一句 @claude review code level，由 AI 幫忙分析與修正錯誤。
• 符合既有專案標準：Claude 會自動參考專案裡的 CLAUDE.md 內容，比照程式風格與工程規範
• 簡易設定，立刻上手：可以透過 CLI /install-github-app 快速部署，也可手動安裝 workflow。

GitHub Actions安裝步驟

claude
/install-github-app

接著輸入要連接的repository，這邊我選擇我的開源專案:

https://github.com/cochiachang/walkassure

接著在Github設定Claude的API Key

如何使用

在專案內增加.github/workflows/claude.yml

請參考https://github.com/cochiachang/walkassure/tree/main/.github/workflows

name: Claude AI Workflow

on:
  issues:
    types: [opened, edited, labeled]
  issue_comment:
    types: [created]

jobs:
  claude-analysis:
      runs-on: ubuntu-latest
      if: contains(github.event.issue.body, '@claude') || contains(github.event.comment.body, '@claude')

      steps:
        - name: Checkout code
          uses: actions/checkout@v4

        - name: Claude AI 回應
          uses: anthropics/claude-code-action@beta
          with:
            anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

        - name: Claude AI 呼叫成功通知
          if: always()
          run: echo "✅ Claude 回應觸發成功！"
  notify:
    runs-on: ubuntu-latest
    needs: [claude-analysis]
    if: always()
    
    steps:
    - name: Send notification
      run: |
        echo "Workflow completed"
        echo "Claude analysis status: ${{ needs.claude-analysis.result }}"
        echo "Build and test status: ${{ needs.build-and-test.result }}"

範例的issue

https://github.com/cochiachang/walkassure/issues/1

接著就可以看到claude已經回應了一個修正

記憶檔案的種類與設計理念

Claude Code 支援三種級別的記憶檔案：

撰寫優質記憶內容

打造有用記憶內容的重點是結構化、具體、長久適用：

• 專案架構與圖表：在 ./CLAUDE.md 中簡述專案目標、邏輯分層、資料流程與常用第三方服務。
• 開發規範：team 常用的測試、commit message 格式、branch 流程也能記錄進去。
• 典型指令集：例如 @scripts/test.sh 或 @README 提醒可快速引用。
• 個人偏好：例如你喜歡 using tabs 還是 spaces、有沒有自動補 commit message 的習慣，都可放在 ~/.claude/CLAUDE.md。

這樣的記憶會幫助 Claude 在解釋、編碼和 refactor 中，更貼合你團隊與個人的風格。

在Claude.md中匯入其他檔案

CLAUDE.md 檔案可以使用 @path/to/import 語法匯入其他檔案。下列範例匯入 3 個檔案：

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

允許相對和絕對路徑，匯入的檔案可以遞迴匯入其他檔案，最大深度為 5。您可以通過運行 /memory 命令查看加載了哪些內存文件。

# Individual Preferences
- @~/.claude/my-project-instructions.md

**Tek 陣列式命名（如 # 命令清單）讓記憶更易讀、維護性高。

以下為一個簡單範例

Tek 陣列式命名（如 # 命令清單）讓記憶更易讀、維護性高。

CLAUDE.md

# 專案指南

## 專案概述

這是一個使用 `create-next-app` 建立的 **Next.js 15** 應用程式，採用現代的 React 19、TypeScript、Tailwind CSS 和 App Router 架構。

## 架構與結構

### 目錄結構
```
claudecode/
└── my-next-app/          # 主要 Next.js 應用程式
    ├── src/
    │   └── app/          # App Router 目錄 (Next.js 13+ 模式)
    │       ├── globals.css
    │       ├── layout.tsx    # 根佈局組件
    │       ├── page.tsx      # 首頁組件
    │       └── favicon.ico
    ├── public/           # 靜態資源 (SVG 圖標)
    ├── package.json      # 依賴項和腳本
    ├── next.config.ts    # Next.js 配置
    ├── tailwind.config.ts # Tailwind CSS 配置
    ├── tsconfig.json     # TypeScript 配置
    ├── eslint.config.mjs # ESLint 配置
    ├── postcss.config.mjs # PostCSS 配置
    └── .gitignore
```

## 技術堆棧

### 核心技術
- **Next.js 15.4.3** - 帶有 App Router 的 React 框架
- **React 19.1.0** - 最新版 React 與改進功能
- **TypeScript 5.8.3** - 類型安全和現代 JavaScript 功能
- **Tailwind CSS 4.1.11** - 實用優先的 CSS 框架
- **ESLint** - 帶有 Next.js 和 TypeScript 規則的代碼檢查

### 主要特性
- **App Router** - 使用 Next.js 13+ App Router 模式 (`src/app/` 目錄)
- **字體優化** - Geist 字體 (Sans & Mono) 與 next/font
- **深色主題支援** - 使用 CSS 變數和 prefers-color-scheme
- **TypeScript 路徑** - 配置 `@/*` 別名指向 `src/*`
- **Turbopack** - 開發環境啟用 (`--turbopack` 標誌)

## 開發工作流程

### 可用腳本
```bash
npm run dev    # 使用 Turbopack 啟動開發伺服器
npm run build  # 生產環境建置
npm run start  # 啟動生產伺服器
npm run lint   # 運行 ESLint
```

### 開發伺服器
- 預設端口: `http://localhost:3000`
- 使用 Turbopack 實現熱重載，加快開發速度
- 主要入口點: `src/app/page.tsx`

## 配置詳情

### TypeScript 配置
- 目標: ES2017
- 啟用嚴格模式
- 路徑映射: `@/*` → `./src/*`
- 包含 Next.js 外掛

### Tailwind 配置
- 實用優先的 CSS 框架
- 自定義顏色變數 (background, foreground)
- 為所有相關文件類型配置內容路徑
- 透過 CSS 變數支援深色主題

### ESLint 配置
- Next.js 核心 web vitals 規則
- TypeScript 支援
- 扁平配置格式 (ESLint 9+)

## 樣式方法

### CSS 架構
- **全域樣式**: `src/app/globals.css`
- **Tailwind**: 帶有自定義 CSS 變數的實用優先方法
- **深色主題**: 透過 `prefers-color-scheme` 自動檢測
- **字體**: Geist Sans 和 Geist Mono 與 CSS 變數

### 顏色系統
```css
:root {
  --background: #ffffff;  /* 亮色主題 */
  --foreground: #171717;
}

@media (prefers-color-scheme: dark) {
  :root {
    --background: #0a0a0a;  /* 深色主題 */
    --foreground: #ededed;
  }
}
```

## 主要開發模式

### 組件結構
- **函數組件** 與 TypeScript
- **伺服器組件** 預設 (App Router)
- **CSS-in-JS**: 帶有條件樣式的 Tailwind 類別
- **圖片優化**: 使用 `next/image` 組件

### 文件命名慣例
- 組件: `PascalCase.tsx`
- 頁面: `page.tsx` (App Router 慣例)
- 佈局: `layout.tsx` (App Router 慣例)
- 樣式: `kebab-case.css`

## Claude Code 最佳實踐

### 在此專案上工作時:

1. **遵循 App Router 模式**
   - 使用 `src/app/` 目錄結構
   - 遵循 Next.js 13+ 慣例
   - 為路由建立 `page.tsx`，為佈局建立 `layout.tsx`

2. **TypeScript 優先**
   - 新文件始終使用 TypeScript
   - 利用配置的路徑別名 (`@/`)
   - 維護嚴格的類型檢查

3. **樣式指南**
   - 主要使用 Tailwind 實用程式
   - 尊重主題的 CSS 變數系統
   - 維護深色主題相容性

4. **效能考慮**
   - 使用 `next/image` 處理圖片
   - 盡可能利用伺服器組件
   - 遵循 Next.js 優化模式

5. **開發命令**
   - 使用 `npm run dev` 進行開發 (包含 Turbopack)
   - 提交前運行 `npm run lint`
   - 使用 `npm run build` 測試生產建置

6. **Git 提交流程**
   - 每次執行 `git commit` 後，必須執行 `ntfy publish claire-topic "git commit: {commit message}"`
   - AI 應動態使用該次 commit 的實際訊息內容，而非固定文字 {commit message}
   - 這將發送提交通知到指定的 ntfy 主題

## 常見任務

### 新增頁面
在適當的 `src/app/` 子目錄中建立 `page.tsx` 文件，遵循 App Router 慣例。

### 新增組件
將可重用組件放在 `src/components/` (需要時建立此目錄) 並使用 `@/` 路徑別名。

### 樣式更新
修改 `src/app/globals.css` 以更改全域樣式，或在組件中使用 Tailwind 實用程式。

### 配置更改
- Next.js: `next.config.ts`
- TypeScript: `tsconfig.json`
- Tailwind: `tailwind.config.ts`
- ESLint: `eslint.config.mjs`

## 注意事項

- 這是一個最小自定義的全新 Next.js 專案
- 使用最新的 React 19 和 Next.js 15 功能
- 配置用於 TypeScript 和 Tailwind 的現代開發
- 準備部署到 Vercel 或其他平台
- 目前不存在額外的文檔或規則文件

## 部署

此專案配置為可在 Vercel 上輕鬆部署，但也可以部署到任何支援 Next.js 應用程式的平台。

認識Claude Code Hooks

https://docs.anthropic.com/en/docs/claude-code/hooks-guide

https://docs.anthropic.com/en/docs/claude-code/hooks

Claude Code Hooks 是什麼？

Hooks 是你在 Claude Code 不同階段，可以自訂執行的 shell 命令或腳本，會在特定事件觸發時自動執行。它可以讓你建立穩定而非隨機的行為，不必透過提示讓 Claude 記得執行特定動作，適合作業自動化、格式化、權限控管等用途

支援的觸發事件

Claude Code 提供以下幾種 hook 事件：

• PreToolUse：在 Claude 使用工具前觸發，可控制是否要阻擋或允許
• PostToolUse：工具使用後觸發，適合執行後續處理
• Notification：Claude 發出通知（如等待回應）時觸發
• UserPromptSubmit：使用者送出 prompt 時觸發
• Stop：主要互動結束時觸發（非中斷行為）
• SubagentStop：子任務完成後觸發

如何設定

在專案資料夾底下的 .claude/settings.toml 或 .claude/settings.json 加上 hook 配置。例如：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"No description\")\"' >> ./.claude/bash-command-log.txt"
          }
        ]
      }
    ]
  }
}

安裝jq

以下是常見的 jq 安裝指令，也可以直接請Claude Code幫忙安裝jq：

Windows:

# 使用 Scoop
scoop install jq

# 使用 Chocolatey
choco install jq

# 使用 winget
winget install jqlang.jq

macOS:

# 使用 Homebrew
brew install jq

# 使用 MacPorts
sudo port install jq

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install jq

Linux (CentOS/RHEL):
sudo yum install jq
# 或
sudo dnf install jq

Linux (Arch):
sudo pacman -S jq

使用結果

這樣就可以有一個文字檔紀錄過去Claude Code曾做過的事情囉