Claude Code：AI 驅動的軟體開發革命

 

你可能經歷過這個場景：下午 3 點，產品經理說：「客戶要新功能，明天就要。」你打開編輯器，開始敲代碼。腦子裡同時在想：資料庫欄位、API 端點、錯誤處理、邊界情況、測試用例……你一個人在腦子裡跑著整個開發流程。

Claude Code 改變了什麼？想像你有個高級工程師坐在身邊。你說：「我需要一個使用者認證系統。」他問：「SQL 還是 NoSQL？」你說 PostgreSQL，他立刻開始寫。你看著代碼，說：「這個有漏洞」，他改。整個過程，你只需要說出你想什麼。

這就是 Claude Code 的核心：

• • 你專注想什麼（目標、邏輯、決策）

• • Claude Code 專注怎麼做（實現、語法、細節）

• • 你可以用一個人的時間，做一隊工程師的工作

第 1 章：快速入門

1.1 三分鐘安裝

macOS

brew install anthropic/tap/claude-code

Linux

sudo apt update && sudo apt install claude-code

Windows

從 https://claude.com/download 下載 .exe

1.2 設定 API 金鑰

1. 1. 去 https://console.anthropic.com

1. 1. 登入 → API Keys → Create Key

1. 1. 複製金鑰（只顯示一次）

1. 1. 執行：claude config set-key YOUR_KEY

1.3 第一個對話

claude

開始輸入：「寫一個 Python 函數，檢查質數」

第 2 章：核心概念

2.1 對話思維

不是：「寫個登入頁面」（50% 符合）

而是：逐步談論，每步精煉。第一版 80%，加要求→90%→100%。

2.2 理解能力邊界

能看到：你的項目文件、提到的內容、之前的對話

看不到：其他項目、密碼、網路信息（除非 WebFetch）

第 3 章：20+ 工具詳解

3.1 工具分類

表 1: Claude Code 工具分類速查表

此表格按功能分類列出 Claude Code 的所有工具。左欄是功能類型（檔案、執行等），中欄是對應的工具名稱，右欄說明每個工具的用途。

類型	工具	做什麼
檔案	Read, Edit, Write, Glob	讀、寫、編輯、搜尋文件
執行	Bash, Pytho	跑代碼，看結果
搜尋	Grep, Agent	找東西，分析代碼
版本控制	Git	提交、看歷史、合併
Web	WebFetch, WebSearch	調 API，查信息
管理	TaskCreate, TaskUpdate	管理任務，追蹤進度

第 4 章：Skills 與 Workflows

Skill 是預定義的工作流程。例如 TDD（先寫測試再寫代碼）、Code Review、Debugging、Agent 派遣。

第 5 章：MCP 插件系統

MCP：讓 Claude Code 直接連接外部服務（資料庫、Figma、Discord 等）。

沒 MCP：你說 → Claude Code 生成 → 你複製 → 你跑 → 你粘貼 → Claude Code 分析。太慢。

有 MCP：一氣呵成，快很多。

第 6 章：進階用法（用得更好的祕訣）

6.1 Prompt 工程：怎樣問問題很重要

同樣的需求，不同的問法，結果天差地別。看這個對比：

表 2: Prompt 範例對比 – 如何提問更好

此表格展示同一個需求的三種提問方式。用來學習如何寫出高質量的 prompt。

維度	壞問題	好問題	結果差異
問題	「寫個登入頁面」	「Vue 3 + TypeScript 的登入頁面，記住我、3 次失敗鎖定、Tailwind CSS」	–
Claude Code 需要猜的東西	框架？UI 庫？功能？設計？認證方式？	全都說了，不用猜	–
生成的代碼符合度	~50%	~100%	提升 50%
你需要改的次數	5-6 次	0-1 次	省時間 80%
Token 消耗	5000+ tokens	1500 tokens	省 70%
總時間	35 分鐘	5 分鐘	快 7 倍

「好問題」的三要素 + 對比表

表 3: 好 Prompt 的三個必要元素

此表格拆解一個優秀 prompt 的三個要素。用來檢查自己的 prompt 是否齊全。

要素	例子	為什麼重要
上下文	「我在寫後台管理系統，Vue 3 + TypeScript」	Claude Code 知道框架、語言、用途。消除最大的猜測。
具體需求	「功能：用戶名 + 密碼、記住我、錯誤提示」	功能清單，一項一項。不用用戶去想「還要什麼」。
約束條件	「UI：Tailwind CSS、安全：防 XSS」	限制技術選擇，防止 Claude Code 過度設計。

