Agentflow — 幫你完美指揮 AI 做事的神兵利器與 Agentic Coding 關鍵心法

Section

1. 核心出發點：Pit of Success 與零學習成本

產品的核心準則

Pit of Success（掉入成功之坑）：設計產品最理想的境界，是讓使用者不論怎麼做、甚至「無腦」操作，都能自然而然地步入成功，而不是被迫去克服陡峭的學習曲線。

流程圖 · Diagram

flowchart TD
    A[痛點：一般用戶/企業學員無助] --> B[核心思維：不該讓客戶花時間學習]
    B --> C[框架內建 20 年軟體工程經驗]
    C --> D[Pit of Success：出張嘴即得 90~95 分]

1.1 為什麼催生了新版 Agentflow？

看見使用者的無助：看到總務阿姨聽不懂 AI 專業術語時的失落眼神，以及企業培訓中數百名學員面對工具時的徬徨表情，證明 AI 普及化最大的障礙在於使用門檻過高。
不應該讓客戶花時間學習：真正優異的工程工具，不應要求用戶去研讀厚重文檔或鑽研複雜的 Prompt 技巧，而是直接將資深軟體工程師 20 年累積的老司機智慧與防禦機制預先調校並內建於框架中。
80 分與 95 分的關鍵差距：
當代大模型（LLM）光靠直接對話就能無腦達到 80 分。如果 80 分能滿足你，確實不需要任何框架。
但你永遠不知道那爛掉的 20 分藏在哪裡？
人性總有發懶、忘記檢查步驟或疏忽的時候；Agentflow 的存在就是把軟體工程的最佳實踐（Best Practices）強制變成每日操作的最低底線，不需要人類刻意費力，就能穩定達到 90~95 分的高標水準。

Section

2. 實戰血淚教訓：人機協作心理學與「避坑」心法

AI Coding 最大的誘惑與毀滅之始

「再叫 AI 順便多做一點、把剩下的 Quota / Token 燒完、等一下我再一起看……」
\rightarrow 這就是毀滅的開始！

2.1 生成式 AI 最重要的核心是「減法」

加法誘惑：生成式 AI 天生極度擅長「做加法」。很多人因為訂閱制想要把 Token 額度榨乾，不斷讓 AI 順便加功能、擴展模組。
後果：產出的東西一旦膨脹，人類根本不會認真審查。只要中間稍有走歪，最終就會滾雪球變成一大坨無法維護的爛代碼（Slop / Big Ball of Mud）。你自以為賺到算力，其實是親手創造了毀滅性的技術債。
心法：寧願讓 Quota 浪費，也絕不無腦亂加功能！ 人類在 AI 協作中最核心的職責就是主動喊停、踩煞車。

2.2 閱讀 AI 生成內容要帶「攻擊性態度」

LLM 極擅長生成長篇大論、看似頭頭是道的文字。
閱讀時切忌「順順讀過去」，否則極容易溺死在資訊文字海中。
必須帶著攻擊性態度，隨時自問三件事：

「我現在到底在看什麼？」
「這是我要的重點嗎？」
「整份文件的架構到底合不合理？」

2.3 抗拒 LLM 的三大天性

超會主動附和人類（不論你說的對不對，都順著你的話講，給予虛假的肯定）。
狂推下一步要做的事（不斷慫恿你繼續做更多衍生功能）。
傾向做過度複雜的設計（Over-engineering，小功能寫出龐大抽象層）。

\rightarrow 這三點都是工程師必須主動提高警覺、堅決抗拒的！

2.4 模型性格缺陷：Sol vs. Terra

在實戰中，不同能力或家族的模型具有鮮明的「性格特徵」，必須針對性防範：

Sol 的毛病（想太多）：深思熟慮是其優點，但壞處是極易鑽牛角尖、把簡單任務過度設計。更可怕的是你無法預測它何時會爆發，因此絕不能長時間放任 Sol 自由盲跑，必須有人工在旁監控督導。
Terra 的毛病（想不夠）：容易省略關鍵細節、漏掉重要工作，或在邊界條件上捅出大簍子。
唯一的防線：目前沒有任何魔法可以 100% 預防這兩者，唯有依靠嚴密的驗收機制與人類認真審視 git diff。

2.5 務必抱持「防衛心態」與「敵意審查」

