Agents Monorepo 設計

設計原則

✓可以上 Git

CLAUDE.md、.claude/skills/、docs/、weekly-snapshot/、reports/、.env.example

不含任何機敏數值的設定檔與文件
⚠️ Skill 放在各 Agent 的 .claude/skills/ 或根目錄 .claude/skills/，不放在 _shared/

✕不能上 Git

.env、secrets/、含客戶資料的 reports、任何 API key 或密碼

全部加進 .gitignore

⬡一個私有 Repo

所有 Agent 放在同一個私有 Git repo，結構統一，共用資料集中管理。

⟳_shared 是共用層

Agent 之間不直接溝通。週期快照寫到 _shared/，其他 Agent 從 _shared/ 讀。

資料夾結構

~/agents/← 私有 Git repo 根目錄

├── .gitignore← **/.env, **/secrets/, **/repos/

├── .env.example← 列出所有需要的 key，但不填值

├── CLAUDE.md← 總管理員：整體規範 + create-agent skill

├── .claude/

│ └── skills/

│ ├── create-agent/← /create-agent：建立新 Agent 的 SOP

│ │ └── SKILL.md

│ └── skill-creator/← /skill-creator：建立新 Skill，create-agent 會呼叫它

│ └── SKILL.md

├── claude-code-slack-channel/← 所有 Agent 共用，只裝一次

│ ├── server.ts← Socket Mode bridge

│ ├── access.json.policy← 所有 Agent 的 approve 規則

│ └── .env← Slack token（不上 Git）

├── _shared/← Agent 間共用資料層（純資料，不放 skill）

│ ├── weekly-snapshot/← 週期快照 Agent 寫入

│ │ ├── 20260512-snapshot.md

│ │ └── 20260430-monthly.md← 月底版

│ └── reports/← 各 Agent 產出的報告

│ ├── cost-202604.md← Cost 分析 Agent 寫

│ └── okr-202604.md← 報告生成 Agent 寫

├── sre-agent/← SRE 執行 Agent

│ ├── CLAUDE.md

│ ├── .env

│ ├── .claude/skills/

│ │ ├── deploy/← /deploy skill

│ │ │ └── SKILL.md

│ │ ├── update-env/

│ │ │ └── SKILL.md

│ │ ├── new-service-with-chart/

│ │ │ └── SKILL.md

│ │ ├── new-service-fresh/

│ │ │ └── SKILL.md

│ │ ├── preview/

│ │ │ └── SKILL.md

│ │ └── ops-task/

│ │ └── SKILL.md

│ ├── repos/← symlink 到各 deploy repo（不上 Git）

│ └── docs/

│ ├── runbooks/

│ └── rca/

├── manager-agent/← 報告生成 Agent + 會議記錄 Agent（共用 repo）

│ ├── CLAUDE.md← 報告生成角色定義

│ ├── .env

│ ├── .claude/skills/

│ │ ├── monthly-report/

│ │ │ └── SKILL.md

│ │ ├── manager-report/

│ │ │ └── SKILL.md

│ │ ├── 2x2-report/

│ │ │ └── SKILL.md

│ │ └── meeting-notes/← 會議記錄 Agent 的 skill

│ │ └── SKILL.md

│ └── docs/

├── reminder-agent/← 提醒 Agent（待建立）

│ ├── CLAUDE.md

│ └── .env

├── snapshot-agent/← 週期快照 Agent（設計中）

│ ├── CLAUDE.md

│ ├── .env

│ └── .claude/skills/

│ └── weekly-snapshot/

│ └── SKILL.md

├── cost-agent/← Cost 分析 Agent（待建立）

│ ├── CLAUDE.md

│ └── .env

├── task-management-agent/← 任務管理 Agent（待建立）

│ ├── CLAUDE.md

│ └── .env

├── alert-agent/← Alert 處理 Agent（設計中）

│ ├── CLAUDE.md