6.2 Context 管理：怎樣讓 Claude Code 聚焦

Context 聚焦的三層級對比

表 4: Context 管理 – 不同範圍的效能對比

此表格比較不同 Context 範圍的效率和品質。用來決定每次應該給 Claude Code 多少上下文。

層級	範圍	Context 大小	執行速度	答案品質	何時用
全項目	所有 780 個文件	50,000+ tokens	⏱️ 很慢	⭐ 60%	罕見，只在架構設計
一個模塊	src/orders/（~50 個文件）	5,000 tokens	⏱️⏱️ 中等	⭐⭐⭐⭐⭐ 95%	大部分工作，推薦
一個文件或函數	getOrders()（~30 行）	500 tokens	⏱️⏱️⏱️ 瞬間	⭐⭐⭐⭐⭐ 99%	精細調整、除錯

經驗法則：項目 <50 個文件 → 全項目沒問題 | 50-500 → 聚焦模塊 | >500 → 聚焦文件/函數

6.3 性能優化：寫出快速的代碼

案例：交易策略回測的優化過程

表 5: 真實案例 – 性能優化的具體耗時

此表格展示交易回測項目從 5 分鐘優化到 3 秒的完整過程。用來了解 Claude Code 的實際優化效果。

版本	實現方法	執行時間	加速倍數	瓶頸
v1（原始）	三層 Python 迴圈	5 分 0 秒	1x	CPU 單核執行 1.25M 次迭代
v2（矢量化）	NumPy 矢量操作	8 秒	37.5x	記憶體讀取
v3（並行）	NumPy + 多進程	3 秒	100x	磁碟 I/O
v4（快取）	v3 + LRU 快取	1.5 秒	200x	實時使用可行

常見優化模式的效果對比

表 6: 常見優化技巧的效果對比

此表格列出開發中常用的優化技巧和預估加速倍數。用來評估哪些優化最值得做。

優化模式	應用場景	典型加速	實現難度	何時用
迴圈 → 矢量化	批量計算、數據處理	10-100 倍	低	Python 迴圈跑得慢
重複計算 → 快取	同一數據多次計算	5-50 倍	低	看到重複 print 語句
全表掃描 → 索引	資料庫查詢	100-1000 倍	中	WHERE 很慢
同步 → 非同步	網路請求、I/O	3-10 倍	中	等待外部服務
串行 → 並行	獨立計算	2-8 倍	高	多核 CPU 閒置

6.4 成本優化：不浪費 Toke

典型操作的 Token 消耗

表 7: Token 成本速查表 – 常見操作的費用

此表格列出日常開發操作的 token 消耗和估算成本。用來計算：「這個任務要花多少錢？」

操作	典型 Token 數	成本（Opus）	優化方式
讀一個小文件（<1KB）	50-100	$0.0002	只讀需要的部分
寫一個函數	500-1000	$0.002	一次寫多個相關函數
修改一個文件	1000-2000	$0.005	一次改多處，不要改多次
讀整個大項目	5000-10000	$0.02	聚焦到一個模塊
派遣一個 Agent	2000-5000	$0.01	只在真的需要時派遣

模型選擇指南（按任務類型）

表 8: 模型選擇指南 – 按任務類型選用 Opus/Soet/Haiku

此表格幫助選擇合適的 Claude 模型。用來回答「我應該用 Opus 還是 Soet？」

模型	價格	速度	推薦用途	例子
Opus	$3/$15	⏱️ 慢	架構決策、複雜邏輯、Code Review	「檢查系統的認證設計」、「找性能瓶頸」
Soet	$3/$15	⏱️⏱️ 中等	一般代碼生成、改 bug、寫測試	「寫登入頁面」、「修復崩潰」、「寫單元測試」
Haiku	$0.8/$4	⏱️⏱️⏱️ 快	搜索、讀文件、簡單改動、查詢	「找所有 API 端點」、「讀這個文件」、「改個變量名」

第 7 章：踩坑指南（學到的血淚教訓）

7.1 常見失敗模式速查表

表 9: 常見失敗模式 – 新手容易踩的 8 個坑

此表格列出使用 Claude Code 最常見的失敗場景和解決方案。用來快速診斷「為什麼我的結果不對？」