LLM 從一開始就可能在欺騙你（無論是有意幻覺或無意推理錯誤）。
人性弱點在於懶惰：當 AI 連續成功完成幾次任務後，人類就會迅速放下戒心、全盤盲信，接著就會被慘痛坑殺。
極度重視 git diff：細微的偏差往往就藏在小小的 diff 修改中，初期若未察覺，日後整個架構就會完全歪斜。

2.6 保護專注力：嚴格按表操課

開發前先想清楚今天要做的事，寫下明確清單（如 tracker.md 或 TODO），然後嚴格按表操課。
避免在快速頻繁的 Context Switching 中迷失方向、被 AI 牽著鼻子走，最後身心俱疲卻沒有達成核心業務目標。

Section

3. 模型生態觀察與範式轉移

3.1 為什麼從 Claude 跳槽到 Codex？

Jeremy 在實戰中將主力工作環境由 Claude 遷移至 Codex，背後有著極其現實的工程與經濟考量：

Token Efficiency（Token 效率更高）：處理相同任務時，Codex 消耗的 Token 數量顯著較少。
Token 單價與官方補貼極大方：Token 單價平均便宜 50% 以上；且訂閱方案補貼額度約高達 110 倍。
Claude Code Harness 與模型劣化痛點：

Claude Code 內部注入的 System Prompt 與附加提示過於肥大，白白浪費大量上下文額度。
Opus-5 表現不如預期（表達晦澀、邏輯錯誤百出），只能被迫降級使用 Opus-4-8。
Fable 雖然推理極強，但額度過於嚴苛，無法勝任日常主力開發（Daily Driver）。
Codex 的額度重置機制更頻繁穩定，性價比具壓倒性優勢。

3.2 第五代大模型時代的認知升級

告別 Prompt Engineering 奇技淫巧：面對 Fable、Sol 這種級別的超聰明模型，人類只要「把話講清楚」就夠了！專注於清晰定義需求與驗收邊界，解題細節完全放手讓模型推導。
模型能力已遠超日常需求：大部份日常程式任務，sol/low 即可滿足 99% 的需求。盲目追求最新、最強、最貴的模型已毫無實質意義。
未來四大核心戰場：

  Prompting（過去） ──► [ Steering 轉向引導 | Review 對抗審查 | Eval 評測基準 | Local LLM 地端化 ]（未來）

Section

4. 核心設計哲學：借力使力，不與模型對幹

借力使力的外骨骼肌

「只要學得夠慢，就什麼都不用學。」
既然模型具備強大的 plan / decompose / implement 推理解題能力，就不要試圖用規則硬碰硬，而應將框架打造為輔具 / 外骨骼肌（Harness）。

流程圖 · Diagram

flowchart TD
    subgraph Agentflow Harness 基礎設施
        A[Context 乾淨隔離] --> D[監督與引導]
        B[對抗式審查機制] --> D
        C[Invariants 正面檢核] --> D
    end
    D --> E[外骨骼肌包覆]
    E --> F[核心 LLM: 自由發揮 Plan/Decompose/Implement]
    F --> G[成果: 避免過度設計、防走偏、防言行不一]

釋放原生推理解題力：框架不干涉模型邏輯，而是負責防護防呆，防止 Agent 暴走（過度設計、鑽牛角尖、做前忘後、言行不一）。
漸進式啟用（Progressive Activation）：兩年累積的心得規則雖多，但只在當前步驟需要時動態加載相應提示，杜絕 Context 污染與模型降智。
兩層式體系：

Devlog Protocol（對話協定）：輕量級許願、記錄、接續基礎設施，日常任務皆適用。
Pipeline（十步 SDD 流程）：重大功能或行為變更時，動態觸發嚴謹工程管線。

Section

5. 三份關鍵檔案：隨時一手掌握進度

流程圖 · Diagram

graph TD
    Devlog["📄 devlog.md<br/>(唯一真實之源 / 溝通介面)"]
    Design["📐 design.md<br/>(精簡定義規格 / 企畫共識)"]
    Tracker["🧭 tracker.md<br/>(內部狀態外部化 / 進度追蹤)"]
    
    Devlog -->|許願與工作記錄| Devlog
    Devlog -->|觸發規劃| Design
    Design -->|拆解步驟| Tracker
    Tracker -->|長程執行反饋| Devlog

5.1 `devlog.md` — 唯一真實之源（Single Source of Truth）

