從本地做起並非目光短淺，而是具有策略眼光。

Stripe 最近發布了一系列文章，介紹他們如何建立「Minions」——完全自主的編碼代理，這些代理能夠獨立完成任務，無需人工幹預。一個代理讀取程式碼庫，另一個編寫實現，一個執行測試，還有一個審查結果。所有操作並行進行，協同一致，最終大規模產生可用於生產環境的程式碼。

讀到這段話，多數工程師的反應不外乎兩種。要么是“這對我們來說還遙不可及”，要么是開始思考要朝著這個方向邁進，需要哪些基礎。

本文討論的是第二種反應。

Stripe所描述的並非一款需要購買的產品，而是可以基於穩固的基礎設施逐步建構的能力。而正是這種基礎設施——即代理配置的儲存、版本控制、分發和組合方式——將能夠真正擴展人工智慧的團隊與那些仍在聊天視窗中複製貼上提示的團隊區分開來。

我把這門學科稱為「智能體平台工程」 。它的第一原則很簡單：將智能體智慧視為基礎設施，而不是即興發揮。

任何規模的問題

無論你是擁有 10 個程式碼庫的獨立工程師，還是擁有 200 個程式碼庫的平台團隊，當你嘗試認真地使用 AI 代理程式時，你都會遇到同樣的結構性問題。

就個人而言，情況是這樣的：你花時間精心配置代理——編寫指令、建立可重複使用的流程、根據工作環境定義代理應該做什麼和不應該做什麼。然後你換了台機器、重新安裝了工具，或是嘗試了不同的代理程式。你的配置全都遺失了。你只能從頭再來。

團隊層面的情況更糟：每個工程師都有自己私有的、沒有文件記錄的、無法共享的代理配置。程式碼庫中代理程式的行為方式缺乏共享知識，其功能和限制也缺乏一致性，新成員也無法快速融入代理程式工作流程。團隊的 AI 能力無法擴展，因為它分散在個人的頭腦和本地文件中。

在企業層面——也就是 Stripe 營運的層面——如果你還沒有解決以下基本問題，你甚至無法開始考慮執行管道的自主代理：代理配置在哪裡，誰擁有它，以及如何讓它到達每個需要它的地方。

大多數工程師與人工智慧代理互動的方式主要有兩種：

1. 臨時模式：無需配置，僅提供提示。適用於一次性任務，但代理程式不會記住您的技術堆疊、約定或約束條件。

2. 單一檔案設定：在程式碼倉庫根目錄下放置一個大的AGENTS.md或CLAUDE.md檔案。這種方式更好，但擴展性不佳——相同的指令會被注入到所有地方，無論它們是否相關，而且這些指令只存在於一個程式碼倉庫中，而你的工作卻需要在二十個程式碼倉庫中完成。

這兩種方法都不是基礎設施。兩者都無法擴充。兩者都無法提供你向自主多智能體系統過渡所需的條件。

問題是：基礎建設實際上會是什麼樣子？

架構：三個儲存庫，一個系統

我最終採用的解決方案是將不同的職責劃分到三個獨立的倉庫中，每個倉庫只負責一個明確的任務。這並非我個人為了提高效率而採取的權宜之計，而是一種精心設計的架構模式，它反映了任何共享基礎設施的平台工程運作方式——對系統進行版本控制，記錄現有內容，並將介面與實現解耦。

agent-library/    ← The brain (tool-agnostic intelligence)
agent-setup/      ← The bridge (tool-specific deployment)
resource-catalog/ ← The map (inventory of everything)

讓我逐一解釋。

1. agent-library — 大腦

這是智能體所有知識和行為的唯一權威來源。它不包含任何工具特定的配置。即使明天我從一個AI編碼工具切換到另一個，這個程式碼庫也不會被修改。

結構：