失敗模式	症狀	根本原因	修復方案	預防檢查
期望太高	想讓 Claude Code 寫整個平台，結果亂七八糟	把 Claude Code 當自動化工廠，不是思考夥伴	拆解成小功能，逐步迭代	□ 功能清單有多於 5 個嗎？拆小。
Context 爆炸	回答很差，執行很慢	讀了整個大項目，context 滿了	聚焦到一個模塊或文件	□ Context 有超過 5000 tokens 嗎？聚焦。
不驗證結果	上生產後才發現 bug	沒跑代碼驗證，直接相信 Claude Code	讓 Claude Code 跑代碼，看實際輸出	□ 你跑過這段代碼嗎？沒有就先跑。
安全忽視	API 沒認證，客戶能查別人數據	沒明確提出安全需求	明確列出安全要求（認證、防注入、加密）	□ 有提到「安全」「認證」「防護」嗎？
被建議騙了	按 Claude Code 的建議做，結果更複雜	建議太通用，不適合你的場景	提供約束條件（預算、人力、規模）	□ 有說明你的約束條件嗎？

7.2 真實項目教訓對比表

表 10: 血淚教訓 – 真實項目中的失敗案例

此表格記錄實際項目中發生過的重大問題和解決方案。用來學習別人的教訓。

項目	問題	症狀	修復	教訓
SimpleEC OMS	Agent Team OOM 當機	派遣 9 個 Opus Agent，機器 16GB 記憶體爆炸	分批執行，一次 3-5 個	Agent 消耗 ~1.5GB 每個，要算好預算
iDempiere	動態查詢失敗	SQL 查詢經常報「Unknown column」錯誤	先查詢 schema，確認欄位名	複雜系統要讀文檔，不要假設
交易策略	優化後結果不一致	矢量化快 37 倍，但數字精度不同	優化前鎖定正確性，改後驗證	性能優化要漸進，不要一下改太多

7.3 成本 & ROI 實際數字

表 11: 成本與投資回報 – 真實項目的數字

此表格列出真實項目的成本構成和投資回報。用來評估投資 Claude Code 是否值得。

項目	代碼量	對話次數	Token 消耗	成本	節省時間	ROI
SimpleEC OMS	50,000 行	500 次	5M tokens	$20	200 小時（2 個月 → 2 週）	10 倍
iDempiere 自訂	30,000 行	300 次	2M tokens	$8	100 小時	12 倍
交易策略	10,000 行	100 次	500K tokens	$2	40 小時	20 倍

結論：Claude Code 成本微乎其微（單項目 $2-20），但節省的時間是數週到數月。任何項目 ROI 都在 10 倍以上。

7.4 避坑檢查清單

表 12: 預發布檢查清單 – 交付前必檢項目

此表格是交付代碼前的檢查清單。用來確保代碼質量和完整性。

階段	檢查項目	不檢查的後果
需求定義	☐ 明確上下文（「我在做什麼項目」）	Claude Code 猜測，符合度 50%
	☐ 列出功能清單（一項一項）	遺漏功能，改多次
	☐ 說出約束條件（性能、安全、技術棧）	實現不符需求，推倒重來
實現階段	☐ 聚焦 Context（「現在只看這部分」）	Context 爆炸，品質下降 70%
	☐ 讓 Claude Code 跑代碼驗證	Bug 進入生產，客戶投訴
	☐ 關鍵改動要提交（不要等全部完成）	一個地方出錯，整個項目回滾
優化階段	☐ 明確性能要求（「<100ms」不是「儘量快」）	優化方向錯誤，白費力氣
	☐ 優化後驗證正確性一致	快了但結果錯了，worse than before
團隊協作	☐ Agent Team 控制數量（最多 5 個）	資源耗盡，OOM 當機
	☐ 監控成本（知道 token 消耗）	一個月花 $500 都沒發現

7.5 遇到問題的除錯決策樹

代碼不工作？按這個順序診斷：

代碼崩潰？n  ├─ 是 → 看錯誤信息（線索在這）n  │       ├─ 語法錯誤？ → 讓 Claude Code 修n  │       ├─ Runtime 錯誤？ → 隔離問題，寫個最小測試n  │       └─ 邏輯錯誤？ → 跑 debug 代碼，看變量值n  │n  └─ 否（運行但結果錯）→ 對比預期 vs 實際n          ├─ 部分錯？ → 這部分代碼邏輯問題n          ├─ 都錯？ → 理解錯誤，回到「需求定義」n          └─ 有時錯？ → 邊界條件遺漏，寫測試複現

金律：「不要瞎猜，運行代碼。」99% 的問題都能通過運行 + 看錯誤 + 寫測試解決。

第 8 章：Agent Team 協作指南