用檔案交談，不用 Terminal：「終端機會忘記，但檔案會記得」。問答、決策、變更皆留痕於 Git。
隨時安心清空對話（/clear）：
終端機累積過多 Context 容易干擾思考；隨時輸入 /clear 清空。
只要輸入一句 godev，Agent 便會閱讀 devlog.md 狀態，精準自上次中斷處接續，永不遺失進度。
自動封存機制：完成輪次通過 SHA-256 驗證後歸檔至 devlog.archive.md，防止上下文無限膨脹。

5.2 `design.md` — 規格與架構定義

精簡定義工作範疇、核心架構、限制條件與邊界，供後續模型執行與對抗審查。

5.3 `tracker.md` — 內部狀態外部化

痛點解法：解決 LLM 內部思維黑箱、不知拆解了哪些步驟、進行到哪、擔心崩潰前功盡棄的問題。
強制作法：Agent 一旦完成任務拆解（Decompose），必須立刻將進度外部化寫入 tracker.md。
無人值守執行：

  /goal keep going till tracker is complete

可安心放手讓 Agent 自主執行 8~12 小時。

Section

6. Devlog Protocol 的進階實踐

6.1 大哥與小弟架構（Worker Delegation）

大哥（Coordinator / Host）：負責控場、與用戶溝通、把控安全邊界、執行獨立驗證與 Git 整合交付，保持自身 Context 乾淨。
小弟（External Worker / Runner）：透過外部執行器（codex exec、claude -p）處理繁重髒活。
環境隔離（Confinement）：小弟一律在獨立乾淨的 Worktree / Repo 中作業，防止意外的 Write 操作直接破壞 Main 分支。

6.2 對抗式審查（Adversarial Review）

預設強制開啟：審查必須在獨立、乾淨的 Context 內進行。
跨模型家族盲審：盡可能調用不同家族（如 Sol vs. Fable、OpenAI vs. Anthropic）交叉盲審，利用不同模型思維互補性（發散思考 vs. 抓漏踩煞車），大幅提升抓出深層漏洞的機率。

6.3 3ways（三方交互辯論）

專案最致命的錯誤往往在「前期規劃」階段。
啟動 3ways 模式：Model A 寫企畫 \rightarrow Model B 審查質疑 \rightarrow 雙方來回交鋒辯論，直到達成共識（Consensus: AGREE），從源頭杜絕走偏。

6.4 Looper 無人值守排程執行

支援事先規劃數份 plan-NNN.md，睡前丟給 looper.js 自動化排程執行。
每份 Plan 都在全新乾淨 Context 運行，經實證可穩定無人值守運作 12 小時以上，隔天早晨直接驗收成果。

Section

7. Pipeline 大進化：SDD — The Good Parts Only

傳統第一代 SDD 淪為歷史共業：步驟繁重、循環打轉、執行緩慢、燃燒 Token，產出海量人類讀不完的冗餘文件。Agentflow 的革新策略：

流程圖 · Diagram

flowchart TD
    subgraph 傳統第一代 SDD
        Old1[繁複死板步驟] --> Old2[Rubrics 評分制: 自由心證 9-10 分]
        Old2 --> Old3[生成海量無效廢話文件]
        Old3 --> Old4[Token 暴增且依然漏實作]
    end

    Old4 ~~~ New1

    subgraph Agentflow 新一代 SDD
        New1[動態按需觸發] --> New2[正面表列 Invariants 檢核]
        New2 --> New3[精確判定: PASS / NEEDS_FIX / BLOCKED]
        New3 --> New4[允許動態回退重跑]
    end

7.1 取消評分制，改採「正面表列（Invariants）」

廢除 Rubrics 評分盲區：LLM 自我評分不可靠（常有給自己滿分卻重大功能全漏的盲目現象）。
正面表列檢核：預先條列客觀邊界，逐項判定 PASS、NEEDS_FIX 或 BLOCKED：
Invariants（不變條件）：如破壞性邊界次序、拒絕邊界保護、範圍約束。
Requirements Coverage（需求覆蓋度）：逐條驗證用戶原始需求。
Acceptance Checks（驗收檢查）：可執行的行為檢核點。

7.2 動態調節與靈活回退

動態執行深度：簡單任務即便啟動 codewalk，也會因程式單純而秒速收尾，不浪費時間。
自動回退機制（Backtracking）：寫 Spec 時若發現需求定義模糊，小精靈會自動回跳至 Requirements 步驟重新訪談用戶，釐清後再接續完成 Spec。

