agentic-os

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agentic OS

Treat Claude Code as a persistent runtime / operating system rather than a chat session. This skill codifies the architecture used by production agentic setups: a kernel config that routes tasks to specialist agents, persistent file-based memory, scheduled automation, and a JSON/markdown data layer.

将Claude Code视为持久化运行时/操作系统，而非聊天会话。本技能梳理了生产级Agent系统所采用的架构：可将任务路由至专业Agent的内核配置、持久化基于文件的内存、定时自动化，以及JSON/Markdown数据层。

When to Activate

激活场景

Building a multi-agent workflow inside Claude Code
Setting up persistent Claude Code automation that survives session restarts
Creating a "personal OS" or "agentic OS" for recurring tasks
User says "agentic OS", "personal OS", "multi-agent", "agent coordinator", "persistent agent"
Structuring long-running projects where context must survive across sessions

在Claude Code内构建多Agent工作流
设置可跨会话重启的持久化Claude Code自动化任务
为重复性任务创建「个人操作系统」或「Agentic操作系统」
用户提及「agentic OS」、「personal OS」、「multi-agent」、「agent coordinator」、「persistent agent」时
构建需跨会话保留上下文的长期项目

Architecture Overview

架构概述

The Agentic OS has four layers. Each layer is a directory in your project root.

project-root/
├── CLAUDE.md          # Kernel: identity, routing rules, agent registry
├── agents/            # Specialist agent definitions (markdown prompts)
├── .claude/commands/  # Slash commands: user-facing CLI
├── scripts/           # Daemon scripts: scheduled or event-driven tasks
└── data/              # State: JSON/markdown filesystem, no external DB

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

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

Layer Responsibilities

各层职责

Layer	Purpose	Persistence
Kernel ( `CLAUDE.md` )	Identity, routing, model policies, agent registry	Git-tracked
Agents ( `agents/` )	Specialist identities with scoped tools and memory	Git-tracked
Commands ( `.claude/commands/` )	User-facing slash commands ( `/daily-sync` , `/outreach` )	Git-tracked
Scripts ( `scripts/` )	Python/JS daemons triggered by cron or webhooks	Git-tracked
State ( `data/` )	Append-only logs, project state, decision records	Git-ignored or tracked

层级	用途	持久化方式
内核（ `CLAUDE.md` ）	身份标识、任务路由、模型策略、Agent注册表	Git追踪
Agents（ `agents/` ）	具备专属工具和内存的专业Agent身份	Git追踪
命令（ `.claude/commands/` ）	面向用户的斜杠命令（ `/daily-sync` 、 `/outreach` ）	Git追踪
脚本（ `scripts/` ）	由cron或Webhook触发的Python/JS守护进程	Git追踪
状态（ `data/` ）	追加式日志、项目状态、决策记录	Git忽略或追踪

The Kernel

内核

CLAUDE.md

is the kernel. It acts as the COO / orchestrator. Claude reads it at session start and uses it to route work.

CLAUDE.md

是系统内核，扮演首席运营官/编排器的角色。Claude会在会话启动时读取该文件，并依据其规则路由任务。

Kernel Structure

内核结构

markdown

undefined

markdown

undefined

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"

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

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

Parse the user request for intent keywords
Match to the Agent Registry trigger column
Load the corresponding agent file from
```
agents/<name>.md
```
Hand off execution with full context
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.

undefined

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.

undefined

Key Principle

核心原则

The kernel should be small and declarative. Routing logic lives in plain markdown tables, not code. This makes the system inspectable and editable without debugging.

内核应简洁且声明式。路由逻辑采用纯Markdown表格编写，而非代码。这使得系统无需调试即可被检查和编辑。

Specialist Agents

专业Agent

Each agent is a standalone markdown file in

agents/

. Claude loads the relevant agent file when routing a task.

每个Agent都是

agents/

目录下的独立Markdown文件。Claude在路由任务时会加载对应的Agent文件。

Agent Definition Format

Agent定义格式

markdown

undefined

markdown

undefined

@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
```

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
```

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

undefined

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

undefined

Multi-Agent Collaboration Pattern

多Agent协作模式

When a task spans multiple agents, the kernel runs them sequentially or in parallel:

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

Kernel routing:
1. @dev - "Build a landing page with [requirements]"
2. @writer - "Write a launch blog post for [product] using the landing page copy"
3. Kernel synthesizes both outputs into a unified response

For parallel execution, use Claude Code's background task capability or shell scripts that invoke Claude Code with specific agent contexts.

当任务涉及多个Agent时，内核会按顺序或并行运行它们：

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

