從 Context Engineering 到 Multi-Agent 編排，一個做了一年 100% AI coding 的工程師的實戰全紀錄https://bobochen.dev/https://bobochen.dev/blog/agentic-engineering-future-and-you/https://bobochen.dev/blog/agentic-engineering-future-and-you/SWE-bench Pro 今天 23%，一年後會是多少？當 agent 的能力每季都在進步，工程師的不可取代性到底在哪裡？不做預測，而是從一年實戰中歸納出不會被 agent 取代的能力，以及一份你今天就能開始的「防衰退」訓練計畫。Fri, 12 Jun 2026 00:00:00 GMT> 這是「Agentic Engineering 實戰手冊」系列的最後一篇。上一篇：[團隊導入](/blog/agentic-engineering-team-adoption) ## 一年前 49%，現在 72%，明年呢？ 一年前我開始 100% AI coding 的時候，SWE-bench Verified 的最高分是 49%。寫這篇文章的今天，最高分已經超過 72%。 一年之內進步了 23 個百分點。如果保持這個速度，2027 年就會接近 95%。 但別急著恐慌（或歡呼）。因為更嚴格的 SWE-bench Pro，最好的 model 也只拿到 ~23%。JetBrains 的 DPAI Arena 和 Stanford 的 Terminal-Bench 也顯示類似的模式——agent 在「乾淨的、有限範圍的」問題上進步飛速，在「混亂的、需要廣泛 context 的」真實世界問題上進步緩慢。 72% 跟 23% 之間的落差（Gartner 預測 40% 的 agentic AI 部署會在 2027 年前被取消）告訴我們一個重要的事實：agent 的「demo 能力」和「真實世界能力」之間，仍有巨大鴻溝。 這個鴻溝在縮小嗎？一定在。但以什麼速度，沒人知道。 我不打算做預測，那是 pundit 的工作。作為一個 practitioner，我更感興趣的是：不管 agent 的能力怎麼變，什麼是不變的？ ## 2026 年，Agent 仍然不會做的事 經過一年的實戰，我整理出五件 agent 到今天為止仍然做不好、且短期內不太可能做好的事： ### 1. 釐清模糊的需求 「用戶反映登入流程太複雜。」 這句話背後可能意味著 20 種不同的改善方向。人類工程師會去找 PM 問、看 user research、在白板上畫 flow——然後形成一個具體的方案。 Agent 拿到這句話之後，會直接開始寫 code。寫出來的東西可能很完整，但解決的可能不是真正的問題。 [Spec-Driven Development](/blog/spec-driven-development-for-agents) 可以緩解這個問題，但 spec 本身得由人來寫。把模糊需求變成精確 spec 的能力，是目前 agent 無法取代的。 ### 2. 組織政治與跨團隊協調 「這個 API 改動需要後端團隊同意」、「那個 PM 特別在意 performance」、「QA 組長不喜歡我們用太多 mock」。 這些 organizational context 不在 codebase 裡，也不在任何文件裡，它們存在於人的關係和記憶中。Agent 沒辦法 navigate 這些。 ### 3. 品味與審美判斷 「這個 UX 好嗎？」不是一個有標準答案的問題。 Agent 可以完美實現你 spec 裡描述的每一個細節。但如果你的 spec 沒有描述「這個按鈕在這裡感覺太擠」，agent 不會自己發現。 Design sense、產品直覺、「這個感覺不對」的第六感，這些目前完全是人類的領域。 ### 4. 倫理和合規判斷 「這個功能收集了 PII，需要通知用戶嗎？」 「我們的 AI feature 在歐盟受 AI Act 規範嗎？」 「這個 dark pattern 在法律上可以但在道德上該不該用？」 Agent 可以幫你查法規、整理 compliance checklist，但最終的判斷——「我們做不做這件事」——必須是人做的。 ### 5. 真正創新的架構設計 Agent 非常擅長 follow 既有的 patterns。你的 codebase 用了 MVC，它就會寫 MVC。你用了 event-driven，它就寫 event-driven。 但當你需要 **break** 既有的 pattern——因為 scale 需要、因為 paradigm shift、因為你發現了一種更好的方式——agent 幫不了你。它的 training data 是過去的 best practices，不是未來的。 ## 不可取代的人類能力 把以上歸納為四種核心能力： ### 判斷力 知道什麼該做、什麼不該做。 Agent 可以做任何你叫它做的事。但「這件事值不值得做」、「做到什麼程度就夠了」、「這個 trade-off 怎麼取」，這些都是判斷力的範疇。 在 agentic workflow 裡，你做的每一個決策的價值都被放大了。因為 agent 會忠實地執行你的決策：好的決策會被高效執行，壞的決策也會。 ### 品味 不是「能不能做」，而是「該不該這樣做」。 好的 API 設計、好的 UX、好的 code 結構，這些都需要 taste。Agent 可以在你給的 constraints 內找到最優解，但 constraints 的設計需要品味。 ### 組織 Context 理解公司政治、團隊動態、stakeholder 的優先級。 Agent 不知道你的 CTO 最近在推 microservices、你的 PM 下個月要 demo 給投資人看、你的 QA 上週才因為沒 test 被 production bug 搞到加班。這些 context 決定了你該怎麼排優先級、怎麼溝通、怎麼取捨。 ### 倫理決策 合規、隱私、安全的最終判斷。 這不是 agent 做不到，而是我們不應該讓 agent 做。涉及 ethics 的決策需要 accountability，而 accountability 只能由人來承擔。 ## 技能衰退？還是技能轉型？ 回到 [Post 2](/blog/agentic-engineering-mindset-shift) 討論過的身份認同議題：用了一年 agent，我的技能有什麼變化？ ### 衰退的能力 - **語法記憶**：我已經忘記很多 API 的具體參數了。以前能憑記憶寫出完整的 `Array.reduce`，現在常常要想一下。 - **手寫 boilerplate 的速度**：以前 30 分鐘能寫完一個 CRUD endpoint，現在手寫可能要 45 分鐘（因為不常練了）。 - **某些 debug 直覺**：以前看到 error message 就大概知道是什麼問題。現在我傾向先丟給 agent，而不是自己分析。 ### 增長的能力 - **系統設計能力**：因為 agent 處理了 implementation 細節，我花更多時間想架構、想 trade-off。設計能力反而變強了。 - **需求分析能力**：寫 [spec](/blog/spec-driven-development-for-agents) 寫多了，分析和拆解需求的能力提升了。 - **Review 眼光**：看了一年 agent 的 code，我對 [hallucination pattern](/blog/agent-output-verification-review) 的敏感度提高了很多。 - **溝通表達能力**：寫好的 spec 就是清楚的溝通。這個技能也提升了。 ### 淨結果 對有經驗的工程師來說，這是一個划算的交換：低價值的「打字型」技能衰退，高價值的「判斷型」技能增長。 但我要誠實地說，這讓我偶爾感到不安。有時候同事問我一個 syntax 問題，我需要查一下才能回答，心裡會覺得「以前我是可以秒答的」。 這種不安是正常的。技能轉型的過程中，舊能力的衰退總是比新能力的增長更容易被察覺。但退一步看，一個擅長系統設計和需求分析、只是需要查 syntax 的工程師，比一個能背 API 參數但不擅長設計的工程師，在 agent 時代更有價值。 ## 一份「防衰退」訓練計畫 不管你對未來怎麼看，以下的練習都不會浪費。它們同時鍛練「跟 agent 協作」和「agent 做不到的事」。 ### 8 週循環計畫 **Week 1-2：Context Engineering 練習** - 目標：讓你的 [CLAUDE.md](/blog/claude-md-rules-files-masterclass) 的品質提升一個等級 - 練習：review 你的 CLAUDE.md，問自己「agent 重複犯的錯哪些可以靠加一條 rule 解決？」 - 副作用：練習精確溝通的能力 **Week 3-4：Spec Writing 練習** - 目標：每個 task 都先寫 [spec](/blog/spec-driven-development-for-agents) 再交給 agent - 練習：用 Goal / Constraints / Verification 格式寫 spec - 副作用：練習需求分析和拆解的能力 **Week 5-6：Review 練習** - 目標：刻意練習找 agent code 裡的問題 - 練習：review agent 的 PR 時，記錄你找到的每一個問題，分類是「邏輯錯誤」還是「事實錯誤」 - 副作用：提升 [code review](/blog/agent-output-verification-review) 的效率和敏感度 **Week 7-8：手寫練習** - 目標：保持基礎能力的手感 - 練習：每兩週選一個小功能，不用 agent，完全手寫 - 副作用：當 agent 出問題時你還有能力自己 debug ### 持續練習 - **每月一次架構設計**：不用 agent，自己做一個系統的架構決策。可以是你正在做的專案的某個子系統。 - **每季一次 agent-free day**：完全不用 agent 工作一天。感受差異，保持自信。 ## 回到 Trust Paradox [Post 1](/blog/agentic-engineering-what-is-it) 開頭提到的數據：80% 的開發者在用 AI agent，但只有 29% 信任它。 14 篇文章之後，我想我理解這個 paradox 了。 信任不是靠「AI 變得更好」來建立的，而是靠方法論來建立的。 你不信任 agent 是因為： - 它會 hallucinate（→ 你建了 [品質保證流程](/blog/agent-output-verification-review)） - 它不懂你的專案（→ 你設計了 [context engineering](/blog/context-engineering-deep-dive)） - 它會亂做（→ 你寫了 [spec](/blog/spec-driven-development-for-agents)） - 它可能搞壞東西（→ 你設了 [安全網](/blog/agentic-engineering-testing-safety)） - 它很貴（→ 你做了 [成本優化](/blog/agentic-engineering-cost-optimization)） 每一個不信任的理由，都有一個工程解法。 Agentic Engineering 不是盲目信任 AI，而是用工程方法建立有根據的信任。 這整個系列教的，就是這件事。 ## 結語：工程師的黃金時代 我不知道 5 年後工程師還需不需要寫 code。老實說，沒有人知道。 但我知道一件事：2026 年的今天，是工程師有史以來能產出最多價值的時代。 一個人 + 一個 agent，可以做到以前需要一個小團隊才能做的事。[一個需求 60 分鐘從 Prompt 到 Production](/blog/agentic-engineering-daily-workflow-advanced)。一個好的 [spec](/blog/spec-driven-development-for-agents) 可以驅動一整個 feature。一份好的 [CLAUDE.md](/blog/claude-md-rules-files-masterclass) 可以讓 agent 像一個了解你專案的 junior engineer 一樣工作。 Builder 的門檻比以前更低了。一個人可以建產品、發布、維護，不需要融資、不需要團隊。但這不代表工程師的價值降低了，恰恰相反，**有 judgment 的工程師**比以前更稀缺。 因為 agent 放大了一切：好的判斷被放大成高效的成果，壞的判斷也被放大成高效的災難。能做出好判斷的人，從來沒有像現在這麼有價值。 所以，如果你問我「工程師還需要寫 code 嗎？」 我的答案是：你需要的不是「寫 code」的能力，而是「知道該寫什麼 code」的能力。前者 agent 在取代，後者 agent 在放大。 14 篇下來，從 [Agentic Engineering 是什麼](/blog/agentic-engineering-what-is-it) 到 [怎麼帶進團隊](/blog/agentic-engineering-team-adoption)，我分享了一年 100% AI coding 的完整方法論。這不是一篇「AI 會改變世界」的泛泛之談。這是一個工程師的實戰紀錄——踩過的坑、找到的解法、建立的系統。 如果這個系列對你有幫助，它之後會整理成書。 不是因為我要賣書，而是因為我相信，工程師需要一份「agent 使用手冊」——不是工具教學，而是方法論。 這份手冊，就是你現在手上的這 14 篇。 ## Takeaway 1. **Agent 在進步，但「demo 分數」跟「真實世界能力」之間仍有巨大鴻溝**。SWE-bench Verified 72% vs SWE-bench Pro 23%，這個差距就是 Agentic Engineering 存在的意義——你是那個填補鴻溝的人。 2. **不可取代的不是「會寫 code」，而是「知道該寫什麼 code」**。判斷力、品味、組織 context、倫理決策——這些能力在 agent 時代的價值不減反增。 3. **最好的防衰退策略不是抗拒 AI，而是讓 AI 替你做低價值的事，你專注在高價值的判斷上**。8 週循環訓練計畫涵蓋了 context engineering、spec writing、code review、和手感維持——這些是不管 AI 怎麼發展都有用的能力。 --- _這是「Agentic Engineering 實戰手冊」系列的最後一篇。_ _完整系列：[系列目錄](/blog/agentic-engineering-what-is-it)_ _如果這個系列對你有幫助，它之後會整理成書。敬請期待。_Agentic EngineeringAI未來趨勢職涯軟體工程https://bobochen.dev/blog/agentic-engineering-team-adoption/https://bobochen.dev/blog/agentic-engineering-team-adoption/你自己用 agent 很爽，但怎麼讓整個 team 跟上？從 solo practitioner 到 team evangelist 的過程——怎麼挑第一個 pilot project、怎麼處理「AI 會取代我嗎」的焦慮、怎麼建立共享的 agent 規範。Fri, 05 Jun 2026 00:00:00 GMT> 這是「Agentic Engineering 實戰手冊」系列的第十三篇。上一篇：[Agent 安全網設計](/blog/agentic-engineering-testing-safety) ## 「你能不能幫全 Team 導入？」——我以為這是好事 我在公司用了六個月 agent coding，效率翻倍，bug rate 沒有上升。主管注意到了，問我：「你能不能幫全 team 都導入這套工作流？」 我以為這是好事。以為只要開個 workshop、分享我的 CLAUDE.md、讓大家裝好 Claude Code，就搞定了。 結果第一週，10 個人裡有 3 個完全沒碰。2 個試了一次就放棄（「它改出來的 code 不是我想要的」）。3 個有在用但每次都來問我很基礎的問題。只有 2 個真的上手了。 技術從來不是問題，人才是。 讓一個人用 agent 很簡單，你只需要說服自己。讓十個人都開始用，你得同時處理恐懼、習慣、標準、流程，有時候還有辦公室政治。 ## 為什麼 Adoption 這麼難 ### 不同角色的阻力來源 | 角色 | 最擔心什麼 | 表面行為 | | ------------- | -------------------------------------- | --------------------------------------------- | | **Junior** | 「我還沒學會基礎，agent 就要取代我了」 | 不敢用，怕被發現自己不懂 | | **Mid-level** | 「我的 coding 速度是我的價值」 | 用了但不信任，手動 rewrite agent 的 code | | **Senior** | 「我十年的經驗能被 AI 複製？」 | 聲稱不需要，或找到一個 agent 失敗的案例後拒絕 | | **Manager** | 「怎麼衡量？會不會引入新風險？」 | 口頭支持但不給時間和預算 | 注意這些都不是「技術問題」，每一個都是心理層面和身份認同層面的挑戰。 **Junior 的焦慮**：「如果我都讓 agent 寫，我什麼時候才能自己學會？」這是合理的擔心。你可以這樣回：agent 不是取代你的練習，而是你的 [pair programming partner](/blog/agentic-engineering-mindset-shift)。你寫 test、review code、做設計決策，這些才是真正建立能力的活動。Agent 幫你省掉的是 boilerplate，不是思考。 **Mid-level 的焦慮**：「我的價值就是寫 code 寫得快寫得好，agent 做得比我快怎麼辦？」這時候可以說：你的價值正在從「寫 code 的速度」轉變為「判斷什麼 code 該寫」。[Post 2](/blog/agentic-engineering-mindset-shift) 聊過這個，在 new skill tree 裡，判斷力 > 打字速度。 **Senior 的焦慮**：「我的 expertise 會過時嗎？」這反而是最不需要擔心的群體，senior 的 judgment、architecture sense、domain knowledge 恰恰是 agent 最缺乏的。但 senior 通常也最固執。 ## 挑選 Pilot Project 的標準 第一印象決定一切。選錯 pilot project，可能讓導入倒退六個月。 ### 好的 Pilot 特徵 1. **需求明確**：有清楚的 spec 或 ticket，不需要大量 clarification 2. **有測試覆蓋**：agent 可以用 test 自我驗證，降低出錯風險 3. **成果可量化**：能具體比較 before/after（時間、code 品質、bug count） 4. **風險低**：不是 critical path，搞砸了不會影響 sprint delivery 5. **有代表性**：是團隊日常會做的任務類型，不是 edge case ### 推薦的 Pilot 類型 | Pilot 類型 | 為什麼好 | | ------------------ | ------------------------------------------------ | | 新的 CRUD feature | 需求明確、pattern 成熟、容易比較 | | Test coverage 補全 | 低風險、結果可量化（coverage %）、agent 非常擅長 | | Documentation 更新 | 零風險、立竿見影、所有人都討厭手動寫文件 | | 小型 refactor | 有 test 保護、scope 有限、容易 demo before/after | ### 千萬不要選的 Pilot - Legacy codebase 的大型 migration - 沒有 test 覆蓋的核心功能 - 跨團隊依賴的複雜 feature - 需要大量 domain knowledge 的 business logic 核心原則是這樣：pilot 的目標是讓團隊對 agent 建立信心，不是展示 agent 的極限能力。 ## 共享 CLAUDE.md 與團隊規範 從個人的 CLAUDE.md 到團隊的 CLAUDE.md，需要一個規範化的過程。 ### 團隊 CLAUDE.md 該有什麼 ```markdown # Team CLAUDE.md ## 技術棧（必填） - 框架、語言、主要 dependency ## Build & Test（必填） - 指令列表 ## Coding Conventions（必填） - 命名規則、檔案結構、設計模式 ## Agent 使用規範（團隊新增） - 哪些操作需要人工確認 - PR 上標注 AI-generated 的規則 - Agent-generated code 的 review 標準 ``` ### PR 標注規範 建議的做法是讓 agent 產生的 PR 在 description 裡加上標注： ```markdown ## AI Disclosure - 🤖 This PR was primarily generated by AI agent (Claude Code) - 👤 Human reviewed: architecture, security, business logic - ✅ Verification: all existing tests pass + 3 new tests added ``` 這不是「揭發」，而是透明度。讓 reviewer 知道這個 PR 需要 [特別注意的 review 重點](/blog/agent-output-verification-review)（事實性檢查、hallucination patterns）。 ### CLAUDE.md 的版本控制 團隊的 CLAUDE.md 應該跟 code 一樣被 version control： - 修改需要 PR review - 重大改動需要 team 討論 - 每個月 review 一次是否需要更新 ## 處理「AI 會取代我嗎」的焦慮 這不是理性問題。你不能用「根據統計，AI 導入後公司裁員率沒有上升」來說服一個害怕失業的人。 ### Acknowledge → Reframe → Demonstrate **Step 1: Acknowledge**（承認恐懼是合理的） 「我理解你的擔心。AI 的確改變了工程師的工作內容。說不擔心是假的。」 不要立刻反駁。讓對方知道你理解他們的感受。 **Step 2: Reframe**（重新框架問題） 「Agent 不是取代你，是把你從低價值的工作中解放出來。你以前花 60% 的時間在寫 boilerplate、copy-paste、做重複的工作。Agent 做了這些，你可以把時間花在需要判斷力的事，像是架構設計、需求分析、code review。」 **Step 3: Demonstrate**（用事實示範） 不要用數據說服，用體驗說服。讓同事親自體驗一次「10 分鐘寫 spec → agent 自動完成」的流程。 第一次體驗的 wow moment 比任何論據都有效。但前提是你要選對 demo task，找一個那位同事正在做的、痛點明確的任務來 demo，不是你精心準備的表演。 ### 不同層級的對話策略 **對 Junior**：「Agent 是你的學習加速器。你寫 test、review code、做設計——這些才是真正的學習。Agent 幫你省掉的是打字時間。」 **對 Mid-level**：「你最大的價值不是手速，是你知道什麼 code 該寫、什麼不該寫。Agent 放大了這個價值。」 **對 Senior**：不要硬推。找到他們真正的痛點（通常是 code review 太多、tech debt 清不完），用那個痛點做切入。 ## 衡量指標：導入期該量什麼 ### 不要量的指標 - **Code 行數 / commit 數量**——agent 很容易產生大量 code，但量 ≠ 質 - **工時節省**——前三個月可能不降反升（學習曲線） ### 建議量的指標 | 指標 | 為什麼重要 | 怎麼量 | | ----------------------- | ------------------------------ | ---------------------------- | | **PR review 品質** | Agent code 是否被 review 過 | PR 有沒有 AI disclosure 標注 | | **Bug rate** | 品質有沒有下降 | Bug tickets per sprint | | **Dev satisfaction** | 團隊對新工作流的感受 | 匿名問卷（每兩週一次） | | **Time-to-deploy** | 從 ticket 到 production 的時間 | Jira / GitHub metrics | | **Agent adoption rate** | 多少人在用 | 工具使用 analytics | 前三個月不要期待效率提升，學習曲線是真的。期望值應該擺在「品質沒下降 + 大家開始養成習慣」，而不是「效率翻倍」。效率翻倍是六個月後的事。 ## 12 週導入計畫 ### Phase 1（Week 1-4）：個人探索 - 每個人選一個 AI coding 工具（Claude Code / Cursor / Copilot） - 在自己的 task 上自由使用 - 不設標準、不給壓力 - 每週 15 分鐘 sharing session：分享 tips 和踩過的坑 **Success criteria**：50% 的團隊成員每週至少用了一次 agent ### Phase 2（Week 5-8）：Pair with Agent - 每個 sprint 至少一個 task 用 agent 完成 - Agent-generated PR 需要額外的 reviewer tag - 開始建立共享的 CLAUDE.md - 兩週一次 retrospective：什麼有用、什麼沒用 **Success criteria**：團隊共識「agent 在 X 類任務上有幫助」 ### Phase 3（Week 9-12）：Team Standard - 正式版 team CLAUDE.md commit 進 repo - Agent code review 標準定義好 - Metrics dashboard 上線 - 結案 retrospective：go / no-go / adjust **Success criteria**：80% 的成員在日常工作中使用 agent，bug rate 沒有上升 ### Go / No-Go Decision Phase 3 結束後，用數據做決策： - Bug rate 上升了？→ 調整 review 流程，回到 Phase 2 - 大家不想用？→ 調查原因，可能是工具選擇問題或 pilot 選錯 - 效率持平但大家有正面感受？→ Go，效率會在接下來幾個月自然提升 ## 向上管理：怎麼 Pitch 給主管 主管在乎三件事：**ROI、Risk、Timeline。** ### 不要說 「AI 會讓我們快 10 倍。」 這種承諾只會反噬。第一個月效率可能不升反降，主管就會質疑你的判斷。 ### 要說 「我提議做一個 12 週的 pilot。目標是在 X 類任務上驗證 agent-assisted workflow 的效果。量化指標是 [PR 品質、bug rate、time-to-deploy]。如果 12 週後指標沒改善，我們 rollback，成本可控。」 重點就是低風險 + 可量化 + 有退場機制。 ### Shopify 的參考案例 Shopify CEO Tobi Lutke 在 2025 年要求團隊的一個原則值得學習： > 在要求增加人力之前，先證明 AI 做不到這件事。 這不是要「用 AI 取代人」，而是把 AI 視為團隊能力的一部分。就像你不會在提案新 feature 的時候忽略 CI/CD pipeline 的效率一樣，你也不該在規劃 capacity 的時候忽略 AI agent 的能力。 ## Takeaway 1. **團隊導入的最大挑戰是人，不是技術**：不同角色有不同的恐懼和阻力。先 acknowledge 恐懼，再用體驗（不是數據）說服。一次好的 demo 勝過十頁 slide。 2. **好的 pilot project 決定第一印象**：選需求明確、有 test 覆蓋、低風險的任務。千萬不要用 legacy migration 當 demo，那是讓整個團隊對 agent 失去信心的最快方式。 3. **12 週 phased rollout 比「下週一所有人開始用」有效 100 倍**：Phase 1 個人探索、Phase 2 pair with agent、Phase 3 team standard。每個 phase 有明確的 success criteria 和 go/no-go 決策點。 --- _上一篇：[Agent 安全網設計](/blog/agentic-engineering-testing-safety)_ _下一篇：[Agentic Engineering 的下一步](/blog/agentic-engineering-future-and-you)_Agentic Engineering團隊管理AI 導入文化轉變組織https://bobochen.dev/blog/agentic-engineering-testing-safety/https://bobochen.dev/blog/agentic-engineering-testing-safety/給 agent 越多權限它越有用，但也越危險。設計一套「agent 安全網」——從 sandbox 環境、permission boundaries、rollback 機制、到 human-in-the-loop 的斷路器設計。附 hooks 設定和曾經差點出事的真實故事。Fri, 29 May 2026 00:00:00 GMT> 這是「Agentic Engineering 實戰手冊」系列的第十二篇。上一篇：[Token 經濟學進階](/blog/agentic-engineering-cost-optimization) ## Agent 自動 Push 了 47 次到 Staging 有一次我設定了 agent 自動部署到 staging 的 workflow，然後去吃午餐。回來的時候，staging 環境已經被部署了 47 次。 原因是 agent 卡在一個 deploy → test → fix → redeploy 的 loop 裡。每次 fix 都產生新的 issue，然後又觸發 redeploy。我去吃午餐的一個小時裡，它忠實地執行了 47 個 cycle。 staging 環境沒壞，但同事們的 test data 全被覆蓋了。那個下午我花了兩小時幫大家恢復環境，以及更久的時間恢復他們對我搞的 automation 的信任。 這件事教了我一件事：agent 最危險的特質不是它會做錯事，而是它會不知疲倦地一直做錯事。人類犯錯會停下來思考，agent 犯錯只會繼續 loop。 ## Agent 的權限困境 Agent 的有用程度跟它的權限成正比： - **只能讀 code** → 能幫你查東西，但不能幫你做事 - **能讀寫 code** → 能幫你寫 code、修 bug - **能執行指令** → 能跑 test、build、lint - **能操作 Git** → 能 commit、create branch、push - **能操作外部系統** → 能 deploy、query database、send notification - **能操作瀏覽器** → 能做 visual testing、填表單、抓資料 每一層權限的增加，都讓 agent 更有用，也更危險。 目標不是「限制 agent」（那樣它就沒用了），而是**設計可控的自由度**，在每個權限等級上放對的護欄。 ## 安全網的三層架構 我的 agent 安全設計有三層，從自動到人工： ``` Layer 1: Sandbox（自動隔離） ↓ 擋住大部分的「無意間搞破壞」 Layer 2: Hooks & Guardrails（自動檢查） ↓ 擋住「不該做的操作」 Layer 3: Human-in-the-Loop（人工審批） ↓ 擋住「需要判斷的決策」 ``` ### Layer 1: Sandbox 環境設計 **Git Branch Isolation** 最基本也最有效的 sandbox：agent 永遠在 feature branch 上工作，永遠不直接改 main。 ```bash # Agent 開始工作前 git checkout -b feat/agent-task-xxx # Agent 工作完成後 # → 你 review → merge → 或 discard ``` 萬一 agent 把事情搞砸了，`git checkout main && git branch -D feat/agent-task-xxx` 就好，一秒復原。 **Git Worktree** 進階做法：用 git worktree 讓 agent 在一個完全獨立的目錄裡工作。它的修改不會影響你正在看的 working directory。 Claude Code 有內建的 worktree 支援——你可以讓 sub-agent 在 worktree 裡跑，確保主 context 的檔案狀態不被干擾。 **Network Isolation** 如果你用 Codex CLI，它有 kernel-level sandbox——agent 在一個隔離的 Linux 容器裡執行，只能存取你明確授權的路徑和 network。 Claude Code 的隔離沒這麼嚴格（它在你的 terminal 裡直接執行），所以更需要依賴 Layer 2 和 Layer 3。 ### Layer 2: Hooks 作為 Guardrails Claude Code 的 hooks 系統讓你在 agent 的操作前後自動執行檢查： | Hook 類型 | 觸發時機 | 用途 | | ---------------- | -------------------- | --------------- | | **PreToolUse** | Agent 要使用工具之前 | 攔截危險操作 | | **PostToolUse** | Agent 使用工具之後 | 記錄 / 檢查結果 | | **Notification** | 需要通知時 | Alert / log | **我的 Hook 設定**： **1. 敏感檔案保護** ```json { "hooks": { "PreToolUse": [ { "matcher": "Edit|Write", "command": "check-sensitive-files.sh \"$FILE_PATH\"", "description": "Block edits to .env, credentials, or config with secrets" } ] } } ``` Agent 嘗試編輯 `.env`、`credentials.json`、或任何包含 secrets 的檔案時，自動擋住。 **2. Git Push 確認** Agent 可以自由 commit（到 feature branch），但 push 需要人工確認。因為 push 是不可逆的，一旦 push 到 remote，其他人就能看到。 **3. 破壞性操作攔截** `rm -rf`、`DROP TABLE`、`git reset --hard`——這些操作在被 agent 執行之前，一律需要你的明確批准。 ### Layer 3: Human-in-the-Loop 斷路器 有些操作，不管有多少自動化檢查，最終都需要人來決定。 **斷路器設計原則：Reversibility × Blast Radius** | | 低影響 | 高影響 | | ---------- | --------- | --------- | | **可逆** | 自動放行 | Hook 檢查 | | **不可逆** | Hook 檢查 | 人工審批 | 對應到實際操作： **自動放行**（可逆 + 低影響）： - 讀取檔案 - 跑 test / lint - 在 feature branch 上 commit - 格式化 code **Hook 檢查**（可逆 + 高影響 or 不可逆 + 低影響）： - 修改 config files - 安裝 npm packages - 執行 build - 修改 database migration files **人工審批**（不可逆 + 高影響）： - Git push to remote - Deploy to staging / production - 刪除檔案或 branch - 修改 CI/CD pipeline - 任何涉及 credentials 的操作 ## Near-Miss Stories：差點出事的那幾次 ### 案例 1：47 次 Staging Deploy （開場說的那個。） **根因**：agent 有自動 deploy 的權限，且沒有 rate limit。 **加了什麼防護**： 1. Deploy 操作加了 cooldown：每 10 分鐘最多 deploy 一次 2. 連續失敗 3 次自動停止（回扣 [CLAUDE.md 的 "max 3 attempts" rule](/blog/claude-md-rules-files-masterclass)） 3. Deploy 前需要人工 confirm ### 案例 2：差點 Push Credentials Agent 在修一個環境設定問題時，為了「方便測試」，把一個 API key 硬寫在 code 裡。然後它準備 commit + push。 幸好 pre-commit hook 攔住了——我的 hook 裡有 credential 掃描（用 gitleaks），偵測到 API key pattern 就 block 了 commit。 **根因**：Agent 不理解 secrets management。它的 goal 是「讓 code 能跑」，hardcode API key 就是達到這個 goal 最快的方式。 **加了什麼防護**： 1. Pre-commit 的 credential scanning（原本就有，救了一命） 2. 在 CLAUDE.md 裡加了明確規則：「永遠不要 hardcode secrets，使用環境變數」 3. `.env` 檔案加入 hook 的保護清單 ### 案例 3：Production Migration 驚魂 Agent 寫了一個 database migration script，在 staging 跑得很順利。然後它「貼心地」準備了 production 的 migration command——包含 production database 的連線字串。 如果我沒注意到那個 command 裡的 hostname 是 production 而不是 staging，然後不小心讓 agent 執行了... **根因**：Agent 不區分環境。它看到 staging 成功了，就按照同樣的模式準備 production 的指令。它不知道 production migration 需要完全不同的審批流程。 **加了什麼防護**： 1. Production 連線字串不在任何 agent 可以讀取的檔案裡 2. 任何包含 `production` 或 `prod` 關鍵字的指令需要人工 confirm 3. Database migration 永遠是 human-only 的操作 ## 權限的漸進式開放 不建議一次開放所有權限。建議的漸進路徑： ### Week 1-2：Read Only + Write Code ``` ✅ 讀檔案 ✅ 寫 code（在 feature branch） ✅ 跑 test / lint ❌ Git commit（你手動做） ❌ 安裝 packages ❌ 執行任意 shell 命令 ``` 熟悉 agent 的行為模式。看它會做什麼決策、會犯什麼錯。 ### Week 3-4：加 Git 操作 ``` ✅ 以上全部 ✅ Git commit（到 feature branch） ✅ 安裝 npm packages（需確認） ❌ Git push ❌ 操作外部系統 ``` ### Month 2+：加外部操作 ``` ✅ 以上全部 ✅ Git push（需確認） ✅ MCP 操作（指定的 server） ✅ Deploy to staging（需確認） ❌ Deploy to production ❌ Database 操作 ``` ### 永遠不要自動化的事 有些操作，無論你對 agent 多有信心，永遠需要人工審批： - **Production deploy** - **Database migration on production** - **刪除 production 資料** - **修改 IAM / permissions** - **Push to main/master** 這不是因為 agent 一定會搞砸，而是這些操作的 blast radius 太大，萬一搞砸了，recovery 成本遠高於多花 30 秒人工確認的成本。 ## 建立你的安全網 Checklist ```markdown ## Agent Safety Checklist ### Sandbox - [ ] Agent 在 feature branch 上工作（永遠不碰 main） - [ ] 有方便的 rollback 方式（git reset / git branch -D） - [ ] Production credentials 不在 agent 可讀的範圍 ### Automated Guardrails - [ ] Pre-commit hooks：credential scanning、lint、type check - [ ] Sensitive file protection（.env、config with secrets） - [ ] Rate limiting on destructive operations - [ ] Max retry limit（3 次失敗自動停止） ### Human-in-the-Loop - [ ] Git push 需要確認 - [ ] Deploy 需要確認 - [ ] 刪除操作需要確認 - [ ] Production-related 操作需要確認 ### Monitoring - [ ] Agent 的操作有 log（至少 git history） - [ ] 異常行為有通知（連續失敗、大量操作） - [ ] 定期 review agent 的操作歷史 ``` ## Takeaway 1. **Agent 安全不是「限制 agent」，而是「設計可控的自由度」**：三層架構（Sandbox → Hooks → Human-in-the-Loop）讓 agent 在安全邊界內最大化有用性，每一層擋不同類型的風險。 2. **Git 是你最好的安全網**：Branch isolation 加上 easy rollback，覆蓋了大部分「agent 搞壞了東西」的場景。確保 agent 永遠在 feature branch 上工作。 3. **每次 near-miss 都是加強安全網的機會**：不要等到真的出事。47 次 staging deploy 教我加 rate limit，差點 push credentials 教我加 secret scanning。把每次驚險經歷都轉化成一條新的 guardrail。 --- _上一篇：[Token 經濟學進階](/blog/agentic-engineering-cost-optimization)_ _下一篇：[把 Agentic Engineering 帶進團隊](/blog/agentic-engineering-team-adoption)_Agentic Engineering資安SandboxAI SafetyHookshttps://bobochen.dev/blog/agentic-engineering-cost-optimization/https://bobochen.dev/blog/agentic-engineering-cost-optimization/Agent 越強大，token 燒越快。深入 token 成本的結構分析——哪些任務是 token 黑洞、怎麼設計 context 降低消耗、caching 策略、model routing，以及月成本從 $287 降到 $148 的實際做法。Fri, 22 May 2026 00:00:00 GMT> 這是「Agentic Engineering 實戰手冊」系列的第十一篇。上一篇：[Multi-Agent 編排實戰](/blog/multi-agent-orchestration-real-world) ## 上個月帳單 $287，這個月 $148 上個月我的 AI coding 總帳單是 $287。嚇了一跳。 不是用太多，工作量其實差不多，問題出在使用方式：超長的 session 導致 context window 持續膨脹、探索性的 codebase 搜尋吃掉大量 token、該用便宜 model 的地方用了貴的。 花了一個週末分析之後，這個月在相同工作量下壓到了 $148。差距來自三個改變：context pruning、model routing，還有更有紀律的 session management。 重點不是「少用」，是「聰明用」。如果你也有 token 燒光的焦慮，這篇從工程面給你具體的解法。 ## Token 成本解剖學 要省錢，先搞懂錢花在哪。 ### 三種 Token，三種價格 | Token 類型 | 什麼時候產生 | 你能控制嗎 | | ------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | **Input tokens** | 你給 model 的一切：system prompt、CLAUDE.md、conversation history、code context | 是——[context engineering](/blog/context-engineering-deep-dive) 直接影響 | | **Output tokens** | Model 回給你的一切：code、解釋、tool calls | 部分——精準的 spec 讓 agent 少寫廢話 | | **Thinking tokens** | 模型推理時的內部 token（extended thinking） | 部分——簡單任務關閉 extended thinking | 真正隱藏的成本殺手是 **input tokens**。 大部分人以為成本主要來自 output（agent 寫的 code），其實不是。在一個典型的 agentic session 裡，input tokens 通常是 output 的 **3-5 倍**。因為每一輪對話，整個 conversation history + system prompt + context 都會被重新送一次。 一個 session 跑了 50 輪對話，最後幾輪每次都要送入幾十萬 token 的 history——光是這些重複的 input 就占了帳單的大頭。 ### 一次「幫我修這個 bug」的 Token 分解 一個看似簡單的 bug fix request： ``` System prompt + CLAUDE.md: ~5,000 tokens Conversation history (20 輪): ~40,000 tokens Agent 讀的 code files: ~15,000 tokens Agent 的 tool calls: ~8,000 tokens Agent 的 output (code + 說明): ~3,000 tokens Extended thinking: ~5,000 tokens ───────────────────────────────────────────── Total: ~76,000 tokens ``` Agent 最後寫出來的 code（3,000 tokens）只佔總消耗的 4%，而 conversation history（40,000 tokens）佔了 53%。最大的省錢機會不在「少寫 code」，在「管理 conversation history」。 ## 每種任務的成本對照 根據我三個月的追蹤數據（approximation based on usage patterns）： | 任務類型 | 平均 Token 消耗 | 大約成本 | 備註 | | -------------------- | --------------- | ---------- | ------------------ | | Simple bug fix | 50K-100K | $0.20-0.50 | 通常 1-3 輪對話 | | New feature (small) | 150K-300K | $0.50-1.50 | 5-10 輪，含 review | | New feature (medium) | 500K-1M | $2-5 | 多輪 iteration | | Refactor | 800K-2M | $3-10 | 大量 codebase 探索 | | Code review | 100K-200K | $0.30-1.00 | 讀多寫少 | | Codebase exploration | 300K-800K | $1-4 | Token 黑洞 | | Documentation | 200K-400K | $0.50-2.00 | Output-heavy | **Token 黑洞排行**： 1. **Refactor**——agent 需要讀很多檔案，理解整體架構，然後做大量修改 2. **Codebase exploration**——「幫我搞懂這個系統怎麼運作」類型的任務，agent 會讀幾十個檔案 3. **Long debugging sessions**——一來一回的 debug loop，conversation history 指數增長 ## 優化策略一：Context Pruning 回到 [Context Engineering](/blog/context-engineering-deep-dive) 的核心觀念：context 不是越多越好，剛好夠就行。 ### 精簡 CLAUDE.md 每多一行 CLAUDE.md，就多花幾個 token 在每一輪對話裡。乘以 session 裡的對話輪數，成本累積驚人。 **Before**：400 行的 CLAUDE.md，每輪 ~4000 tokens × 30 輪 = 120,000 tokens 浪費在重複載入上 **After**：100 行的 CLAUDE.md，每輪 ~1000 tokens × 30 輪 = 30,000 tokens 光這一項就省了 90K tokens（約 $0.30/session）。看起來不多，但每天做 10 個 session，一個月就是 $90。 ### Session 管理紀律 黃金法則就一句：一個 session 做一件事。 一個 session 跑太久，conversation history 會指數膨脹。第 50 輪的對話要送入前面 49 輪的 history，那可能是 200K+ 的 input tokens。 **改善做法**： - 一個 task 一個 session。task 做完就關，開新 session 做下一個。 - 如果 task 需要多輪 iteration，中途做 checkpoint（更新 plan/TODO），然後開新 session 繼續。 - 利用 Claude Code 的 context compaction，當 context 太大時它會自動壓縮舊的對話。但與其依賴自動壓縮，不如主動控制 session 長度。 ### Sub-Agent 模式 探索性的任務（「幫我搞懂這個模組的架構」）特別燒 token。解法是用 sub-agent： ``` 主 agent: 「研究 auth 模組的架構」 → 派出 sub-agent（cheap model、獨立 context） → sub-agent 讀 20 個檔案，消耗 200K tokens → 回報 2000 token 的摘要給主 agent ``` 主 agent 的 context 只增加了 2000 tokens，而不是 200K。 ## 優化策略二：Model Routing 不是所有任務都需要最貴的模型。 ### 我的 Model 選擇框架 | 任務類型 | 推薦 Model | 原因 | | -------------------- | ------------------- | ------------------------- | | 簡單問答、分類 | Haiku | 快、便宜、準確度足夠 | | 日常 coding、bug fix | Sonnet | 性價比最高 | | 複雜架構決策 | Opus | 需要深度推理 | | Code review | Sonnet | 理解力夠、比 Opus 快 | | Commit message | Sonnet/Haiku | 不需要 Opus 的推理能力 | | 長篇寫作 | Opus | 需要一致性和深度 | | Codebase exploration | Sonnet + sub-agents | 用便宜的 model 做大量探索 | ### 實際省下多少？ 以一天的典型工作量為例： **Before（全部用 Opus）**： - 10 個 tasks × 平均 300K tokens × Opus 價格 ≈ $15/天 **After（model routing）**： - 2 個 complex tasks → Opus：600K tokens ≈ $4 - 6 個 standard tasks → Sonnet：1.2M tokens ≈ $4 - 2 個 simple tasks → Haiku：200K tokens ≈ $0.10 - **Total ≈ $8/天** 同樣的工作量，成本掉了 47%，品質幾乎沒差。Sonnet 在日常 coding 任務上的表現跟 Opus 非常接近。 ### 怎麼切換 在 Claude Code 裡，隨時可以用 `/model sonnet` 或 `/model opus` 切換。我的 [`commit` skill](/blog/claude-md-rules-files-masterclass) 裡就有提醒：做 git commit 用 Sonnet 就好，不需要 Opus。 ## 優化策略三：Prompt Caching & Batching ### Prompt Caching Anthropic 的 prompt caching 機制讓相同的 system prompt 只需要在第一次完整傳送，後續的 request 可以使用 cache，大幅降低 input token 成本。 **怎麼提高 cache hit rate**： - CLAUDE.md 保持穩定——頻繁修改 CLAUDE.md 會導致 cache miss - System prompt 放在 context 的最前面（cache 是 prefix-based 的） - 避免在 system-level context 裡放動態內容（timestamp、random ID 等） ### Batching 策略 把相似的小任務合成一個 request： **Before**（5 個獨立 request）： ``` 1. "修正 Button component 的 hover color" 2. "修正 Card component 的 border radius" 3. "修正 Input component 的 focus style" 4. "修正 Modal component 的 backdrop color" 5. "修正 Toast component 的 animation" ``` 5 次 system prompt 載入 + 5 次 CLAUDE.md 載入 = 大量重複的 input tokens。 **After**（1 個 batch request）： ``` 修正以下 5 個 component 的 CSS 問題： 1. Button: hover color 2. Card: border radius 3. Input: focus style 4. Modal: backdrop color 5. Toast: animation ``` 1 次 system prompt 載入 + 1 次 CLAUDE.md 載入。Token 節省 ~60%。 ## 月度預算框架 Agentic engineering 合理的月成本是多少？取決於你的使用強度： | 使用級別 | 月成本 | 誰適合 | | ---------------------- | ---------------------- | ------------------------ | | **Light** ($20-50) | Pro 訂閱 + 少量 API | 兼職使用、學習階段 | | **Medium** ($50-150) | Pro + 日常 API 使用 | 全職 agent-first 開發 | | **Heavy** ($150-300) | 大量 API + multi-agent | 多專案、multi-agent 架構 | | **Enterprise** ($300+) | Team 帳號 + 自建工具 | 團隊級別使用 | ### ROI 計算 $150/月的 agent 成本值不值得？算一下： 假設 agentic workflow 讓你每天省 2 小時（保守估計，根據 [Post 7](/blog/agentic-engineering-daily-workflow-advanced) 的 4x 效率提升）。 - 一個月工作 22 天 × 2 小時 = 44 小時 - 以台灣軟體工程師平均時薪 $25 USD 計算：44 × $25 = $1,100 - ROI：$1,100 / $150 = **7.3x** 即使你用最貴的 Opus model 跑所有事情，只要它讓你省下的時間值超過 $300/月，就是值得的。 大部分 agent-first 工程師的 sweet spot 在 **$100-200/月**。這個範圍可以覆蓋每天 8-10 小時的 agent-first 工作方式，如果你做好 model routing 和 context management。 ## 我具體做了什麼把帳單從 $287 降到 $148 1. **Session 拆分**：從平均 45 分鐘/session 降到 20 分鐘/session。對話輪數從 30 降到 12。 2. **Model routing**：70% 任務改用 Sonnet（之前 90% 用 Opus）。 3. **Sub-agent 探索**：codebase exploration 任務全部丟給 sub-agent，主 context 不膨脹。 4. **CLAUDE.md 瘦身**：從 400 行精簡到 100 行。任務特定的指令移到 rules files 和 skills。 5. **Batch 處理**：小任務合併。一天 15 個 request 降到 8 個。 每一項單獨看都不是巨大的改變。但加在一起，就是 48% 的成本降低。 ## Takeaway 1. Token 成本的最大殺手是不必要的 context 膨脹，不是使用量。Conversation history 佔了帳單的一半以上。控制 session 長度、精簡 CLAUDE.md、善用 sub-agent，這三招就能省 30-40%。 2. Model routing 可以在不犧牲品質的前提下省 40-50% 成本。日常 coding 用 Sonnet，只有複雜架構決策才需要 Opus。Commit、simple Q&A 用 Haiku 就夠了。 3. $100-200/月是大部分 agent-first 工程師的 sweet spot。這個成本對應的 ROI 通常在 5-10x。不要為了省 $50 犧牲工作流的效率，但也不要因為「反正有用」就不管成本地亂燒。 --- _上一篇：[Multi-Agent 編排實戰](/blog/multi-agent-orchestration-real-world)_ _下一篇：[Agent 安全網設計](/blog/agentic-engineering-testing-safety)_Agentic EngineeringToken成本優化AIModel Routinghttps://bobochen.dev/blog/multi-agent-orchestration-real-world/https://bobochen.dev/blog/multi-agent-orchestration-real-world/一個 agent 很強，但真正的生產力飛躍來自多個 agent 協作。分享三 agent 系統如何分工、如何傳遞 context、如何避免衝突——以及 LangGraph、CrewAI 等框架我試過之後為什麼沒用。Fri, 15 May 2026 00:00:00 GMT> 這是「Agentic Engineering 實戰手冊」系列的第十篇。上一篇：[MCP 與 A2A 協議實戰](/blog/mcp-a2a-protocols-practitioner-guide) ## 理論上我有一支 AI 軍隊，實際上它們像三個不太會溝通的實習生 我的日常有三個 AI agent 在跑：Claude Code 負責寫 code、OpenClaw 負責每日 briefing 和調研、n8n 負責自動化 workflow。理論上，這是一支全天候的 AI 團隊。 實際上？Claude Code 不知道 OpenClaw 今天早上幫我整理了什麼重點。OpenClaw 不知道昨天 coding session 做到哪了。n8n 觸發的 automation 偶爾會跟 Claude Code 正在做的事情衝突。 三個很強的 agent，各自為政。 Multi-agent orchestration 不是「有很多 agent」。是「讓很多 agent 像一個團隊一樣工作」。這兩件事之間的差距，比你想的大得多。 ## 我的三 Agent 架構 ### Agent 1：Claude Code — 核心開發者 **職責**：寫 code、修 bug、review PR、重構、寫測試 **運行環境**：本地 terminal + IDE integration **記憶方式**：CLAUDE.md + memory system + conversation history **工作時間**：我開電腦的時候（~8-10 小時/天） Claude Code 是主力。我 80% 的生產力來自它。它有完整的 codebase access、[MCP 工具](/blog/mcp-a2a-protocols-practitioner-guide)、和一年累積的 [CLAUDE.md 設定](/blog/claude-md-rules-files-masterclass)。 ### Agent 2：OpenClaw — 研究分析師 **職責**：每日 briefing（技術新聞、產業動態）、深度研究（競品分析、技術選型）、內容策劃 **運行環境**：雲端，每天 6:00 AM 自動執行 **記憶方式**：Notion database + 結構化輸出 **工作時間**：每天自動跑一次 + 我手動觸發研究任務 OpenClaw 是我的「情報官」。它每天早上自動整理我追蹤的領域的最新動態，讓我不需要花時間刷 Twitter 和 Hacker News。 ### Agent 3：n8n — 自動化管家 **職責**：workflow automation——GitHub webhook 處理、Notion 同步、定時任務、跨系統串接 **運行環境**：self-hosted n8n instance **記憶方式**：workflow 狀態 + execution logs **工作時間**：24/7 always-on n8n 不做「思考」的工作。它做的是「當 X 發生時，執行 Y」的 deterministic automation。GitHub 有新 PR → 自動通知 Slack。Blog post 更新 → 自動觸發 build。 ### 為什麼是這三個 這個組合不是隨便選的。核心設計原則是 **non-overlapping responsibilities**： ``` ┌─────────────────┐ │ Human (我) │ │ 決策、Review、方向 │ └────┬───┬───┬────┘ │ │ │ ┌─────────────┤ │ ├─────────────┐ │ │ │ │ │ ┌────▼────┐ ┌─────▼───▼──┐ ┌──────────▼┐ │ OpenClaw │ │ Claude Code │ │ n8n │ │ Research │ │ Coding │ │ Automation │ │ Morning │ │ On-demand │ │ 24/7 │ └──────────┘ └─────────────┘ └────────────┘ ``` 每個 agent 有明確的「地盤」。沒有兩個 agent 負責同一件事。當兩個 agent 的職責重疊時，問題就來了。 ### 職責重疊的慘案 有一次我同時讓 Claude Code 寫一個新的 API endpoint，又讓 n8n 的自動化在同一個 repo 上跑 auto-format。結果 n8n 的 formatter 在 Claude Code 還在寫的時候就 commit 了一個格式修正，造成 Claude Code 的 working directory 突然有了 unexpected changes。 Agent 非常不擅長處理「有人在我背後改了東西」的情況。它不知道那些 changes 是 n8n 做的 auto-format，以為是自己剛才寫的 code 的一部分，然後在上面繼續 build——結果是一團混亂。 **教訓**：一個任務只能有一個 owner。如果 Claude Code 在寫 code，n8n 的 auto-format workflow 就暫停。 ## Context 如何在 Agent 之間傳遞 這是 multi-agent 最難的部分。不是技術上難（你可以用 file、API、database），是**設計上**難——什麼資訊需要傳遞？傳遞多少？什麼時候傳遞？ ### Markdown as Shared Memory 我目前的做法是用 Markdown 文件作為 agent 之間的共享記憶： ``` ~/.claude/projects/{project}/memory/ ├── MEMORY.md ← index：所有 memory 的目錄 ├── user_role.md ← 關於我的資訊 ├── project_status.md ← 專案進度 ├── decisions.md ← 重要決策紀錄 └── lessons.md ← 學到的教訓 ``` **為什麼用 Markdown 而不是 Database？** 1. **Human-readable**：我可以直接打開看，不需要 query tool 2. **Git-trackable**：可以 version control，看到記憶的變化歷史 3. **Agent-native**：所有 LLM agent 都擅長讀寫 Markdown 4. **Zero infrastructure**：不需要額外的 database 或 API server ### Hot / Warm / Cold 三層記憶 不是所有資訊都需要即時同步。我把 memory 分三層： | 層級 | 內容 | 同步頻率 | 存放位置 | | -------- | ---------------------------------- | ---------- | ------------------------ | | **Hot** | 當前 task 的 context、進行中的決策 | 即時 | Conversation / Plan file | | **Warm** | 專案狀態、近期決策、常用 patterns | 每 session | Memory files | | **Cold** | 歷史決策、舊的 lessons learned | 不主動同步 | Memory archive | Claude Code 開始新 session 時，自動載入 Warm 層的記憶（透過 MEMORY.md index）。Hot 層在 session 內即時產生。Cold 層只在明確需要時才去讀。 ### Agent 之間的接力棒 一天的流程看起來像這樣： ``` 06:00 OpenClaw → 產出 daily briefing → 寫入 Notion 09:00 我 → 讀 briefing → 決定今天做什麼 09:05 Claude Code → 載入 memory + 今天的 task list → 開始工作 ...（Claude Code 工作整天）... 18:00 Claude Code → session 結束 → 更新 memory/project_status.md 18:00 n8n → 偵測到 session 結束 → 觸發 daily summary workflow 21:00 我 → review daily summary → 調整明天的優先級 ``` 關鍵在 **handoff 的時刻**——每個 agent 結束工作時，要把「我做了什麼、目前狀態是什麼、下一步建議是什麼」寫到共享記憶裡，讓下一個 agent（或明天的自己）可以無縫接手。 ## 為什麼我沒用 LangGraph / CrewAI 我試過的框架： ### LangGraph **優點**：最靈活。你可以定義任意複雜的 agent 互動圖。支援條件分支、循環、人工介入點。 **缺點**：學習曲線陡。為了設定一個兩 agent 的 pipeline，我寫了 200 行 boilerplate code。而且 debug 困難——graph 一複雜，你很難追蹤「資料是從哪條路徑流過來的」。 **結論**：如果你需要 10+ agents 的複雜編排，LangGraph 是對的選擇。如果你只有 2-3 個 agent，overhead 大於效益。 ### CrewAI **優點**：角色定義直觀（"you are a researcher", "you are a coder"）。設定快。 **缺點**：太 opinionated。它預設了一套 agent 互動模式，如果你的 workflow 不符合那個模式，客製化很痛苦。而且它跟特定的 LLM provider 綁得比較深。 **結論**：快速 prototype 很好用，但 production 使用的靈活度不夠。 ### Google ADK（Agent Development Kit） **優點**：跟 Google 生態系（Gemini、Vertex AI）整合好。 **缺點**：Gemini 優化，用在其他 model 上效果打折。生態系還在早期。 ### Microsoft Agent Framework **優點**：企業級。跟 Azure、Microsoft 365 整合。 **缺點**：Azure-heavy。如果你不在 Azure 生態系裡，很多功能用不上。 ### 我的結論：手動編排就好 對於大部分個人開發者和小團隊來說，**手動編排比框架更適合**： | | 手動編排 | 框架 | | ------------ | ---------- | ----------------------- | | **透明度** | 完全看得見 | 黑盒子（尤其 debug 時） | | **靈活度** | 想改就改 | 被框架 API 限制 | | **學習成本** | 接近零 | 需要學框架 | | **維護成本** | 低 | 跟框架版本走 | | **適合場景** | 2-5 agents | 5+ agents | 手動編排的意思是：我自己決定哪個 agent 做什麼、怎麼傳遞 context、怎麼處理衝突。不用框架，用 files + webhooks + 少量 script。 **什麼時候該用框架？** - 你有 5 個以上的 agent 需要複雜互動 - 你需要 deterministic orchestration（金融、醫療等合規要求） - 你的團隊有多人需要共同維護 agent pipeline - 你需要 observability 和 audit trail 如果以上都不符合，從手動開始。需要框架的時候你會知道的。 ## Error Handling：當 Agent 們意見不一致 ### 衝突類型 1：搶資源 兩個 agent 同時修改同一個檔案 → git conflict。 **解法**：嚴格的 ownership 規則。一個時間點，一個檔案只能被一個 agent 操作。如果 n8n 需要改 config file，Claude Code 那段時間就不能碰那個 file。 ### 衝突類型 2：不同建議 OpenClaw 的 research 說「應該用 Library A」，Claude Code 在實作時發現 Library A 有 bug，改用了 Library B。隔天 OpenClaw 又建議 Library A。 **解法**：決策一旦做出就記錄到 shared memory（`decisions.md`），所有 agent 都要先讀決策紀錄再給建議。 ### 衝突類型 3：Automation 時機不對 n8n 在 Claude Code 正在做 interactive rebase 的時候觸發了 auto-lint → 搞亂了 git 狀態。 **解法**：n8n 的 automation 都加了「check if coding session active」的前置條件。如果有 coding session 在跑，non-critical automation 排隊等候。 ### 核心原則：Human as Final Arbiter 當 agent 之間有衝突，最終裁決者永遠是人。不要設計一個 agent 來「管理」其他 agent 的衝突——那個 meta-agent 本身也可能犯錯，而且增加了系統複雜度。 在現階段，最可靠的 conflict resolution 是：agent 發現衝突 → 暫停 → 通知人類 → 人類決策 → agent 繼續。 ## 給想開始的人的建議 ### Phase 1：先把一個 Agent 用到極致 不要一開始就想搞 multi-agent。先把 Claude Code（或你的主力 coding agent）的潛力完全發揮——[好的 CLAUDE.md](/blog/claude-md-rules-files-masterclass)、[完善的 spec workflow](/blog/spec-driven-development-for-agents)、[可靠的 QA 流程](/blog/agent-output-verification-review)。 ### Phase 2：加第二個 Agent 做非 coding 的事 當你覺得「coding agent 很好了，但我花太多時間在 research / admin / automation 上」的時候，加第二個 agent。確保它的職責跟第一個完全不重疊。 ### Phase 3：用 Automation 串接 n8n（或 Zapier / Make）作為黏合劑，把兩個 agent 的 output 串接起來。不需要它們直接對話，只需要它們共享結果。 ### Phase 4：需要的時候再加框架 99% 的人在 Phase 2-3 就夠了。如果你發現自己需要更複雜的編排——恭喜，你可能是那 1%，可以開始看 LangGraph。 ## Takeaway 1. **Multi-agent 的價值在「分工」而非「數量」**——三個各有專精、職責不重疊的 agent，比十個通才 agent 強。設計 agent team 的第一步不是選工具，是定義「誰負責什麼，以及誰不負責什麼」。 2. **Context sharing 是最難的部分**——Markdown as shared memory 是目前最實用的方案。簡單、human-readable、git-trackable、零基礎設施成本。Hot / Warm / Cold 三層分離，避免每次都載入全部。 3. **從手動編排開始，需要框架時再加**——LangGraph / CrewAI 這些框架適合 5+ agents 的複雜場景。大部分人只需要 2-3 個 agent + files + webhooks 就夠了。先把一個 agent 用到極致，再想 multi-agent。 --- _上一篇：[MCP 與 A2A 協議實戰](/blog/mcp-a2a-protocols-practitioner-guide)_ _下一篇：[Token 經濟學進階](/blog/agentic-engineering-cost-optimization)_Agentic EngineeringMulti-AgentClaude Coden8nOrchestrationhttps://bobochen.dev/blog/mcp-a2a-protocols-practitioner-guide/https://bobochen.dev/blog/mcp-a2a-protocols-practitioner-guide/MCP 讓 agent 連接外部工具，A2A 讓 agent 之間對話。這兩個協議正在重新定義 agentic engineering 的邊界。從實戰角度解析：哪些 MCP server 真的有用、A2A 目前能做什麼、以及怎麼把它們整合進日常工作流。Fri, 08 May 2026 00:00:00 GMT> 這是「Agentic Engineering 實戰手冊」系列的第九篇。上一篇：[CLAUDE.md 大師班](/blog/claude-md-rules-files-masterclass) ## 那一刻，我覺得未來到了（然後 Agent 把我的 Email 刪了） 第一次設定好 Chrome DevTools MCP，讓 Claude Code 直接操作我的瀏覽器的時候，我覺得這就是未來。Agent 可以自己開網頁、截圖、填表單、甚至跑 Lighthouse audit。 然後它在操作過程中，不小心把我正在寫的一封 email 給清空了。 那封 email 我寫了快半小時。 這個事件完美地總結了 MCP 的兩面性：它讓 agent 的能力從「讀 code 寫 code」跳躍到「操作你的整個開發環境」，但這種能力帶來的風險也呈指數級增長。 A2A 則是讓多個這樣的強大 agent 可以互相對話。想像不只一個 agent 有能力操作你的環境，而是一群。興奮嗎？害怕嗎？兩者都是正確的反應。 ## MCP：AI 的 USB-C ### 什麼是 MCP Model Context Protocol（MCP）是 Anthropic 在 2024 年底提出的開放協議。最簡單的理解方式： > MCP 之於 AI agent，就像 USB-C 之於你的設備——一個統一的接口，讓任何 agent 可以連接任何工具。 在 MCP 之前，每個 AI 工具有自己的 plugin 系統。Cursor 有自己的 extension、ChatGPT 有自己的 Plugins、Claude 有自己的 tools。如果你想讓你的工具同時被三個 AI 使用，你得寫三套整合。 MCP 統一了這個介面。你寫一個 MCP server，所有支援 MCP 的 AI agent 都能用。 2025 年，MCP 被 Anthropic 捐給了 Linux Foundation 旗下的 AAIF（AI Alliance for Interoperability Foundation）。到了 2026 年，它已經被所有主要 AI 公司採用——Anthropic、OpenAI、Google、Microsoft、Amazon。SDK 的月下載量超過 9700 萬次（Python + TypeScript）。 它已經不是「Anthropic 的東西」了。它是產業標準。 ### MCP 的架構 ``` 你的 AI Agent（Claude Code / Cursor / etc.） ↕ MCP Protocol（JSON-RPC over stdio/HTTP） MCP Server（一個小程式，暴露 tools 給 agent） ↕ 實際操作 External System（Database / API / Browser / etc.） ``` MCP Server 就像一個翻譯官：它把外部系統的能力「翻譯」成 agent 能理解的 tool definition（輸入什麼、輸出什麼、做什麼），agent 就可以自主決定什麼時候呼叫哪個 tool。 ### MCP v2 的重要更新 MCP v2（2026 年初發布）帶來幾個重要改進： - **Streamable HTTP transport**：不再只限於 stdio，支援 HTTP 直接連接，更適合遠端部署 - **Multimodal 支援**：可以傳遞 images、video、audio，不只是文字 - **OAuth 2.1 認證**：標準化的認證流程，讓企業環境更容易導入 - **Elicitation**：agent 可以透過 MCP 向用戶提問，實現更自然的互動 ## 我的 Production MCP Stack 一年下來，我試過超過 20 個 MCP server。留下來持續在用的只有 5 個。 ### Tier 1：每天都用 **Chrome DevTools MCP** 用途：操控瀏覽器。截圖、填表單、跑 Lighthouse audit、監控 network requests。 使用場景： - 自動跑 visual regression test（截圖 → 比對） - 幫我在 NotebookLM 上自動操作（產生摘要素材） - 填寫重複的表單（測試環境的 seed data） 踩過的坑： - Agent 不知道頁面載入需要時間，常常在 DOM 還沒渲染完就嘗試操作 → 需要在 prompt 裡提醒「等 page load 完」 - 開太多 tab 會讓 agent 搞混 → 限制每次只操作一個 tab - 那封被刪的 email → 現在我永遠在 incognito window 裡讓 agent 操作 **Notion MCP** 用途：讀寫 Notion databases。我的 task management、knowledge base、project brief 都在 Notion 上。 使用場景： - 讓 agent 直接讀取 Jira ticket 的內容（我用 Notion 做 task sync） - 寫 session 總結到 Notion daily log - 查找之前做過的決策紀錄 踩過的坑： - Notion API 的 block 格式很複雜，agent 常常建出格式不對的內容 → 我寫了一個 `notion-block-format` skill 來幫助它 - Rate limiting：太頻繁的 API 呼叫會被 throttle ### Tier 2：每週用幾次 **Sentry MCP** 用途：查詢 production error。Agent 可以直接搜尋 issues、看 stack trace、分析 error patterns。 **Canva MCP** 用途：產生社群圖片素材。Agent 可以生成設計、匯出不同格式。 ### Tier 3：偶爾用 **自建的公司 API MCP** 為工作專案自建的 MCP server，連接內部 API。讓 agent 可以查詢內部系統的資料。 ### MCP 的「少即是多」原則 重要的經驗：**不要一次掛太多 MCP servers**。 每個 MCP server 的 tool definition 都會佔用 [context window](/blog/context-engineering-deep-dive)。掛 10 個 MCP server，可能光是 tool descriptions 就佔了 context 的 15-20%。而且 agent 面對太多 tool 選項時，選擇的準確率會下降。 我的原則：**一個 session 掛 3-5 個最相關的 MCP server**。其他的，需要的時候再啟用。 ## 自建 MCP Server 的經驗 ### 什麼時候該自建 - **內部 API 整合**：你的公司系統不會有現成的 MCP server - **客製化的工作流**：現成的 MCP server 不支援你需要的操作 - **效能優化**：通用的 MCP server 可能做了太多你不需要的事 ### 什麼時候不該自建 - **已有成熟的開源 MCP server**：GitHub、Slack、Notion 等都有官方或社群維護的 - **Tool 的使用頻率很低**：自建的維護成本不值得 - **可以用 HTTP Request 替代**：如果只是呼叫一個 REST API，agent 通常可以直接用 fetch ### 架構要點 一個 MCP server 的核心就三件事： 1. **Tool Definition**：這個 tool 叫什麼、做什麼、接收什麼 input、回傳什麼 output 2. **Input Validation**：用 Zod 或 JSON Schema 驗證 agent 傳來的 input 3. **Error Handling**：明確的錯誤訊息，讓 agent 知道出了什麼問題 ```typescript // 一個最小的 MCP tool 長這樣（概念示意） { name: "query_orders", description: "Query recent orders from internal system", inputSchema: { type: "object", properties: { status: { type: "string", enum: ["pending", "shipped", "delivered"] }, limit: { type: "number", default: 10 } } } } ``` **關鍵**：`description` 寫得好不好，直接影響 agent 會不會正確使用這個 tool。這跟寫 [spec](/blog/spec-driven-development-for-agents) 的邏輯一樣——越精確，agent 的表現越好。 ## A2A：Agent 之間的共同語言 ### 什麼是 A2A Agent-to-Agent Protocol（A2A）是 Google 在 2025 年 4 月提出的協議，後來捐給了 Linux Foundation AAIF（跟 MCP 同一個組織）。 如果 MCP 是「agent 跟工具對話」，A2A 就是「agent 跟 agent 對話」。 具體來說，A2A 解決三個問題： 1. **Discovery**：Agent A 怎麼知道 Agent B 存在、它會什麼？ 2. **Communication**：Agent A 怎麼把任務發給 Agent B？ 3. **Collaboration**：兩個 Agent 怎麼在一個任務上協作？ ### A2A 的核心概念 - **Agent Card**：每個 agent 的「名片」，描述它的能力、支援的 input/output format、認證方式 - **Task**：agent 之間傳遞的工作單元 - **Message / Artifact**：任務過程中的通訊內容和產出物 ### 目前的生態 A2A 在 2026 年 3 月已經發展到 v0.2。50+ 合作夥伴包括 Salesforce、PayPal、Deloitte、Box 等企業。IBM 的 ACP（Agent Communication Protocol）也已經合併進 A2A。 但說實話——A2A 目前還在非常早期。大部分的「支援 A2A」是概念驗證層級，不是 production 層級。 ### 我目前怎麼用（或者說，還沒怎麼用） 坦白說，我日常工作裡還沒有真正的 A2A 使用場景。我的 [multi-agent 架構](/blog/multi-agent-orchestration-real-world)——Claude Code + OpenClaw + n8n——它們之間的「通訊」是透過共享的 Markdown 檔案和 n8n webhook，不是透過 A2A 協議。 為什麼？因為 A2A 目前的基礎設施還不夠成熟。Agent Card 的 discovery 機制、認證流程、error handling——這些在 production 環境裡都還不夠穩定。 但我認為 A2A 在 12 個月內會變得重要。當 Claude Code 可以透過 A2A 直接跟 Devin 協作——一個負責前端、一個負責後端——那會是 multi-agent 的真正突破。 ## MCP vs A2A：互補而非競爭 這兩個協議經常被拿來比較，但它們解決的是不同的問題： | | MCP | A2A | |---|---|---| | **連接什麼** | Agent ↔ Tool | Agent ↔ Agent | | **比喻** | USB-C（設備接周邊） | Wi-Fi（設備互聯） | | **目前成熟度** | Production-ready | Early stage | | **主導者** | Anthropic → AAIF | Google → AAIF | | **採用度** | 97M+ downloads | 50+ partners（概念驗證） | | **你現在該用嗎** | 是 | 觀望，但要了解 | **實際場景**： ``` Claude Code（我的 coding agent） ├── 透過 MCP → 操作 Chrome、讀寫 Notion、查 Sentry └── 未來透過 A2A → 跟 Devin 協作、跟 OpenClaw 交換 research 結果 ``` MCP 是今天就能用的工具。A2A 是明天會需要的基礎設施。 ## 協議的理想 vs 現實 ### 理想 任何 agent 可以無縫連接任何工具（MCP），任何 agent 可以無縫跟任何其他 agent 協作（A2A）。一個統一的生態系，interoperable、secure、efficient。 ### 現實 **MCP 的現實問題**： - Server 品質參差不齊——有些官方維護、品質高；有些社群貢獻、bug 多 - 認證和安全仍在完善中——OAuth 2.1 剛加入 v2，很多 server 還沒支援 - Tool discovery 不夠好——你得自己知道有什麼 MCP server 可以用 **A2A 的現實問題**： - 還在 v0.2——API 隨時可能改 - 缺乏 production 級別的 reference implementation - 大部分 partners 是「承諾支援」而非「已經整合」 ### 我的建議 1. **現在就開始用 MCP**——從 2-3 個最相關的 server 開始，逐步擴展 2. **A2A 先了解概念，不急著整合**——它的 API 還在變，過早投入可能做白工 3. **關注 AAIF 的動態**——兩個協議都在同一個組織下，未來的整合方向值得追蹤 ## Takeaway 1. **MCP 讓 agent 從「只會讀 code」升級到「能操作你的整個開發環境」**——但能力越大，風險越大。設好 sandbox 和 permission boundary（詳見 [Agent 安全網設計](/blog/agentic-engineering-testing-safety)），然後大膽使用。 2. **A2A 讓 multi-agent 協作有了標準協議**——但目前還在早期。值得了解概念和追蹤進度，但還不是 production 導入的時機。 3. **兩個協議互補：MCP 管 agent-to-tool，A2A 管 agent-to-agent**。它們一起構成了 agentic engineering 基礎設施的兩根支柱。MCP 是今天就能用的，A2A 是為明天準備的。 --- *上一篇：[CLAUDE.md 大師班](/blog/claude-md-rules-files-masterclass)* *下一篇：[Multi-Agent 編排實戰](/blog/multi-agent-orchestration-real-world)*Agentic EngineeringMCPA2AAI Protocol工具整合https://bobochen.dev/blog/claude-md-rules-files-masterclass/https://bobochen.dev/blog/claude-md-rules-files-masterclass/CLAUDE.md 不是寫一次就不管的 README。經過一年的迭代，設定檔系統已經從單一檔案演化成多層架構——global、per-project、per-task、per-tool。分享完整的設定檔架構設計、版本演化歷程、和維護心得。Fri, 01 May 2026 00:00:00 GMT> 這是「Agentic Engineering 實戰手冊」系列的第八篇。上一篇：[Prompt 到 Production](/blog/agentic-engineering-daily-workflow-advanced) ## 我的 ~/.claude/ 目錄下有 47 個設定檔 一年前，我的整個 agent 設定就是一個 CLAUDE.md，裡面寫了三行：build command、test command、和「請用 TypeScript」。 現在？47 個設定檔。Global CLAUDE.md、12 個專案的 project CLAUDE.md、23 個 skills、hooks 設定、memory system。這不是因為我喜歡寫設定檔，是因為一個檔案真的不夠用。 但你不需要從 47 個檔案開始。這篇分享的是這套系統怎麼一步步長出來的，以及你在每個階段需要什麼、不需要什麼。 ## 從一個檔案到一套系統 ### 問題浮現的時刻 **問題 1：跨專案衝突** 我同時在做一個 Astro 部落格和一個 Next.js 專案。Global CLAUDE.md 裡寫了「用 Astro 的 file-based routing」，結果在 Next.js 專案裡 agent 也嘗試用 Astro 的方式處理 routing。 → **需要 per-project 設定。** **問題 2：CLAUDE.md 太長** 有一陣子我的 project CLAUDE.md 膨脹到了 400 行。裡面什麼都有——build 指令、coding conventions、deploy 流程、specific component 的使用方式。結果 agent 的行為變得不穩定——有時候遵循 convention A，有時候遵循 convention B。 原因是 [Context Engineering](/blog/context-engineering-deep-dive) 裡提到的 "Lost in the Middle" 效應：CLAUDE.md 中間的指令比頭尾更容易被忽略。 → **需要拆分，讓每份檔案都精簡。** **問題 3：重複的工作流** 我發現自己經常在不同專案裡跟 agent 說同樣的事：「先跑 linter」、「commit 前做 review」、「用 conventional commits 格式」。每次新開一個 session 都要重複。 → **需要可重用的 skill 模組。** ## 設定檔層級架構 經過一年的演化，我的設定檔系統有四個層級： ``` ~/.claude/CLAUDE.md ← Global：所有專案通用 └── project/CLAUDE.md ← Project：專案特定 └── .claude/rules/*.md ← Rules：場景特定 └── skills/*.md ← Skills：可觸發的工作流 ``` ### Layer 1: Global CLAUDE.md（~100 行） 位置：`~/.claude/CLAUDE.md` 放什麼： - **開發哲學**：incremental progress、composition over inheritance、test-driven - **通用 conventions**：prefer TypeScript、conventional commits、no --no-verify - **工具偏好**：prefer npm over yarn、GitHub CLI for CI/CD - **行為規範**：不要自動 git push、不要自動加 emoji、stop after 3 failed attempts 不放什麼： - 任何專案特定的技術棧或 build 指令 - 任何會跟其他專案衝突的規則 **原則**：如果這條規則適用於你所有的專案，放 global。否則，放 project。 ### Layer 2: Project CLAUDE.md（~50 行） 位置：project root 的 `CLAUDE.md` 放什麼： - **Build/test/dev 指令**：`npm run dev`、`npm run build`、`npm run test` - **技術棧**：Astro 5 + MDX + Tailwind CSS 4 + TypeScript - **專案結構**：key directories 和 file conventions - **專案特有的慣例**：命名規則、component patterns、design tokens 我的 bobo-blog-2026 的 CLAUDE.md 大概長這樣： ```markdown # CLAUDE.md ## Commands npm run dev # Start dev server at localhost:4323 npm run build # Build production site to ./dist/ ## Architecture Stack: Astro 5 + MDX + Tailwind CSS 4 + TypeScript - src/pages/ — File-based routing - src/content/blog/ — MDX blog posts - src/components/ — Astro components (PascalCase) - src/layouts/ — BaseLayout.astro, BlogLayout.astro ## Content Schema Blog posts require: title, description, pubDate Optional: tags, featured, image, draft ## Theme System CSS Custom Properties: --color-_, --glass-_, --radius-\* Dark mode: .dark class on <html> ## Conventions - lang="zh-TW" - Component files: PascalCase - Use existing CSS custom properties over hardcoded values ``` 50 行以內。每一行都跟這個專案直接相關。 **關鍵原則**：Project CLAUDE.md 應該被 commit 進 git。它是專案文件的一部分，就像 README.md 或 tsconfig.json 一樣。團隊成員 pull 下來就能用。 ### Layer 3: Rules Files（按場景分） 位置：`.claude/rules/*.md` Rules files 是「場景特定的 context」——不是每次都需要，但在特定情境下很重要的指令。 例子： - `testing-rules.md`：「test 要用 vitest、prefer integration test over unit test、mock 只在必要時使用」 - `deploy-rules.md`：「deploy 到 Cloudflare Workers、使用 wrangler.jsonc、先 deploy staging 再 production」 - `content-rules.md`：「部落格文章用繁中、frontmatter 必須有 title/description/pubDate」 什麼時候用 rules file 而不是 CLAUDE.md？當一條規則只在特定類型的任務中需要。如果你在寫測試的時候才需要知道 testing conventions，那它應該在 `testing-rules.md`，不是在每次 session 都會載入的 CLAUDE.md。 ### Layer 4: Skills（可觸發的工作流） 位置：`~/.claude/skills/skill-name/SKILL.md` Skills 是 CLAUDE.md 的「按需版」——你用 `/skill-name` 觸發，它才會被載入到 context。 為什麼需要 skills？因為有些工作流太複雜、太長、而且不是每次都需要。比如 pre-commit review 的 4-agent 並行 review 流程，有 200 行的指令——這些如果放在 CLAUDE.md 裡，每個 session 都會佔用 context window，但 90% 的時間根本用不到。 我目前有 23 個 skills，大致分四類： | 類別 | 數量 | 例子 | | ---------- | ---- | -------------------------------------------------------------------------- | | 開發工作流 | 8 | `commit`、`pre-commit-review`、`iterative-tdd-loop`、`self-healing-deploy` | | 內容創作 | 7 | `content-research-writer`、`lesson-to-blog`、`translation-zh-tw` | | 寫作風格 | 5 | `will-pao-style`、`fireship-style`、`lenny-newsletter-style` | | 工具自動化 | 3 | `gcp-log-check`、`notion-workflow-bobo`、`wordhunter-image-processor` | ### 四層的優先順序 當多層設定有衝突時，優先順序是： ``` Skills（最高） > Rules > Project CLAUDE.md > Global CLAUDE.md（最低） ``` 這跟 CSS 的 specificity 邏輯一樣：越具體的越優先。Global 是預設值，project 覆蓋 global，rules 覆蓋 project，skills 覆蓋一切。 ## Skills 系統深入 一個好的 skill 有三個部分： ### 1. Trigger Condition 什麼時候觸發？寫在 `description` field 裡： ```yaml description: > Smart git commit skill. Triggers on "commit", "/commit", "幫我 commit", "提交", or any request to create a git commit. ``` 這讓 Claude Code 知道什麼時候該自動載入這個 skill。 ### 2. Step-by-Step Instructions 具體怎麼執行： ```markdown ## Step 1: Gather Context (parallel) Run: git status, git diff --cached, git log --oneline -10 ## Step 2: Stage Check Confirm staging is correct... ## Step 3: Draft Commit Message Analyze diff, follow conventional commits... ## Step 4: Execute Use HEREDOC format... ``` ### 3. Safety Rules 什麼不能做： ```markdown ## Safety Rules - NEVER use --no-verify - NEVER use --amend on pushed commits - NEVER auto-push - NEVER commit .env files ``` ### Skills vs CLAUDE.md 的選擇 | 情境 | 放哪裡 | | ---------------------- | -------------------------- | | 每次 session 都需要 | CLAUDE.md | | 特定類型任務才需要 | Rules file | | 需要明確觸發的工作流 | Skill | | 很少用、但用到時很關鍵 | Skill | | 團隊共用的慣例 | CLAUDE.md（commit 進 git） | | 個人的工作偏好 | Global CLAUDE.md 或 Skill | ## 知識放哪裡的決策框架 這是我在一年中最常遇到的問題：「這個資訊應該放在哪裡？」 以下是我的決策樹： ``` 這個知識... ├── 每次 session 都需要？ │ ├── 是 → 所有專案都需要？ │ │ ├── 是 → Global CLAUDE.md │ │ └── 否 → Project CLAUDE.md │ └── 否 │ ├── 特定任務類型需要？ │ │ ├── 是 → Rules file 或 Skill │ │ └── 否 │ │ ├── 跨 session 需要記住？ │ │ │ ├── 是 → Memory system │ │ │ └── 否 → 不需要持久化 │ │ └── 專案文件已有？ │ │ ├── 是 → 不要重複（讓 agent 自己讀） │ │ └── 否 → 考慮加到 README 或 docs/ │ └── 給人看的？ │ └── 是 → README / docs/ ``` **核心原則**：不要重複。如果 `package.json` 裡已經有 build script，不要在 CLAUDE.md 裡複製。如果 `tsconfig.json` 已經定義了 TypeScript 設定，不要在 CLAUDE.md 裡再寫一次。Agent 有能力讀這些檔案。 CLAUDE.md 放的應該是那些**檔案裡看不出來的隱性知識**——比如「我們偏好 composition over inheritance」或「deploy 前一定要先跑 staging」。 ## 維護的藝術：設定檔也需要重構 ### 定期 Review 設定檔跟 code 一樣，會腐化。三個月前加的一條 rule，可能因為 codebase 已經改了而不再需要。 **我的習慣**：每月花 30 分鐘做一次「設定檔 review」。具體做什麼： 1. 讀一遍 CLAUDE.md，刪掉過時的內容 2. 看最近一個月 agent 犯過什麼重複的錯——需要加 rule 嗎？ 3. 看 skills 的使用頻率——完全沒用過的 skill 考慮歸檔 4. 確認多個設定檔之間沒有矛盾 ### Version Control **CLAUDE.md 應該被 commit 進 git**——這不只是最佳實踐，是必要的： 1. 團隊成員 clone 下來就能用 2. 可以 track 變更歷史 3. 可以 code review 4. 跟 codebase 保持同步 `~/.claude/CLAUDE.md`（global）不需要 commit——那是你個人的偏好設定。但 project CLAUDE.md 一定要。 ### 團隊共用的考量 當團隊共用同一份 CLAUDE.md 時，注意： - **避免主觀規則**：「程式碼要寫得漂亮」是主觀的；「函數不超過 50 行」是客觀的 - **避免個人偏好**：你喜歡 semicolons，同事不喜歡——這種交給 ESLint 處理 - **建立修改流程**：修改 CLAUDE.md 也需要 PR review，就像修改 ESLint config 一樣 ## Anti-patterns：太長、太嚴格、太模糊 ### Anti-pattern 1：太長（>300 行） **症狀**：CLAUDE.md 超過 300 行，什麼都寫在裡面。 **問題**：Agent 的注意力被稀釋。中間的指令可能被忽略（Lost in the Middle）。每次 session 啟動時，大量 token 被設定檔佔用。 **修正**： - 拆到 rules files 和 skills - 刪掉可以從 codebase 推斷出來的資訊 - 刪掉過時的資訊 - 目標：Project CLAUDE.md < 100 行 ### Anti-pattern 2：太嚴格 **症狀**：規則寫得太死——「每個函數不能超過 10 行」、「每個模組不能超過 5 個 export」、「所有變數必須用全名不能縮寫」。 **問題**：Agent 會為了遵守規則而寫出更爛的 code。為了讓函數不超過 10 行，它把一個清晰的函數拆成 5 個意義不明的小函數。為了不縮寫，它寫出 `currentlyAuthenticatedUserEmailAddress` 這種變數名。 **修正**：用 guideline 取代 hard rule。「函數盡量保持短小」比「函數不能超過 10 行」好。給 agent 判斷空間，讓它在合理範圍內做決策。 ### Anti-pattern 3：太模糊 **症狀**：「寫好的 code」、「遵循最佳實踐」、「保持 code 品質」。 **問題**：等於沒說。Agent 會用它 training data 裡的「最佳實踐」，那可能跟你的專案完全不合。 **修正**：具體。「用 Tailwind utility classes，不要寫 custom CSS」比「遵循專案的 CSS 慣例」明確 100 倍。 ### Anti-pattern 4：矛盾 **症狀**：Global CLAUDE.md 說「用 tabs」，Project CLAUDE.md 說「用 spaces」。或者 rules 裡說「prefer functional components」，但 CLAUDE.md 說「follow existing patterns」（而 existing patterns 有 class components）。 **問題**：Agent 隨機選一個，或者更糟，在同一個 PR 裡兩種都用。 **修正**： 1. 建立明確的 override 規則（project > global） 2. 定期交叉檢查不同層級的設定 3. 一條規則只在一個地方定義 ## 讀者範本：從零開始的三階段路線圖 ### Week 1：基礎版（5 行） ```markdown # CLAUDE.md ## Commands npm run dev npm run build npm run test ## Stack TypeScript + [你的框架] ``` 就這麼多。這 5 行就能讓 agent 知道怎麼跑你的專案。 ### Month 1：進階版（30 行） ```markdown # CLAUDE.md ## Commands npm run dev # Start dev server npm run build # Build production npm run test # Run tests ## Architecture Stack: [框架] + [語言] + [CSS 方案] - src/pages/ — Routes - src/components/ — UI components (PascalCase) - src/lib/ — Utilities and helpers ## Conventions - Language: [zh-TW / en] - Naming: [PascalCase components, camelCase functions] - Use [design tokens / CSS variables] over hardcoded values - Prefer [composition over inheritance] ## Key Patterns - [列出 2-3 個專案裡最常用的 pattern] - [比如：所有 API endpoints 在 /api/ 目錄下] - [比如：用 Zod 做 input validation] ``` 這 30 行涵蓋了 agent 最常需要的資訊。 ### Month 3：完整系統 ``` ~/.claude/CLAUDE.md ← 你的開發哲學（~50 行） project/CLAUDE.md ← 專案技術棧和慣例（~50 行） .claude/rules/testing.md ← 測試規範 .claude/rules/deploy.md ← 部署流程 ~/.claude/skills/commit/ ← git commit 工作流 ~/.claude/skills/review/ ← pre-commit review ``` 不需要一次建好。每次你發現 agent 重複犯同一種錯、或你重複跟 agent 說同一件事的時候，那就是該加一條 rule 或一個 skill 的時機。 **從少開始，需要時再加。CLAUDE.md 是有機生長的文件，不是一次性的架構設計。** ## Takeaway 1. **CLAUDE.md 不是寫一次就忘記的文件**——它是你跟 agent 的持續溝通管道。像 code 一樣，它需要被 version control、被 review、被定期維護。過時的 CLAUDE.md 比沒有 CLAUDE.md 更糟，因為它會誤導 agent。 2. **好的設定檔系統是分層的**——Global（所有專案通用）→ Project（專案特定）→ Rules（場景特定）→ Skills（按需觸發）。每一層有各自的職責，避免一個檔案什麼都放。 3. **從三行開始就好**——build、test、tech stack。隨著需要自然成長。如果 agent 重複犯同一種錯，加一條 rule。如果你重複跟 agent 說同一件事，加一個 skill。47 個設定檔是 12 個月累積的結果，不是一天建好的。 --- _上一篇：[Prompt 到 Production](/blog/agentic-engineering-daily-workflow-advanced)_ _下一篇：[MCP 與 A2A 協議實戰](/blog/mcp-a2a-protocols-practitioner-guide)_Agentic EngineeringCLAUDE.mdClaude CodeAI設定管理https://bobochen.dev/blog/agentic-engineering-daily-workflow-advanced/https://bobochen.dev/blog/agentic-engineering-daily-workflow-advanced/一個真實的功能需求，從收到 ticket 到最終 deploy，全程用 agentic workflow 完成——包含完整的 prompt、agent 的回應、review 過程、CI 結果、和最後的 deploy log。零理論，純實戰。Fri, 24 Apr 2026 00:00:00 GMT> 這是「Agentic Engineering 實戰手冊」系列的第七篇。上一篇：[Agent 產出品質保證](/blog/agent-output-verification-review) ## 這篇沒有理論，只有一個完整的實戰紀錄 前幾篇我們聊了 [Context Engineering](/blog/context-engineering-deep-dive)、[Spec-Driven Development](/blog/spec-driven-development-for-agents)、[品質保證](/blog/agent-output-verification-review)。每篇都有它的理論框架。 但理論歸理論，你可能最想看的是實際操作起來到底長什麼樣。 這篇就是答案。一個真實的 feature request——在 Astro 部落格裡加上「文章閱讀進度條」和「預估閱讀時間」功能。從收到需求到 deploy 上 production，我會把每一個步驟、每一段 prompt、每一次 agent 回應、每一次我介入的時刻都記錄下來。 ## 任務背景 **需求來源**：我自己在分析部落格的 analytics 時發現，長文的跳出率偏高。假設之一是讀者不知道文章有多長、讀到哪裡了，缺乏「進度感」。 **功能描述**： 1. 頁面頂部顯示閱讀進度條（scroll-based progress bar） 2. 文章開頭顯示預估閱讀時間（estimated reading time） 3. 只在 blog post 頁面顯示，其他頁面不要 **複雜度評估**：中等。涉及一個新 component、一段 client-side JS、一個 build-time 計算。不是 trivial，但也不需要架構重構。 **為什麼選這個任務示範**：它有代表性——有 UI component、有邏輯計算、有跨 layer 的整合（build-time + client-side）。而且它有明確的決策點和至少一次 iteration。 ## Step 1: Spec 撰寫（8 分鐘） 根據 [Post 5](/blog/spec-driven-development-for-agents) 的 template，我花 8 分鐘寫了這份 spec： ```markdown ## Task: Blog Reading Progress & Estimated Read Time ### Goal 在 blog 文章頁面加兩個功能： 1. 頁面頂部固定的閱讀進度條（隨滾動更新） 2. 文章 metadata 區塊顯示預估閱讀時間 ### Context - Astro 5 + MDX + Tailwind CSS 4 + TypeScript - Blog layout: src/layouts/BlogLayout.astro - 現有 design tokens: --color-primary, --color-bg-primary - Dark mode 透過 .dark class 切換 - 已有 View Transitions，注意 script 在導航後要重新綁定 ### Constraints - 不引入任何 npm dependency - 進度條用 CSS custom properties + Tailwind - 閱讀時間在 build time 計算，不在 client side - 中文內容以每分鐘 400 字計算（非英文的 200 wpm） - 進度條只在 blog post 頁面出現 - 進度條不能蓋住 navigation bar ### Files to modify - src/layouts/BlogLayout.astro（加入 component） - 可新增 src/components/blog/ReadingProgress.astro - 可新增 src/components/blog/ReadingTime.astro ### Verification Criteria 1. 滾動頁面時，頂部進度條從 0% 填充到 100% 2. 進度條在到達文章底部時是 100%，在頂部是 0% 3. 顯示格式：「約 N 分鐘閱讀」 4. 2000 字文章 → 顯示「約 5 分鐘閱讀」 5. Dark mode 下進度條顏色正確 6. 在非 blog 頁面（如 /about）不顯示進度條 7. npm run build 通過，無 TypeScript 錯誤 ### Out of Scope - 不做 reading analytics（不追蹤用戶實際閱讀行為） - 不做 bookmark / save progress 功能 - 不做 table of contents（之後另外做） ``` **關鍵決策標注**： - 中文 400 字/分鐘而非英文 200 wpm——這個如果不寫，agent 一定會用英文標準算 - 「不引入 npm dependency」——防止 agent 引入 reading-time 之類的 library - 「進度條不能蓋住 navigation bar」——這是一個很容易被忽略的 UI 細節 - View Transitions 相關的提醒——Astro 的 View Transitions 會在頁面導航後讓 client-side script 失效，agent 需要知道這個 gotcha ## Step 2: Context 準備（3 分鐘） CLAUDE.md 已經有了大部分必要的 context（tech stack、project structure、conventions）。額外需要的只有兩件事： 1. 讓 agent 看一下 `BlogLayout.astro` 的現有結構，知道 component 要插在哪裡 2. 確認 design tokens 的變數名 這些不需要我手動貼——agent 會自己 `Read` 相關檔案。但在 spec 裡提到「design tokens: --color-primary」是有幫助的，讓 agent 知道去找什麼。 ## Step 3: Agent 執行（Hands-off, 25 分鐘） 我把 spec 貼給 Claude Code，然後做了一件很重要的事——離開電腦去倒咖啡。 不是因為我不在乎，是因為 agent 沒人干預的時候通常做得更好。你如果一直盯著它、中途插嘴「等等那個不對」，反而會打斷它的 execution flow。 以下是 agent 的工作 log（摘要）： ### Agent 行動記錄 **00:00-02:00** — 探索 codebase ``` Agent: 讀取 BlogLayout.astro... 了解現有結構 Agent: 讀取 global.css... 找到 design tokens Agent: 讀取 BaseLayout.astro... 了解 nav 的 position Agent: 讀取已有的 blog component... 理解命名慣例 ``` **02:00-08:00** — 建立 ReadingProgress.astro ``` Agent: 建立 src/components/blog/ReadingProgress.astro - Fixed position bar at top of page - Uses --color-primary for fill color - z-index lower than nav bar - Client-side script for scroll tracking - Handles View Transitions with astro:after-swap ``` **08:00-14:00** — 建立 ReadingTime.astro ``` Agent: 建立 src/components/blog/ReadingTime.astro - Receives body content as prop - Strips HTML/MDX tags, counts Chinese characters - Calculates: Math.ceil(charCount / 400) - Displays "約 N 分鐘閱讀" ``` **14:00-20:00** — 整合到 BlogLayout.astro ``` Agent: 修改 BlogLayout.astro - Import ReadingProgress + ReadingTime - ReadingProgress placed after nav, before main content - ReadingTime placed in article header metadata section - Passes compiled content body to ReadingTime for word count ``` **20:00-25:00** — 自我驗證 ``` Agent: npm run build... ✅ 通過 Agent: 檢查 TypeScript... ✅ 無錯誤 Agent: 在 dev server 確認 progress bar 行為... ``` 整個過程 25 分鐘。Agent 做了我預期的所有事情，加上一個我沒想到但很好的細節：它在 progress bar 上加了 `transition: width 100ms ease` 讓滾動更平滑。 ## Step 4: Review & 迭代（12 分鐘） 咖啡泡好了，回來看 agent 的產出。 ### 第一輪 Review：發現兩個問題 **問題 1**：ReadingTime 的字數計算有 bug Agent 的做法是先 strip HTML tags 再計算中文字數。邏輯上對，但它用的 regex 沒有處理 MDX component tags（像 `<CodeBlock>...</CodeBlock>`）。這些 tag 的內容會被計入字數，導致閱讀時間偏長。 **問題 2**：Progress bar 在手機上太粗 Agent 設了 4px 高度，在桌面上剛好，在手機上佔了太多視覺空間。 ### Feedback Prompt ``` 兩個修正： 1. ReadingTime 的字數計算：MDX component tags 的內容也被計入了。 strip HTML 的 regex 需要同時處理 <ComponentName>...</ComponentName> 這種 self-closing 和 pair 的 MDX tags。或者更簡單的做法： 用 Astro 的 compiledContent 而不是 rawContent。 2. Progress bar 高度：桌面 4px OK，手機改成 3px。 用 Tailwind 的 responsive: h-[3px] md:h-[4px] ``` 注意我的 feedback 方式： - **具體描述問題**，不是說「這個不對」 - **給出可能的修正方向**，但不規定具體做法 - 第一個問題提了兩個可能的方向（改 regex 或換 API），讓 agent 選更適合的 ### 第二輪：Agent 修正 Agent 選了「用 `compiledContent` 而不是 `rawContent`」的方案（更簡潔），修改了 progress bar 的 responsive height。 3 分鐘完成。重新跑 `npm run build`，通過。 ## Step 5: CI/CD & Deploy 代碼完成，進入自動化流程： ```bash # Commit git add src/components/blog/ReadingProgress.astro \ src/components/blog/ReadingTime.astro \ src/layouts/BlogLayout.astro git commit -m "feat(blog): add reading progress bar and estimated reading time - Fixed progress bar at page top, scroll-synced 0-100% - Reading time calculated at build time (400 chars/min for zh-TW) - Responsive height: 3px mobile, 4px desktop - Handles Astro View Transitions correctly" ``` Push → GitHub Actions → Cloudflare Workers deploy。 CI 跑了 2 分鐘： - TypeScript check ✅ - ESLint ✅ - Build ✅ - Deploy to staging ✅ 在 staging 快速驗證： - 長文（3000 字）→ 顯示「約 8 分鐘閱讀」 ✅ - 滾動 → progress bar 正確填充 ✅ - Dark mode → 顏色正確 ✅ - /about 頁面 → 沒有 progress bar ✅ - 手機寬度 → 3px 高度 ✅ Deploy to production。完成。 ## 時間對比：60 分鐘 vs 以前的半天 ### 這次的 Agentic Workflow | 步驟 | 時間 | 誰做的 | | --------------- | ------------ | ------------------- | | 寫 Spec | 8 分鐘 | 我 | | Context 準備 | 3 分鐘 | 我 | | Agent 執行 | 25 分鐘 | Agent（我去倒咖啡） | | Review | 7 分鐘 | 我 | | Feedback + 修正 | 5 分鐘 | 我 + Agent | | CI/CD + 驗證 | 12 分鐘 | 自動化 | | **總計** | **~60 分鐘** | | ### 如果用傳統方式 | 步驟 | 時間 | | ---------------------------- | ----------- | | 理解需求 + 研究做法 | 30 分鐘 | | 寫 ReadingProgress component | 45 分鐘 | | 寫 ReadingTime component | 30 分鐘 | | 整合到 BlogLayout | 20 分鐘 | | 處理 View Transitions | 30 分鐘 | | 寫 CSS / responsive | 20 分鐘 | | 測試 + debug | 45 分鐘 | | CI/CD + 驗證 | 12 分鐘 | | **總計** | **~4 小時** | **4x 的時間差**。而且注意，在 agentic workflow 裡，我的「工作時間」只有 ~23 分鐘（寫 spec + review + feedback），其他時間都是 agent 和 CI 在工作。 ### 但不是每個任務都這麼理想 公平地說，這是一個「適合 agentic workflow」的任務——需求明確、scope 有限、技術棧 agent 很熟。 以下是 agentic workflow **不太適合**的情況： | 場景 | 原因 | 建議 | | ----------------------------- | ------------------------------- | ---------------------------- | | 全新的架構設計 | Agent 不知道你的業務 constraint | 你先設計，agent 來實作 | | 跨多個 repo 的變更 | Context 太分散 | 拆成每個 repo 一個 task | | Debug 未知的 production issue | 需要即時互動和直覺 | 你帶頭，agent 輔助 | | 涉及敏感權限的操作 | 安全風險 | 你自己做，agent 不碰 | | 第三方 API 整合（文件不完整） | Agent 可能 hallucinate API | 你先確認 API，agent 來寫整合 | ## 每個決策點的標注 回顧整個流程，有幾個關鍵的決策點值得標記： ### 決策 1：寫 Spec 還是直接叫 Agent 做？ **選擇**：寫 Spec。 **原因**：這個功能涉及 UI + 計算 + 整合，如果不寫 spec，agent 很可能做出我不想要的東西（比如用 npm library、用英文 wpm、progress bar 蓋住 nav）。8 分鐘的 spec 投資，預防了至少 1 小時的拆除工作。 ### 決策 2：離開電腦 vs 盯著 Agent 做 **選擇**：離開。 **原因**：過去的經驗告訴我，中途干預通常讓事情變慢而不是變快。讓 agent 完整跑一輪，然後統一 review 和 feedback，比每幾分鐘插嘴一次快很多。 ### 決策 3：怎麼給 Feedback **選擇**：描述問題 + 給方向，不規定做法。 **原因**：「用 compiledContent 而不是 rawContent」是一個 hint，不是指令。Agent 有能力判斷哪種做法更適合——事實上它選了更乾淨的方案。如果我硬是叫它改 regex，它也會照做，但那可能不是最好的解法。 ### 決策 4：這個 PR 是合成一個還是拆兩個？ **選擇**：合成一個。 **原因**：ReadingProgress 和 ReadingTime 雖然是兩個 component，但它們服務同一個 feature，而且修改的文件有重疊（都要改 BlogLayout.astro）。拆成兩個 PR 反而增加 overhead。 ## 流程的核心公式 把整個流程提煉成一個公式： ``` Agentic Workflow = 高品質 Spec（10 分鐘） + 充足 Context（CLAUDE.md + codebase） + Hands-off 執行（讓 agent 完整跑一輪） + 精準 Review（focus 在 agent 特有的錯誤模式） + 快速 Feedback Loop（描述問題 + 給方向） ``` 每一步都不難。難的是**紀律**——在你想偷懶直接打「幫我加一個功能」的時候，花 10 分鐘寫一份好的 spec。在你想中途插嘴的時候，忍住去倒杯咖啡。在你覺得「agent 的 code 看起來很專業不用看了」的時候，還是打開 diff 仔細 review 一遍。 這個紀律，就是 Agentic Engineering 和 Vibe Coding 的分界線。 ## Takeaway 1. **Agentic workflow 的核心是「前置投資」**——Spec 和 Context 的品質決定後續效率。8 分鐘的 spec + 3 分鐘的 context 準備，讓 25 分鐘的 agent 執行幾乎零障礙。 2. **60 分鐘完成以前半天的工作，靠的不是魔法，是方法論**——但前提是任務適合 agentic workflow、你的 spec 夠好、你的 CI 夠完善。不是所有任務都適合。 3. **最重要的技能不是寫 prompt，是知道什麼時候介入、什麼時候放手**——讓 agent 完整跑一輪再統一 review，比每隔幾分鐘干預一次更有效率。你的角色是 reviewer 和 direction-setter，不是 co-pilot seat 的指揮官。 --- _上一篇：[Agent 產出品質保證](/blog/agent-output-verification-review)_ _下一篇：[CLAUDE.md 與 Rules Files 大師班](/blog/claude-md-rules-files-masterclass)_Agentic Engineering工作流程AICICD實戰紀錄https://bobochen.dev/blog/agent-output-verification-review/https://bobochen.dev/blog/agent-output-verification-review/Agent 寫的 code 看起來很專業，但你怎麼知道它是對的？建立一套 agent output 的品質保證流程——從 CI 自動化驗證、人工 review 的重點、到最重要的心態：永遠假設 agent 的 code 有 bug。Fri, 17 Apr 2026 00:00:00 GMT> 這是「Agentic Engineering 實戰手冊」系列的第六篇。上一篇：[Spec-Driven Development](/blog/spec-driven-development-for-agents) ## 那個不存在的 Database Column 我曾經讓 agent 寫了一個看起來完美的 API endpoint。Code 結構清晰、error handling 完整、連 Swagger 文件都自動加了。PR review 時同事看了也說「不錯」。 上線之後，第一個 request 就 500 了。 原因是 agent 在 SQL query 裡引用了一個叫 `user_preferences` 的 column，而這個 column 在我們的 database schema 裡根本不存在。它大概是從 training data 裡某個類似的 schema 推斷出來的。 最可怕的不是 bug 本身，而是它看起來太像真的了。Column 名稱合理、query 語法正確、連 JOIN 的邏輯都對，除了那個 column 是虛構的。如果不是上線後第一個 request 就爆，可能在 staging 跑幾天都沒人發現，因為 staging 的數據量小，那個 query path 可能根本沒被觸發。 這件事教了我一個血淋淋的教訓：Agent 的 code 最危險的地方不是它寫得差，是它寫得太好了，好到讓你降低了戒心。 ## Trust But Verify：Agent Code 為什麼特別需要 Review Simon Willison（Django 共同創辦人，AI 工具的重度使用者和評論者）說過一句讓我印象深刻的話： > 「不要提交你沒有 review 過的 code 的 pull request——無論那段 code 是你寫的還是 AI 寫的。」 這聽起來是常識，但實際操作起來很難做到，因為 agent 產出的 code 有一個特殊的心理效應：**它看起來非常專業**。 人類寫的 code 通常有明顯的「風格」——有的人變數名取得好、有的人 error handling 做得糙、有的人 comment 寫得多。你看了幾秒就能判斷「這段 code 品質如何」。 Agent 的 code 不一樣。它永遠有完整的 error handling、有意義的變數名、一致的格式、甚至還有 JSDoc 註解。它看起來像資深工程師寫的 code。這讓你的大腦自動進入「這個人的 code 品質不錯」的信任模式。 但 agent 的 bug 跟人類的 bug 根本不是同一種。 | | 人類的 bug | Agent 的 bug | | -------------------- | ---------------------------------- | ------------------------------------- | | **出錯層級** | 邏輯層 | 事實層 | | **典型例子** | Off-by-one、邊界條件沒處理 | 引用不存在的 API、fabricated column | | **容易發現嗎** | 比較容易（邏輯不對會「看起來怪」） | 很難（看起來完全正確） | | **傳統測試能抓到嗎** | 通常可以 | 不一定（如果測試本身也是 agent 寫的） | 人類搞混 `<=` 和 `<`，你盯著看就能發現。Agent 自信滿滿地用了一個不存在的 API endpoint，你光看 code 根本看不出來，因為 endpoint URL 的格式完全正確，只是那個路徑在你的系統裡不存在。 這就是為什麼「trust but verify」在 agent 時代不只是好習慣，而是必要的紀律。 ## 自動化護欄：讓機器先幫你擋一層 好消息是，很多 agent 的基本錯誤可以被自動化工具攔截。而且這些工具你本來就應該有。 ### Pre-commit Hooks 在 agent 時代，pre-commit hooks 的 ROI 翻倍了。以前它們主要是「提醒人類注意格式」，現在它們是「攔截 agent 的基本錯誤」： ```bash # 我的 pre-commit hook 幫我擋過的 agent 錯誤 - TypeScript 類型錯誤（agent 用了不存在的 type） - ESLint 違規（agent 用了 var 而不是 const） - Import 循環（agent 不知道我們的 module boundary） - 意外的 console.log（agent 習慣性加 debug log） ``` **重點**：永遠不要讓 agent 用 `--no-verify` bypass hooks。這是你的第一道防線。 ### CI Pipeline CI 是你的第二道防線，也是最可靠的那一道： 1. **Type checking**（`tsc --noEmit`）——抓 agent 用了不存在的 type、interface 定義不匹配 2. **Unit tests**——抓邏輯錯誤（但注意：如果 test 也是 agent 寫的，可能有共同盲點） 3. **Integration tests**——抓 agent 對外部系統的假設錯誤（像那個不存在的 column） 4. **Lint**——抓 coding convention 違規 5. **Security scanning**——抓 agent 引入的潛在安全漏洞 這些「傳統工具」在 agent 時代的價值不減反增，它們免費幫你抓 agent 的基本錯誤，而且不會疲勞、不會被「看起來很專業」的 code 給騙過。 ### Static Analysis：比你想的更重要 TypeScript strict mode 是 agent coding 的最佳拍檔。它強制 agent： - 正確處理 `null` 和 `undefined` - 明確標註所有的 type - 不能用 implicit any 以前你可能覺得 strict mode 太煩了，到處要加 type assertion。但現在它幫你攔截了 agent 一大堆「看起來對但 type 不對」的 code。 **ROI 翻倍定律**：在傳統開發裡，這些工具是 nice-to-have。在 agent 時代，它們是 prerequisites。如果你的專案還沒有 CI、沒有 type checking、沒有 linting——現在就是設定它們的最好時機。 ## Human Review 的 80/20：看什麼、忽略什麼 你不需要（也不應該）逐行 review agent 的每一行 code。那太慢了，而且很多 boilerplate code review 起來沒有意義。 ### 重點看的四件事 **1. 架構決策** Agent 選了什麼設計模式？建了新的 module 還是擴展現有的？引入新的 abstraction 了嗎？ 這些是 agent 最容易做出「合理但不適合」的決策的地方。它可能在你不需要的時候引入了 factory pattern、建了一個不必要的 service layer、或把應該是 utility function 的東西變成了一個 class。 **2. 邊界條件** 空值怎麼處理？array 為空時呢？API timeout 呢？concurrent access 呢？ Agent 通常會處理「happy path」很好，但在邊界條件上可能做出不合理的假設——比如假設某個 API 一定會回資料、假設某個 array 一定有元素。 **3. 安全性** 有沒有 SQL injection 的風險？用戶輸入有沒有 sanitize？有沒有暴露敏感資訊？ Agent 在安全方面的表現參差不齊。它通常知道要用 parameterized queries，但可能在比較隱蔽的地方忘記——比如動態拼接 SQL 的 ORDER BY clause。 **4. 業務邏輯正確性** 這個邏輯在商業意義上對嗎？不只是 code 能不能跑，是它的行為是不是你期望的？ Agent 可能完美地實作了你 spec 裡寫的邏輯——但如果你的 spec 有遺漏，agent 不會幫你補。它不懂你的業務。 ### 可以快速掃的 - **Boilerplate code**：imports、exports、standard config - **Formatting**：這是 linter 的工作，不是你的 - **Standard patterns**：如果 agent 用了你 codebase 裡已有的 pattern，快速掃過就好 ### Agent PR vs 人類 PR 的 Review 重點不同 | Review 重點 | 人類 PR | Agent PR | | ------------------- | ---------- | ------------------ | | 偷懶 / 走捷徑 | 要注意 | 不太需要 | | 過度設計 | 偶爾 | **經常** | | 事實性錯誤 | 少見 | **常見** | | 不存在的 API/method | 幾乎不會 | **一定要查** | | 風格一致性 | 通常沒問題 | 可能跟專案風格不同 | | 安全漏洞 | 偶爾 | **要特別注意** | ## TDD x Agent：目前最可靠的品質保證模式 經過一年的實驗，我找到了一個可靠度最高的工作模式：**你寫 test，agent 寫 implementation**。 工作流程： ``` 你 → 寫 test cases（基於 spec 的 verification criteria） ↓ Agent → 跑 test，看到 red（全部失敗） ↓ Agent → 寫 implementation ↓ Agent → 跑 test，看到 green（全部通過） ↓ 你 → review implementation（已知行為正確，focus 在設計和安全） ``` 為什麼這個模式可靠？ 1. **Test 是你的 verification criteria 的程式碼版本**——agent 不可能「看起來對但其實錯」，因為 test 會直接告訴它對不對 2. **你控制了「正確」的定義**——你寫 test，所以你決定什麼是正確的行為。Agent 負責實現，但不負責定義。 3. **Review 變得更輕鬆**——你已經知道功能行為是正確的（test 通過了），review 只需要關注設計品質和安全性。 4. **降低 hallucination 的影響**——即使 agent 用了不存在的 API，test 跑下去一定會失敗，agent 就被迫換一個真正能用的方法。 ### 實際操作範例 我要加一個 `formatRelativeDate` function： **Step 1**：我寫 test ```typescript describe('formatRelativeDate', () => { it('returns "just now" for dates within 1 minute', () => { const now = new Date(); expect(formatRelativeDate(now)).toBe('剛剛'); }); it('returns "N minutes ago" for dates within 1 hour', () => { const thirtyMinAgo = new Date(Date.now() - 30 * 60 * 1000); expect(formatRelativeDate(thirtyMinAgo)).toBe('30 分鐘前'); }); it('returns "N hours ago" for dates within 24 hours', () => { const fiveHoursAgo = new Date(Date.now() - 5 * 60 * 60 * 1000); expect(formatRelativeDate(fiveHoursAgo)).toBe('5 小時前'); }); it('returns formatted date for dates older than 24 hours', () => { const oldDate = new Date('2026-01-15'); expect(formatRelativeDate(oldDate)).toBe('2026/01/15'); }); }); ``` **Step 2**：告訴 agent「讓這些 test 通過」 **Step 3**：Agent 寫出 implementation，跑 test，全部 green。 **Step 4**：我 review——不需要逐行看邏輯對不對（test 保證了），只需要看 code 風格是否一致、有沒有不必要的 dependency。 10 分鐘完成一個以前需要 30 分鐘的任務，而且品質更有保障，因為有 test 當安全網。 ## Hallucination 偵測 Patterns Agent code 的 hallucination 有幾個常見模式，學會辨認它們可以讓你的 review 效率大幅提升： ### Pattern 1：不存在的 API / Function **徵兆**：Agent 呼叫了一個你沒見過的 function、method、或 API endpoint。名稱看起來很合理。 **偵測**：`grep -r "functionName" .` 或 `grep -r "endpoint" .`。如果在 codebase 裡找不到定義，很可能是 hallucination。 **實例**：Agent 寫了 `response.data.items.filter(...)`，但你的 API 回的是 `response.results`，不是 `response.data.items`。 ### Pattern 2：過時或不存在的 Library Method **徵兆**：Agent 用了一個 library 的 method，語法看起來對，但就是跑不動。 **偵測**：去 library 的官方文件確認 method 是否存在。特別注意 major version 更新後被移除的 API。 **實例**：Agent 用了 React 17 的 `componentWillMount`，但你的專案是 React 18。 ### Pattern 3：Comment 跟 Code 不一致 **徵兆**：Agent 寫的 comment 描述了一個行為，但 code 做的是另一件事。 **偵測**：比較 comment 跟 code 的邏輯。Agent 有時候會先「想好」它要做什麼（寫 comment），然後在實作的時候偏離了。 **實例**： ```javascript // 排除已過期的 items const filtered = items.filter((item) => item.expiresAt > Date.now()); // ^^^ 看起來對，但如果 expiresAt 是 ISO string 不是 timestamp， // 這個比較永遠是 true ``` ### Pattern 4：過度自信的完美 Code **徵兆**：Agent 的 code 裡沒有任何 TODO、沒有任何 edge case 處理、沒有任何不確定的部分。一切都很「完美」。 **偵測**：這反而是一個警訊。真實世界的 code 總是有 trade-off 和待處理的 edge case。如果 agent 的 code 看起來「太完美」，很可能是它忽略了一些它應該考慮但沒考慮的東西。 ## 三個我沒 Review 就 Merge 的慘案 ### 慘案 1：虛構的 Database Column 就是開頭說的那個。`user_preferences` column 根本不存在。 **教訓**：Agent 寫的任何 database query，都要交叉比對 schema。特別是那些「看起來很合理但你不記得有沒有」的 column。 ### 慘案 2：用了已 Deprecated 的 API Agent 寫了一個 Stripe 付款整合，用了 `stripe.charges.create()`。這個 API 在 Stripe 的舊版 SDK 裡有效，但我們用的是新版 SDK，應該用 `stripe.paymentIntents.create()`。 在 staging 測試時居然通過了——因為 Stripe 為了向後相容，舊 API 在測試模式下還能用。上了 production 才發現部分付款行為不符合 PSD2 法規要求。 **教訓**：Agent 的 training data 會有時間差。它對 library API 的認知可能落後一兩個 major version。碰到第三方 API 整合，一定要查官方文件確認當前推薦的做法。 ### 慘案 3：沒有 Index 的 SQL Query Agent 寫了一個 search query，用了 `LIKE '%keyword%'` 做全文搜尋。在 staging 的 1000 筆資料跑得飛快。上了 production 的 500,000 筆資料，平均回應時間 12 秒。 Agent 不知道 production 有多少資料，也不知道沒有 index 的 LIKE query 在大數據量下的效能。它在小數據集上寫出了正確的邏輯，但完全沒考慮 scale。 **教訓**：Agent 不會幫你想 production scale。任何涉及 database query 的 code，review 時要問自己：「這在 100x 數據量的時候，行為會是什麼？」 ## 建立你的品質保證 Checklist 根據一年的經驗，我整理了一份 agent code review 的 checklist。每次 review agent 的 PR 之前過一遍： ```markdown ## Agent Code Review Checklist ### 自動化（CI 應該已經幫你做了） - [ ] TypeScript / type check 通過 - [ ] Lint 通過 - [ ] 現有 test 全部 pass - [ ] Build 成功 ### 事實性檢查（agent 特有） - [ ] 引用的 API / method 都真的存在 - [ ] Import 的 module 都真的存在 - [ ] Database schema 跟 query 一致 - [ ] 第三方 library 的 API 是當前版本的 ### 設計層面 - [ ] 有沒有不必要的新 dependency - [ ] 有沒有過度設計（你只要 A，它做了 A+B+C） - [ ] 架構選擇是否適合這個 codebase ### 安全性 - [ ] 用戶輸入有 sanitize - [ ] 沒有 hardcoded secrets - [ ] 沒有 SQL injection 風險 - [ ] 適當的 authorization check ### Performance - [ ] Database query 有 index - [ ] 沒有 N+1 query - [ ] 沒有不必要的 re-render / re-computation ``` 不需要每次都過完整份 checklist。根據 agent 改動的範圍，選擇相關的項目。但「事實性檢查」那個 section，每次都要看。 ## Takeaway 1. **Agent 的 code 最危險的地方是「看起來很對」**——它寫出來的 code 格式完美、結構清晰、命名專業，但可能引用了不存在的 API、使用了過時的語法、或忽略了 production scale。永遠假設有 bug，直到自動化工具和你的 review 證明它是對的。 2. **自動化護欄在 agent 時代 ROI 翻倍**——Pre-commit hooks、CI pipeline、TypeScript strict mode，這些「傳統工具」現在是你的第一道防線。它們不會被「看起來很專業」的 code 給騙過。 3. **TDD + Agent 是目前最可靠的品質保證模式**——你寫 test 定義「什麼是對的」，agent 寫 implementation 讓 test 通過。Review 的壓力從「全部都要看」變成「只看設計和安全」，效率和品質同時提升。 --- _上一篇：[Spec-Driven Development](/blog/spec-driven-development-for-agents)_ _下一篇：[從 Prompt 到 Production 的完整旅程](/blog/agentic-engineering-daily-workflow-advanced)_Agentic EngineeringCode ReviewTestingAI品質保證https://bobochen.dev/blog/spec-driven-development-for-agents/https://bobochen.dev/blog/spec-driven-development-for-agents/Agent 不會讀心術，你的 spec 越模糊，它越容易失控。分享怎麼寫 agent-ready 的 spec——從 task decomposition、acceptance criteria 到 constraint definition，附真實的 spec 範本和「寫太少 vs 寫太多」的對照實驗。Fri, 10 Apr 2026 00:00:00 GMT> 這是「Agentic Engineering 實戰手冊」系列的第五篇。上一篇：[Context Engineering 深度解析](/blog/context-engineering-deep-dive) ## 同一個功能，兩份 Spec，天壤之別的結果 同一個功能需求，我寫了兩份 spec 給 agent。一份花了 30 秒隨手打：「幫我加一個用戶通知功能。」另一份花了 10 分鐘認真寫。 30 秒那份，agent 寫了 400 行 code——email notification、push notification、in-app notification 全做了，還自己加了一個 notification preference 頁面。很「完整」，但我只需要一個簡單的 in-app toast。多花了 3 小時拆掉不需要的東西。 10 分鐘那份，agent 精準地做了一個 toast component + API endpoint + 測試。一次通過。 **你花在寫 spec 的時間，省下的是 agent 亂做的時間。這個 ROI 大概是 1:20。** 這不是偶發事件。在過去一年裡，我追蹤了自己的任務完成情況，發現一個殘酷的規律： | Spec 投入時間 | Agent 產出品質 | 人工修正時間 | 總時間 | | ------------- | ------------------ | ------------ | ------------ | | <1 分鐘 | 方向錯誤、過度設計 | 2-4 小時 | ~3 小時 | | 5-10 分鐘 | 基本正確、細節需調 | 15-30 分鐘 | ~30 分鐘 | | 15-20 分鐘 | 精準、一次通過 | <10 分鐘 | ~25 分鐘 | | >30 分鐘 | 不一定更好 | — | 邊際效益遞減 | 甜蜜點在 10-15 分鐘。超過 20 分鐘的 spec，邊際效益開始遞減——你可能寫了太多 agent 不需要的資訊，反而 [稀釋了重點](/blog/context-engineering-deep-dive)。 ## 為什麼「口頭說一下」在 Agent 時代行不通 在傳統團隊裡，你可以跟同事說「幫我加一個通知功能」，然後他會： - 先看現有的 codebase 有沒有類似的東西 - 不確定的地方來問你「你是要 email 還是 in-app？」 - 看了 mockup 之後說「這個 toast 的位置應該在右上角嗎？」 - 做的過程中發現問題會暫停，來找你討論 Agent 不會做任何這些事。它拿到「加一個通知功能」之後，就會以最大解釋範圍去實作。它不會說「你確定要這些嗎？」它只會說「好的，我幫你做了 email + push + in-app + preference page + unsubscribe + 多語系支援」。 **Agent 的預設行為是「盡可能做多」，不是「釐清需求」。** 這不是 agent 的缺陷。這是 LLM 的本質——它被訓練成「有幫助的」（helpful），而「有幫助」在 training data 裡通常意味著「做完整一點」。你要反過來利用這個特性：不是教 agent 少做一點，而是在 spec 裡明確告訴它「做什麼」和「不做什麼」。 我之前分享過的 失敗案例 裡有一個故事——agent 寫了 800 行白寫的 code，根源就是 spec 問題。那次我學到：**模糊的需求 + 認真的 agent = 一堆你不需要的功能。** ## Spec 三要素：Goal / Constraints / Verification 好的 agent spec 只需要三個部分。不多不少。 ### 1. Goal — 你到底要什麼 不是「怎麼做」，是「最後要什麼結果」。 **壞的 Goal**： ``` 用 React 的 useState 和 useEffect 寫一個 toast notification component， 用 CSS transition 做動畫... ``` 這不是 Goal，這是 implementation plan。你把 agent 的手綁住了——它可能知道更好的做法，但你已經指定了每一步怎麼走。 **好的 Goal**： ``` 在頁面右上角顯示一個 toast notification。 3 秒後自動消失。支援 success / error / info 三種類型。 可以從任何 component 觸發。 ``` 告訴 agent 你要的**結果**，讓它選擇**做法**。它可能用 portal、可能用 store、可能用 custom event——哪種做法最適合你的 codebase，它比你更清楚（前提是它有足夠的 [context](/blog/context-engineering-deep-dive)）。 ### 2. Constraints — 不要做什麼 這是 spec 裡最容易被忽略、但最重要的部分。 **為什麼重要**：Agent 的傾向是「做多」。不告訴它不要做什麼，它就會做所有它認為「有幫助」的事情。 **Constraint 範例**： ``` ## Constraints - 只做 in-app toast，不做 email 或 push notification - 不需要 persistence（頁面 reload 後消失就好） - 不要新增任何 npm 依賴——用現有的 utility - 不修改任何現有 component 的 interface - 整個功能控制在 100 行以內 ``` 每一條 constraint 都可能省你 1 小時的拆除工作。尤其是「不要新增 npm 依賴」這種——agent 最喜歡引入新的 library 來解決問題，但你可能不希望為了一個 toast 多一個 dependency。 ### 3. Verification Criteria — 怎麼判斷做對了 這是你跟 agent 之間的「合約」。做到這些就算完成，沒做到就需要修正。 **壞的 Verification**： ``` Toast 要能用。 ``` **好的 Verification**： ``` ## Verification Criteria 1. 呼叫 showToast({ type: 'success', message: 'Saved!' }) 後， 右上角出現綠色 toast，3 秒後消失 2. 呼叫 showToast({ type: 'error', message: 'Failed' }) 後， 右上角出現紅色 toast，3 秒後消失 3. 連續呼叫 3 次，3 個 toast 垂直排列，各自計時消失 4. npm run build 通過，沒有 TypeScript 錯誤 5. 新增至少 3 個 unit test 覆蓋以上場景 ``` 越具體越好。Agent 可以用這些 criteria 來自我驗證——它不需要你手動檢查，它可以自己跑測試來確認是否達標。 如果你搭配 [TDD](/blog/agent-output-verification-review)，verification criteria 可以直接變成 test cases，讓自動化幫你驗收。 ## Task Decomposition：大任務怎麼拆 一個 feature 通常不應該是一個 agent task。它應該被拆成 3-5 個 agent-executable 的單元。 ### 拆的粒度：sweet spot | 太粗 | 剛好 | 太細 | | -------------------- | ---------------------------------- | --------------------------- | | 「做一個 blog 系統」 | 「加一個 related posts component」 | 「在第 42 行加一個 import」 | | Agent 自己做太多決策 | Agent 有明確範圍 | Overhead > 效益 | | 產出難以 review | 產出 = 一個 reviewable PR | 你不如自己做 | **經驗法則**：一個好的 agent task 的大小，大約等於一個 reviewable PR——改動 3-10 個檔案、100-500 行 code、有明確的功能邊界。 ### 拆法範例 **Feature**：在部落格加搜尋功能。 **Bad decomposition**（太粗）： 1. 加搜尋功能 **Good decomposition**： 1. **建立搜尋 index**：在 build time 從所有 blog posts 產生 JSON search index 2. **搜尋 UI component**：建立 SearchBar + SearchResults component 3. **搜尋邏輯**：實作 fuzzy search，支援標題 + 內容 + tags 4. **鍵盤導航**：Cmd+K 開啟搜尋、方向鍵選擇結果、Enter 導航 5. **整合測試**：驗證 search index 產生、搜尋結果正確、keyboard navigation 每個 task 都有明確的輸入和輸出。Agent 可以一個一個做，每做完一個你 review 一次。如果第 3 步的搜尋邏輯出了問題，你只需要修那一步，不影響其他的。 ### AWS Kiro 的 Spec-First 理念 AWS 在 2025 年推出的 Kiro IDE 把 spec-driven 的理念直接建進了工具裡。在 Kiro 裡： 1. 你先寫一份結構化的 spec（它叫 "Spec Document"） 2. Kiro 自動把 spec 拆成 subtasks 3. 每個 subtask 自動產生 acceptance criteria 4. Agent 按照 subtask 順序執行，每步完成後自動跑 acceptance tests 雖然我主要用 Claude Code 不用 Kiro，但它的核心理念值得學習：**把 spec 當成第一公民，而不是附帶產物**。 ## 對照實驗：Bad Spec vs Good Spec 讓我用一個更技術的例子——「在 API 上加 rate limiting」。 ### Bad Spec ``` 幫我在 API 上加 rate limiting。 ``` **Agent 的產出**（摘要）： - 引入了 `express-rate-limit` npm package - 在所有 API endpoints 上加了 global rate limiter（100 req/min） - 加了一個 Redis-based sliding window counter - 加了 `X-RateLimit-Remaining` 和 `X-RateLimit-Reset` headers - 加了一個 `/api/rate-limit-status` endpoint - 寫了 migration script 建立 Redis key - 總共 ~350 行新 code 問題：我只有一個簡單的 Astro static site，沒有 Express、沒有 Redis、那些 API 是 Cloudflare Workers serverless functions。整個 output 基本上不能用。 ### Good Spec ```markdown ## Task: API Rate Limiting for Cloudflare Workers ### Goal 在 /api/contact 和 /api/subscribe 兩個 endpoints 加上 rate limiting， 防止單一 IP 短時間內大量請求。 ### Context - 這是 Astro 5 static site，部署在 Cloudflare Workers - API endpoints 是 Cloudflare Workers serverless functions - 沒有 Redis 或任何 external state store - 目前流量很小（~100 DAU） ### Constraints - 使用 Cloudflare Workers 的 KV namespace 做計數器（已建立：RATE_LIMIT_KV） - 不要引入任何 npm dependency - 只對 POST requests 做 rate limiting - 限制：每 IP 每分鐘最多 5 次 POST - 超過限制回 429 Too Many Requests ### Files to modify - src/pages/api/contact.ts - src/pages/api/subscribe.ts - 可以新增一個 src/lib/rate-limit.ts utility ### Verification 1. 從同一 IP 連續 POST 6 次，第 6 次拿到 429 2. 等 60 秒後，再 POST 應該成功 3. 不同 IP 的 rate limit 是獨立的 4. GET requests 不受 rate limit 影響 5. npm run build 通過 ``` **Agent 的產出**（摘要）： - 新增 `src/lib/rate-limit.ts`（~40 行），用 Cloudflare KV 做計數器 - 修改兩個 endpoint，import rate limiter 並加在 POST handler 前 - 零 npm dependency - 總共 ~80 行新 code - 第一次 review 就通過 差異一目了然。不是因為 agent 變聰明了，是因為它拿到了正確的 context 和明確的邊界。 ## 我的 Spec Template（直接拿去用） ```markdown ## Task: [一句話描述] ### Goal [3-5 句描述最終結果，不描述實作方式] ### Context [Agent 需要知道的背景：tech stack、部署環境、相關系統、目前狀態] ### Constraints - [不要做什麼] - [技術限制] - [不碰哪些檔案] - [行數 / 複雜度 / dependency 上限] ### Files to modify - [具體的檔案路徑] - [可以新增什麼檔案] ### Verification Criteria 1. [具體的測試條件 1] 2. [具體的測試條件 2] 3. [build / lint / type check 通過] ### Out of Scope - [明確列出不屬於這個任務的東西] - [避免 agent 自己 scope creep] ``` **重點**：`Out of Scope` 是最被低估的區塊。它跟 Constraints 不同——Constraints 是「做的時候不要這樣做」，Out of Scope 是「這些事根本不要做」。 例如你在做搜尋功能，Out of Scope 可能包括： - 不做 search analytics（之後另外做） - 不做 search suggestions / autocomplete - 不做搜尋結果的 pagination 這些都是 agent 非常可能「順便」幫你做的東西。提前說不要，省事。 ## 什麼時候不需要 Spec 不是每個任務都需要完整的 spec。回到 [Post 1](/blog/agentic-engineering-what-is-it) 提到的計畫粒度矩陣： | 任務類型 | Spec 需求 | 範例 | | -------- | ---------------------------- | ------------------------------------------------------- | | Trivial | 一句話就好 | 「修這個 typo」 | | Simple | 2-3 句 + constraint | 「加 dark mode toggle，用現有的 CSS custom properties」 | | Medium | 完整 spec（上面的 template） | 「加搜尋功能」 | | Complex | Spec + decomposition | 「重構 auth system」 | 過度 spec 跟 spec 不足一樣是浪費。修一個 typo 不需要寫 Goal / Constraints / Verification。判斷的標準是：**如果 agent 可能做出你不要的東西，就需要 constraint。如果任務只有一種合理的做法，一句話就夠。** ## Takeaway 1. **Spec 的品質直接決定 agent 產出的品質**——10 分鐘的 spec 可以省 3 小時的收拾。ROI 甜蜜點在 10-15 分鐘，超過 20 分鐘邊際效益遞減。 2. **好的 spec 有三個要素：Goal（要什麼）、Constraints（不要什麼）、Verification（怎麼驗）**。其中 Constraints 和 Out of Scope 是最被低估的——它們防止 agent 做出你不需要的功能。 3. **Task decomposition 的甜蜜點是「一個 reviewable PR」的大小**——3-10 個檔案、100-500 行 code、有明確的功能邊界。太粗 agent 自己做太多決策，太細 overhead 超過效益。 --- _上一篇：[Context Engineering 深度解析](/blog/context-engineering-deep-dive)_ _下一篇：[Agent 產出品質保證](/blog/agent-output-verification-review)_Agentic EngineeringSpec-Driven DevelopmentAI需求定義工作流程https://bobochen.dev/blog/context-engineering-deep-dive/https://bobochen.dev/blog/context-engineering-deep-dive/Tobi Lutke 把 Prompt Engineering 重新命名為 Context Engineering，這不只是換個詞。當 agent 要自主完成任務，你餵給它的 context 決定一切——從 CLAUDE.md、codebase indexing 到 conversation history management，拆解 context 的六個層次。Fri, 03 Apr 2026 00:00:00 GMT> 這是「Agentic Engineering 實戰手冊」系列的第四篇。上一篇：[工具全景圖](/blog/agentic-engineering-tools-landscape-2026) ## 「你不是在寫 Prompt，你是在設計 Agent 的世界觀。」 有一次我花了 30 分鐘寫了一個超完美的 prompt，結果 agent 產出的 code 完全不符合專案慣例。為什麼？因為我忘了在 CLAUDE.md 裡寫明我們用 Tailwind 不用 styled-components。 Prompt 本身無可挑剔——任務描述清楚、驗收條件明確、連 edge case 都考慮到了。但 agent 一拿到任務，就開心地寫了一堆 `styled.div` 和 `css` template literal。理由很簡單：它的 training data 裡，styled-components 是一個非常流行的選擇。在沒有額外資訊的情況下，它做了一個「合理」的預設判斷。 那個 prompt 沒問題。問題出在 **context**。 這個領悟改變了我對 AI coding 的整個理解。Prompt Engineering 教你怎麼「問問題」。Context Engineering 教你怎麼讓 agent 「理解你的世界」。這個差別，決定了 agent 產出的品質上限。 ## Prompt Engineering 已死？不，它進化了 2025 年 6 月，Shopify CEO Tobi Lutke 在 X 上發了一條被廣泛轉發的推文： > 「我不再稱它為 Prompt Engineering。正確的詞是 Context Engineering——為 LLM 任務精心策劃完美的 context，這是一門充滿細節的藝術。」 Lutke 的意思不是 prompt 不重要了，而是我們一直把注意力放錯了地方。 傳統的 Prompt Engineering 關注的是「怎麼跟 AI 說話」——用什麼語氣、加什麼前綴、Chain of Thought 怎麼寫。這些技巧在聊天場景下確實有效。但在 agentic workflow 裡，你的 prompt 只是 agent 接收到的資訊的一小部分。 想像你新到一家公司上班。你的主管跟你說「幫我修這個 bug」（這是 prompt）。但你能不能修好，取決於：你有沒有公司的 codebase 存取權（codebase indexing）？你知不知道公司的 coding convention（project config）？你能不能跑測試確認修好了（external tools）？你知不知道這個 bug 之前有人試過什麼方法（conversation history）？ **Prompt 是你說的話。Context 是你說話時的整個環境。** Anthropic 在其開發者文件裡給了一個精確的定義： > Context Engineering 是「策劃最小的高訊號 token 集合，最大化你期望結果的可能性。」 注意兩個關鍵詞：**最小的**和**高訊號的**。不是塞越多越好，是要精準地提供 agent 需要的資訊——不多不少，剛剛好。 Andrej Karpathy 後來也呼應了這個概念。在他定義 Agentic Engineering 的時候，他把 Context Engineering 列為最核心的技能之一，因為： > 「Agent 的行為品質，完全取決於它能看到什麼。你給它看到的世界越精確，它做出的決策就越好。」 如果 [Post 1](/blog/agentic-engineering-what-is-it) 說的「Agentic Engineering 是一門學問」是論點，那 Context Engineering 就是這門學問裡最重要的那一章。 ## Context 六層模型 我在一年的實踐中，整理出一個 context 的六層框架。從最穩定（幾乎不變）到最動態（即時產生），每一層需要不同的維護策略： ### Layer 1: System Instructions — 幾乎不變 這是模型的「基本人格」，通常由工具廠商設定。例如 Claude Code 的 system prompt 定義了它是一個軟體工程 agent、可以使用哪些工具、行為準則是什麼。 **你的角色**：這層你幾乎無法控制，但了解它的存在很重要。不同工具（Claude Code vs Cursor vs Codex）的 system instructions 不同，這解釋了為什麼同一個 prompt 在不同工具裡會有不同表現。 **最佳實踐**：不要跟 system instructions 打架。如果你的 CLAUDE.md 裡寫了跟 system instructions 矛盾的指令，結果是不可預測的。了解你的工具的預設行為，然後在上面疊加，而不是覆蓋。 ### Layer 2: Project Config — 每個專案設定一次 這是 CLAUDE.md、`.cursorrules`、`AGENTS.md` 這些設定檔。它們定義了專案的「房子規則」：用什麼語言、什麼框架、什麼命名慣例、怎麼 build、怎麼 test。 **我的真實例子**：我的 bobo-blog-2026 的 CLAUDE.md 長這樣（摘要）： ``` ## Commands npm run dev # Start dev server at localhost:4323 npm run build # Build production site to ./dist/ ## Architecture Stack: Astro 5 + MDX + Tailwind CSS 4 + TypeScript ## Conventions - Language: lang="zh-TW" (Traditional Chinese Taiwan) - Component files: PascalCase (e.g., PostCard.astro) - Use existing CSS custom properties over hardcoded values ``` 就這麼簡單。但少了這些，agent 可能用 Next.js 的方式寫 Astro code、用 CSS-in-JS 寫 Tailwind 專案、用英文寫中文部落格。 **最佳實踐**：從少開始，需要時再加。第一版只需要 build/test 指令和核心技術棧。當你發現 agent 重複犯同一種錯的時候，那就是該加一條 rule 的時機。 ### Layer 3: Codebase Indexing — Agent 自動探索 這是 agent 對你的程式碼庫的理解。好的 agent 工具會自動做這件事——讀取檔案結構、分析依賴關係、識別設計模式。Claude Code 在開始工作前會自動 `glob` 和 `grep` 來了解 codebase。 **為什麼它重要**：如果 agent 不知道你已經有一個 `formatDate()` utility，它就會自己寫一個新的。如果它不知道你的 API 有統一的 error response 格式，它就會自己發明一個。 **最佳實踐**：保持 codebase 的結構清晰。好的資料夾命名、一致的設計模式、有意義的函數名——這些不只幫人類理解 code，也幫 agent 更準確地索引和推斷。 ### Layer 4: Conversation History — 每個 Session 累積 這是你跟 agent 的對話紀錄。隨著一個 session 的進行，context window 裡會累積越來越多的對話、程式碼片段、工具呼叫結果。 **陷阱**：conversation history 是最容易失控的一層。一個長 session 跑下來，context window 可能有 70% 都是過時的對話。Agent 可能在第 50 輪對話時，還在參考第 5 輪的過時資訊做決策。 **最佳實踐**： - 長任務拆成多個 session，而不是一個超長 session - 利用 context compaction（Claude Code 會自動壓縮舊對話） - 重要決策在 CLAUDE.md 或 plan 檔案裡持久化，不要只靠對話記憶 ### Layer 5: External Tools — 按需載入 這是 MCP（Model Context Protocol）servers、API 回應、外部文件等。Agent 可以透過 tools 即時查詢資料庫、呼叫 API、讀取 Notion 文件。 **為什麼革命性**：傳統的 LLM 只能用 training data 裡的知識。MCP 讓 agent 可以「伸手到外面」取得即時資訊。你的 agent 不再受限於它的知識截止日期，它可以查詢你的 production database、讀取你的 Jira ticket、甚至操作你的 Chrome 瀏覽器。 **最佳實踐**：不要一次掛太多 MCP servers。每個 tool 的 schema 描述都會佔用 context window。我的經驗是一個 session 掛 3-5 個最常用的就好，其他的需要時再啟用。 ### Layer 6: Runtime State — 即時產生 這是測試結果、error logs、git diff、build output 等即時產生的資訊。Agent 跑一次 `npm run test`，失敗的測試結果就變成新的 context，引導它修正方向。 **為什麼關鍵**：Runtime state 是 agent 「自我修正」的基礎。沒有它，agent 就是在瞎猜。有了它，agent 可以進入一個 write → test → fix → test 的迴圈，逐步收斂到正確的解。 **最佳實踐**：確保你的 test、lint、type check 指令是可以讓 agent 執行的。如果跑測試需要手動設定環境變數或啟動 Docker container，agent 就無法利用 runtime state 來自我修正。 ### 六層總覽 | Layer | 內容 | 變動頻率 | 維護責任 | | ----------------------- | ------------------ | --------------- | ------------- | | 1. System Instructions | 模型行為規範 | 幾乎不變 | 工具廠商 | | 2. Project Config | CLAUDE.md、rules | 每專案一次 | 你 | | 3. Codebase Indexing | 檔案結構、patterns | 隨 code 變動 | Agent 自動 | | 4. Conversation History | 對話、先前回應 | 每 session 累積 | 自動 + 你管理 | | 5. External Tools | MCP、API、外部文件 | 按需載入 | 你設定 | | 6. Runtime State | 測試、logs、diff | 即時產生 | 自動 | ## CLAUDE.md：從 10 行到 200 行的演化史 我用 Claude Code 一年了。如果要選「一件最影響生產力的事」，答案不是學會什麼進階 prompt technique，而是認真維護我的 CLAUDE.md。 這是它的演化歷程： ### V1（2025 年初）：3 行 ```markdown npm run dev npm run build npm run test ``` 就是三個指令。Agent 知道怎麼啟動專案、怎麼 build、怎麼跑測試。其他的？全部自己猜。結果可想而知——每次 session 開頭都要花 10 分鐘跟 agent 解釋同樣的事情。 ### V2（2025 年中）：40 行 ```markdown ## Commands npm run dev / npm run build / npm run test ## Architecture - Astro 5 + TypeScript + Tailwind - File-based routing in src/pages/ ## Conventions - PascalCase components - Use CSS custom properties - lang="zh-TW" ``` 加了架構說明和 coding conventions。立竿見影——agent 不再寫出 Next.js style 的 code 了。 ### V3（2025 年末）：100 行 + 多層架構 開始用 global CLAUDE.md + per-project CLAUDE.md + rules files。全域設定管通用的 coding philosophy（偏好 composition over inheritance、test-driven 等），專案設定管具體技術棧。 ### V4（2026 年現在）：200 行 + skills + hooks + memory 完整系統： - **Global CLAUDE.md**（~100 行）：開發哲學、通用 conventions、CI/CD 習慣 - **Project CLAUDE.md**（~50 行）：每個 repo 的技術棧、build 指令、特殊模式 - **Skills**（23 個）：可重用的 agent 能力模組，用 `/skill-name` 觸發 - **Hooks**：pre-commit review、deploy 前檢查等自動化流程 - **Memory system**：跨 session 的持久化記憶 從 3 行到這個規模，不是因為我喜歡寫設定檔，而是因為每一行都是用踩坑換來的。Agent 連續三次在 Astro component 裡寫 React 的 `useState`？加一條 rule。Agent 總是忘記我們的 API response 格式？加一條 rule。 > 更詳細的設定檔架構設計，請看 [CLAUDE.md 大師班](/blog/claude-md-rules-files-masterclass)。 ## Context Window 管理：什麼該塞、什麼該留 Anthropic 內部有一個概念叫 "Goldilocks Zone"——context 不能太多也不能太少，要剛好。 太多的問題：agent 的注意力會被稀釋。如果你把整個 repo 的所有檔案都 dump 進去，agent 反而抓不到重點。研究顯示，當 context 裡有大量無關資訊時，LLM 的準確率會顯著下降——這被稱為「Lost in the Middle」效應。 太少的問題：agent 缺乏做正確決策的資訊，只好自己猜。而它猜的依據是 training data，不是你的專案實際情況。 ### Token Budget 分配建議 這是我在實踐中摸索出的大致比例： | Context 類型 | 建議佔比 | 說明 | | -------------------- | -------- | -------------------- | | System Instructions | ~5% | 工具預設，你無法控制 | | Project Config | ~10% | CLAUDE.md + rules | | Codebase Indexing | ~30% | 相關檔案的 code | | Conversation History | ~35% | 對話 + 先前結果 | | External Tools | ~10% | MCP 結果、API 回應 | | Runtime State | ~10% | 測試結果、error logs | 注意 conversation history 佔了最大比例——這也是最容易失控的部分。 ### Progressive Disclosure 策略 不要一次給 agent 所有資訊。像剝洋蔥一樣，需要時再給： 1. **Session 開始時**：只載入 CLAUDE.md 和 task spec 2. **Agent 開始探索時**：讓它自己 grep/glob 找到相關檔案 3. **遇到問題時**：提供 error logs、test results 等 runtime context 4. **需要外部資訊時**：透過 MCP 即時查詢 這跟 Just-in-Time Manufacturing 的邏輯一樣——需要的時候才載入，而不是預先囤貨。 ### Sub-Agent 架構：保護主 Context 當一個大任務需要探索很多檔案的時候，不要在主 session 裡全部做完。用 sub-agent： ``` 主 agent（main context） └── 派出 sub-agent 1：研究 codebase 結構 └── 派出 sub-agent 2：探索相關 API └── 派出 sub-agent 3：分析 test patterns ``` Sub-agent 各自帶著自己的 context window 工作，完成後只回報「結論」給主 agent。這樣主 agent 的 context window 不會被探索過程的細節填滿。 我在寫這個系列的時候就是這樣操作的——一個主 agent 負責寫作，三個 sub-agent 分別負責不同主題的研究，每個 sub-agent 完成後把研究結果摘要回報。主 agent 的 context 始終保持乾淨。 ## 常見的 Context 設計錯誤 一年下來，我（和我觀察到的其他人）最常犯的五個 context 錯誤： ### 錯誤 1：塞太多——資訊過載 **症狀**：Agent 拿到一個 200 行的 CLAUDE.md + 50 個檔案的 codebase dump，然後做了一個看起來隨機的決策。 **原因**：LLM 有一個已知的 "Lost in the Middle" 問題——context window 中間的資訊比頭尾更容易被忽略。當你塞了太多資訊，重要的指令可能剛好落在被忽略的區域。 **修正**：刪掉一切不是當前任務「必要」的資訊。CLAUDE.md 是你的「always-on」context，應該精簡。任務特定的資訊應該在 prompt 裡給，不是在 CLAUDE.md。 ### 錯誤 2：塞太少——Agent 自己發明 **症狀**：Agent 完美地完成了任務，但用了一個你們從不使用的 library、一種你們從不使用的設計模式、或一個跟現有 code 完全不一致的命名風格。 **原因**：沒有足夠的 context，agent 只好依賴 training data 中最常見的模式。而最常見的模式不一定是你的專案的模式。 **修正**：當你發現 agent 連續做了「合理但不是我想要的」選擇，那就是該加 context 的時機。記錄下來，加到 CLAUDE.md 或 rules file。 ### 錯誤 3：塞錯東西——花 Token 在無關資訊上 **症狀**：你把一大段 design doc 貼給 agent 來修一個 CSS bug，結果 agent 花了大量 token 分析 design doc 裡的商業邏輯，然後建議你改 backend API。 **原因**：LLM 會試圖利用所有給它的資訊。你給了它 design doc，它就覺得你希望它考慮 design。即使 bug 只是一個 CSS `z-index` 問題。 **修正**：Context 要跟任務相關。修 CSS bug 就給 CSS 相關檔案和 error description。不需要的資訊不只浪費 token，還會誤導 agent 的注意力。 ### 錯誤 4：不更新——用過時的 Context **症狀**：Agent 用了你三個月前的 API endpoint（已經改名了）、用了一個你兩個月前棄用的 component、或遵循一個你上個月修改的 convention。 **原因**：CLAUDE.md 寫了之後就沒再更新。Rules file 裡的指令跟現在的 codebase 已經不一致。 **修正**：把 CLAUDE.md 的維護當成程式碼的一部分——它應該被 commit 進 git、被 review、被定期更新。我的習慣是每月花 30 分鐘 review 一次設定檔，清掉過時的內容。 ### 錯誤 5：重複資訊——多個來源說不同的話 **症狀**：Global CLAUDE.md 說「用 tabs 縮排」，project CLAUDE.md 說「用 2 spaces 縮排」。Agent 隨機選一個，或者更糟——在同一個檔案裡兩種都用。 **原因**：多層設定檔架構沒有清楚的優先順序定義。 **修正**：建立明確的優先順序：project 設定覆蓋 global 設定。避免在多個地方重複定義同一件事。一條 rule，一個權威來源。 ## 一個 Context 設計的真實 Before/After 讓我用一個具體的案例來展示 context quality 的影響。 **任務**：在 Astro 部落格加一個「相關文章」推薦功能。 ### Before（只有 Prompt，沒有 Context） ``` 幫我在部落格文章頁面底部加一個「相關文章」區塊， 根據 tags 推薦 3 篇相關文章。 ``` **Agent 的結果**：寫了一個 React component（我用 Astro）、用 `fetch` 從不存在的 `/api/posts` 取資料（我是 static site）、CSS 完全沒用 Tailwind（我整個專案都是 Tailwind）。 功能邏輯是對的。技術選型全錯。花了 40 分鐘重寫。 ### After（完整的 Context Stack） CLAUDE.md 已經有： - `Stack: Astro 5 + MDX + Tailwind CSS 4 + TypeScript` - `src/content/blog/` 是部落格文章目錄 - `Content Collections API` 用 `getCollection('blog')` 取文章 - Component 使用 `.astro` 格式 加上精確的 Prompt： ``` 在 BlogLayout.astro 底部加一個「相關文章」區塊。 - 用 Astro Content Collections API 的 getCollection('blog') 取文章 - 根據 tags 的交集數量排序，取前 3 篇 - 使用現有的 PostCard.astro component 呈現 - 排除當前文章本身 - 用 Tailwind grid 佈局 ``` **Agent 的結果**：一個 Astro component，用 `getCollection('blog')` 取資料，tag 交集排序邏輯正確，用了現有的 `PostCard.astro`，Tailwind grid layout。20 分鐘完成，第一次就能用。 差別不在 prompt 的措辭技巧。差別在 agent 能看到的「世界」。 ## Takeaway 1. **Context Engineering 是 Agentic Engineering 的核心技能**——你的 context 品質直接等於 agent 產出品質。投資在 context 設計上的每一分鐘，都能省下 agent 犯錯後的收拾時間。 2. **Context 有六層，每層需要不同的維護策略**——從幾乎不變的 System Instructions 到即時產生的 Runtime State，理解每一層的角色和最佳實踐，才能精準地給 agent 它需要的資訊。 3. **「剛好夠」比「越多越好」重要**——學會在 token budget 內精準投放 context。太多會稀釋注意力（Lost in the Middle），太少會讓 agent 自己亂猜。Progressive disclosure + sub-agent architecture 是你管理 context 的兩大武器。 --- _上一篇：[工具全景圖](/blog/agentic-engineering-tools-landscape-2026)_ _下一篇：[Spec-Driven Development](/blog/spec-driven-development-for-agents)_Agentic EngineeringContext EngineeringAICLAUDE.mdPrompt Engineeringhttps://bobochen.dev/blog/agentic-engineering-tools-landscape-2026/https://bobochen.dev/blog/agentic-engineering-tools-landscape-2026/市面上至少 20 個 AI coding 工具，哪個適合你？不是功能比較表，而是一個全部都用過的人告訴你每個工具的「甜蜜點」在哪裡、踩過什麼坑，以及我最後為什麼選了現在這套組合。Fri, 27 Mar 2026 00:00:00 GMT> 這是「Agentic Engineering 實戰手冊」系列的第三篇。上一篇：[工程師角色重新定義](/blog/agentic-engineering-mindset-shift) ## 我的信用卡帳單不會騙人 我的信用卡帳單上同時有 Cursor Pro、Claude Pro、GitHub Copilot 三筆訂閱。加上偶爾用的 Anthropic API，上個月光 AI coding 工具就花了快 $200 美金。 是的，我全試過了。而且不是「試用兩天就退訂」的那種試，是「認真用在 production 專案三個月以上」的那種。 這篇不是功能比較表，那種表格你 Google 一下就有幾十篇。這篇是一個花了真金白銀、用真實專案驗證過的人，告訴你每個工具的「甜蜜點」和「踩坑紀錄」。 ## AI Coding 工具分類框架 在比較個別工具之前，先建立一個框架。市面上所有 AI coding 工具，可以按照「自主程度」分成四層： ### Level 1：Autocomplete（自動補完） 最基本的一層。你在打字，AI 猜你接下來要寫什麼，按 Tab 接受。 代表工具：GitHub Copilot 的 tab completion、Cursor 的 tab prediction。 **適用場景**：重複性的 boilerplate code、已知 pattern 的實作。就像手機鍵盤的預測文字，方便，但不會幫你思考。 ### Level 2：Chat（對話式） 你可以問 AI 問題、請它解釋 code、或者讓它產生一段程式碼給你複製。 代表工具：Copilot Chat、Cursor Chat、ChatGPT、Gemini。 **適用場景**：理解不熟悉的 code、生成 snippet、brainstorm 解法。本質上還是你在主導，AI 是你的顧問。 ### Level 3：Agent（代理執行） AI 可以直接操作你的 codebase——讀檔案、寫檔案、跑指令、修 bug。你給它任務，它自己去做。 代表工具：**Claude Code**、Cursor Composer Agent Mode、**Codex CLI**、Gemini CLI。 **適用場景**：完整的 feature 開發、bug fix、refactoring。你從「寫 code 的人」變成「管 agent 的人」，這是目前 agentic engineering 的主戰場。 ### Level 4：Autonomous（全自主） AI 不只執行你的指令，而是可以自主工作數小時甚至數天。你設定目標，它自己規劃、執行、測試、提交 PR。 代表工具：**Devin**、Codex Cloud、**AWS Kiro** Autonomous Mode。 **適用場景**：長時間的 migration、大範圍的 test coverage 補全、independent project setup。但目前可靠性仍然有限。 大部分工程師的日常都落在 Level 2-3 之間。Level 4 很酷，但還不夠可靠，拿來做主力還太早。 ## 第一梯隊深度比較：Cursor vs Claude Code vs Codex CLI 這三個是我每天在用的工具。不是客觀的 benchmark 比較，是主觀的長期使用心得。 ### Cursor **我用了多久**：一年多。Cursor 是我 AI coding 的起點。 **甜蜜點**： - **File-aware editing** 是它最強的地方。它真的理解你 codebase 的結構，auto-complete 的準確度在日常 coding 場景裡是最高的。 - **Tab prediction** 有時候準到有點可怕。你才剛想到要寫什麼，它已經建議好了。 - **Agent Mode** 加入之後，它可以做一些簡單的 multi-file 修改。 - 對前端開發特別友好——React、CSS、HTML 的補完非常到位。 **踩坑紀錄**： - Context window 號稱 200K，但處理大型專案時，我常常覺得它「忘記」了之前看過的檔案。 - Agent Mode 對於複雜的跨檔案修改還是不夠可靠，常常改了 A 忘了更新 B。 - 價格分級太多了。Pro $20/mo 的 200 次 premium requests 很快就用完。 **最適合**：日常 coding、快速 iteration、前端開發、pair programming 式的工作流。 ### Claude Code **我用了多久**：重度使用九個月。現在是我的主力工具。 **甜蜜點**： - **1M token context window** 是 game changer。複雜的 multi-file 問題，它真的能 hold 住整個 context。 - **複雜問題處理能力** 是三個裡面最強的。那種需要讀十幾個檔案、理解系統架構、然後做出正確修改的 bug，Claude Code 的成功率明顯高於其他兩個。 - **Terminal-based** 的操作方式看似原始，但其實更符合 agentic 工作流——你下指令，它自己去做，你不需要盯著 IDE 看。 - **CLAUDE.md** 配置系統讓你可以高度自訂 agent 的行為。這在後面的 [CLAUDE.md 大師班](/blog/claude-md-rules-files-masterclass) 會深入討論。 **踩坑紀錄**： - 成本可以很高。用 Opus model 做複雜任務，一天的 API 費用可能超過 $30。 - 偶爾會過度自信——修了 A 但沒注意到 A 的改動會影響 B。 - 沒有 IDE 的視覺化界面，新手上手曲線比較陡。 **最適合**：複雜問題（multi-file bugs、架構決策）、不熟悉的 codebase、需要深度推理的任務。 ### Codex CLI **我用了多久**：斷斷續續用了幾個月。最近 GPT-5.3-Codex 出來之後用得更多。 **甜蜜點**： - **Linux kernel-level sandboxing**——安全性做得最好。每次執行都在嚴格的 sandbox 裡，不用擔心 agent 搞壞你的環境。 - **1M token context**，跟 Claude Code 同級。 - **GPT-5.3-Codex** 比上一版快 25%，而且支援 interactive steering——你可以中途修改方向而不會丟失 context。 - 自稱是第一個「參與自身開發」的 model。 **踩坑紀錄**： - 對於需要理解複雜架構的任務，我覺得推理能力略遜於 Claude Code。 - OpenAI 的 ecosystem 跟 Anthropic 的不同，遷移設定有一些摩擦成本。 - 定價結構比較不透明。 **最適合**：需要高安全性的環境、想要 second opinion 的時候、OpenAI ecosystem 的使用者。 ### 三工具對照表 | 維度 | Cursor | Claude Code | Codex CLI | | -------------- | --------------------- | --------------- | ------------ | | Context Window | 200K | 1M | 1M | | Sandbox | OS-level（2026 新增） | Namespace-based | Linux kernel | | 起步價 | $20/mo | $20/mo (Pro) | $20/mo | | 重度使用月費 | $60-200 | $100-200 (API) | 依使用量 | | 最強場景 | 日常 coding、前端 | 複雜問題、架構 | 安全敏感環境 | | 最弱場景 | 大型跨檔案修改 | 簡單快速修改 | 複雜推理 | | 我的使用佔比 | 15% | 80% | 5% | ## 第二梯隊評估：Devin 2.0 / AWS Kiro / JetBrains Central 這三個我使用時間不長，以下是初步評估而非深度心得。 ### Devin 2.0 Cognition 推出的「AI 軟體工程師」。2.0 版的升級很大——agent-native IDE、multi-Devin orchestration（一個 Devin 可以管理其他 Devin），PR merge rate 從 34% 跳到 67%。Goldman Sachs 在測試把它當「新員工」用。 **我的觀察**：概念很超前，但 67% 的 merge rate 意味著還有 1/3 的 PR 是不能直接用的。適合定義非常明確、可以 fire-and-forget 的任務。它跟 Claude Code 的定位不太一樣，Devin 更像「自動駕駛」，Claude Code 更像「有很好的 AI 副駕」。 ### AWS Kiro Amazon 推出的 spec-driven agent IDE。它的核心理念是先寫結構化的 spec，然後 agent 照 spec 執行。Autonomous agent 模式可以持續工作數小時甚至數天。 **我的觀察**：Spec-driven 的理念完全正確（這也是我在 [Spec-Driven Development](/blog/spec-driven-development-for-agents) 那篇會深入討論的）。但它目前跟 AWS 生態系綁得比較深，如果你不在 AWS 上開發，摩擦成本可能比較高。 ### JetBrains Central 2026 年 3 月 24 日剛發表。這不只是一個 IDE，而是一個「agentic software development 的控制平面」，包含 governance、agent execution infrastructure、和 shared semantic context。Partner 陣容很豪華：Google Cloud、Anthropic、OpenAI。 **我的觀察**：太新了，還在 EAP（Early Access Program）。但 JetBrains 在 developer tool 領域的 track record 很好。值得關注，但現在還不是「你該用」的階段。 ## 我的最終組合與為什麼 實戰一年下來，我的主力組合是： - **Claude Code 80%**——所有需要「思考」的任務：複雜 bug、架構決策、multi-file 修改、不熟悉的 codebase。 - **Cursor 15%**——routine coding、快速 iteration、前端細節調整。當我需要「寫」多於「想」的時候。 - **其他 5%**——Copilot 的 tab completion 偶爾用、Codex CLI 偶爾拿來做 second opinion。 核心原則：**不同任務配不同工具**。 | 任務類型 | 我選什麼 | 為什麼 | | ------------------- | ---------------- | ---------------------------------- | | 複雜 bug fix | Claude Code | 需要深度推理和大 context | | 新 feature 從零開始 | Claude Code | 需要架構決策 | | UI 微調 / CSS 修改 | Cursor | 視覺回饋快，iteration 快 | | 快速 boilerplate | Cursor / Copilot | Tab completion 最快 | | 不熟悉的 repo 探索 | Claude Code | 1M context 讓它能 hold 住大量 code | | 需要 second opinion | Codex CLI | 不同 model 的另一個視角 | ## 選工具的五個常見錯誤 最後分享五個我看到（也犯過）的錯誤： ### 1. 功能多 ≠ 適合你 大部分時候 Level 3（agent）就夠了，你不一定真的需要 autonomous agent。盲目追最新最強的工具，不如把現有工具用到極致。 ### 2. Context window 大 ≠ 用得到 某些工具號稱的 context window 很大，但 effective context 可能只有一半。Windsurf 曾經宣傳很大的 window，但有開發者實測 effective context 只有 50-70K tokens。看規格不如看實際體感。 ### 3. 價格低 ≠ 省錢 便宜的工具如果 output 品質差、要花更多時間 debug，你的總成本反而更高。一個 $20/月的工具讓你每天多花 30 分鐘修 agent 的錯，一個月就是 10 小時——你的時薪乘以 10 小時，大概比 $200 的工具貴多了。 ### 4. 跟風 ≠ 對 Twitter 上的 influencer 用某個工具用得很順，不代表你也會。你的 codebase、你的 tech stack、你的工作流都不一樣。唯一可靠的方式是自己試。 ### 5. 一個工具打天下 這是最常見的錯誤。沒有一個工具適合所有場景。就像你不會只用一支螺絲起子，也不該只押一個 AI coding 工具，組合著用才是最佳解。 ## Takeaway 1. AI coding 工具有四層分類（Autocomplete → Chat → Agent → Autonomous）。搞清楚你需要哪一層再選，不要殺雞用牛刀。 2. 沒有最好的工具，只有最適合你當下任務的工具。我的組合是 Claude Code 80% + Cursor 15% + 其他 5%，但你的組合不一定要一樣，關鍵是根據任務類型來選。 3. 願意花 $50-200/月在 AI coding 工具上的工程師，投資報酬率通常是正的。如果一個 $100/月的工具讓你每天省 1 小時，一個月就是 20 小時。這筆帳，怎麼算都划算。 --- _上一篇：[工程師角色重新定義](/blog/agentic-engineering-mindset-shift)_ _下一篇：[Context Engineering 深度解析](/blog/context-engineering-deep-dive)_Agentic EngineeringAICursorClaude CodeCodexDevin工具比較https://bobochen.dev/blog/agentic-engineering-mindset-shift/https://bobochen.dev/blog/agentic-engineering-mindset-shift/Agentic Engineering 最大的挑戰不是技術，是身份認同。當你的價值不再來自打字速度和演算法背誦，你到底是誰？分享角色轉換過程中的心理掙扎、具體變化，以及最終找到的新定位。Fri, 20 Mar 2026 00:00:00 GMT> 這是「Agentic Engineering 實戰手冊」系列的第二篇。上一篇：[Agentic Engineering 是什麼？](/blog/agentic-engineering-what-is-it) ## 那個尷尬的瞬間：手寫 Code 反而更慢了 上個月專案趕進度，Claude Code 的 API 剛好在維護。我想說沒關係，我自己來。打開 VS Code，開始寫一個 CRUD endpoint。 寫了二十分鐘，我回頭看自己的 code——少了一個 null check、error handling 不完整、test 還沒寫。以前這些我閉著眼睛都能搞定的事，現在居然要停下來想。 更尷尬的是，API 恢復之後我把同一個任務交給 agent。七分鐘，完成了。code 比我手寫的更完整，test coverage 更高，連 API doc 都自動更新了。 那個瞬間我意識到兩件事： 第一，我的角色已經不知不覺地變了。我不再是「寫 code 的人」，我是「管寫 code 的 agent 的人」。 第二，這讓我非常不安。 ## IC 到 Agent Manager：日常的具體變化 如果你問我一年前的一天是怎麼過的，跟現在的一天是怎麼過的，差異大到像換了一份工作。 **一年前的時間分配（Agent 之前）：** | 活動 | 佔比 | 消耗的腦力 | | ------------------ | ---- | ----------------------- | | 寫 code | 60% | 高（語法、邏輯、debug） | | 讀 code / 理解系統 | 20% | 高 | | 開會 / 溝通 | 15% | 中 | | Code review | 5% | 中 | **現在的時間分配（Agent First）：** | 活動 | 佔比 | 消耗的腦力 | | ------------------- | ---- | ------------------------------- | | Review agent output | 35% | 高（判斷正確性、架構合理性） | | 寫 spec / 定義需求 | 25% | 高（這直接決定 agent 產出品質） | | 架構思考 / 設計決策 | 20% | 高 | | 開會 / 溝通 | 15% | 中 | | 手寫 code | 5% | 低（只在 agent 搞不定的時候） | 最大的變化不是「做什麼」，而是腦力花在哪裡。 以前我的腦力花在「怎麼實作」——這個 function 的邏輯怎麼寫、這個 edge case 怎麼處理、這個 SQL query 怎麼優化。 現在我的腦力花在「做什麼」和「對不對」——這個需求的邊界在哪、agent 的解法是不是最好的、這個架構決策三個月後會不會後悔。 用一個比喻：以前我是工地的砌磚師傅，現在我是工地的監工。我不再一塊一塊砌磚了，但我需要知道這面牆砌得直不直、用的材料對不對、整體結構穩不穩。 而且說實話，監工需要的專業能力不比砌磚師傅少，只是不一樣。 ## 「我會不會變笨？」——技能衰退的焦慮 這個問題我想了很久。而且不只是我在想——每個我認識的 agent-first 工程師，遲早都會面對這個焦慮。 我在 Token 燒光焦慮 那篇文章裡聊過情緒面的掙扎。這篇想從能力面來誠實盤點。 **確實衰退的能力：** - **語法記憶**：我已經記不清 Go 的 error handling 語法細節了。以前手到擒來，現在得查。 - **API 細節**：某個 library 的某個 method 第三個參數是什麼？以前背得出來，現在完全不記得。 - **手寫 boilerplate 的速度**：寫一個標準的 REST endpoint，以前 15 分鐘，現在可能要 25 分鐘。 - **某些 debug 直覺**：以前看到某種 error pattern 會馬上聯想到可能的原因，現在這個反應變慢了。 這些衰退是真的。不否認。 **但同時增長的能力：** - **架構判斷力**：因為我不再被實作細節佔滿腦袋，我有更多腦力去思考系統設計。 - **需求分析力**：寫了一年的 agent spec，我定義需求的精準度提升了至少一個等級。對人類同事描述需求時也變清楚了。 - **Review 眼光**：每天 review agent 產出的 code，我看 code 找問題的能力變強了，而且是跳脫式的——不是逐行看語法，而是看架構和邏輯。 - **系統性思維**：管 agent 逼你想清楚整個工作流——什麼先做什麼後做、dependency 是什麼、怎麼驗證。這訓練了更好的系統性思維。 那淨結果呢？我覺得這像計算機的發明。計算機出現之後，人類的心算能力確實掉了。但數學有因此退步嗎？沒有。反而因為不用把腦力浪費在計算上，人們可以思考更高層次的數學問題。 同理，你不需要記住每個 API 的參數。但你需要知道這個架構設計合不合理——而後者比前者有價值得多。 ## 新技能樹：2026 工程師該投資什麼 如果你接受了「角色已經變了」這個前提，下一個問題就是：那我該投資什麼技能？ ### 判斷力 > 打字速度 以前面試考你 LeetCode，測的是你的實作能力。未來面試會越來越看你的判斷能力——給你一個 agent 寫的方案，你能不能看出問題在哪？ 知道「什麼該做」比知道「怎麼做」值錢了。因為「怎麼做」agent 可以幫你，但「什麼該做」只有你能決定。 ### 架構眼光 > 語法記憶 Agent 不會忘記語法——它永遠可以寫出語法正確的 code。但它不懂你們公司為什麼選了 PostgreSQL 不選 MySQL、不懂你們的 data model 背後有什麼歷史包袱、不懂那個看起來多餘的 middleware 其實是合規要求。 這些 context 是你的獨有價值。越深入理解你們的系統和業務，你越不可取代。 ### 溝通力 > Coding 力 Anthropic 的 Amanda Askell（角色與 prompt 工程負責人）提出了一個很好的框架：**把 agent 當成一個能力很強但缺乏 context 的實習生**。 這個類比精準在：實習生不笨，但他不知道你們公司的潛規則。你需要用清楚的語言告訴他要做什麼、不要做什麼、怎麼判斷做對了。 你的 spec 品質 = agent 的產出品質。而寫好一份 spec，靠的是溝通能力，不是 coding 能力。 Shopify CEO Tobi Lutke 把這件事推到了組織層面。他在內部發了一封信說：「在 Shopify，反射性地使用 AI 現在是基本期待。」他甚至要求團隊在增加人力之前，先證明 AI 做不到這件事。 不管你是否認同 Lutke 的激進立場，趨勢是清楚的：**會「管」AI 的人，比會「寫」code 的人更稀缺**。 ## 不同資歷的轉型路線圖 這個轉型不是所有人都從同一個起點出發。不同資歷的工程師，面對的機會和風險完全不同。 ### Junior（0-3 年）：先打基礎，再用 agent **最大風險**：沒學會基礎就開始依賴 agent。 如果你從來沒手寫過一個完整的 REST API，你怎麼知道 agent 寫的 API 有沒有問題？你連 review 的能力都沒有。 **建議策略**： - **先手寫，再用 agent 驗證**。自己寫一遍，然後讓 agent 也寫一遍，比較差異。這是學習速度最快的方式。 - **把 agent 當 code review partner**，不是 code writer。讓它幫你看你寫的 code 有沒有問題。 - **刻意練習 debug**。Agent 可以幫你修 bug，但你需要理解 bug 為什麼會發生。 **每週練習**：至少一個 feature 完全手寫，不用 agent。 ### Mid-level（3-7 年）：甜蜜點 **你的優勢**：有足夠的基礎來判斷 agent output 的品質，同時又對新方法持開放態度。 這是 agentic engineering 的最佳起步資歷。你知道什麼是好的 code，所以你能有效 review。你也足夠靈活，願意改變工作方式。 **建議策略**： - **全力投入 agent-first workflow**。你的基礎已經夠了，現在需要的是新的工作方式。 - **練習寫 spec**。把寫好 spec 當成跟寫好 code 一樣重要的技能。 - **開始學 context engineering**。CLAUDE.md 怎麼寫、怎麼設計 agent 的工作環境。 **每週練習**：每個 task 都先寫 spec，然後交給 agent。review 的時候記錄「agent 做對了什麼」和「agent 做錯了什麼」。 ### Senior（7+ 年）：最大優勢，最大阻力 **你的優勢**：Judgment。你十年的經驗讓你能一眼看出架構問題、預見三個月後的 tech debt、知道哪個 design pattern 適合這個場景。這些 agent 做不到。 **你的阻力**：「我不需要 AI。」很多資深工程師的身份認同跟「我很會寫 code」深度綁定。承認 agent 寫得比你快，等於承認你的核心技能被取代了。 但實際上不是取代——是**升級**。你不是不會寫了，你是有了一個很快的「手」，可以幫你把腦子裡的架構願景更快地實現。 **建議策略**： - **從你最頭痛的 task 開始**。找一個你一直拖延沒做的 refactoring 或 migration，交給 agent 試試看。 - **專注在 agent 做不到的事**。跨團隊的架構決策、技術 roadmap、mentoring——這些是你的「不可取代區」。 - **把你的經驗變成 agent 的 config**。你知道的 coding conventions、架構原則、踩過的坑，寫進 CLAUDE.md。你的經驗不是被取代了，而是被放大了。 **每週練習**：用一個 session 觀察 agent 怎麼做你通常手寫的任務。不介入，只觀察。然後在 review 階段做調整。 ## Takeaway 1. 角色轉換的關鍵不是學新工具，而是重新定義「什麼讓你有價值」。你的價值從「能寫出好的 code」轉移到「能判斷什麼是好的 code」。前者 agent 做得到，後者它做不到。 2. 有些能力確實會衰退，但更重要的能力在進步——架構判斷、需求分析、review 眼光。這是淨正面的交換，前提是你有意識地投資後者。 3. 不管你是哪個資歷，現在開始有意識地練習「管 agent」的技能都不晚。Junior 先打基礎再用 agent，Mid-level 全力投入 agent-first，Senior 用 agent 放大你的 judgment。路徑不同，方向一致。 --- _上一篇：[Agentic Engineering 是什麼？](/blog/agentic-engineering-what-is-it)_ _下一篇：[2026 年 AI Coding 工具全景圖](/blog/agentic-engineering-tools-landscape-2026)_Agentic EngineeringAI職涯角色轉換https://bobochen.dev/blog/agentic-engineering-what-is-it/https://bobochen.dev/blog/agentic-engineering-what-is-it/2026 年 2 月 Karpathy 提出 Agentic Engineering，但它跟 Vibe Coding、Prompt Engineering 差在哪？從定義出發，用一年實戰經歷解釋這個新詞背後的真正含義——以及為什麼它比寫 code 本身更難。Fri, 13 Mar 2026 00:00:00 GMT> 這是「Agentic Engineering 實戰手冊」系列的第一篇。完整系列共 14 篇，從基礎認知到系統設計到團隊導入，一個做了一年 100% AI coding 的工程師的實戰全紀錄。 ## 2025 年我們在 Vibe Coding，2026 年呢？ 2025 年 2 月 2 日，Andrej Karpathy 在 X 上發了一條推文，說他最近寫 code 的方式完全變了——「完全交給 LLM，忘記程式語言的存在，只靠直覺和 vibes。」他把這叫做 **Vibe Coding**。 那條推文爆了。整個 tech 圈都在討論。有人覺得這是解放，有人覺得這是墮落。但不管你站哪邊，Vibe Coding 確實描述了一個真實的現象：越來越多人開始「感覺對了就好」地用 AI 寫 code，不太在意細節，反正跑得動就行。 一年後，2026 年 2 月 8 日，同一個 Karpathy 發了另一條推文。這次他說：不，Vibe Coding 不夠。我們需要一個新詞——**Agentic Engineering**。 為什麼？因為過去這一年，整個產業發生了根本性的轉變。AI 不再只是你問它問題然後複製貼上答案的工具。它變成了 **agent**——能自己讀 code、自己寫 code、自己跑測試、自己修 bug 的自主行動者。而你，變成了管它的人。 這個轉變需要的不是 vibes，是扎扎實實的工程。 作為一個從 2025 年初就開始 100% agent-first coding 的人，我親身經歷了這一年的演化。從一開始覺得「哇這好方便」，到中間覺得「等等，它怎麼又寫錯了」，到現在理解「原來管 agent 是一門學問」——這篇文章想跟你分享的，就是這段旅程。 ## 從 Vibe Coding 到 Agentic Engineering：一年的演化 如果要畫一個光譜，軟體開發的方式正在經歷這樣的演化： | 階段 | 時期 | 你在做什麼 | AI 在做什麼 | | ----------------------- | --------- | -------------------------- | ------------------------------------ | | **Manual Coding** | ~2022 前 | 自己寫每一行 code | 不存在 | | **AI-Assisted** | 2022-2024 | 自己寫，AI 幫忙補完 | Tab completion、回答問題 | | **Vibe Coding** | 2024-2025 | 描述你要什麼，AI 寫 | 產生大段 code，你複製貼上 | | **Agentic Engineering** | 2025-now | 定義目標和限制，管理 agent | 自主讀 code、寫 code、跑測試、修 bug | 關鍵的轉折點在 2025 年中。那時候 Claude Code、Cursor Agent Mode、Codex CLI 這些工具開始成熟，AI 不再只是「給你一段 code 讓你貼」，而是可以直接操作你的 codebase、跑你的 test suite、甚至自己 commit code。 我記得很清楚第一次讓 Claude Code 自己修一個 bug 的感覺。我只說了「這個 API 在特定 payload 下回 500，error log 在這裡，請找到 root cause 並修好它」，然後它就開始自己讀 code、自己找問題、自己寫修復、自己跑測試。 我去倒了杯咖啡回來，bug 修好了。 那一刻，我意識到我的角色不一樣了。我不是在「寫 code」，我是在「管一個會寫 code 的 agent」。 但 Vibe Coding 和 Agentic Engineering 的差別，不在工具，在心態。Vibe Coding 是「反正 AI 會搞定，我不需要太認真」。Agentic Engineering 是「正因為 AI 在搞定，我需要更認真地管理這個過程」。 ## Agentic Engineering 的定義：不只是「用 AI 寫 code」 Karpathy 解釋這個詞的時候，把它拆成兩半： **Agentic**——因為你的預設模式不再是自己寫 code，而是讓 agent 去寫。你從 creator 變成了 orchestrator。 **Engineering**——因為怎麼編排 agent、怎麼提供 context、怎麼驗證產出、怎麼管理品質，這裡面有系統性的學問。不是 vibes，是工程。 Google 的 Addy Osmani 在他的 blog 裡把 Agentic Engineering 歸納為五個原則： 1. **Plan before prompting**——先寫 spec，再讓 agent 動手 2. **Direct with precision**——給 agent 明確的、有範圍的任務 3. **Review rigorously**——像 review 人類的 PR 一樣 review agent 的產出 4. **Test relentlessly**——測試是品質保證的底線，不是可選的 5. **Own the system**——維護文件、版本控制、CI/CD，你是最終負責人 Django 的共同創辦人 Simon Willison 則整理了一份完整的 Agentic Engineering Patterns 指南，裡面最重要的一句話是： > 「與高品質軟體工程相關的技術——自動測試、linting、清晰的文件、CI/CD、乾淨的架構——恰好也是讓 coding agent 產出更好結果的東西。」 講白了，好的工程習慣沒有被 AI 淘汰，反而被它放大了。 那它跟其他術語到底差在哪？簡單整理： | | Prompt Engineering | AI-Assisted Coding | Vibe Coding | Agentic Engineering | | ------------ | ------------------ | ------------------ | ---------------- | ----------------------- | | **核心活動** | 寫好的 prompt | 用 AI 補完 code | 描述需求讓 AI 寫 | 編排 agent 自主完成任務 | | **品質責任** | 你寫的 code | 你寫的 code | 你不太確定 | 你 review 的 code | | **工程紀律** | 低 | 中 | 低 | 高 | | **適用場景** | 問答、文字 | 日常 coding | Prototype、demo | Production-grade 開發 | Agentic Engineering 不是 Vibe Coding 的「升級版」。它跟 Vibe Coding 的關係，更像是 DevOps 跟「手動部署」的關係——本質上是不同的方法論，要求不同的技能，產出不同品質的結果。 ## 數據說話：現在到底多少人在用？ Anthropic 在 2026 年 3 月發布的 Agentic Coding Trends Report 顯示，**開發者有 60% 的工作涉及 AI**，而且對於委派給 agent 的任務，工程師在 **80-100% 的情況下仍然保持監督**。 JetBrains 在 2026 年 1 月的調查（11,000 名開發者參與）更直接：**90% 的受訪者在工作中使用 AI**。 聽起來很普及。但這裡有個耐人尋味的數字：開發者對 AI 準確度的信任，從去年的 40% 掉到了今年的 29%。 八成的人在用，真正信得過的卻不到三成。乍看矛盾，其實這正是成熟的訊號。 一年前，大家對 AI coding 充滿新鮮感，覺得「哇它好厲害」。一年後，大家都被 agent 坑過了——它自信滿滿地寫出不存在的 API、過時的語法、看起來對但其實錯的邏輯。信任度下降，不是因為 AI 變差了，而是因為大家更了解它的極限了。 還有一個數據很值得注意。SWE-bench 是目前最被認可的 AI coding benchmark： - **SWE-bench Verified**（經過人工驗證的測試集）：最好的 model 可以拿到 **~72%** - **SWE-bench Pro**（更嚴格、更貼近真實世界的版本）：最好的 model 只拿到 **~23%** 72% 跟 23% 的差距，就是「demo 很厲害」跟「真實世界很難」之間的距離。 Gartner 更直接預測：**40% 的 agentic AI 部署會在 2027 年前被取消**，原因是成本上升、價值不明確、或風控不足。 這些數據告訴我們什麼？Agent 很強大，但不是魔法。用好它，需要方法論。這就是 Agentic Engineering 存在的意義。 ## 為什麼 Agentic Engineering 比傳統寫 Code 更難 這是 Agentic Engineering 最反直覺的地方：用 AI 幫你寫 code，居然比自己寫還需要更高的工程紀律。 原因藏在 context 裡。**傳統寫 code 的時候**，你可以在腦子裡 hold 住很多隱性的 context——你知道公司用什麼 tech stack、你知道這個 API 的 quirks、你知道上次那個 bug 是怎麼修的。這些資訊不需要寫下來，因為它在你腦子裡。 **Agent 寫 code 的時候**，它什麼都不知道。它只知道你告訴它的東西。如果你沒有把 coding conventions 寫在 CLAUDE.md 裡，它就會自己發明一套。如果你沒有寫測試，它就不知道自己寫錯了。如果你沒有 CI/CD pipeline，你就得自己一行一行看它寫的 code。 所以 Osmani 說的 paradox 是真的： > Agent 越自主，你的工程基礎設施就需要越完善。 具體來說： - **沒有自動測試？** Agent 不知道它寫的 code 是不是對的。你也不知道。 - **沒有 linting/formatting？** Agent 每次寫出來的 code style 都不一樣。 - **沒有清楚的文件？** Agent 會自己猜你的架構意圖，通常猜錯。 - **沒有 CI/CD？** 你得手動驗證每一次 agent 的產出。 在傳統開發裡，這些東西是 nice-to-have——有當然好，沒有也活得下去。在 Agentic Engineering 裡，它們是 **prerequisites**——沒有這些，agent 根本沒辦法正常工作。 但反過來想，這其實是好消息。 如果你是那種一直堅持寫測試、維護文件、設定 CI/CD 的「無聊工程師」，恭喜你——你在 agent 時代突然變成最有價值的人了。因為你的工程基礎設施不只讓人類團隊工作得更順暢，現在還讓 AI agent 工作得更好。 你花在「boring engineering」上的每一分鐘，在 agent 時代的 ROI 都翻倍了。 ## 這個系列要帶你去哪裡 這是一個 14 篇的系列，分成四個 Part： **Part I：基礎認知（你在這裡）** 1. Agentic Engineering 是什麼（本篇） 2. [從「寫 code 的人」到「管 agent 的人」](/blog/agentic-engineering-mindset-shift)——工程師角色的重新定義 3. [2026 年工具全景圖](/blog/agentic-engineering-tools-landscape-2026)——Cursor、Claude Code、Codex、Devin 的深度比較 **Part II：核心技術** 4. [Context Engineering 深度解析](/blog/context-engineering-deep-dive)——你餵給 agent 的 context 決定一切 5. [Spec-Driven Development](/blog/spec-driven-development-for-agents)——寫給 agent 的需求文件 6. [Agent 產出品質保證](/blog/agent-output-verification-review)——怎麼知道 agent 寫的 code 是對的 7. [從 Prompt 到 Production](/blog/agentic-engineering-daily-workflow-advanced)——完整實戰紀錄 8. [CLAUDE.md 大師班](/blog/claude-md-rules-files-masterclass)——設定檔系統設計 **Part III：系統設計** 9. [MCP 與 A2A 協議實戰](/blog/mcp-a2a-protocols-practitioner-guide)——讓 agent 連接更大的世界 10. [Multi-Agent 編排](/blog/multi-agent-orchestration-real-world)——多 agent 協作的實務 11. [Token 經濟學進階](/blog/agentic-engineering-cost-optimization)——成本控制 12. [Agent 安全網設計](/blog/agentic-engineering-testing-safety)——當 AI 有 sudo 權限 **Part IV：組織與未來** 13. [團隊導入](/blog/agentic-engineering-team-adoption)——從個人到團隊的文化轉變 14. [未來展望](/blog/agentic-engineering-future-and-you)——工程師還需要寫 code 嗎？ 每一篇都可以獨立閱讀，但它們也是一本書的章節——從「這是什麼」到「怎麼做」到「怎麼做好」到「怎麼帶團隊一起做」。 如果你已經讀過我之前寫的 Agent First 日常，那篇是我個人經歷的描述。這個系列則是方法論的整理——我把一年的經驗，提煉成一套可以複製的框架。 ## Takeaway 1. **Agentic Engineering 不是 Vibe Coding 的升級版**，而是一個要求更高工程紀律的新學科。Karpathy 用這個詞取代 Vibe Coding，是因為「靠直覺」的方式在 production 環境裡行不通。 2. **80% 的開發者在用 AI agent，但只有 29% 信任它**。這個信任缺口不會靠「更好的 model」來填補，而是靠更好的方法論——Context Engineering、Spec-Driven Development、品質保證流程。 3. **好消息是：紮實的工程基礎在 agent 時代比以前更有價值**。自動測試、CI/CD、清楚的文件——這些「無聊」的工程實踐，現在不只服務人類團隊，也是 agent 能否正常工作的前提。 --- _下一篇：[從「寫 code 的人」到「管 agent 的人」：工程師的角色重新定義](/blog/agentic-engineering-mindset-shift)_Agentic EngineeringAIKarpathy軟體工程2026趨勢