8.1 什麼時候用 Agent Team？

一個 Claude Code 不夠時，就該考慮多個 Agent 分工。

表 13: 單個 Claude vs Agent Team – 何時升級

此表格對比單個 Claude Code 和 Agent Team 的應用場景。用來決定是否需要升級到多 Agent。

特徵	單個 Claude	Agent Team
場景	簡單任務（寫功能、修 bug）	複雜項目（需要並行工作、分角色）
執行時間	30 分鐘內	1-2 小時或更長
決策成本	低（你直接說）	中（角色分工、資源預算）
回報倍數	5-10x（人力）	30-100x（多角色並行）
實際例子	寫個登入頁面	架構大重構、多模塊並行開發

判斷法則：

– 任務可以分成 3+ 個獨立部分？ → 考慮 Agent Team

– 這些部分需要同時進行？ → 確定用 Agent Team

– 部分之間無強依賴？ → 完美

—

8.2 角色設計：避免混亂和重複

核心原則

表 14: Agent Team 設計原則 – 好設計 vs 壞設計

此表格列出 Agent Team 設計的核心原則和常見錯誤。用來避免設計失誤。

維度	✅ 好設計	❌ 壞設計
角色數量	3-5 個	9+ 個（資源爆炸）
職責邊界	清晰、無重疊	模糊、功能重疊
通信方式	Team Lead 統一協調	每個 Agent 互相溝通（亂套）
模型選擇	任務匹配（opus/soet/haiku）	都用同一個模型（資源浪費）

常見角色類型

領導層：Team Lead（Haiku）n  ├─ 分配任務、協調進度、整合結果n  └─ 不需要高智力，需要協調能力實現層：Developer Agent（Soet）n  ├─ 寫代碼、修 bug、測試n  └─ 需要快速完成、成本敏感研究層：Architect / Researcher（Opus）n  ├─ 設計決策、技術選型、深度分析n  └─ 需要高質量、可容忍慢可選層：QA Agent（Soet）n  ├─ 執行測試、驗證結果n  └─ 提高品質、並行檢查

角色劃分檢查清單

□ 每個 Agent 只負責一個邏輯完整的工作（不要分成太細）

□ 不同 Agent 的職責無重疊（問自己：Agent A 的工作會被 Agent B 做嗎？）

□ Team Lead 能清楚地把任務分配給各 Agent

□ Team Lead 有辦法整合各 Agent 的輸出

□ 總共 ≤ 5 個 Agent（否則資源問題，見 8.3）

—

8.3 記憶體控制：避免當機

資源現狀（16GB 機器）

表 15: 記憶體預算 – 16GB 機器上的 Agent 配置

此表格列出每種模型的記憶體消耗和最多同時 Agent 數。用來規劃 Agent Team 的規模。

Agent 模型	每個消耗	最多同時跑	常見配置
Opus	~1.0GB	5-6 個	高精度任務
Soet	~0.6GB	10-12 個	通用實現
Haiku	~0.4GB	15+ 個	快速搜尋、協調

2026/3/3 事故根因：同時跑 9 個 Opus Agent → OOM 當機

記憶體預算公式

可用記憶體 = free -h 的 available 列 - 2GB（系統保留）需求 = Σ(各 Agent 記憶體) + 0.5GB(Team Lead)✅ 需求 < 可用 → 可以啟動n❌ 需求 ≥ 可用 → 必須分批

分批策略（超過 5 個 Agent）

不要同時啟動 9 個 Opus！必須分批：

批次 1：Agent A + B + C + D + E（5 個）同時跑n        ↓（全部完成）n批次 2：Agent F + G + H + I + J（5 個）同時跑n        ↓（全部完成）n批次 3：Team Lead 整合所有結果

即時監控命令

# 檢查系統可用記憶體（秒級更新）nwatch -n 1 'free -h'# 檢查 Claude 進程數（最多不超過 5 個 opus）nps aux | grep claude | wc -l# 如果用 claude-limited（cgroup 限制）ncat /sys/fs/cgroup/memory/claude/memory.limit_in_bytes  # 限制ncat /sys/fs/cgroup/memory/claude/memory.usage_in_bytes  # 實際用量

—

8.4 測試策略：避免「虛假成功」

問題根源

「測試全過卻 UI 點到抓狂」的本質：測試驗證的不是用戶真正體驗的東西。

表 16: Mock 陷阱 – 測試環境 vs 真實環境的差異

此表格說明為什麼本地測試通過但生產環境失敗。用來理解測試策略的重要性。