│ ├── .env

│ ├── .claude/skills/

│ │ └── handle-alert/

│ │ └── SKILL.md

│ └── docs/

│ └── runbooks/← Runbook 與 RCA 存放位置

└── sales-agent/← 現有，搬進來即可

├── CLAUDE.md

├── .env← .gitignore 擋掉

└── .claude/

根目錄 CLAUDE.md 職責

📋~/agents/CLAUDE.md — 總管理員

角色

整個 agents monorepo 的進入點，定義所有 Agent 的共同規範

職責

整體結構規範、_shared/ 路徑定義、建立新 Agent 的 SOP、.gitignore 規則說明

skill

/create-agent → 自動建立新 Agent 的資料夾結構與 CLAUDE.md

使用方式

cd ~/agents → claude → /create-agent

# ~/agents/CLAUDE.md 內容範本

# Agents Monorepo

## 我的職責
管理所有 Agent 的建立、結構規範、共用資料層。

## 整體結構規範
- 每個 Agent 放在獨立資料夾：{agent-name}-agent/
- 共用資料統一放在 _shared/
- 機敏資料一律放 .env，不上 Git
- 每個 Agent 的 CLAUDE.md 必須標注讀取 _shared/ 的路徑

## _shared/ 路徑定義
- 週期快照：_shared/weekly-snapshot/YYYYMMDD-snapshot.md
- 月報原料：_shared/reports/cost-YYYYMM.md
- 共用 skill：_shared/skills/

## 建立新 Agent
使用 /create-agent 指令
    

create-agent 指令 SOP

詢問基本資訊

Agent 名稱、職責描述、需要讀哪些 _shared/ 資料、需要寫到哪些 _shared/ 路徑

建立資料夾結構

mkdir -p {name}-agent/.claude/commands · mkdir -p {name}-agent/docs

生成 CLAUDE.md

根據職責描述生成角色定義，自動填入 _shared/ 讀寫路徑

詢問需要哪些 .env 變數

把變數名稱加進根目錄 .env.example，不填值

建立 .env 空白檔案

touch {name}-agent/.env · 提醒你填入實際值

詢問需要哪些 commands

根據職責建議常用指令，逐一建立 .claude/skills/{name}.md 骨架

輸出建立摘要

列出所有建立的檔案、需要你手動填入的 .env 變數、下一步建議

Agent 間資料共享模式

模式一

共用儲存

週期快照寫到 _shared/weekly-snapshot/，所有需要資料的 Agent 都去那裡讀。Agent 之間不需要互相認識。

現在就可以用

模式二

約定路徑

Cost 分析 Agent 寫到 _shared/reports/cost-YYYYMM.md，報告生成 Agent 從那裡讀。兩個 Agent 約定好路徑格式即可。

現在就可以用

模式三

事件觸發

Agent A 完成後發事件，Agent Broker 路由，觸發 Agent B。需要 Agent Broker 才能實現。

未來 / 需要 Broker

關鍵設定檔範本

# 機敏檔案
**/.env
**/secrets/

# symlink repos（本地路徑，不適合跨主機）
**/repos/

# macOS
.DS_Store

# 含客戶資料的報告（視需要）
_shared/reports/customer-*.md
      

# ── SRE Agent ──
KUBECONFIG=
HELM_REPO_USERNAME=
HELM_REPO_PASSWORD=
PROMETHEUS_URL=
JIRA_TOKEN=
JIRA_BASE_URL=

# ── 報告生成 Agent / 會議記錄 Agent / 提醒 Agent（共用）──
NOTION_API_KEY=
NOTION_DAILY_DB_ID=
NOTION_OKR_PAGE_ID=

# ── Cost 分析 Agent ──
GMAIL_CLIENT_ID=
GMAIL_CLIENT_SECRET=
EXCHANGE_RATE_API_KEY=

