エージェンティックOS

エージェンティックOS は何をしますか？

Claude Codeをチャットセッションではなく、永続的なランタイム/オペレーティングシステムとして扱います。このスキルは、本番環境のエージェンティックセットアップで使用されるアーキテクチャ（タスクを専門エージェントにルーティングするカーネル設定、永続的なファイルベースのメモリ、スケジュールされた自動化、JSON/マークダウンデータレイヤー）を体系化したものです。

有効化するタイミング

• Claude Code内でマルチエージェントワークフローを構築する場合
• セッション再起動後も生存する永続的なClaude Code自動化を設定する場合
• 繰り返しタスクのための「個人用OS」または「エージェンティックOS」を作成する場合
• ユーザーが「エージェンティックOS」、「個人用OS」、「マルチエージェント」、「エージェントコーディネーター」、「永続的エージェント」と言った場合
• コンテキストがセッションをまたいで生存する必要がある長期実行プロジェクトを構築する場合

アーキテクチャ概要

エージェンティックOSには4つのレイヤーがあります。各レイヤーはプロジェクトルート内のディレクトリです。

project-root/
├── CLAUDE.md          # カーネル: アイデンティティ、ルーティングルール、エージェントレジストリ
├── agents/            # 専門エージェント定義（マークダウンプロンプト）
├── .claude/commands/  # スラッシュコマンド: ユーザー向けCLI
├── scripts/           # デーモンスクリプト: スケジュールまたはイベント駆動タスク
└── data/              # 状態: JSON/マークダウンファイルシステム、外部DBなし

レイヤーの責務

レイヤー	目的	永続性
カーネル (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 - エージェンティックOSカーネル

## アイデンティティ
あなたは[プロジェクト名]のCOOです。タスクを専門エージェントにルーティングします。
あなたは直接コードを書きません。適切なエージェントに委任し、結果を統合します。

## エージェントレジストリ

| エージェント | 役割 | トリガー |
|---|---|---|
| @dev | コード、アーキテクチャ、デバッグ | ユーザーが「構築」「修正」「リファクタ」と言った場合 |
| @writer | ドキュメント、コンテンツ、メール | ユーザーが「作成」「草稿」「ブログ」と言った場合 |
| @researcher | 調査、分析、事実確認 | ユーザーが「調査」「分析」「比較」と言った場合 |
| @ops | DevOps、デプロイ、インフラ | ユーザーが「デプロイ」「CI」「サーバー」と言った場合 |

## ルーティングルール
1. ユーザーリクエストから意図キーワードを解析する
2. エージェントレジストリのトリガー列に一致させる
3. `agents/<name>.md`から対応するエージェントファイルを読み込む
4. 完全なコンテキストを添えて実行を引き継ぐ
5. 結果を統合してユーザーに提示する

## モデルポリシー
- デフォルトモデル: リポジトリまたはハーネスのデフォルトを使用する。
- @devタスク: 複雑なアーキテクチャには、より高度な推論モデルを優先する。
- @researcherタスク: 設定された調査対応モデルと承認済み検索ツールを使用する。
- コスト上限: プロジェクトの設定された費用しきい値を超える前に警告する。

主要原則

カーネルは小さく宣言的に保つこと。ルーティングロジックはコードではなく、プレーンなマークダウンテーブルに記述します。これにより、システムをデバッグなしで検査および編集できるようになります。

専門エージェント

各エージェントはagents/内の独立したマークダウンファイルです。Claudeはタスクルーティング時に関連するエージェントファイルを読み込みます。

エージェント定義フォーマット

# @dev - ソフトウェアエンジニア

## アイデンティティ
あなたはシニアソフトウェアエンジニアです。クリーンでテスト済み、プロダクション品質のコードを書きます。
シンプルな解決策を好みます。要件が曖昧な場合は明確化の質問をします。

## メモリスコープ
- コンテキストのために `data/projects/<current-project>.md` を読む
- アーキテクチャ上の決定のために `data/decisions/` を読む
- 実行ログを `data/logs/<date>[email protected]` に追記する

## ツールアクセス
- プロジェクトルート内の完全なファイルシステムアクセス
- Git操作（ステータス、差分、コミット、ブランチ）
- テストランナーへのアクセス
- `.claude/mcp.json` で設定されたMCPサーバー

## 制約
- 新機能には常にテストを書く
- `main` に直接コミットしない。機能ブランチを使用する
- 新しいファイルを作成するよりも既存ファイルを編集することを優先する
- 可能な限り関数は50行未満に保つ

マルチエージェント協調パターン

タスクが複数のエージェントにまたがる場合、カーネルはそれらを順次または並行して実行します:

ユーザー: 「ランディングページを構築し、ローンチブログ記事を書いてください」

カーネルルーティング:
1. @dev - 「[要件]に従ってランディングページを構築してください」
2. @writer - 「ランディングページのコピーを使用して[製品]のローンチブログ記事を書いてください」
3. カーネルが両方の出力を統合して統一的に応答

並列実行の場合は、Claude Codeのバックグラウンドタスク機能または特定のエージェントコンテキストでClaude Codeを呼び出すシェルスクリプトを使用します。

コマンドと日次ワークフロー

スラッシュコマンドは.claude/commands/内のマークダウンファイルです。再利用可能なワークフローを定義します。

コマンド構造

# /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>で呼び出します。

永続的メモリ

メモリはファイルベースです。ベクターDB、Redis、PostgreSQLは不要です。data/内のJSONおよびマークダウンファイルがデータベースです。

メモリディレクトリ構造

data/
├── daily-logs/         # 追記専用の日次アクティビティログ
├── projects/           # プロジェクトごとのコンテキストファイル
├── decisions/          # アーキテクチャおよびビジネス上の決定 (ADR形式)
├── inbox/              # トリアージ待ちの新しいタスクやアイデア
├── contacts/           # 人、会社、関係性のメモ
└── templates/          # 再利用可能なプロンプトとフォーマット

日次ログフォーマット

# 2026-04-22 - 日次ログ

## セッション
- 09:00 - セッション1: 認証モジュールのリファクタリング (@dev)
- 11:30 - セッション2: 投資家向けアップデートの草稿 (@writer)

## 決定
- JWTからセッションクッキーに切り替え (`data/decisions/2026-04-22-auth.md` 参照)

## ブロッカー
- ベンダーからのAPIキーを待機中 (フォローアップ 2026-04-24)

## 次のアクション
- [ ] 認証リファクタのPRをマージする
- [ ] 投資家向けアップデートをレビューのために送信する

自動振り返りパターン

各セッションの終わりに、カーネルが振り返りを追記します:

## 振り返り - セッション3
- うまくいったこと: 並列エージェント実行で20分節約
- うまくいかなかったこと: @researcherがペイウォールのあるソースに遭遇、より良いソースランキングが必要
- 変更すべきこと: 調査ノートに `ソース階層` フィールドを追加 (A/B/C信頼性)

これにより、コード変更なしで時間とともにシステムが改善されるフィードバックループが生まれます。

スケジュール自動化

エージェンティックOSのタスクは、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 Timer

# ~/.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、ナラティブコンテンツにはマークダウンを使用します。

構造化状態のための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"
  }
}

