agentic-os

Agentic OS

將 Claude Code 視為持久運行的執行階段（Runtime）或作業系統，而非單次的對話 Session。本 Skill 將正式生產環境中 Agentic 系統的架構規範化：包含一個負責將任務分派給專責 Agent 的核心配置（Kernel config）、基於檔案的持久化記憶、定時自動化，以及 JSON/Markdown 資料層。

什麼時候使用

• 在 Claude Code 內建立多 Agent 工作流程
• 設定跨 Session 重新啟動後依然存活的持久化 Claude Code 自動化流程
• 為日常重複性任務打造「個人 OS」或「Agentic OS」
• 使用者提及「agentic OS」、「personal OS」、「multi-agent」、「agent coordinator」、「persistent agent」
• 規劃跨 Session 仍需保留上下文（Context）的長期專案結構

架構總覽

Agentic OS 包含四個層級，每個層級對應專案根目錄下的一個資料夾：

project-root/
├── CLAUDE.md          # 核心（Kernel）：身份、路由規則、Agent 註冊表
├── agents/            # 專責 Agent 定義檔（Markdown 提示詞）
├── .claude/commands/  # 斜線指令：面向使用者的 CLI 介面
├── scripts/           # 背景服務腳本：由 Cron 或 Webhook 觸發的定時/事件驅動任務
└── data/              # 狀態層：JSON/Markdown 檔案系統，無需外部資料庫

各層職責

層級	用途	持久化方式
核心 (CLAUDE.md)	身份判定、路由分派、模型策略、Agent 註冊表	Git 追蹤
Agents (agents/)	具備獨立工具與記憶範圍的專責 Agent 身份	Git 追蹤
Commands (.claude/commands/)	面向使用者的斜線指令（如 /daily-sync、/outreach）	Git 追蹤
Scripts (scripts/)	由 Cron 或 Webhook 觸發的 Python/JS 背景腳本	Git 追蹤
狀態 (data/)	只增不刪的 Log 紀錄、專案狀態、決策紀錄	Git 忽略或追蹤

核心（The Kernel）

CLAUDE.md 即為系統核心，角色類似營運長（COO）或協調器（Orchestrator）。Claude 會在 Session 啟動時讀取此檔案，並依據內容分派工作。

核心結構

# CLAUDE.md - Agentic OS Kernel

## 身份
你是 [project-name] 的營運長（COO），負責將任務分派給相應的專責 Agent。
你絕不直接撰寫程式碼，而是授權給合適的 Agent 執行並整合結果。

## Agent 註冊表

| Agent | 角色 | 觸發條件 |
|---|---|---|
| @dev | 程式碼、系統架構、除錯 | 使用者說「build」、「fix」、「refactor」 |
| @writer | 技術文件、內容創作、信件草稿 | 使用者說「write」、「draft」、「blog」 |
| @researcher | 市場/技術研究、分析、事實查核 | 使用者說「research」、「analyze」、「compare」 |
| @ops | DevOps、部署、基礎架構 | 使用者說「deploy」、「CI」、「server」 |

## 路由規則
1. 解析使用者需求中的意圖關鍵字
2. 比對 Agent 註冊表中的「觸發條件」欄位
3. 從 `agents/<name>.md` 載入對應的 Agent 檔案
4. 附帶完整上下文並交接執行
5. 整合執行結果並呈現給使用者

## 模型策略
- 預設模型：使用儲存庫或環境預設設定。
- @dev 任務：針對複雜架構，優先選用高推理能力的模型。
- @researcher 任務：使用已配置且具備研究能力的模型與核可的搜尋工具。
- 成本上限：若即將超出專案設定的預算門檻，需事先發出警告。

核心原則

核心應保持輕量且宣告式。路由邏輯應寫在直觀的 Markdown 表格中，而非程式碼內。這樣能讓系統無需經過複雜除錯，就能隨時檢視與修改。

專責 Agent（Specialist Agents）

每個 Agent 都是 agents/ 資料夾下的獨立 Markdown 檔案。Claude 在路由任務時會載入對應的 Agent 檔案。

Agent 定義格式

# @dev - 軟體工程師