agent-library/
├── library.yaml          ← Central manifest
├── SKILLS-INDEX.md       ← Human-readable index of all skills
├── layers/               ← Context-specific instructions
│   ├── global.md         ← Identity, principles, environment map
│   ├── repos.md          ← Shared git conventions
│   ├── work/             ← Work domain
│   │   ├── domain.md     ← Conservative rules, safety constraints
│   │   ├── terraform.md  ← Terraform-specific workflow
│   │   ├── gitops.md     ← GitOps/FluxCD rules
│   │   └── code.md       ← Code conventions
│   └── personal/         ← Personal domain
│       ├── domain.md     ← Experimental mode, fast iteration
│       ├── fintech-app.md
│       └── infra-gcp.md
├── skills/               ← Reusable procedures
│   ├── global/           ← Available everywhere
│   └── work/             ← Domain-specific
├── rules/                ← Always-on constraints
└── prompts/              ← Reusable prompt templates

關鍵概念是「層」 。每一層都是一個 Markdown 文件，它會成為特定目錄下的AGENTS.md檔案（或等效檔案）。這些層被設計成累積式的－代理程式會從上一層載入到下一層，每一層都在前一層的基礎上加入上下文。

當代理程式在~/repos/work/terraform/下執行時，它會載入：

~/.agent/AGENTS.md              → global.md        (who I am, core principles)
~/repos/AGENTS.md               → repos.md         (git conventions)
~/repos/work/AGENTS.md          → work/domain.md   (conservative, safety-first)
~/repos/work/terraform/AGENTS.md → work/terraform.md (terraform workflow)

每一層都目標明確。 global.md global.md不了解 Terraform。 work/terraform.md work/terraform.md不了解 React。代理自下而上地建構其上下文，只包含它目前所在位置所需的資訊。

library.yaml清單檔案是黏合劑。它聲明了每一層、每一項技能、每一條規則和每一個提示——它們是什麼，它們在程式碼倉庫中的位置，以及它們應該部署在檔案系統中的哪個位置：

layers:
  - name: work-terraform
    description: "Terraform-specific rules for work domain"
    source: layers/work/terraform.md
    target: ~/repos/work/terraform/AGENTS.md
    scope: "~/repos/work/terraform/*"

skills:
  - name: terraform-plan
    description: "Terraform plan/apply workflow"
    source: skills/work/terraform-plan.md
    scope: "~/repos/work/terraform/*"

2. agent-setup — 橋接器

這個程式碼庫是連接與工具無關的大腦和我目前使用的特定AI代理工具的適配器。如果明年我更換工具，我只需要替換這個程式碼庫，大腦本身保持不變。

它的核心是一個名為setup.sh腳本，該腳本讀取library.yaml並透過符號連結部署所有內容：

# Creates: ~/repos/work/terraform/AGENTS.md → agent-library/layers/work/terraform.md
# Creates: ~/.agent/skills/terraform-plan → agent-library/skills/work/terraform-plan.md
# ... and so on for every layer, skill, rule, and prompt

為什麼使用符號連結而不是副本？

因為當我在agent-library中編輯某個層時，變更會立即生效，無需重新部署。只有當我新增檔案（需要建立新的符號連結）時， setup.sh才需要再次執行。對於對現有文件的編輯，符號連結已經指向正確的位置。

該儲存庫還包含特定於工具的設定、快捷鍵和擴充功能——這些內容僅對特定工具才有意義。

3. resource-catalog — 地圖

這是我工程生態系中所有資源的索引。它遵循Backstage目錄格式——與企業級工程平台使用的標準相同。

# components/agent-library.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: agent-library
  description: "Tool-agnostic agent configuration library"
  annotations:
    github.com/project-slug: your-username/agent-library
spec:
  type: ai-agent-config
  lifecycle: production
  owner: your-name
  system: personal-ai-agent-platform

我擁有的每個儲存庫——基礎設施、應用程式、文件，以及代理庫本身——都在這裡註冊，包括其類型、所有者、系統和來源位置。