# ── 週期快照 Agent ──
PROMETHEUS_URL=
GITHUB_TOKEN=

# ── 卡片管理 Agent ──
JIRA_TOKEN=
GITHUB_TOKEN=

# ── Sales Agent ──
CLAUDE_API_KEY=
ECOMMERCE_API_KEY=
SLACK_BOT_TOKEN=

# ── Alert 處理 Agent ──
PROMETHEUS_URL=
SLACK_ALERT_CHANNEL_ID=
JIRA_TOKEN=

# ── 任務管理 Agent ──
NOTION_API_KEY=
GOOGLE_CALENDAR_TOKEN=

# ── Slack 審核（所有 Agent 共用）──
SLACK_APP_TOKEN=
SLACK_BOT_TOKEN=
SLACK_APPROVE_CHANNEL_ID=
SLACK_NOTIFY_CHANNEL_ID=
      

# SRE 執行 Agent

## 我的職責
負責所有 K8s 相關操作：
- 服務上版（/deploy）
- 環境變數更新（/update-env）
- 新增服務，有/無 chart（/new-service-with-chart、/new-service-fresh）
- Preview 環境建立（/preview）
- 偶爾出現的維運任務（/ops-task，來自 Jira）

## 我讀取的資料
- 週期快照：../_shared/weekly-snapshot/（查 Infra 指標歷史）
- 共用 skill：../_shared/skills/helm-deploy.md

## 我寫入的資料
- RCA 文件：./docs/rca/YYYYMMDD-{service}.md
- Runbook 記錄：./docs/runbooks/alert-log.md

## Cluster 資訊
- prod-bob：namespace prod-bob / prod-sandbox-bob
- prod-microhbot-new：namespace prod-microhbot-new

## Approve 規則
- 執行任何 helm 指令前，推 Slack #agent-approve 等確認
- prod namespace 操作需雙重確認
- Env 變數實際值從 .env 讀取，不在對話中顯示
      

# 報告生成 Agent

## 我的職責
負責生成所有定期報告：
- Monthly Report（每月）
- Manager Group Report（雙週）
- 2x2 個人工作回報（每月）

## 我讀取的資料
- 週期快照：../_shared/weekly-snapshot/（所有報告的原料）
- Cost 報告：../_shared/reports/cost-YYYYMM.md
- Notion Daily Pages（透過 Notion API）

## 我寫入的資料
- 月報文件：../_shared/reports/monthly-YYYYMM.md
- OKR 進度討論：../_shared/reports/okr-YYYYMM.md

## 重要規則
- 生成報告前先讀最新的 snapshot，不問使用者已知的數值問題
- 只問使用者「判斷與決策」類的問題
- 與會議記錄 Agent 共用同一個 repo（manager-agent/）
      

# 提醒 Agent

## 我的職責
Schedule 管理，在不同時間點提醒並要求回填：
- 每天早上 10 點前：確認今日預計工作
- 每天 18:00：問今天實際做了什麼
- 每週一：整理本週計劃
- 月底：提醒準備報告原料

## 我讀取的資料
- Notion Daily Page（透過 Notion API）

## 我寫入的資料
- 回填 Notion Daily Page 下半部（實際工作 / 今日回顧）

## 重要規則
- 只通知，不執行任何寫入操作（Routine 模式）
- 收到你的回覆後，才把內容整理寫回 Notion
- 與報告生成 Agent 共用同一個 repo（manager-agent/）
      

# 週期快照 Agent

## 我的職責
每週自動聚合一份 snapshot.md，作為所有報告的共用原料。
月底加跑一次月度版快照。

## 我讀取的資料
- Notion Daily Pages（Notion API）
- Prometheus / Thanos（Infra 指標）
- optimization-backlog.md（成本清單）
- git log（working-zone / cs-pi-agent / agent-teammate）

## 我寫入的資料
- 週快照：../_shared/weekly-snapshot/YYYYMMDD-snapshot.md
- 月快照：../_shared/weekly-snapshot/YYYYMM-monthly.md