## 身份
你是一位資深軟體工程師，專門撰寫乾淨、經過測試且達生產環境標準的程式碼。
你偏好簡潔的解決方案；當需求模糊時，你會提出澄清問題。

## 記憶存取範圍
- 讀取 `data/projects/<current-project>.md` 以取得專案內容
- 讀取 `data/decisions/` 以參考架構決策紀錄
- 將執行日誌追加寫入至 `data/logs/<date>-@dev.md`

## 工具權限
- 專案根目錄下的完整檔案系統存取權限
- Git 操作權限（status, diff, commit, branch）
- 測試執行工具存取權
- `.claude/mcp.json` 中配置的 MCP 伺服器

## 行為約束
- 撰寫新功能時必須同步編寫測試
- 絕不直接 Commit 到 `main` 分支；必須使用 Feature 分支
- 優先修改現有檔案，避免無謂創建新檔案
- 儘量將函式長度控制在 50 行以內

多 Agent 協作模式

當任務橫跨多個 Agent 領域時，核心會依序或平行呼叫它們：

使用者：「幫我建立一個 Landing Page，並撰寫產品發布的 Blog 文章」

核心路由流程：
1. @dev - 「根據 [需求] 打造 Landing Page」
2. @writer - 「參考 Landing Page 文案，為 [產品] 撰寫發布 Blog 文章」
3. 核心整合兩者的輸出成果，產生統一的回覆內容

若需平行執行，可利用 Claude Code 的背景任務功能，或透過 Shell 腳本附帶特定 Agent 的 Context 來呼叫 Claude Code。

指令與日常工作流程（Commands and Daily Workflows）

斜線指令（Slash Commands）是位於 .claude/commands/ 內的 Markdown 檔案，用於定義可重複使用的自動化工作流程。

指令結構

# /daily-sync

執行晨報同步流程：

1. 讀取 `data/logs/last-sync.md` 以獲取脈絡
2. 檢查專案狀態：執行 `git status`、檢查待審 PR 及 CI 狀態
3. 檢視 `data/inbox/` 內待處理的新任務或決策事項
4. 整理出阻塞因素（Blockers）、優先事項與下一步行動摘要
5. 將晨報內容追加至 `data/logs/daily/<date>.md`

標準指令集

指令	用途
/daily-sync	晨報同步：狀態回報、阻塞因素、優先事項
/outreach	執行外聯流程（Email、LinkedIn 等）
/research <topic>	深度研究並追蹤引用來源
/apply-jobs	針對目標職缺客製化履歷與求職信
/analytics	拉取 Stripe、GitHub 或自訂資料源的數據
/interview-prep	生成面試單字卡或模擬面試問題
/decision <topic>	記錄決策過程（優缺點評估與最終方案）

啟用指令

將指令檔案放置於 .claude/commands/<command-name>.md，Claude Code 便會自動偵測。使用者即可透過 /<command-name> 直接呼叫。

持久化記憶（Persistent Memory）

記憶是以檔案形式儲存，無需 Vector DB、Redis 或 PostgreSQL。data/ 目錄下的 JSON 與 Markdown 檔案就是系統的資料庫。

記憶目錄結構

data/
├── daily-logs/         # 只增不刪的每日活動 Log
├── projects/           # 各專案上下文檔案
├── decisions/          # 架構與商業決策紀錄（ADR 格式）
├── inbox/              # 待分流的新任務或想法
├── contacts/           # 人脈、公司與互動紀錄
└── templates/          # 可重複使用的提示詞與格式範本

每日 Log 格式

# 2026-04-22 - 每日 Log

## 工作階段
- 09:00 - 階段 1：重構驗證模組 (@dev)
- 11:30 - 階段 2：起草投資人更新簡報 (@writer)

## 決策紀錄
- 從 JWT 切換為 Session Cookies（詳見 `data/decisions/2026-04-22-auth.md`）

## 阻塞因素
- 等待廠商提供 API Key（預計 2026-04-24 追蹤）

## 下一步行動
- [ ] 合併驗證模組重構 PR
- [ ] 寄送投資人更新草稿進行審閱