目錄並非存放代理邏輯的地方。它只是一張地圖，而非引擎。這種區別至關重要：目錄告訴你代理agent-library在以及它是什麼。而agent-library本身則包含代理所知道的一切。將這兩者混淆就好比將原始碼嵌入到package.json中。

技能：可重複使用過程庫

除了層（定義代理的行為方式）之外，該庫還包含技能——用於常見任務的可重複使用、逐步程序。

技能範例如下：

# Skill: Terraform Plan

Use this skill when working with Terraform in the work domain.

## Steps
1. Check context — confirm directory and workspace
2. terraform fmt -recursive
3. terraform validate
4. terraform plan -out=tfplan
5. Review plan — summarize what will change
6. Highlight risks — flag any destroys or critical changes
7. Wait for confirmation — never apply without explicit approval
...

## Red Flags (Stop and Ask)
- Any resource marked for destruction
- Changes to IAM policies
- Changes to production databases

技能需要明確呼叫： /skill:terraform-plan 。它們不會自動加載——這是有意為之。代理不會預先載入所有可能需要的程式。它會在任務需要時才載入技能。

代幣效率設計

這就是建築價值所在。

一個簡單粗暴的方法是：把所有內容放在一個大的AGENTS.md中。包括所有規則、所有技能、所有上下文。這樣一來，智能體就永遠知道所有資訊。

問題在於：這個檔案會變得非常龐大。你發送給代理的每個訊息都會攜帶完整的上下文資訊作為令牌。當你編寫 Python 腳本時，實際上是在為 Terraform 規則付費。你編寫文件時，實際上是在載入 GitOps 流程。

這個架構從三個層面解決了這個問題：

第一層：層級作用域以目錄為單位。 Terraform層僅在~/repos/work/terraform/目錄下啟動。在你的 React 應用程式中不會激活，在你的文件中也不會激活。

第二層：每一層只聲明與其層級相關的內容。 global.md global.md了 6 項通用技能（除錯、程式碼審查、重構、測試、文件編寫、Git 工作流程）。它沒有列出terraform-plan或catalog-management ——這些在大多數情況下都無關緊要。 work work/terraform.md列出了terraform-plan ，除此之外沒有其他內容，因為這是該領域唯一需要的技能。

第三級：元技能的作用域限定在其所屬目錄內。 create-skill （用於建立新技能的技能）僅在agent-library/目錄下可用。 catalog-management僅在resource-catalog/下可用。代理程式在執行您的金融科技應用程式時，為何需要知道如何修改代理程式庫？

結果：當代理人位於work/terraform/目錄下時，其活動上下文恰好為：

• 六項全球技能

• 1. 領域技能（基礎設施審查）

• 1 目錄技能（terraform-plan）

就這樣，沒有噪音。

5分鐘內完成災難復原

整個系統的設計宗旨只有一個：如果所有東西都壞了，你可以在 5 分鐘內從頭開始重建。

# Step 1: Clone the three repos
mkdir -p ~/repos && cd ~/repos
git clone [email protected]:your-username/agent-library.git
git clone [email protected]:your-username/agent-setup.git
git clone [email protected]:your-username/resource-catalog.git

# Step 2: Deploy
cd agent-setup && bash setup.sh

# Step 3: Verify
cd ~/repos/work/terraform && your-agent "What context am I in?"
# → Agent responds with terraform-specific context ✓

完成。代理程式擁有完整的身份資訊、所有領域知識、所有技能，以及適用於其工作的每個目錄的所有正確規則。

這只有在以下情況才有可能發生：

1. 所有資料都儲存在 Git 倉庫中，不存在可能遺失的本機設定。

2. 大腦與工具是分離的。重新安裝工具並不會遺失智慧。

3. 清單文件聲明了所有內容。 library.yaml library.yaml是對系統的完整描述setup.sh只是執行它。

心智模式：智能體智慧的套件管理器

你可以把它想像成一個軟體包管理器，只不過是用來管理智能體的思維和行為的。

