影片：https://youtu.be/-DiOWxu8VZ8
/* agentflow 起手式(安裝與使用) -------------------------------------------------- */
- https://github.com/agfnow/agentflow
- 選擇適合的安裝方式
- 只用 claude 的話選 `/plugin` 那個，日後可自動更新
- 其餘一律選 `npx skills add` 那個(但注意安裝過程中要正確選擇自己的 agent，例如 codex)
- 如何確認有安裝成功
- `/skills` 看有無出現 `agentflow` 即可確定
- `AG_GUIDE.zh-tw.md` 重要資訊都有寫在裏面，真心不騙值得仔細一讀
- 初始化一個空白 repo
- 在 devlog 許願與執行
- 重複第二次以練習 `/clear` 與 `godev` 慣例
- 示範也能在 terminal 直接提問，內容同樣會存入 devlog
- repo root
- ag.json 是 agentflow 設定檔可進行各種微調
- `.agentflow/`
- 所有 agentflow 相關工作檔案皆收納於此(此目錄名稱也可修改)
- devlog.md 是主要工作區
- devlog.archive.md 將完成事項從 devlog.md 移出並永久歸檔於此
- `.agentflow/artifacts`
- 每一輪(Ask round)的工作檔案皆保存於此
- 例如 `.agentflow/artifacts/A-342-low-friction-closeout` 代表第 342 輪的工作成果皆存於其內
- `.agentflow/features`
- 如果有建立 feature branch/worktree 則完事後成果會保存於此
- 例如 `.agentflow/features/prevent-slop-overengineering` 代表曾有一個名為 `prevent-slop-overengineering` feature branch 並且已開發完成也合併回 main，這裏是留存當時它所有工作成果
- `.claude`, `.codex`
- 這是為裝安裝 stop hook 而代為建立的目錄
- stop hook 的作用是在每一輪結束時進行各種檢查以確保成果品質
/* 先說 -------------------------------------------------- */
- 看到總務阿姨聽不懂的失落眼神就知道 AI 普及化還有很大努力空間，因此催生了新版 agentflow
- 看到企業客戶數百名學員無助的表情即知理想與現實尚有極大差距，而我希望能彌平它！
- 如果這已能滿足你的需求，那剩下時間請專心吃喝玩樂兼聊天就好，不用聽下去...🤭
- 只是你永遠無法確定那欄掉的 20 分藏在在哪裏？
- 例如某些工作要指依給 subagent 進行，或適時的切換不同模型與能力
- 但沒人能確保自己`永遠`不會忘掉其中一步，或有時就是發懶不想打字而混過去
- 此框架存在的目地就是讓一切 best practices 成為每日操作的最底線，人類不需特別努力就能自動達到最高標！
+ 當年在矽谷學到做產品最重要的準則：pit of success (讓用戶無腦就能輕鬆成功)
+ 實現此準則最高明的方式就是直接將老司機智慧內建於 agentflow 框架內
- 也就是所有需要人類`思考、判斷、學習與煩惱`的細節皆預先調校好並內建
- 你不需20年軟體工程經驗即能承接最佳開發手法只無腦出張嘴就能做出好產品
/* 基本概念 -------------------------------------------------- */
- devlog 提供用戶許願與小精靈運作等基礎設施
- 就算完全不需要 SDD 功能，也能享受 devlog 帶來的好處
- 但當要寫複雜程式時，pipeline 的十大 SDD 步驟就會自動觸發
- 雖然兩年來所有精華心得皆已內建於 agentflow 內
- 但只在需要時才載入相關的提示
- 以避免過多提示造成 context 污染、讓模型變笨、也浪費錢
- 你可能聽過 `只要學的夠慢，就什麼都不用學`
↑ 意指模型能力會越來越強能自動做好所有事！
- 既然模型能力強大，就讓它盡情發揮內建的完整推理解題能力
- 也就是 `plan/decompose/implementation` 完全外包給它做而不干涉
- agentflow 的角色是包覆在 agent 外層的`輔具/外骨骼肌裝置`
- 在 harness 週邊建構各種基礎架構讓 agent 順暢運作
- 也從旁監督、輔助並防止 agent 暴走(例如過度設計、鑽牛角尖、做前忘後、言行不一等各種毛病)
→ 此設計最大好處是但當模型變更聰明時，agentflow 仍能與之發揮`加乘`效果，因為即已預留空間讓 LLM 充份發揮
- devlog.md
- design.md
- tracker.md
/* devlog.md 的重點 -------------------------------------------------- */
→ 今天就算你只學會這點就算值回票價嚕~😎
- 用戶在檔案裏許願與發問
- agent 也隨時在裏面回報進度與最終報告
- 不怕遺失前面工作結果
- 不用一個畫面跑三天不敢關掉或清理
- 只要一句 `/godev` 就能從前次中斷處接續下去，從此不再意外遺失任何工作成果！
- 突然需回頭處理半年前的舊專案時也是一句 `godev` 就能接下去做
- 因為 agent 會自動讀 devlog 內容知道之前做了什麼以及現在要如何接下去
/* design.md 的重點 -------------------------------------------------- */
/* tracker.md 的重點 -------------------------------------------------- */
- 將 agent 不透明的內部運作狀態`外部化`以利`追蹤進度`並`永久保存`
- 最新大模型預設會做 plan/decompose/implement 雖然很方便
- 但用戶往往無法知道它內部到底想了些什麼以及最後拆解成哪些步驟？
- 更大的痛點是不易追蹤它的執行進度與還剩多少工作待辦？
- 雖然 agent 可能邁立 todolist/tasklist 但從未保證會完整執行
- 最大的恐懼是如果半路當掉可能前功盡棄、一切從來
- 要求模型一旦完成 decompse 就立即寫出 tracker.md 供追蹤
- 可用 `/goal keep going till tracker is complete` 就放給它跑八小時
/* devlog protocol 重要特色 -------------------------------------------------- */
- 大哥 vs. 小弟 的概念
- 大哥 = 控場 (與用戶交談、分派任務給不同小弟)
- 小弟 = 苦力 (實際跑腿做事的肌肉)
- worker 有兩種
- 內建的 subagent
- 透過 shell 執行的 external runner (`codex exec`, `claude -p`)
- 目前一律用 external runner
- 目地是 confinement (主要是防止意外 write 操作)
- 背後也有多種安全措施例如在全新乾淨的獨立 repo 內作業以避免意外污染 main branch
- 不但強迫在乾淨獨立 context 內執行
- 並盡可能使用不同 model family 或同家族但不同能力模型
- 目地是增加多樣性以提高發現問題的機率，讓審查品質更好
- 例如規畫用 `sol/low` 但審察用 `fable`
- 小精靈會自動代跑 `claude -p` 與 `codex exec`
- 但如果你只有訂 claude or codex 也能運行無阻，小精靈會聰明的改用同家族不同能力模型
- 專案初始進行規化時是最易出錯階段，這步如果走偏就會影響後續所有成果
- 因此內建 `3ways` 模式，讓一家模型先寫好企畫，再交給第二家模型審查
- 最重要的是接著兩家模型會一來一往交談、辯論直到達成共識
- 通常由 Fable vs. Sol 進行對戰
→ 經實證此手法效果極佳，fable 極善長發散思考而 sol 精於細節與踩煞車，往往可找抓出大量錯誤讓 fable 修正
- 自動化所有建立 feature branch, worktree 等設定、合併與善後流程
- 團隊多人協作時彼此工作成果與記錄皆確保`互不干擾`且`永久保存`
# 可排程執行多份工作， 每份皆確保在乾淨獨立 context 內執行，人類不用守候在旁
- 例如可事先規畫好五份 `plan.md`，睡前交待 agent 開始執行，等明早睡醒後即可驗收五份成果
- 已驗證每份 plan 可獨立執行超過 12hrs 沒問題，代表人類可長時間離開電腦
-
控場：sol/low -> opus-4-8/medium
-
打手：luna/max -> sonnet-5/high
/* agentflow pipeline 重要特色 -------------------------------------------------- */
- 失敗之處
- 太多步驟且每步驟下方還有多輪循環，人類根本記不住何時該跑哪些步驟
- 執行的時間太久、耗用太多 token、生出文件太多人類根本讀不完，也不確定成效是否真的良好
- 總之這是所有第一代 SDD 家族共通的`歷史共業`
- 讓我們承認吧，sdd 有它的好處與優點，但缺點也一大堆，例如產生大量文件、跑很久、很燒錢，最慘的是不見得有用。
- 因此重點在：如果擷取它的優點但消滅所有缺點？並且同時滿足所有人的日常工作習慣與需求？
- 我花了兩年實做各式 agent harness 與 agentic workflow engine，這是我最終心法的結晶，目地是幫各位避免再踩相同的雷而能直接享受最終的完美果實。
- 但當第一認使用 Fable/Sol 看到它們的的表現時我心中即知時代已完全改變了
- 因為當代大模型已變的超聰明並能主動做好`規畫、拆解、實作、審查`四步驟
- 因此沒必要繼續用傳統手法與大模型對幹，反而應想辦法讓它盡情發揮這些強項！
→ 這個領悟徹底改變了 agentflow 的發展方向！
- rubrics/score 的缺點
- LLM 自評不可靠，它說 9 分可能完全是自由心證，問再多次也不可能拿到正確答案
- 就算拿 10 分仍可能漏掉重要功能沒實作、或重大問題沒發覺
- 改良手法
- 改用`正面表列`事先列出必需完成的目標與檢核條件，等完工後逐項比對
- 每項比對後會拿到單定答案：PASS, NEEDS_FIX, or BLOCKED
- 如此至少明確知道比對了哪些條件、每個條件的實際成果
- 最新時法主要檢視三大類條件
- Invariants
- Requirements coverage
- Acceptance checks
- `spec-report.md` 範例
## Invariants
- **INV-1 — Destructive-boundary order:**
- **INV-2 — Refusal preservation:**
- **INV-9 — Scope boundary:**
## Requirements coverage
- **R-1:** Observable behavior and Failure behavior; verified by INV-1 and INV-2.
- **R-2:** Observable behavior and Failure behavior; verified by INV-2, INV-3, and INV-4.
- **R-3:** Observable behavior and Failure behavior; verified by INV-2 and INV-5.
## Acceptance checks
- **R-8 conformance:**
- **R-9 conformance:**
- **R-10 conformance:**
- 例如訪談完開始寫 spec 時才發現有細節不清楚
- 小精靈會立即跳回前面 requirements 步驟再次訪談用戶問清楚細節
- 然後回去繼續寫完 spec
→ 這一切以往都需工人智慧操作，現在已全自動化並在背景執行
- 例如：簡單的任務就算啟動 codewalk 步驟，也會在內部被立即判定程式碼太單純不需深入探究而快速收尾。
1. requirements
- 用戶需求訪談，生成 requirements.md 供檢視
2. codewalk
- 既有專案(brownfield)先掃瞄既有程式架構，找出注意事項
- 生成 codewalk.md 供後續接手的 agent 參考
3. explore
- 依任務複雜度探索不確定性以找出潛在風險、威脅與未知細節
4. spike
- 依 explore 結論針對不確定性建立小型、快速的 prototype 以驗証細節
5. spec
- 將用戶需求寫成 spec
6. implementation
- 此部份完全交由 LLM 內部自由發揮，只要最後有完成 spec 內容就好
7. security-scan
- 對程式碼做基礎資安檢測
- 也可啟用指定的第三方資安掃瞄工具進行完整檢查
8. acceptance
- 比對實作成果與 spec 內 `invariants` 條件是否完全符合
9. cross-check
- 即 code review，且預設採`對抗式審查`
10. learn
- 將開發過程中犯的錯、學到的心得等資訊記錄下來並籍此修改 skill
"pipeline-roles": {
"requirements": "better",
"codewalk": "basic",
"explore": "basic",
"spike": "basic",
"spec": "better",
"implementation": "basic",
"security-scan": "off",
"acceptance": "basic",
"cross-check": "better",
"learn": "custom"
},
"external-workers": [
{
"id": "codex-default",
"command": [
"codex",
"exec"
],
"priority": 3,
"family": "codex",
"tiers": {
"best": "gpt-5.6-sol/medium",
"better": "gpt-5.6-terra/high",
"basic": "gpt-5.6-luna/xhigh",
"cheap": "gpt-5.4/medium",
"custom": "gpt-5.4-mini/high"
}
},
/* 採用 agentflow pipeline 前一定要知道的事 -------------------------------------------------- */
-
用 ag 一定有成本，但如跑較久、較花錢，生成的檔案也多，但它確保品質，讓用戶能當白癡
-
用 ag 可至少 90~95 分，因為大部份已知錯誤皆已內建防呆機制在內，從源頭就減少走偏的機會
-
但沒人能肯定 100 分，畢竟 LLM 是機率計算，每次答案不一樣，每輪都有可能話唬爛
/* 採用後整體好處 -------------------------------------------------- */
-
能有穩定的許願與執行 sop (devlog+ag)真的好放心
-
也因此可更專心在規畫高層次功能並批次寫成 plan md 丟進去執行
-
也有更多時間心力審查產出結果
-
最終將逐漸找出工作節奏(外加 codex 用量很多、做的又細心，讓事情能妥善完成)
-
-
最新設計理念是
導引式開發-
讓 agent 透過 devlog 手把手帶人類走完開發流程
-
這能增加人機協作的信任感
-
ai 就像老師傅般在旁默默助拳，將所有複雜實作細節全藏在背後(例如善用 subagent 與乾淨 context)
-
而人類可輕易坐享其成
-