自動反思模式（Auto-Reflection Pattern）

在每個 Session 結束時，核心會追加一段反思紀錄：

## 反思 - 階段 3
- 成功經驗：平行執行 Agent 節省了 20 分鐘
- 改善空間：@researcher 遇到付費牆來源，需要調整來源權重排序
- 調整方案：在研究筆記中新增 `source-tier` 欄位（標示 A/B/C 可信度）

這能建立持續自我優化的回饋機制，無需修改任何系統程式碼即可隨時間漸進改善。

定時自動化（Scheduled Automation）

Agentic OS 任務是透過外部 Cron 系統來進行定時排程，而非依賴 Claude Code 內建的 Cron（因 Session 結束後即會失效）。

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 Timer

# ~/.config/systemd/user/agentic-daily-sync.service
[Unit]
Description=Agentic OS Daily Sync

[Service]
Type=oneshot
ExecStart=/usr/local/bin/claude --cwd /path/to/project --command /daily-sync

# ~/.config/systemd/user/agentic-daily-sync.timer
[Unit]
Description=Run daily sync every morning

[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
  }]
};

資料層（Data Layer）

檔案系統即為你的資料層。結構化資料請使用 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

凡需供人類閱讀的內容，如決策、Log、研究筆記、聯絡人紀錄等，一律使用 Markdown。

Schema 演進

切勿重命名既有欄位。應採新增欄位並將舊欄位標記為廢棄（Deprecated）：

{
  "name": "Website v2",
  "status": "in-progress",
  "milestone": "beta-launch",
  "_deprecated_priority": "high",
  "priority_v2": { "level": "high", "rationale": "Blocks investor demo" }
}

這樣可在無需撰寫資料轉移（Migration）腳本的前提下，確保歷史資料依舊可讀。

反模式（Anti-Patterns）

單一巨型 Agent（Monolithic Single Agent）

# 錯誤示範 - 由單一 Agent 包辦所有工作
你是一位全端開發者、文案撰寫員、研究員兼 DevOps 工程師。

應拆解為多個專責 Agent，由核心統一處理路由分派。

無狀態 Session（Stateless Sessions）

# 錯誤示範 - Session 間缺乏記憶傳承
每次開啟 Claude Code 都從頭開始。

務必在 Session 啟動時讀取 data/，並於 Session 結束時將變更寫回。

硬編碼金鑰（Hardcoded Credentials）

# 錯誤示範 - 在 Agent 檔案或 CLAUDE.md 中明文寫入 API Key
你的 OpenAI API key 是 sk-xxxxxxxx

應使用環境變數或經由腳本載入的 .env 檔案，由 Agent 透過 process.env.API_KEY 引用。

簡單狀態使用外部資料庫

# 錯誤示範 - 單人使用的 Agentic OS 卻引進 PostgreSQL

在尚未出現多使用者共用或 GB 級資料規模前，請堅持使用 JSON/Markdown 檔案。

過度設計路由邏輯

# 錯誤示範 - 將路由邏輯寫死在程式碼中而非 Markdown 表格
if (intent.includes('deploy')) { agent = opsAgent; }

請保持路由邏輯以宣告方式呈現在 CLAUDE.md 的 Markdown 表格中，易於檢視、編輯與除錯。

最佳實踐（Best Practices）

• [ ] CLAUDE.md 控制在 200 行以內，確保能完整放入 Context Window
• [ ] 每個 Agent 檔案控制在 100 行以內，且專注於單一領域
• [ ] data/ 中敏感的 Log 設定為 Git 忽略，決策與規格文件則納入 Git 追蹤
• [ ] 指令命名採用動詞形式：使用 /daily-sync 而非 /run-daily-sync
• [ ] Log 採取只增不刪（Append-only）原則；切勿修改過往的每日 Log
• [ ] 每個 Agent 均應包含 記憶存取範圍（Memory Scope）區塊，明確定義其可讀取的檔案
• [ ] 每次 Session 結束時均會寫入反思紀錄
• [ ] 定時任務使用外部 Cron 機制（LaunchAgent, systemd, pm2），而非 Claude Code 的 Session Cron
• [ ]