agentic-os

Agentic OS

将 Claude Code 打造为一个持久化的运行环境 / 操作系统，而不仅仅是一个聊天会话。本 Skill 规范总结了生产级 Agent 系统所采用的架构方案：通过内核配置将任务路由至各个专家 Agent，搭配基于文件的持久化记忆、定时自动化，以及基于 JSON/Markdown 的数据层。

适用场景

• 在 Claude Code 中构建多 Agent 工作流
• 搭建跨会话重启依然常驻的 Claude Code 自动化流程
• 为日常高频任务打造“个人 OS”或“Agentic OS”
• 用户提及“agentic OS”、“个人 OS”、“多 Agent”、“Agent 协调器”、“持久化 Agent”
• 规划需要跨会话保留上下文信息的长期项目

架构概览

Agentic OS 包含四个层级。每个层级对应项目根目录下的一个文件夹：

project-root/
├── CLAUDE.md          # 内核：身份设定、路由规则、Agent 注册表
├── agents/            # 专家 Agent 定义文件（Markdown 提示词）
├── .claude/commands/  # 斜杠命令：面向用户的命令行接口 (CLI)
├── scripts/           # 守护进程脚本：定时任务或事件驱动任务
└── data/              # 状态存储：基于 JSON/Markdown 的文件系统，无需外部数据库

各层职责分工

层级	职责	持久化方式
内核 (CLAUDE.md)	身份定义、任务路由、模型策略、Agent 注册表	Git 跟踪管理
专家 Agent (agents/)	具象化的专家身份，搭配独立作用域的工具与记忆	Git 跟踪管理
命令 (.claude/commands/)	面向用户的斜杠命令（如 /daily-sync、/outreach）	Git 跟踪管理
脚本 (scripts/)	由 Cron 或 Webhook 触发的 Python/JS 守护脚本	Git 跟踪管理
状态 (data/)	追加式日志、项目状态、决策记录	Git 忽略或跟踪管理

内核 (Kernel)

CLAUDE.md 即为系统的内核，扮演着首席运营官 (COO) 或调度器的角色。Claude 在会话启动时会优先读取该文件，并据此对后续工作进行路由调度。

内核文件结构

# CLAUDE.md - Agentic OS Kernel

## Identity
You are the COO of [project-name]. You route tasks to specialist agents.
You never write code directly. You delegate to the right agent and synthesize results.

## Agent Registry

| Agent | Role | Trigger |
|---|---|---|
| @dev | Code, architecture, debugging | User says "build", "fix", "refactor" |
| @writer | Documentation, content, emails | User says "write", "draft", "blog" |
| @researcher | Research, analysis, fact-checking | User says "research", "analyze", "compare" |
| @ops | DevOps, deployment, infrastructure | User says "deploy", "CI", "server" |

## Routing Rules
1. Parse the user request for intent keywords
2. Match to the Agent Registry trigger column
3. Load the corresponding agent file from `agents/<name>.md`
4. Hand off execution with full context
5. Synthesize and present the result back to the user

## Model Policies
- Default model: use the repository or harness default.
- @dev tasks: prefer a higher-reasoning model for complex architecture.
- @researcher tasks: use the configured research-capable model and approved search tools.
- Cost ceiling: warn before exceeding the project's configured spend threshold.

核心原则

内核应当保持精简且声明化。路由逻辑直接写在 Plain Markdown 表格中，而不是死板的代码里。这使得整个系统无需繁琐调试，即可随时预览和直接修改。

专家 Agent (Specialist Agents)

每个 Agent 都是 agents/ 目录下的一个独立 Markdown 文件。当 Claude 进行任务路由时，会自动加载对应的 Agent 文件。

Agent 定义格式

# @dev - Software Engineer

## Identity
You are a senior software engineer. You write clean, tested, production-grade code.
You prefer simple solutions. You ask clarifying questions when requirements are ambiguous.

## Memory Scope
- Read `data/projects/<current-project>.md` for context
- Read `data/decisions/` for architectural decisions
- Append execution logs to `data/logs/<date>-@dev.md`

## Tool Access
- Full filesystem access within project root
- Git operations (status, diff, commit, branch)
- Test runner access
- MCP servers as configured in `.claude/mcp.json`

## Constraints
- Always write tests for new features
- Never commit directly to `main`; use feature branches
- Prefer editing existing files over creating new ones
- Keep functions under 50 lines when possible

多 Agent 协作模式

当一个任务跨越多个领域时，内核会串行或并行调用对应的 Agent：

用户: "Build a landing page and write the launch blog post"

内核路由调度:
1. @dev - "Build a landing page with [requirements]"
2. @writer - "Write a launch blog post for [product] using the landing page copy"
3. 内核汇总两者的输出，合成为最终回复

若需并行执行，可借助 Claude Code 的后台任务 (background task) 功能，或通过 Shell 脚本同时传入不同 Agent 的上下文来调用 Claude Code。