library.yaml相當於你的package.json －它聲明了所有應該存在的東西以及它們的功能。 setup.sh 相當於你的npm install setup.sh ——它接收清單文件，並在任何機器上配置所有內容。層是你的來源模組－可組合、作用域明確、按需載入。技能是你的函數庫——你需要時才呼叫的程序，而不是事先呼叫。

與傳統套件管理器不同的是：這裡的「套件」不是程式碼，而是針對特定上下文進行推理的指令。

這不僅僅是關乎個人層面。如果你是一個平台團隊，並且希望每位工程師都能以一致的方式使用代理程式——相同的生產環境安全規則、相同的程式碼審查規範、相同的升級流程——那麼你就需要將代理程式發佈到agent-library 。工程師執行setup.sh即可。搞定。智慧功能實現了分散式、版本化和可審計，就像任何其他共享基礎設施一樣。

這是Stripe方法的基礎。在能夠在真實程式碼庫上並行執行自主代理之前，您需要解決以下問題：代理從哪裡獲取指令？誰來更新它們？變更如何傳播？如何確保處理支付服務的代理不會像處理內部工具的代理那樣運作？

本文所描述的架構正是這些問題的一種解答——它從單一開發人員的設定開始，但設計上可以擴展。

日常運作狀況

當我在~/repos/work/terraform/目錄下開啟終端機時：

代理商已經知道它處於保守模式，任何terraform apply都需要經過審核的計劃和明確的確認，提交前的鉤子必須在任何提交之前執行，以及整個工作流程中要使用的具體技能。

當我在~/repos/personal/fintech-app/目錄下開啟終端機時：

代理商知道它可以快速行動，這是一個 Python 金融分析平台，API 金鑰存在於環境變數中，而不是程式碼中，並且在提交之前會執行測試。

當我想要新增一項新技能時：

我執行/skill:create-skill 。代理程式會引導我完成建立檔案、在library.yaml中註冊並設定正確的權限範圍、更新SKILLS-INDEX.md以及提交變更的過程。技能提交後即可生效－無需重新部署（使用了符號連結）。

當有同事加入我的團隊或我收到一台新機器時：

三個 Git 克隆和一個 Bash 腳本。相同的代理，相同的行為，相同的上下文。

那些至關重要的設計決策

為什麼不使用一個大型程式碼庫？因為這樣可以實現關注點分離。核心功能不應該依賴工具。目錄不應該包含可執行邏輯。如果將它們混在一起，就會造成耦合，使整個系統變得脆弱。

為什麼目錄要採用 Backstage 格式？因為它是專為此而設計的行業標準——描述目錄內容、所有權以及與其他內容的關聯。它易於閱讀，與工具無關，並且可擴展。

為什麼使用符號連結而不是副本？無需重新部署即可實現即時更新。只需編輯庫中的terraform.md文件，即可立即在~/repos/work/terraform/目錄下生效。無需同步步驟，來源配置和已部署配置之間不會出現偏差。

為什麼要將技能限定在特定目錄中而不是全部載入？這是為了提高令牌效率和認知清晰度。載入了 30 個技能的智能體需要決定要使用哪個技能。而只載入了 2 個技能的智能體則知道該使用哪個技能。

我尚未建造的東西

這是一篇客觀公正的文章，所以這裡列出了目前仍在計劃中的功能——以及哪些功能使架構更接近 Stripe 的模式：

• 擴充（下一步）：用於目錄查找、倉庫導航和直接從終端同步庫等操作的自訂工具

• MCP 整合：模型上下文協定伺服器用於更深入、更結構化的工具整合——使代理程式能夠存取即時資料來源，而不僅僅是靜態指令。

• 多智能體編排：能夠並行產生多個專門的智能體來執行複雜任務－一個智能體讀取程式碼庫，另一個負責實現，還有一個負責驗證。 Stripe 的 Minions 正是朝著這個方向發展，這種架構經過專門設計，確保層系統能夠為每個專門的智能體提供其所需的確切上下文，而且不多不少。