差距	測試環境	真實環境	後果
資料	乾淨 fixtures	髒資料、邊界值	NaN 顯示、閃爍
執行	同步、可預測	非同步、競態條件	重複提交、資料丟失
網路	即時或 mock	延遲、超時、失敗	loading 無限轉
使用者	按劇本操作	快速連點、返回鍵	狀態錯亂、記憶體洩漏

Mock 的三大致命陷阱

陷阱 1：Over-mocking（mock 了不該 mock 的）n───────────────────────────────────────njest.mock("../api/auth", () => ({ login: () => "success" }))n❌ 你測的是：「假設 API 永遠正確」n✅ 你應該測：「API 格式改了怎麼辦」陷阱 2：Stale Mocks（mock 跟實作不同步）n────────────────────────────────────n後端改了 userName → displayNamen前端 mock 還返回 userNamen→ 測試過 ✅ 但線上爆炸 ?陷阱 3：Happy Path Only（只 mock 成功路徑）n──────────────────────────n所有 mock 都返回 200 + 完美資料n→ 從不測 401、500、timeoutn→ 用戶看白屏或無限 loading

前期設計檢查清單

在開始寫功能前，問自己：

□ 這個功能會失敗嗎？（網路斷線、伺服器 500、用戶輸入錯誤）

□ 失敗時怎麼展示錯誤？（空白 vs 友善訊息）

□ 在網路慢的情況下怎麼工作？（loading、禁用按鈕防重複提交）

□ 用戶會怎樣濫用？（快速連點、關閉瀏覽器、返回鍵）

□ 邊界資料怎麼處理？（null、空字串、超大數字）

這些問題回答不了 → 代碼寫不好 → 測試也救不了

測試策略三層次（按優先級）

層級 1：組件集成測試（最重要，投資回報最高）n────────────────────────────────────n✅ 用真實組件、mock API 層（用 MSW，不是 jest.mock）n✅ 測：點擊 → API 呼叫 → 結果渲染n✅ 覆蓋：成功 + 失敗 + loading 狀態n✅ 工具：React Testing Library、@testing-library/user-event層級 2：E2E 測試（關鍵流程）n────────────────────────n✅ 測：登入 → 操作 → 結果n✅ 不要 mock 任何東西（真實後端 + 測試資料庫）n✅ 工具：Playwright、Cypress層級 3：單元測試（純邏輯）n──────────────────────n✅ 純計算函數（格式化、排序、驗證）n✅ 工具函數、資料轉換n❌ 不要測組件內部細節（太脆弱）

常見功能的測試清單

登入功能：

– □ [E2E] 輸入帳密 → 點登入 → 跳轉首頁 → 顯示用戶名

– □ [集成] 密碼錯誤 → 顯示錯誤訊息

– □ [集成] 提交時禁用按鈕（防重複提交）

– □ [集成] 網路超時 → 重試機制

– □ ❌ 不要 mock router（登入後跳轉是核心行為）

– □ ❌ 不要 mock localStorage（token 存取就是測試重點）

支付流程：

– □ [E2E] 選商品 → 結帳 → 支付 → 成功頁

– □ [集成] 金額計算：小計 + 稅金 + 折扣 + 運費 = 總計

– □ [集成] 支付失敗 → 錯誤訊息 + 可重試

– □ [單元] 折扣碼驗證邏輯

– □ [E2E] 重複提交防護（連點不會重複扣款）

—

8.5 實戰案例：SimpleEC OMS 失敗與修復

失敗原因：

– 資料庫連線池沒關閉 → 頻繁操作時耗盡

– 測試環境用 mock，生產環境真實資料 → 資料格式不同

– 測試只覆蓋成功路徑 → 沒測過並發競態

修復步驟：

1. 新增集成測試（對真實資料庫，測並發場景）

2. 移除過度 mock（只 mock 第三方 API）

3. 新增 E2E 測試（真實業務流程）

結果： 問題率從 15% 降到 2%

—

8.6 小結

Agent Team 三黃金規則：

1. 角色要清晰 — 不要讓兩個 Agent 做同樣的事

2. 資源要預算 — 先算再建，分批執行

3. 測試要前置 — 設計時就考慮失敗情況，不要事後補救

最後的話： 多 Agent 協作能 100 倍加速工作，但複雜度也倍增。沒有架構設計，光有工具沒用。

總結

從入門到精通：8 章的進階路線