## 重要規則
- 定時自動執行，不需要使用者觸發
- 執行完成後推通知到 Slack #agent-notify
- 任何 API 連線失敗，停止並通知使用者檢查 .env
      

遷移到新主機

1

Clone repo

git clone git@github.com:you/agents.git ~/agents

2

建立各 Agent 的 .env

cp ~/agents/.env.example ~/agents/sre-agent/.env # 然後手動填值

3

重建 repos/ symlink

ln -s ~/projects/helm-charts ~/agents/sre-agent/repos/helm-charts

4

_shared/ 資料已在 Git，直接可用

ls ~/agents/_shared/weekly-snapshot/ # snapshot 都在

Slack 審核架構（所有 Agent 共用）

💬claude-code-slack-channel 橋接

# 架構
你的 Mac
├── Claude Code CLI（任一 agent workspace）
│     ↕ MCP stdio
├── claude-code-slack-channel（本地 server）
│     ↕ WebSocket Socket Mode（不需要公開 URL）
└── Slack workspace
      ├── #agent-approve  ← 需要你 approve 的操作
      └── #agent-notify   ← 完成通知 / 失敗通知
        

✅#agent-approve

所有 Agent 需要你做決定的操作都推到這裡。有訊息 = 需要你處理。

🖥 [SRE Agent] helm upgrade prod-bob ⚠️
⚡ [快照 Agent] 初次 API 設定需確認
🚨 [Alert Agent] Root Cause 需你判斷

🔔#agent-notify

背景執行完成或失敗的通知。不需要即時處理，之後再看。

🖥 [SRE Agent] ✅ helm upgrade 完成
💰 [Cost Agent] 月報原料已產出
🖥 [SRE Agent] ❌ ImagePullBackOff

⚙️Policy 規則（access.json.policy）

// auto_approve：直接執行，不問
{ "id": "safe-reads", "effect": "auto_approve", "match": { "tool": "Read" } }

// require_approval：推 Slack 等你按按鈕
{ "id": "prod-helm", "effect": "require_approval",
  "match": { "tool": "Bash", "pattern": "helm.*(prod)" },
  "approvers": 1, "ttlMs": 300000 }

// deny：直接拒絕，說明原因
{ "id": "no-db", "effect": "deny",
  "match": { "tool": "Bash", "pattern": "psql|mysql" },
  "reason": "直接操作 DB 不在授權範圍" }
        

📁在 monorepo 的位置

~/agents/
├── claude-code-slack-channel/   ← 所有 Agent 共用，只裝一次
│   ├── server.ts
│   ├── access.json.policy       ← 所有 Agent 的 policy 規則
│   └── .env                     ← Slack token（不上 Git）
├── sre-agent/
├── manager-agent/
└── sales-agent/
        

一個 Slack channel bridge，服務所有 Agent。不需要每個 Agent 各自安裝。

Cloudflare D1 的位置（未來）

✓適合放 D1

OKR 進度數值（可 query 歷史趨勢）、Alert 記錄（可查 MTTR）、Cost 歷史數據（可跑月比較 SQL）、Agent 執行記錄

結構化、需要跨 Agent 查詢的資料

✕不適合放 D1

CLAUDE.md、snapshot.md、SOP 文件、commands/ 指令

純文字設定檔，放 Git 就好

◎整體資料架構（含 D1）

Git repo（私有）
└── CLAUDE.md / commands / docs / snapshot.md
    → 可跨主機 clone，遷移容易

Cloudflare D1（未來）
└── OKR 數值 / Alert 記錄 / Cost 歷史 / 執行記錄
    → 結構化，可 SQL 查詢，不怕遷移

本地 .env（不上 Git）
└── API keys / DB 密碼 / 機敏 Env 變數
    → 遷移時手動複製或用密碼管理工具
        