• 集中式分發：從本地符號連結轉向基於拉取的模型，任何機器或 CI 環境都可以自動從agent-library取得最新的代理程式配置。

這些步驟都是提升自主性的階梯。但如果沒有基礎，這一切都無法實現：版本化、作用域明確、可組合的、由您掌控的代理配置。

結論

Stripe 的 Minions 功能令人印象深刻。但它們並非魔法——而是首先建構了正確的基礎設施的結果。

這裡描述的架構——三個程式碼倉庫、清晰的職責分離、基於清單的部署以及作用域上下文載入——就是從最小規模開始建置的基礎架構。一個開發人員，一台機器，三個 Git 程式碼倉庫。

本地部署並非最終目標。它只是對一種可擴展模式的概念驗證：智能體智能即配置，配置應存放在 Git 中，而 Git 應存放在一個可以進行版本控制、分發和組合的系統中。

從本地做起，著眼於規模化發展，打好基礎，為下一步行動奠定基礎。

這就是智能體平台工程。

更新 - 1

跨組織代理發現問題

自從本文發表以來，@globalchatads 在評論中引發了一場精彩的討論，提出了一個關鍵問題：這種本地 Monorepo/Symlink 架構對於單一開發人員來說非常棒，但它如何才能真正擴展到多團隊的企業環境中呢？

如果 A 團隊（安全團隊）的代理人需要執行 B 團隊（網路團隊）擁有的稽核工具，A 團隊的代理人如何發現該工具？最簡單的做法是給代理一個 Git 個人存取權杖 (PAT) 來讀取 B 團隊的程式碼倉庫。然而，在零信任企業中，跨網域共享 Git 代幣會造成巨大的安全開銷和緊密耦合。

解決方案：面向代理商的跨組織發現

我們需要的不是可網路路由的服務註冊中心，而是共享檔案系統或直接儲存庫存取。我從標準 Web 協定中汲取靈感，將RFC 8615（ .well-known/ ）目錄模式整合到此架構中。

以下是分散式（Polyrepo）架構在實務上的工作原理：

1. GitOps 作為真理之源： B 團隊在自己的程式碼倉庫中維護本機agent-library 。

2. 建置步驟：當變更合併時，CI/CD 管道解析其內部library.yaml ，提取用於公共使用的工具（例如，MCP 伺服器端點），並編譯標準化的agent-capabilities.json 。

3. 部署：此 JSON 資料將發佈到內部高可用端點。

4. 執行時發現：當 A 團隊的代理需要與網絡域互動時，它只需查詢 https://api.networking.internal/.well-known/agent-capabilities.json 即可了解有哪些工具可用以及需要哪些 OAuth 範圍。

為了證明這一點，我對參考架構庫進行了更新，新增了三項關鍵內容：

• 📄 **[發現協議]

文件](https://github.com/Sarony11/agentic-infrastructure-bootstrap/blob/main/docs/cross-org-agent-discovery.md)：深入了解 JSON 模式和發現機制。

• ⚙️ **[模擬 CI/CD

Pipeline](https://github.com/Sarony11/agentic-infrastructure-bootstrap/blob/main/agent-library/.github/workflows/publish-capabilities.yaml)：一個範例 GitHub Action，展示了團隊如何編譯和發布他們的功能。

• 🛠️ **[網域發現]

技能](https://github.com/Sarony11/agentic-infrastructure-bootstrap/blob/main/agent-library/skills/global/discover-domain.md)：一個基礎工具，允許本機代理查詢遠端網域並即時了解其功能。

非常感謝社區推動這一概念的進一步發展。從本地腳本到標準協定的演進，正是下一代智慧體平台工程的精髓所在！

原文出處：https://dev.to/sarony11/agentic-platform-engineering-how-to-build-an-agent-infrastructure-that-scales-from-your-laptop-to-11np