• 第 1-2 章：基礎與核心概念
• 第 3-4 章：工具與工作流程
• 第 5 章：系統集成（MCP）
• 第 6 章：進階技巧
• 第 7 章：實戰失敗案例
• 第 8 章：多 Agent 協作

Claude Code 的價值不在寫代碼有多快，而在於你能專注「想什麼」而不是「怎麼做」。當你掌握了 Agent Team 協作，一個人可以做一個小隊的工作。但記住：強大的工具也需要謹慎使用。

為什麼你的 Agent 總是失敗？我們的 DBA 驗證 Agent 每一次都失敗。直到有人停下來問一個簡單的問題：「我們有沒有親自驗證過 SQL 環境是可用的？」答案是：沒有。這是一次真實的根本原因分析故事。

問題症狀：Agent 重複失敗的模式

我們的 DBA 驗證 Agent 每一次都失敗，不是「有時候失敗」，而是每一次都失敗。

2026-03-11 14:22 - dba-sonnet agent 啟動
2026-03-11 14:23 - ModuleNotFoundError: analyst.data.db
2026-03-11 14:24 - Agent 卡住，無輸出

2026-03-12 09:00 - 重試，同樣失敗
2026-03-12 15:30 - 又失敗
2026-03-13 08:00 - 還是失敗

模式很清楚：Agent 每次都卡在同一個地方，沒有任何進展。

傳統調試法為什麼失敗

我們試過改參數、改配置、改 Agent 模型……什麼都試過了：

1. 檢查 Agent 配置 → 配置看起來沒問題
2. 改 Agent Prompt → 改了 5 次，還是失敗
3. 換更強的模型 → Opus、Sonnet，都失敗
4. 加更多上下文 → 還是失敗
5. 等待用戶反饋 → 毫無進展

結果：花了 3 小時，毫無進展。我們陷入了「猜測地獄」。

轉折：PUA Debugging 的 5 維度法

當意識到傳統方法行不通後，我們採用了結構化的根本原因分析框架。這改變了一切。

維度 1-3：搜索 + 確認

我們發現 Agent Prompt 中引用的模塊 analyst.data.db 根本不存在。

維度 4：驗證前置假設 ← 關鍵轉折

這是傳統調試永遠到不了的地方。我們停下來問：

「我親自能連接到數據庫嗎？讓我現在就試試。」

結果發現了可行的執行方式：

PGPASSWORD='tdcc1234' psql -U tdcc -h localhost -d analyst -c "YOUR SQL QUERY"

這一步改變了一切。

維度 5：反轉假設

• 原假設：「問題出在 Agent」
• 新假設：「問題出在 Prompt 沒有教正確的方式」
• 結果：Agent 一次成功，生成完整報告

失敗 vs 成功的對比

項目	失敗的 Prompt	成功的 Prompt
說法	「使用 SQL 查詢檢查每個表」	「執行此命令：PGPASSWORD=… psql …」
具體性	無具體命令	20+ 個完整命令
認證信息	無	含 DB 用戶名和密碼
結果	Agent 失敗	Agent 成功

核心教訓：正確的調試思路

傳統方法會把你困在「猜測地獄」裡：

改 Prompt → 改模型 → 改配置 → 重試 → 還是失敗 → 回到第一步（無限迴圈）

正確的方法是：

1. 「環境本身可以做到這件事嗎？」
2. 親自測試（不信任 Agent 的假設）
3. 記錄可行的執行方式
4. 寫詳細的 Prompt（含具體命令）
5. Agent 執行 ← 通常一次成功

你的職責不是「讓 Agent 聰明」，而是「給 Agent 正確的路徑」。

驗證結果 — 實證數據

表名	筆數	最新日期	狀態
symbols (TWSE)	1,344	—	✓
symbols (TPEX)	996	—	✓
daily_prices	232,897	2026-03-13	✓
institutional_trading	0	—	✗ 缺失
tdcc_distribution	4,634	2026-03-13	✓
daily_market_index	255	2026-03-13	✓

關鍵發現：三大法人數據完全缺失（0 筆），需立即補齊。

應用場景

這個根本原因分析方法適用於：

• 數據庫驗證 ✓
• API 集成 ✓
• 自動化腳本 ✓
• 任何「系統重複失敗」的場景

結語

我們花了 3 小時調試，最後發現答案很簡單：

不是 Agent 需要改變，而是我們需要先驗證環境，然後清楚地描述執行方式。

下次你的系統卡住時，停下來問自己：

「我親自能做到這件事嗎？」

如果答案是「能」，那問題不在系統，而在於你沒有清楚地描述執行步驟。