Kernel routing:
1. @dev - "Build a landing page with [requirements]"
2. @writer - "Write a launch blog post for [product] using the landing page copy"
3. Kernel synthesizes both outputs into a unified response

如需并行执行，可使用Claude Code的后台任务功能，或调用带有特定Agent上下文的Shell脚本。

Commands and Daily Workflows

命令与日常工作流

Slash commands are markdown files in

.claude/commands/

. They define reusable workflows.

斜杠命令是

.claude/commands/

目录下的Markdown文件，用于定义可复用的工作流。

Command Structure

命令结构

markdown

undefined

markdown

undefined

/daily-sync

Run the morning briefing:

Read
```
data/logs/last-sync.md
```
for context
Check project status:
```
git status
```
, pending PRs, CI health
Review
```
data/inbox/
```
for new tasks or decisions needed
Generate a summary of blockers, priorities, and next actions
Append the briefing to
```
data/logs/daily/<date>.md
```

undefined

Run the morning briefing:

Read
```
data/logs/last-sync.md
```
for context
Check project status:
```
git status
```
, pending PRs, CI health
Review
```
data/inbox/
```
for new tasks or decisions needed
Generate a summary of blockers, priorities, and next actions
Append the briefing to
```
data/logs/daily/<date>.md
```

undefined

Standard Command Set

标准命令集

Command	Purpose
`/daily-sync`	Morning briefing: status, blockers, priorities
`/outreach`	Run outreach workflow (email, LinkedIn, etc.)
`/research <topic>`	Deep research with citation tracking
`/apply-jobs`	Tailor resume + cover letter for a target role
`/analytics`	Pull metrics from Stripe, GitHub, or custom sources
`/interview-prep`	Generate flashcards or mock interview questions
`/decision <topic>`	Log a decision with pros/cons and chosen path

命令	用途
`/daily-sync`	晨间简报：状态、阻塞项、优先级
`/outreach`	执行外展工作流（邮件、LinkedIn等）
`/research <topic>`	深度研究并追踪引用来源
`/apply-jobs`	针对目标岗位定制简历和求职信
`/analytics`	从Stripe、GitHub或自定义数据源提取指标
`/interview-prep`	生成抽认卡或模拟面试问题
`/decision <topic>`	记录决策的利弊分析和最终选择

Activating Commands

激活命令

Place command files in

.claude/commands/<command-name>.md

. Claude Code auto-discovers them. Users invoke them with

/<command-name>

将命令文件放置于

.claude/commands/<command-name>.md

，Claude Code会自动发现它们。用户可通过

/<command-name>

调用命令。

Persistent Memory

持久化内存

Memory is file-based. No vector DB, no Redis, no PostgreSQL. JSON and markdown files in

data/

are the database.

内存基于文件实现，无需向量数据库、Redis或PostgreSQL。

data/

目录下的JSON和Markdown文件即为数据库。

Memory Directory Structure

内存目录结构

data/
├── daily-logs/         # Append-only daily activity logs
├── projects/           # Per-project context files
├── decisions/          # Architectural and business decisions (ADR format)
├── inbox/              # New tasks or ideas awaiting triage
├── contacts/           # People, companies, relationship notes
└── templates/          # Reusable prompts and formats

data/
├── daily-logs/         # 追加式日常活动日志
├── projects/           # 项目专属上下文文件
├── decisions/          # 架构与业务决策（ADR格式）
├── inbox/              # 待分类的新任务或想法
├── contacts/           # 人员、公司、关系记录
└── templates/          # 可复用提示词和格式

Daily Log Format

每日日志格式

markdown

undefined

markdown

undefined

2026-04-22 - Daily Log

Sessions

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

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
```
)

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)

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

Next Actions

Merge auth refactor PR
Send investor update for review

undefined

Merge auth refactor PR
Send investor update for review

undefined

Auto-Reflection Pattern

自动反思模式

At the end of each session, the kernel appends a reflection:

markdown

undefined

每个会话结束时，内核会追加反思内容：

markdown

undefined

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)


This creates a feedback loop that improves the system over time without code changes.

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 tasks run on a schedule using external cron, not Claude Code's built-in cron (which dies when the session ends).

Agentic OS任务通过外部cron工具定时运行，而非Claude Code内置的cron（会话结束后会失效）。

macOS: LaunchAgent

xml

<!-- ~/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>

xml

<!-- ~/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

ini

undefined

ini

undefined

~/.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


```ini

[Unit] Description=Agentic OS Daily Sync

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