ナラティブのためのマークダウン

人間が読むもの（決定、ログ、調査ノート、連絡先記録）にはマークダウンを使用します。

スキーマ進化

既存のフィールドの名前は決して変更しないでください。新しいフィールドを追加し、古いフィールドを非推奨とマークします:

{
  "name": "Website v2",
  "status": "in-progress",
  "milestone": "beta-launch",
  "_deprecated_priority": "high",
  "priority_v2": { "level": "high", "rationale": "投資家デモをブロックするため" }
}

これにより、移行スクリプトなしで履歴データを読み取り可能に保てます。

アンチパターン

モノリシックな単一エージェント

# 悪い例 - 1つのエージェントがすべてを行う
あなたはフルスタック開発者、ライター、研究者、DevOpsエンジニアです。

専門エージェントに分割します。カーネルがルーティングを処理します。

ステートレスセッション

# 悪い例 - セッション間でメモリがない
Claude Codeが開くたびに毎回新しく始める。

セッション開始時に常にdata/を読み、セッション終了時に書き戻します。

ハードコードされた認証情報

# 悪い例 - エージェントファイルまたはCLAUDE.md内のAPIキー
あなたのOpenAI APIキーはsk-xxxxxxxxです

環境変数またはスクリプトで読み込まれる.envファイルを使用します。エージェントはprocess.env.API_KEYを参照します。

単純な状態のための外部データベース

# 悪い例 - 一人ユーザーのエージェンティックOSにPostgreSQL

複数の同時ユーザーまたはGB単位のデータが発生するまで、JSON/マークダウンファイルを使用します。

過剰設計なルーティング

# 悪い例 - マークダウンテーブルではなくコード内のルーティングロジック
if (intent.includes('deploy')) { agent = opsAgent; }

CLAUDE.mdのマークダウンテーブルでルーティングを宣言的に保ちます。検査、編集、デバッグが容易です。

ベストプラクティス

• CLAUDE.mdは200行未満でコンテキストウィンドウに収まる
• 各エージェントファイルは100行未満で1つのドメインに集中している
• data/は機密ログ用にgit無視、決定と仕様用にgit管理
• コマンドは命令形の名前を使用: /run-daily-syncではなく/daily-sync
• ログは追記専用。過去の日次ログは決して編集しない
• すべてのエージェントには、読み取るファイルを定義するメモリスコープセクションがある
• 振り返りは各セッションの終わりに書かれる
• スケジュールされたタスクは、Claude Codeのセッションcronではなく、外部cron（LaunchAgent、systemd、pm2）を使用する
• コスト追跡: セッションごとのAPI支出をdata/logs/<date>-costs.jsonに記録する
• 1プロジェクト＝1エージェンティックOS。無関係なプロジェクトで単一のCLAUDE.mdを共有しない