Slash 命令与日常工作流

斜杠命令是存放在 .claude/commands/ 目录下的 Markdown 文件，用于定义可复用的工作流。

命令文件结构

# /daily-sync

Run the morning briefing:

1. Read `data/logs/last-sync.md` for context
2. Check project status: `git status`, pending PRs, CI health
3. Review `data/inbox/` for new tasks or decisions needed
4. Generate a summary of blockers, priorities, and next actions
5. Append the briefing to `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> 直接触发。

持久化记忆

记忆完全基于本地文件构建。不需要 Vector DB（向量数据库）、不需要 Redis，也不需要 PostgreSQL。存放在 data/ 目录下的 JSON 和 Markdown 文件就是全量数据库。

记忆目录结构

data/
├── daily-logs/         # 追加式日常活动日志
├── projects/           # 各项目专属上下文文件
├── decisions/          # 架构与业务决策记录（采用 ADR 格式）
├── inbox/              # 待分流的新任务或灵感想法
├── contacts/           # 人脉、合作公司与关系备注
└── templates/          # 可复用的 Prompt 模板与标准格式

日常日志格式

# 2026-04-22 - Daily Log

## Sessions
- 09:00 - Session 1: Refactored auth module (@dev)
- 11:30 - Session 2: Drafted investor update (@writer)

## Decisions
- Switched from JWT to session cookies (see `data/decisions/2026-04-22-auth.md`)

## Blockers
- Waiting on API key from vendor (follow up 2026-04-24)

## Next Actions
- [ ] Merge auth refactor PR
- [ ] Send investor update for review

自动复盘模式 (Auto-Reflection)

在每次 Session 结束时，内核会追加一段复盘总结：

## Reflection - Session 3
- What worked: Parallel agent execution saved 20 minutes
- What didn't: @researcher hit a paywalled source, need better source ranking
- What to change: Add `source-tier` field to research notes (A/B/C credibility)

这样就形成了一个自闭环的反馈机制，无需改动任何底层代码，就能让系统随时间推移越来越聪明。

定时自动化 (Scheduled Automation)

Agentic OS 的定时任务依靠外部 Cron 运行，而不是依赖 Claude Code 自带的定时机制（因为会话关闭时内置 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 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

适合人类阅读的文本请一律采用 Markdown：如决策记录、日志、调研笔记、联系人档案等。

Schema 演进策略

切勿直接重命名现有字段！建议增加新字段并将旧字段标注为弃用 (deprecated)：

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

这种做法保证了在不需要写任何数据迁移脚本的情况下，历史数据依然完全可读。

反模式 (Anti-Patterns)

臃肿的单体 Agent (Monolithic Single Agent)

# 错误做法 - 一个 Agent 承担所有职责
You are a full-stack developer, writer, researcher, and DevOps engineer.

拆分为专职的专家 Agent，由内核负责路由调度。

无状态会话 (Stateless Sessions)

# 错误做法 - 会话之间没有任何记忆
Starting fresh every time Claude Code opens.

在 Session 开始时务必先读取 data/，Session 结束时及时将变更写回 data/。

硬编码凭据 (Hardcoded Credentials)

# 错误做法 - 在 Agent 文件或 CLAUDE.md 中写入 API Key
Your OpenAI API key is sk-xxxxxxxx

使用环境变量或由脚本加载的 .env 文件。Agent 中统一通过 process.env.API_KEY 进行引用。

为简单状态引入外部数据库

# 错误做法 - 为单用户个人 Agent 系统配置 PostgreSQL

在没有海量数据（如 GB 级）或多用户并发场景前，坚持使用简单的 JSON / Markdown 文件。

过度设计的路由逻辑

# 错误做法 - 在代码中死板硬编码路由规则
if (intent.includes('deploy')) { agent = opsAgent; }

保持路由逻辑在 CLAUDE.md 的 Markdown 表格中声明化呈现。直观、易改、易排错。

最佳实践 (Best Practices)

• [ ] CLAUDE.md 行数控制在 200 行以内，能完整塞入上下文窗口
• [ ] 每个 Agent 文件控制在 100 行以内，聚焦于单一专业领域
• [ ] data/ 中的敏感日志添加至 Git 忽略，决策与规范文件纳入 Git 跟踪
• [ ] 命令采用动词祈使句命名：如 /daily-sync，而非 /run-daily-sync
• [ ] 日志仅允许追加 (Append-only)，绝不篡改历史日志
• [ ] 每个 Agent 都配备 Memory Scope 章节，清晰定义其可读取的文件范围
• [ ] 在每次 Session 结束时自动写入 Reflection 复盘
• [ ] 定时任务统一使用外部 Cron（如 LaunchAgent、systemd、pm2），绝不使用 Claude Code 随会话结束而销毁的临时 Cron
• [ ]