```ini

~/.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

undefined

[Unit] Description=Run daily sync every morning

[Timer] OnCalendar=--* 8:00:00 Persistent=true

[Install] WantedBy=timers.target

undefined

Cross-Platform: pm2

跨平台: pm2

bash

undefined

bash

undefined

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

undefined

module.exports = { apps: [{ name: 'agentic-daily-sync', script: 'claude', args: '--cwd /path/to/project --command /daily-sync', cron_restart: '0 8 * * *', autorestart: false }] };

undefined

Data Layer

数据层

The data layer is your filesystem. Use JSON for structured data and markdown for narrative content.

数据层基于文件系统实现。结构化数据使用JSON，叙述性内容使用Markdown。

JSON for Structured State

结构化状态的JSON示例

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"
  }
}

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 for Narrative

叙述性内容的Markdown示例

Use markdown for anything a human reads: decisions, logs, research notes, contact records.

Markdown适用于所有需人类阅读的内容：决策记录、日志、研究笔记、联系人信息等。

Schema Evolution

schema演进

Never rename existing fields. Add new fields and mark old ones deprecated:

json

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

This keeps historical data readable without migration scripts.

切勿重命名现有字段。如需更新，添加新字段并标记旧字段为已废弃：

json

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

这种方式无需迁移脚本即可保证历史数据的可读性。

Anti-Patterns

反模式

Monolithic Single Agent

单体式单一Agent

markdown

undefined

markdown

undefined

BAD - One agent does everything

You are a full-stack developer, writer, researcher, and DevOps engineer.


Split into specialist agents. The kernel handles routing.

You are a full-stack developer, writer, researcher, and DevOps engineer.


应拆分为多个专业Agent，由内核负责任务路由。

Stateless Sessions

无状态会话

markdown

undefined

markdown

undefined

BAD - No memory between sessions

Starting fresh every time Claude Code opens.


Always read `data/` at session start and write back at session end.

Starting fresh every time Claude Code opens.


必须在会话启动时读取`data/`目录内容，并在会话结束时写入更新。

Hardcoded Credentials

硬编码凭证

markdown

undefined

markdown

undefined

BAD - API keys in agent files or CLAUDE.md

Your OpenAI API key is sk-xxxxxxxx


Use environment variables or a `.env` file loaded by scripts. Agents reference `process.env.API_KEY`.

Your OpenAI API key is sk-xxxxxxxx


应使用环境变量或由脚本加载的`.env`文件。Agent可通过`process.env.API_KEY`引用凭证。

External Database for Simple State

简单状态使用外部数据库

markdown

undefined

markdown

undefined

BAD - PostgreSQL for a solo user's agentic OS


Use JSON/markdown files until you have multiple concurrent users or GBs of data.


在拥有多并发用户或GB级数据前，应使用JSON/Markdown文件存储状态。

Over-Engineered Routing

过度设计的路由逻辑

markdown

undefined

markdown

undefined

BAD - Routing logic in code instead of markdown tables

if (intent.includes('deploy')) { agent = opsAgent; }


Keep routing declarative in `CLAUDE.md` markdown tables. It is inspectable, editable, and debuggable.

if (intent.includes('deploy')) { agent = opsAgent; }


路由逻辑应保持声明式，编写在`CLAUDE.md`的Markdown表格中。这样更易于检查、编辑和调试。

Best Practices

最佳实践

```
CLAUDE.md
```
is under 200 lines and fits in context window
Each agent file is under 100 lines and focused on one domain
```
data/
```
is git-ignored for sensitive logs, git-tracked for decisions and specs
Commands use imperative names:
```
/daily-sync
```
, not
```
/run-daily-sync
```
Logs are append-only; never edit past daily logs
Every agent has a
```
Memory Scope
```
section defining what files it reads
Reflections are written at the end of every session
Scheduled tasks use external cron (LaunchAgent, systemd, pm2), not Claude Code's session cron
Cost tracking: log API spend per session in
```
data/logs/<date>-costs.json
```
One project = one Agentic OS. Do not share a single
```
CLAUDE.md
```
across unrelated projects.

```
CLAUDE.md
```
不超过200行，可完全放入上下文窗口
每个Agent文件不超过100行，专注于单一领域
```
data/
```
目录中敏感日志设为Git忽略，决策记录和规格文档设为Git追踪
命令使用祈使式命名：
```
/daily-sync
```
，而非
```
/run-daily-sync
```
日志采用追加式写入；切勿编辑过往的每日日志
每个Agent都包含「Memory Scope」部分，定义其可读取的文件
每个会话结束时写入反思内容
定时任务使用外部cron工具（LaunchAgent、systemd、pm2），而非Claude Code的会话级cron
成本追踪：在
```
data/logs/<date>-costs.json
```
中记录每个会话的API开销
一个项目对应一个Agentic OS。不要在无关项目间共享同一个
```
CLAUDE.md
```
。