Agency Agents教學手冊
agency-agents 教學手冊(企業標準技術白皮書) 版本:v4.0 | 最後更新:2026-11-13 上游基準:msitarzewski/agency-agents main@8ae6164(2026-11-08):283 個 Agent、18 個部門、17 種工具 適用對象:資深工程師、架構師、技術主管、資安與品質負責人 授權:內部教育訓練使用(上游專案為 MIT License) 目錄 0. 文件資訊與閱讀指南 0.1 本手冊的目標 0.2 版本基準與查核方式 0.3 符號說明 0.4 建議閱讀路線 0.5 本章審查與驗證清單 1. 總覽(Overview) 1.1 agency-agents 是什麼 1.2 核心設計理念 與泛用 Prompt、Prompt 庫、封閉工具的差異 1.3 與傳統開發模式的差異 1.4 適用與不適用場景 適用場景 不適用或需特別小心的場景 1.5 部門總覽 1.6 社群生態 官方管道 社群翻譯版本 1.7 發展歷程與路線圖 發展歷程 路線圖(上游 README,2026-11) 1.8 本章審查與驗證清單 2. 系統架構設計(Architecture) 2.1 整體架構圖 2.2 四份「單一真實來源」合約檔 tools.json 實際結構 2.3 轉換與安裝管線 轉換產物不提交 2.4 Agent 檔的兩個語意群組 2.5 NEXUS 協作層 2.6 多 Agent 協作模型 2.7 與企業系統的整合邊界 2.8 本章審查與驗證清單 3. 安裝與環境建置(Installation & Setup) 3.1 前置需求 3.2 取得專案 3.3 目錄結構 3.4 方式一:桌面 App(最簡單) 3.5 方式二:CLI 安裝(install.sh 完整參考) 參數總表(取自 install.sh 的 usage 區塊) 各工具安裝範例 3.6 選擇性安裝 依 NEXUS runbook 安裝整個團隊 3.7 以環境變數覆寫安裝路徑 3.8 複製(預設)與符號連結(–link) 3.9 Windows 環境 3.10 平行轉換與安裝 3.11 驗證安裝 3.12 本章審查與驗證清單 4. Agent 結構解析(Agent Design) 4.1 Agent 檔案的完整結構 4.2 Frontmatter 規格(以 lint-agents.sh 為準) 4.2.1 services 欄位 4.3 color 規則 4.4 章節標題與轉換的關係 4.5 程式碼區塊的巢狀規則 4.6 Qwen Code 保留的 placeholder 4.7 Persona 設計原則 ✅ 好的 Persona ❌ 不良 Persona 4.8 Workflow 與交付物設計 任務輸入格式(給 Agent 的 prompt) 4.9 完整範例:企業版 API Reviewer 4.10 離線驗證工具:check_agent.py 驗證結果 4.11 本章審查與驗證清單 5. 與 AI Coding 工具整合(Integration) 5.1 整合方式總覽 5.2 Claude Code 5.2.1 安裝 5.2.2 呼叫方式 5.2.3 Claude Code 如何解讀 agency-agents 的欄位 5.2.4 企業做法:專案層副本加上工具白名單 5.2.5 組織層統一派發 5.3 GitHub Copilot 5.4 Codex 5.5 Gemini CLI 與 Antigravity 5.6 Qwen Code、ZCode 5.7 Cursor 5.8 OpenCode 5.9 Osaurus、DeepSeek Harness(skill-md 家族) 5.10 Kimi Code 5.11 OpenClaw 5.12 Aider 與 Windsurf(roster 類) 5.13 Hermes(延遲載入 router plugin) 5.14 Mistral Vibe 5.15 工具選擇建議 5.16 MCP Memory 整合(跨 session 記憶) 設定步驟 記憶治理 5.17 本章審查與驗證清單 6. 實戰:AI 開發流程(End-to-End Workflow) 6.1 案例說明:企業客戶管理系統(CRM) 系統需求 技術棧(2026-11 基準) 6.2 Agent 協作流程 交接規則 6.3 Phase 1:需求分析(Product Manager) Prompt Phase 1 預期產出(節錄) 🔍 Phase 1 人工驗收 6.4 Phase 2:架構設計(Backend Architect、UX Architect) Prompt(Backend Architect) Phase 2 預期產出(節錄) 🔍 Phase 2 人工驗收 6.5 Phase 3:實作(Backend Architect 實作模式、Frontend Developer) Prompt(後端) Phase 3 預期產出(節錄) 🔍 Phase 3 人工驗收 6.6 Phase 4:程式碼與 AI 產出安全審查 🔍 Phase 4 人工驗收(審查「審查報告」) 6.7 Phase 5:測試(API Tester、Evidence Collector) 🔍 Phase 5 人工驗收 6.8 Phase 6:放行審查(Reality Checker) 🔍 Phase 6 人工驗收 6.9 Phase 0 選配:全面產品探索 6.10 使用 NEXUS runbook 快速組隊 6.11 本章審查與驗證清單 7. SSDLC(安全開發流程) 7.1 agency-agents 在 SSDLC 中的定位 7.2 Security 部門角色對照(12 位) 7.3 需求與設計階段 安全需求 STRIDE 威脅建模 🔍 威脅模型人工驗收 7.4 開發階段:OWASP Top 10:2025 審查 🔍 OWASP 審查人工驗收 7.5 測試與發佈階段 DevSecOps 管線範本 7.6 資料分級:哪些東西不能進 prompt 7.7 Agent 檔的供應鏈安全 升級前掃描:scan_agent_risk.py 🔍 升級審查程序 7.8 本章審查與驗證清單 8. 系統維運(Maintenance) 8.1 日常維運工作一覽 8.2 修改 Agent 之後的標準流程 8.3 上游的 CI 合約(企業 Fork 應保留) 8.4 企業 Fork 的附加 CI 8.5 Prompt 優化循環 使用紀錄範本 8.6 版本資訊放哪裡 8.7 成本控制 8.8 疑難排解 8.9 本章審查與驗證清單 9. 系統升級(Upgrade Strategy) 9.1 升級流程 9.2 升級指令 9.3 客製化策略(避免衝突) 方案比較 9.3.1 方案 A:新增企業部門的完整步驟 9.3.2 方案 B:專案層覆蓋(Claude Code) 9.4 安裝紀錄(可重現性) 9.5 自動同步上游(GitHub Actions) 9.6 分支策略 9.7 本章審查與驗證清單 10. 最佳實踐(Best Practices) 10.1 Agent 設計原則 ✅ DO ❌ DON’T 10.2 審查 AI 產出的通用框架 幻覺偵測清單 10.3 什麼時候該用多 Agent 五種協作策略 常見組合速查 10.4 Prompt Engineering 技巧 結構化 Prompt 骨架 10.5 常見錯誤 10.6 本章審查與驗證清單 11. 企業導入建議(Enterprise Adoption) 11.1 導入路線圖 Phase 1:試點(約 9 週) Phase 2:擴展 Phase 3:優化(持續) 11.2 教育訓練 入門課大綱 11.3 治理(Governance) 最小代理權原則(Least Agency) 使用規範範本 角色與責任(RACI) 11.4 KPI 設計 成效指標 使用指標 月報範例 11.5 本章審查與驗證清單 12. 附錄(Appendix) 12.1 常用 Prompt 模板 模板 A:需求分析 模板 B:API 設計 模板 C:程式碼審查 模板 D:安全審查 模板 E:測試案例 模板 F:審查 AI 產出的「審查者」Prompt 12.2 新 Agent 模板 12.3 完整 Agent 名冊(2026-11-08,283 個) 12.4 FAQ Q1:需要付費嗎? Q2:支援哪些模型? Q3:可以修改 Agent 嗎? Q4:一次用幾個 Agent? Q5:Agent 的品質如何保證? Q6:Windows 可以用嗎? Q7:不同 Agent 的建議互相衝突怎麼辦? Q8:上游支援哪些工具? Q9:如何貢獻新 Agent? Q10:Healthcare 與 Research 是新部門嗎? Q11:如何回報安全問題? Q12:桌面 App 與 CLI 該選哪個? Q13:上游有版本號嗎? 13. 檢查清單(Checklist) 13.1 新進成員快速上手 環境(新進成員) 基本使用 安全意識 13.2 專案導入 前置 環境(專案) 規範 持續改善 13.3 上游升級 14. 參考資源與社群(Resources & Community) 14.1 官方資源 14.2 工具官方文件 14.3 延伸閱讀 14.4 社群管道 14.5 企業內部資源建議結構 附錄 A:v3.1 → v4.0 修正紀錄 A.1 事實更正 A.2 新增內容 附錄 B:驗證紀錄 B.1 驗證環境 B.2 名冊與工具計數 B.3 手冊工具表與 tools.json 比對 B.4 runbook 組隊工具 B.5 手冊本身的自動檢查 B.6 待驗證項目 0. 文件資訊與閱讀指南 0.1 本手冊的目標 本手冊不是上游 README 的翻譯。它是一份企業導入白皮書,目標有三個: ...