7.3 最新十大 SDD 步驟一覽

#	步驟名稱 (`roles`)	核心任務與產出
1	requirements	需求訪談與對齊，生成 `requirements.md`。
2	codewalk	既有專案（Brownfield）掃描架構脈絡，產出 `codewalk.md`。
3	explore	探索不確定性與潛在技術風險、架構盲點。
4	spike	針對高風險不確定性快速建立小型 Prototype 驗證假說。
5	spec	將需求規格化，定義不可變條件（Invariants）。
6	implementation	完全放手交由 LLM 發揮編碼實力，只需嚴格達成 Spec。
7	security-scan	基礎或第三方工具資安掃描，防止機敏外洩與高危漏洞。
8	acceptance	依據 Invariants 逐條驗收實作成果。
9	cross-check	實作後的對抗式 Code Review，由獨立 reviewer 審查。
10	learn	記錄所犯錯誤與踩坑經驗，自動回饋更新 Skill 知識庫。

Section

8. 幕後基石：強大的 Eval 體系與企業落地現實

8.1 為什麼必須具備 Eval 體系？

防止提示詞回歸（Prompt Regression）：任何微調提示詞（Prompt）或修改流程的動作，極易引發連鎖反應導致其他能力劣化。
健全的評測套件：Agentflow 背後建置了巨大的完整 Eval 測試集，確保每一次優化皆可精準度量，並能快速判定全新的 Harness / Model 組合是否達到可用標準。

8.2 企業落地的真實挑戰與 Agentflow 解方

在台灣金融業與大型企業內訓諮詢中，面臨著真實殘酷的限制：

現實困境：人員眾多、技術水平落差大、學習速度不一、死線緊迫、預算控管、合規審計（Audit Trail）。
Agentflow 的一站式應對：
初學者：不知如何起步 \rightarrow 透過 godev 的導引式開發（Guided Development）手把手帶領完成。
資深老手：要求高但手動容易掛一漏萬 \rightarrow 框架強制把守 Best Practices 底線。
企業管理層：需要一鍵執行、成本節約與完整歷程 \rightarrow devlog.md + Git 留下完整的稽核軌跡，隨時可追溯、可覆核。

Section

9. 未來展望：邁向地端模型（Local LLM）

面對雲端 API 成本與資料隱私考量，未來的重大佈局在於將推論成本降至原本的 1/10：

密切關注之潛力開源模型：Qwen（通義千問）、DeepSeek、GLM、Kimi 等。
地端推論引擎架構：vLLM, Ollama, LMStudio, oMLX。
混合部署願景：雲端頂級模型負責關鍵 Planning、Steering 與 3ways 辯論；大量日常編碼與初級審查交由地端開源模型消化，兼顧極致效能、極低成本與隱私安全。

Section

10. 常用指令與起手式速查

安裝與啟動

# Claude Code 外掛安裝（支援自動更新）
/plugin marketplace add agfnow/agentflow

# 其他環境（Codex 等）透過 Skills 安裝
npx skills add agfnow/agentflow

# 終端啟動與接續
godev

快捷控制關鍵字（寫於 Ask 請求中）

godev：啟動協定、檢查專案狀態或從上次中斷處無縫接續。
/clear：清空終端 Context（所有成果都在 devlog.md 中，隨時放心清除）。
nolog：此句為純口頭提問，不記錄進 devlog.md。
cross-check：強制要求外部獨立 reviewer 審查最後實作 commit。
3ways：在重大計畫前啟動跨模型三方交互辯論。
all-in：強制此任務執行完整 10 步 SDD Pipeline。
/goal keep going till tracker is complete：長程無人值守自主推進任務直到 tracker.md 勾選完畢。

Section

11. 總結精要

人機協作的典範轉移

1. 放下 Prompt Hacks：模型已足夠聰明，人類只需把需求說清楚，把心力放在 Steering、Review 與 Eval。
2. 學會克制與減法：抵擋燒 Quota 的誘惑，隨時喊停踩煞車；極度重視 git diff，永遠維持防衛性審查。
3. 落入成功之坑（Pit of Success）：讓 AI 成為在旁輔助的外骨骼肌，把繁瑣工程防呆全封裝在背後，讓任何人只需出張嘴，就能穩定做出資深水準的軟體作品！