Agentic OS
將 Claude Code 視為一個持久的運行時/操作系統，而非單純的聊天會話。此技能將生產級代理系統所使用的架構模式化：一個將任務路由給專業代理的核心配置、持久的基於檔案記憶、排程自動化，以及一個 JSON/Markdown 資料層。
啟動時機
- 在 Claude Code 內部建立多代理工作流程
- 設定能跨會話重啟持久運作的 Claude Code 自動化
- 為重複性任務建立「個人 OS」或「代理 OS」
- 使用者提及「agentic OS」、「personal OS」、「multi-agent」、「agent coordinator」、「persistent agent」
- 構建需要跨會話保持上下文長期執行的專案
架構總覽
Agentic OS 包含四個層級，每個層級對應專案根目錄下的一個目錄。
project-root/
├── CLAUDE.md # 核心：身份、路由規則、代理註冊表
├── agents/ # 專業代理定義（Markdown 提示詞）
├── .claude/commands/ # 斜線命令：面向使用者的 CLI
├── scripts/ # 守護行程腳本：排程或事件驅動任務
└── data/ # 狀態：JSON/Markdown 檔案系統，無需外部資料庫
各層級職責
| 層級 | 目的 | 持久性 |
|---|---|---|
核心 (CLAUDE.md) | 身份、路由、模型政策、代理註冊表 | Git 追蹤 |
代理 (agents/) | 專業代理的身份，包含限定範圍的工具與記憶 | Git 追蹤 |
命令 (.claude/commands/) | 面向使用者的斜線命令 (/daily-sync, /outreach) | Git 追蹤 |
腳本 (scripts/) | 由 cron 或 webhook 觸發的 Python/JS 守護行程 | Git 追蹤 |
狀態 (data/) | 僅追加的日誌、專案狀態、決策記錄 | Git 忽略或追蹤 |
核心
CLAUDE.md 是核心。它扮演 COO / 協調者的角色。Claude 在會話啟動時讀取它，並用它來路由工作。
核心結構
# CLAUDE.md - Agentic OS 核心
## 身份
你是 [專案名稱] 的 COO。你負責將任務路由給專業代理。
你永遠不會直接撰寫程式碼。你將任務委派給合適的代理，並整合結果。
## 代理註冊表
| 代理 | 角色 | 觸發條件 |
|---|---|---|
| @dev | 程式碼、架構、除錯 | 使用者說「build」、「fix」、「refactor」 |
| @writer | 文件、內容、電子郵件 | 使用者說「write」、「draft」、「blog」 |
| @researcher | 研究、分析、事實查核 | 使用者說「research」、「analyze」、「compare」 |
| @ops | DevOps、部署、基礎設施 | 使用者說「deploy」、「CI」、「server」 |
## 路由規則
1. 解析使用者請求中的意圖關鍵字
2. 比對代理註冊表的「觸發條件」欄位
3. 從 `agents/<name>.md` 載入對應的代理檔案
4. 攜帶完整上下文移交執行
5. 合成並將結果呈現回使用者
## 模型政策
- 預設模型：使用儲存庫或環境的預設設定。
- @dev 任務：對於複雜架構，偏好使用高推理能力的模型。
- @researcher 任務：使用配置的研究用模型及已核准的搜尋工具。
- 成本上限：在超出專案配置的花費門檻前發出警告。
關鍵原則
核心應該簡潔且宣告式。路由邏輯應放在純 Markdown 表格中，而非程式碼中。這使得系統可檢查、可編輯，且無需除錯。
專業代理
每個代理是 agents/ 中的一個獨立 Markdown 檔案。Claude 在路由任務時載入相關的代理檔案。
代理定義格式
# @dev - 軟體工程師
## 身份
你是一位資深軟體工程師。你撰寫乾淨、經過測試、符合生產標準的程式碼。
你偏好簡單的解決方案。當需求不明確時，你會提出釐清問題。
## 記憶範圍
- 讀取 `data/projects/<current-project>.md` 以了解上下文
- 讀取 `data/decisions/` 以了解架構決策
- 將執行日誌附加到 `data/logs/<date>[email protected]`
## 工具存取權限
- 專案根目錄內的完整檔案系統存取權
- Git 操作（status, diff, commit, branch）
- 測試執行器存取權
- 如 `.claude/mcp.json` 中所配置的 MCP 伺服器
## 限制
- 永遠為新功能撰寫測試
- 永遠不要直接提交到 `main`；應使用功能分支
- 優先編輯現有檔案，而非建立新檔案
- 盡可能保持函數在 50 行以內
多代理協作模式
當任務橫跨多個代理時，核心會依序或並行執行它們：
使用者：「建立一個登陸頁面，並撰寫啟動部落格文章」
核心路由：
1. @dev - 「使用 [需求] 建立登陸頁面」
2. @writer - 「針對 [產品] 並使用登陸頁面文案，撰寫啟動部落格文章」
3. 核心將兩者的輸出合成為統一回應
對於並行執行，可使用 Claude Code 的背景任務功能，或使用帶有特定代理上下文的 shell 腳本來呼叫 Claude Code。
命令與日常工作流程
斜線命令是位於 .claude/commands/ 中的 Markdown 檔案。它們定義了可重複使用的工作流程。
命令結構
# /daily-sync
執行晨間簡報：
1. 讀取 `data/logs/last-sync.md` 以了解上下文
2. 檢查專案狀態：`git status`、待處理 PR、CI 健康狀況
3. 檢視 `data/inbox/` 中是否有新任務或待決策事項
4. 產生障礙、優先事項與下一步行動的摘要
5. 將簡報附加到 `data/logs/daily/<date>.md`
標準命令集
| 命令 | 用途 |
|---|---|
/daily-sync | 晨間簡報：狀態、障礙、優先事項 |
/outreach | 執行外展工作流程（電子郵件、LinkedIn 等） |
/research <topic> | 深度研究，附帶引用追蹤 |
/apply-jobs | 為目標職位量身打造履歷 + 求職信 |
/analytics | 從 Stripe、GitHub 或自訂來源提取指標 |
/interview-prep | 產生學習卡片或模擬面試問題 |
/decision <topic> | 記錄決策，包含優缺點與選擇路徑 |
啟用命令
將命令檔案放置在 .claude/commands/<command-name>.md。Claude Code 會自動發現它們。使用者透過 /<command-name> 來呼叫。
持久記憶
記憶是基於檔案的。無需向量資料庫、Redis 或 PostgreSQL。data/ 中的 JSON 和 Markdown 檔案就是資料庫。
記憶目錄結構
data/
├── daily-logs/ # 僅追加的每日活動日誌
├── projects/ # 每個專案的上下文檔案
├── decisions/ # 架構與業務決策（ADR 格式）
├── inbox/ # 等待分類的新任務或想法
├── contacts/ # 人物、公司、關係筆記
└── templates/ # 可重複使用的提示詞與格式
每日日誌格式
# 2026-04-22 - 每日日誌
## 會話
- 09:00 - 會話 1：重構驗證模組 (@dev)
- 11:30 - 會話 2：草擬投資者更新 (@writer)
## 決策
- 從 JWT 切換到 Session Cookie（參見 `data/decisions/2026-04-22-auth.md`）
## 障礙
- 等待供應商的 API 金鑰（2026-04-24 跟進）
## 下一步行動
- [ ] 合併驗證重構 PR
- [ ] 發送投資者更新以供審閱
自動反思模式
在每個會話結束時，核心會附加一段反思：
## 反思 - 會話 3
- 有效做法：並行代理執行節省了 20 分鐘
- 無效做法：@researcher 遇到付費牆來源，需要更好的來源排名
- 改進方向：在研究筆記中添加 `source-tier` 欄位（A/B/C 可信度）
這創建了一個回饋迴路，無需修改程式碼即可隨著時間推移改善系統。
排程自動化
Agentic OS 任務透過外部 cron 工具來排程執行，而非使用 Claude Code 的內建 cron（因為會話結束時內建 cron 會終止）。
macOS：LaunchAgent
<!-- ~/Library/LaunchAgents/com.agentic.daily-sync.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" ...>
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.agentic.daily-sync</string>
<key>ProgramArguments</key>
<array>
<string>/claude</string>
<string>--cwd</string>
<string>/path/to/project</string>
<string>--command</string>
<string>/daily-sync</string>
</array>
<key>StartCalendarInterval</key>
<dict>
<key>Hour</key>
<integer>8</integer>
<key>Minute</key>
<integer>0</integer>
</dict>
<key>StandardOutPath</key>
<string>/tmp/agentic-daily-sync.log</string>
</dict>
</plist>
Linux：systemd 計時器
# ~/.config/systemd/user/agentic-daily-sync.service
[Unit]
Description=Agentic OS 每日同步
[Service]
Type=oneshot
ExecStart=/usr/local/bin/claude --cwd /path/to/project --command /daily-sync
# ~/.config/systemd/user/agentic-daily-sync.timer
[Unit]
Description=每天早上執行每日同步
[Timer]
OnCalendar=*-*-* 8:00:00
Persistent=true
[Install]
WantedBy=timers.target
跨平台：pm2
# ecosystem.config.js
module.exports = {
apps: [{
name: 'agentic-daily-sync',
script: 'claude',
args: '--cwd /path/to/project --command /daily-sync',
cron_restart: '0 8 * * *',
autorestart: false
}]
};
資料層
資料層就是你的檔案系統。對結構化資料使用 JSON，對敘述性內容使用 Markdown。
Json 用於結構化狀態
// data/projects/website-v2.json
{
"name": "Website v2",
"status": "in-progress",
"milestone": "beta-launch",
"agents_involved": ["@dev", "@writer"],
"files": {
"spec": "docs/website-v2-spec.md",
"design": "designs/website-v2.fig"
},
"metrics": {
"commits": 47,
"last_session": "2026-04-22T11:30:00Z"
}
}
Markdown 用於敘述性內容
對任何人類可讀的內容使用 Markdown：決策、日誌、研究筆記、聯絡記錄。
結構演進
永遠不要重新命名現有欄位。應新增欄位並將舊標記為已棄用：
{
"name": "Website v2",
"status": "in-progress",
"milestone": "beta-launch",
"_deprecated_priority": "high",
"priority_v2": { "level": "high", "rationale": "Block investor demo 的障礙" }
}
這樣可以在無需遷移腳本的情況下保持歷史資料的可讀性。
反模式
單一巨型代理
# 錯誤 - 一個代理包辦所有事情
你是一位全端開發者、作家、研究員和 DevOps 工程師。
應拆分為專業代理。核心負責路由。
無狀態會話
# 錯誤 - 會話之間沒有記憶
每次 Claude Code 開啟都從頭開始。
務必在會話開始時讀取 data/，並在會話結束時寫回。
硬編碼憑證
# 錯誤 - API 金鑰寫在代理檔案或 CLAUDE.md 中
你的 OpenAI API 金鑰是 sk-xxxxxxxx
使用環境變數或由腳本載入的 .env 檔案。代理應引用 process.env.API_KEY。
為簡單狀態使用外部資料庫
# 錯誤 - 為單一使用者的代理 OS 使用 PostgreSQL
直到你需要處理多位並發使用者或 GB 級資料之前，請使用 JSON/Markdown 檔案。
過度設計的路由
# 錯誤 - 路由邏輯寫在程式碼而非 Markdown 表格中
if (intent.includes('deploy')) { agent = opsAgent; }
保持路由在 CLAUDE.md 中以宣告式 Markdown 表格呈現。它應該是可檢查、可編輯且可除錯的。
最佳實踐
-
CLAUDE.md少於 200 行且能放入上下文視窗 - 每個代理檔案少於 100 行且專注於單一領域
- 敏感日誌的
data/目錄應被 Git 忽略，決策與規格則由 Git 追蹤 - 命令使用祈使句名稱：
/daily-sync，而非/run-daily-sync - 日誌僅追加；永遠不要編輯過去的每日日誌
- 每個代理都有一個「記憶範圍」章節，定義其讀取的檔案
- 每個會話結束時都要撰寫反思
- 排程任務使用外部 cron（LaunchAgent、systemd、pm2），而非 Claude Code 的會話 cron
- 成本追蹤：將每次會話的 API 花費記錄在
data/logs/<date>-costs.json中 - 一個專案 = 一個 Agentic OS。不要在不同專案間共用同一個
CLAUDE.md。