HumanLayer創業者のDex Horthy（@dexhorthy）は2025年3月、その地獄を100社以上のSaaS事業者と話して整理し、humanlayer/12-factor-agentsとして公開した。GitHubで★19,949、フォーク1,509という規模に達したこのドキュメント集は、Herokuの12-Factor Appsにインスパイアされた『LLMエージェントを本番品質に持っていくための12個のモジュラー設計則』である。

AIエージェントフレームワーク全体の比較・選定基準は AIエージェントフレームワーク比較ガイド2026 をご覧ください。

1. 12-Factor Agentsとは何か：Dex Horthyが提示したLLMエージェント設計原則

12-Factor AgentsはHumanLayer社CEO/創業者のDex Horthy（GitHub: @dexhorthy）が2025年3月に公開したドキュメント集で、リポジトリはhumanlayer/12-factor-agentsにある。最終pushは2025年9月21日、Open Issuesは20件、Discordコミュニティとaidotengineerでの17分カンファレンストークが付随する。

タイトルはHerokuエンジニアのAdam Wigginsが2012年に提示した『The Twelve-Factor App』（12factor.net）への明示的なオマージュで、SaaSの設計原則をLLMエージェント時代に拡張した形になっている。

12-Factor Agentsの基本情報

Dexは前提として「すべてのフレームワークを試した結果、本番顧客向けエージェントの多くはフレームワークを使っていない」という観察を提示している。CrewAI・LangChain・smolagents・LangGraph・Griptapeを全部触った上での結論として書かれているため、フレームワーク否定論ではなくフレームワーク疲れに対する処方箋として読むべきだ。

1.1 「エージェント＝loop until done」というアンチパターン

Dexの最初の問題提起は明快で、AnthropicがBuilding Effective Agentsで定義した「ここにプロンプトとツール一式があるからゴールに達するまでループしろ」というパターンは、本番運用には耐えないというものだ。

実際に出回っている『AIエージェント』を名乗るプロダクトの大半は、決定的コードの中にLLMステップを要所要所で差し込んでいるだけで、純粋なエージェントループはほとんど使われていない。エージェントは大部分が普通のソフトウェアで構成されている、というのが現場の現実である。

1.2 70-80%の壁と『フレームワーク逆コンパイル地獄』

READMEに掲載されたSaaSビルダーの典型的なジャーニーは7ステップで描かれている。

1. エージェントを作りたいと決める
2. プロダクト設計とUXマッピングを行う
3. 早く動かしたいから$FRAMEWORKを採用する
4. 品質70-80%まで到達する
5. 顧客向け機能には80%では足りないと気づく
6. 80%を超えるためにフレームワーク内部・プロンプト・フローを逆コンパイルし始める
7. ゼロから書き直す

12-Factor Agentsの存在意義は、この7ステップ目に到達せずに済むよう、ステップ3の段階で『フレームワークではなく原則を取り込む』選択肢を提示することにある。

1.3 12原則の全体マップ

公式の12原則は以下のとおりだ。順番は依存関係を厳密に表すものではなく、各原則は独立適用可能になっている。

Appendix扱いの『Factor 13: Pre-fetch all the context you might need』も付随しており、これは『LLMが必要としそうなコンテキストを先回りで取得しておく』最適化指針だ。

2. 設計の全体像：エージェントループとステートレスReducerの関係

12原則の背骨を理解するうえで欠かせないのが、Dexが提示するエージェントループのミニマル疑似コードだ。

initial_event = {"message": "..."}
context = [initial_event]
while True:
    next_step = await llm.determine_next_step(context)
    context.append(next_step)

    if next_step.intent == "done":
        return next_step.final_answer

    result = await execute_step(next_step)
    context.append(result)

ループは4ステップに分解される。

1. LLMが構造化JSONで次ステップ（ツール呼び出し）を出力する
2. 決定的コードがツールを実行する
3. 結果をコンテキストウィンドウに追記する
4. 「done」が返るまで繰り返す

この素朴ループはFactor 9のエラー圧縮を加えれば自己回復もできる。ただしDex本人が「実際にはこれだけではうまく動かない」と明言しているとおり、ここに残り11原則を積層しないと本番品質には届かない。

このフロー図は12原則をすべて1枚に並べたものだ。中心にあるのがThread（コンテキストウィンドウそのもの）で、すべてのツール呼び出し・人間応答・エラーがイベントとして追記される。これを実現するのがFactor 5の「実行状態とビジネス状態の統一」である。

2.1 「状態 = thread.foldl」というモデル

Factor 12『Make your agent a stateless reducer』はDex自身が「これは半分楽しみで書いた」と前置きしている原則だが、本質はエージェントを純粋関数に閉じ込めることにある。

つまり、エージェントの現在状態は「これまでに発生したイベント列をfoldlした結果」として常に再構築可能であり、エージェント本体は次のステップを決定するだけのステートレス関数になる、というモデルだ。

これはReduxのreducer、Event Sourcing、関数型のFold/Scanと同じ発想で、再開・分岐・リプレイ・タイムトラベルデバッグといった嬉しさがそのままLLMエージェントに持ち込める。

3. Factor 1-4：プロンプトとコンテキストを自分のコードとして持つ

12原則の前半4つは「LLMとアプリケーションコードの境界」を設計するための原則群だ。フレームワークが隠蔽しがちな部分を、明示的に開発者の手元に取り戻す方向で設計されている。

3.1 Factor 1: Natural Language to Tool Calls

最も基本的な原則で、自然言語のリクエストを構造化されたツール呼び出しに変換するという考え方だ。Dexは例として「2月のAI tinkerers meetupのスポンサー代として$750のpayment linkをTerri宛てに作って」という自然言語を、Stripe APIを叩く構造化JSONに変換するパターンを示している。

# LLMが自然言語を受け取り、構造化オブジェクトを返す
next_step = await llm.determine_next_step(
    "create a payment link for $750 to Jeff "
    "for sponsoring the february AI tinkerers meetup"
)

# 構造化出力に応じて決定的コードが分岐する
if next_step.function == "create_payment_link":
    stripe.payment_links.create(next_step.parameters)
elif next_step.function == "something_else":
    ...

ポイントは、LLMの仕事は「次に何をするかをJSONで返すこと」だけに絞り、実行は決定的コードに任せる役割分担だ。

3.2 Factor 2: Own your prompts

フレームワークが提供する「role・goal・personality・toolsを渡せばあとはやっておく」タイプのブラックボックス抽象を捨て、プロンプトをファーストクラスのコードとして所有しろという原則だ。

Dexのサンプルでは、HumanLayerが推進する型付きプロンプトDSLであるBAMLを使った例が掲載されている。

function DetermineNextStep(thread: string) -> DoneForNow | ListGitTags | DeployBackend | DeployFrontend | RequestMoreInformation {
    prompt #"
        {{ _.role("system") }}

        You are a helpful assistant that manages deployments for frontend and backend systems.
        You work diligently to ensure safe and successful deployments by following best practices
        and proper deployment procedures.

        Before deploying any system, you should check:
        - The deployment environment (staging vs production)
        - The correct tag/version to deploy
        - The current system status
    "#
}

プロンプトを型と一緒に書ける、Gitで差分が取れる、レビューできる、テストできる——この4つを満たさないプロンプト管理は本番運用に耐えない、というのがFactor 2の主張だ。フレームワーク内部に隠蔽されると、最後の20%を詰める段階でブラックボックスを開かないと進めなくなる。

3.3 Factor 3: Own your context window（最重要原則）

READMEのトップに『Looking for Context Engineering? Jump straight to factor 3』と書かれているとおり、Dexが12原則の中で最も力を入れているのがこれだ。

LLMはステートレス関数で、入力（コンテキストウィンドウ）の質がそのまま出力の質を決める。そして「コンテキストウィンドウに何を入れるか」は標準のmessage形式（system/user/assistant/tool）に縛られる必要はない、というのが核心だ。

例えば、message形式ではなく独自XMLでgit操作履歴を表現すれば、トークン効率と注意効率を大幅に高められる、とDexは具体例を提示している。

RAG・エンベディング・検索を含めた『コンテキスト供給の総合設計』は RAG完全ガイド2026：仕組みから運用まで と合わせて読むと、より立体的に理解できます。

3.4 Factor 4: Tools are just structured outputs

『ツール』を特別な概念にせず、「LLMが出すJSON＋決定的コードによるディスパッチ」として捉え直す原則だ。

class Issue:
    title: str
    description: str
    team_id: str
    assignee_id: str

class CreateIssue:
    intent: "create_issue"
    issue: Issue

class SearchIssues:
    intent: "search_issues"
    query: str
    what_youre_looking_for: str

この設計を採ると、「LLMがツールを呼んだら必ず特定の関数を実行する」という1対1マッピングから解放され、同じintentでも文脈に応じて異なる挙動を取れる柔軟性が得られる。Factor 8の「制御フローを所有する」と組み合わせることで真価を発揮する。

4. Factor 5-8：状態統一・人間連携・制御フローを自分のコードに引き戻す

ここから先は「フレームワークが隠蔽するエージェント外側の挙動」を、開発者の手元に取り戻すための原則群だ。

4.1 Factor 5: Unify execution state and business state

AIフレームワークの多くは「実行状態（現在ステップ・次ステップ・待機状態・リトライ回数）」と「ビジネス状態（OpenAIメッセージ列・ツール呼び出しと結果）」を別々に管理する。

Dexの主張はこれを1本化せよ、というものだ。理想は「実行状態はビジネス状態（≒threadイベント列）から導出可能」にすること。これによって以下7つの利点が一気に手に入る。

• Simplicity: 真実の源（source of truth）が1つになる
• Serialization: threadが自明にシリアライズ・デシリアライズ可能
• Debugging: 全履歴が1箇所に集約される
• Flexibility: 新しい状態はイベント型を追加するだけで足る
• Recovery: threadを読み込めば任意の地点から再開できる
• Forking: threadの一部をコピーして別IDで分岐できる
• Human Interfaces: threadをそのままMarkdown・Web UIに変換できる

これがそのままFactor 12のステートレスReducerにつながる伏線になっている。

4.2 Factor 6: Launch/Pause/Resume with simple APIs

エージェントは結局のところプログラムなので、起動・一時停止・再開のAPIを普通のプログラムと同じ作法で提供せよ、という原則だ。

ユーザー・他アプリ・パイプライン・他エージェントから簡単なAPIで起動できること、長時間処理の前で一時停止できること、Webhookなど外部トリガーで再開できることが要件になる。これはFactor 5・Factor 8と密接に絡む。

特に注意すべき点として、多くのAIオーケストレータは「ツール選択とツール実行の間で一時停止できない」という制約を持つ、とDexは指摘している。Factor 7の人間承認フローを実装するうえで決定的な制約になる。

4.3 Factor 7: Contact humans with tool calls

LLM APIにはデフォルトで「プレーンテキストを返すか、構造化データを返すか」という最初の1トークンに大きな重みが乗る、という性質がある。

天気の問い合わせなら最初のトークンは"the"、fetch_weatherを呼ぶなら|JSON>のような特殊トークン。Dexはここで「常にJSONを返させて、その中でrequest_human_inputやdone_for_nowのような意図を宣言させる」設計を提案する。

class Options:
    urgency: Literal["low", "medium", "high"]
    format: Literal["free_text", "yes_no", "multiple_choice"]
    choices: list[str]

class RequestHumanInput:
    intent: "request_human_input"
    question: str
    context: str
    options: Options

if next_step.intent == "request_human_input":
    thread.events.append({
        "type": "human_input_requested",
        "data": next_step,
    })
    thread_id = await save_state(thread)
    await notify_human(next_step, thread_id)
    return  # ループを抜けて応答待ち

人間への質問もツール呼び出しの一種として統一的に扱うことで、Slack・メール・SMSなど媒体を選ばずに人間-エージェント間のやりとりを設計できる。HumanLayer社のプロダクト自体がこのパターンを実装したマネージドサービスである。

4.4 Factor 8: Own your control flow

LangGraphやLangChainが提供する「制御フロー」を、自分のアプリケーションコードとして書け、という強い主張の原則だ。

def handle_next_step(thread: Thread):
    while True:
        next_step = await determine_next_step(thread_to_prompt(thread))

        if next_step.intent == "request_clarification":
            thread.events.append({"type": "request_clarification", "data": next_step})
            await send_message_to_human(next_step)
            await db.save_thread(thread)
            break  # 非同期ステップ：Webhookで再開
        elif next_step.intent == "fetch_open_issues":
            thread.events.append({"type": "fetch_open_issues", "data": next_step})
            issues = await linear.fetch_open_issues()
            thread.events.append({"type": "fetch_open_issues_result", "data": issues})
            # ループ継続
        elif next_step.intent == "deploy_backend":
            # 高リスク操作：人間承認待ち
            await request_approval(next_step)
            break

request_clarification・fetch_git_tags・deploy_backendのように、ツール呼び出しの種類によってループを抜けるか継続するかを開発者が決められる。さらに以下のような実装が自分のコードに収まる。

• ツール結果の要約・キャッシュ
• 構造化出力に対するLLM-as-judge
• コンテキストウィンドウのコンパクション
• ロギング・トレーシング・メトリクス
• クライアントサイドのレートリミット
• 永続的なsleep/pause/イベント待ち

ハーネス（実行ループ）そのものの設計判断と実装パターンは エージェントハーネス基礎：自律エージェント実装の最小構成と落とし穴 で、さらに踏み込んだ実装則を扱っています。

5. Factor 9-12：エラー圧縮・小型化・トリガー多様化・ステートレスReducer

12原則の後半は『エージェントを本番のソフトウェアシステムに組み込むときの境界条件』を扱う。1個でも欠けると運用フェーズで負債になる。

5.1 Factor 9: Compact Errors into Context Window

LLMエージェントの『自己回復』はエラー・スタックトレースをそのままコンテキストに戻すだけで成立することが多い。Dexはこれを最小実装として示している。

thread = {"events": [initial_message]}
consecutive_errors = 0

while True:
    next_step = await determine_next_step(thread_to_prompt(thread))
    thread["events"].append({"type": next_step.intent, "data": next_step})

    try:
        result = await handle_next_step(thread, next_step)
        thread["events"].append({"type": next_step.intent + "_result", "data": result})
        consecutive_errors = 0
    except Exception as e:
        consecutive_errors += 1
        if consecutive_errors < 3:
            thread["events"].append({"type": "error", "data": format_error(e)})
            continue
        else:
            raise

ポイントは「連続エラーカウンタを設けて無限ループを防ぐ」「format_errorで長大なスタックトレースを圧縮する」の2点。生のスタックトレースを丸ごとコンテキストに戻すとトークンを浪費するので、要約・圧縮が前提だ。

5.2 Factor 10: Small, Focused Agents

『なんでもできる巨大エージェント1個』より『3-10、最大20ステップで完結する小さいエージェントを多数並べる』方が本番品質が安定する、という原則だ。

理由はシンプルで、コンテキストが大きくなるほどLLMは集中力を失う。20ステップに収まる小さなエージェントを複数組み合わせる方が、デバッグも責任分割も明確になる。

As context grows, LLMs are more likely to get lost or lose focus

『LLMがもっと賢くなれば不要では？』という反論に対し、Dexは「賢くなれば1エージェントあたりのステップ数を増やせるが、それでも分割の利点（テスト容易性・観測可能性・並列実行）は残る」と答えている。

5.3 Factor 11: Trigger from anywhere, meet users where they are

エージェントはSlack・メール・SMS・Discord・Webhook・cron・他エージェントなど、ユーザーがいる場所すべてから起動できるべきだ、という原則だ。

これはFactor 6（Launch/Pause/Resume API）とセットで考える必要があり、HTTPだけでなくWebSocket・キュー・メッセージブローカーすべてをトリガー源として扱えるアーキテクチャを要求する。

5.4 Factor 12: Make your agent a stateless reducer

最後の原則は半分ジョーク半分本気のまとめで、「エージェントを純粋関数 = ステートレスReducerにせよ」というものだ。

type AgentEvent =
  | { type: "user_message"; data: { content: string } }
  | { type: "tool_call"; data: { intent: string; params: unknown } }
  | { type: "tool_result"; data: { intent: string; result: unknown } }
  | { type: "human_input"; data: { content: string } }
  | { type: "error"; data: { message: string } };

type Thread = { id: string; events: AgentEvent[] };

// エージェント本体はステートレス：thread → 次のAgentEvent
const determineNextStep = async (thread: Thread): Promise<AgentEvent> => {
  const prompt = threadToPrompt(thread);
  return await llm.next(prompt);
};

// 状態は常にイベント列をfold（reduce）した結果
const currentState = (thread: Thread) =>
  thread.events.reduce(applyEvent, initialState);

このモデルが綺麗に乗ると、エージェントの動作はReduxのreducerやイベントソーシングと同型になり、リプレイ・分岐・タイムトラベルデバッグ・並列実行・分散化がすべて『普通のソフトウェアと同じ作法』で扱えるようになる。

エージェント時代のエンジニア像とキャリア設計は Agentic AIエンジニア・ロードマップ2026 を参照すると、12-Factor Agentsの位置付けがより明確になります。

6. 12-Factor Agentsを実装に落とすチェックリストと類似アプローチ比較

ここまで読んで「結局どの原則から実装するか」を判断するための、実装チェックリストと類似アプローチの比較を示す。

6.1 実装チェックリスト（推奨優先度順）

6.2 類似アプローチとの比較

12-Factor Agentsを位置付けるため、代表的な5つのアプローチと並べて比較する。

12-Factor Agentsの立ち位置は「フレームワークではなく原則集」「マネージドではなく開発者所有」「設計思想ではなく実装可能な12個の具体則」という3点で他とは交わらない。

6.3 関連OSS・関連ドキュメント

Dex本人と関係者が公開している関連リソースをまとめておく。これらを順に読むと12-Factor Agentsの理解が深まる。

• 12 Factor Apps — オリジナルのHeroku版、本家
• Anthropic: Building Effective Agents — エージェントパターンの公式整理
• BAML（boundaryml/baml） — Dexがプロンプト所有に推す型付きDSL
• got-agents/agents — 12-Factor準拠のOSSエージェント実装
• humanlayer/kubechain — Dex本人が「12原則を破って書いた」分散エージェントフレームワーク
• Tom Petricek: Library patterns: Why frameworks are evil — Dexが思想的下敷きとして引用
• Sandi Metz: The Wrong Abstraction — 早すぎる抽象化への警鐘

エージェント時代のトークン経済を含めた最適化観点は、別記事の AIエージェントのトークン最適化ガイド2026 で、コンテキストウィンドウ圧縮の具体手法と合わせて扱っている。

6.4 12-Factor Agentsを採用しない方が良いケース

最後に、Dex本人もREADMEで触れている「フレームワークを選んだ方が良いケース」を明確化しておく。

• 社内ツール・PoC・ハッカソンプロジェクト：70-80%品質で十分なら、CrewAIやLangChainの方が立ち上がりが圧倒的に速い
• MLエンジニアが主導するR&D：パターン研究には事前パッケージ済みのAutoGen・LangGraphの方が適している
• OpenAI/Anthropicに完全依存できる用途：Assistants APIで足りるなら、自前で12原則を実装する価値は薄い

12-Factor Agentsの主戦場は「顧客向け本番プロダクトで品質80-100%を狙う」段階だ。この段階に至っていないチームが先回りで12原則を実装すると、過剰設計になりやすい点には注意したい。

参照ソース

• humanlayer/12-factor-agents（公式リポジトリ） — Dex Horthy著、CC BY-SA 4.0 / Apache 2.0
• Factor 3: Own your context window（公式ドキュメント） — 最重要原則のフル解説
• The Twelve-Factor App（12factor.net） — Adam Wiggins著、本家12原則
• Anthropic: Building Effective Agents — エージェントパターンの公式整理
• Tool Use Podcast: Dex Horthy（2025年3月） — 著者本人による背景説明
• aidotengineer conf talk（17分） — 公式カンファレンストーク

v2.1.140〜143を一望する：4連続リリースの全体像

Claude Codeは1日1リリースに近い高速サイクルで進化しています。今回扱う5月12〜15日の4本は、いずれも前週（5/11）にリリースされた claude agents（Research Preview）と /goal コマンドの周辺を整える「仕上げの週」でした。リリース全体を時系列で並べると、claude agentsの土台 → サブエージェント呼び出し改善 → 通知・ワークスペース → バックグラウンドセッションのフラグ拡充 → プラグイン依存 という流れが見えてきます。

主要な追加機能・修正を1枚にまとめます。

以下、各リリースを実務で使う順に深掘りします。

v2.1.139：claude agents が研究プレビューで登場

claude agentsは、これまで /bg や ←← で散発的に起動していたバックグラウンドセッションをひとつのリストに統合する新しいビューです。claude agents をターミナルで叩くと、実行中（Working）／ユーザー入力待ち（Blocked on you）／完了済み（Completed）のセッションが一画面に並びます。

合わせて入った /goal コマンドは、完了条件を宣言してターン跨ぎで作業を継続させる仕組みです。interactive / -p / Remote Control のいずれからも使え、経過時間・ターン数・トークン消費がオーバーレイ表示されます。長時間の自動化タスクで「目的に到達するまで止まらない」運用が公式機能として組み込まれたのは大きな転換点です。

ただし /goal は v2.1.140 と v2.1.142 で複数の不具合（hook無効環境でハング／背景シェル稼働中に評価器が暴走）が立て続けに修正されています。「機能としては入ったが本格運用は次バージョン待ち」と見るのが妥当です。

その他、transcript viewのキーボードショートカット（? でヘルプ、{/} でユーザープロンプト間ジャンプ、v でショートカット表示）、hookの args: string[]（shellを経由せず直接プロセス起動）、PostToolUse hookの continueOnBlock（リジェクト理由をClaudeに戻してターン継続）、/mcp 再接続時の .mcp.json 自動反映といった地味だが効く改善が多数入っています。

v2.1.140：subagent_type が大小文字・区切り文字を無視するようになった

このバージョンの目玉は、Agentツール呼び出しの subagent_type が緩いマッチで解決されるようになったことです。たとえばユーザー定義エージェント code-reviewer に対して、モデルが "Code Reviewer" / "code_reviewer" / "CodeReviewer" のいずれを書いても解決されます。

これまでは subagent_type のタイポでサブエージェント起動が失敗し、Claudeがリトライまたは諦めるケースが頻発していました。とくに .claude/agents/ 配下のファイル名と説明文の表記揺れ（Code Reviewer と説明し、ファイル名は code-reviewer.md）でハマる典型パターンが解消されます。

# v2.1.140 以降、以下はすべて同じエージェントに解決される
claude -p "Use the Code Reviewer agent to audit src/"
claude -p "Use code_reviewer to audit src/"
claude -p "Use CodeReviewer to audit src/"
# → .claude/agents/code-reviewer.md が起動

合わせて修正されたリグレッションが密度高めです:

• /goal が disableAllHooks / allowManagedHooksOnly 設定下で沈黙ハングする問題（無限スピナー）を、明示的なメッセージ表示に変更
• symlinked settings のホットリロードで変更イベントが誤帰属し、無関係な ConfigChange hookが暴発する問題を修正
• claude --bg 起動時にバックグラウンドサービスがidle-exit直前だと「connection dropped mid-request」で失敗する競合状態
• Windowsで gh 等の不在実行ファイルに対し、毎チェックごとに同期的な where.exe を再生成し続けイベントループがストールする問題
• Read ツール呼び出しで offset が空白パディング・+プレフィックス付きの文字列で来るとバリデーションが失敗する問題

「symlinked settings」「Readのoffset文字列バリデーション」あたりは、Claude Code Skills（プラグインから供給される設定ファイル群）を本格運用しているユーザーが踏みがちな地雷でした。

v2.1.141：通知・WorkspaceID・cwdスコープ

terminalSequence hookフィールドの追加が地味に強力です。これまでhookは標準出力に文字列を返すだけでしたが、JSON出力に terminalSequence を含めるとデスクトップ通知・ウィンドウタイトル変更・ベルを、controlling terminalがなくても発行できるようになりました。バックグラウンドセッションから完了通知を出す用途で効きます。

ANTHROPIC_WORKSPACE_ID 環境変数は、Workload Identity Federation（WIF）でフェデレーションルールが複数ワークスペースをカバーする場合に、ミントされるトークンを特定ワークスペースにスコープするためのものです。Enterprise/Teamプランの管理者向けで、組織ガバナンス周りの精緻化と言えます。

claude agents --cwd <path> で、claude agentsのセッション一覧をディレクトリスコープで絞り込めるようになりました。複数プロジェクトを並行運用しているユーザーには必須のフラグです。

その他、/feedback に「直近24時間/7日のセッションを含める」オプション、Rewindメニューに「Summarize up to here」（過去ターンだけ圧縮して直近を残す）、Auto modeの権限ダイアログに「なぜそのルールでプロンプトが出たか」の説明が出るようになりました。

v2.1.142：claude agentsに8種類のフラグが一気に追加、Fast ModeがOpus 4.7

このバージョンが今回の4連続リリースで最も影響が大きい回です。claude agentsから派生するバックグラウンドセッションを、通常セッションと同じ粒度で構成できるようになりました。

新しく使えるフラグ:

たとえば、専用のMCPサーバ群・専用のskillセットを使うバックグラウンドエージェントを以下のように起動できます。

claude agents launch \
  --add-dir ~/work/datasets \
  --settings .claude/bg-settings.json \
  --mcp-config .claude/bg-mcp.json \
  --plugin-dir .claude/bg-plugins \
  --permission-mode auto \
  --model claude-opus-4-7 \
  --effort high \
  -p "Watch the dataset directory and run the validation suite when new files land"

これまでは通常セッションでしか細かい構成ができず、claude agents経由のバックグラウンドセッションは「現在のClaude Code設定がそのまま継承される」しかありませんでした。デバッグ用エージェント・本番監視用エージェント・コードレビュー用エージェントを異なる権限・MCP・モデルで並行常駐させる運用が、ようやく公式に手当てされた形です。

Fast Mode が Opus 4.7 へ

Fast ModeはClaude Codeで /fast トグルや --fast フラグで有効化する、応答速度優先のモードです。これまではOpus 4.6が固定でしたが、v2.1.142 から Opus 4.7 に切り替わりました。

公式リリースノートには「速度を保ったまま」とあり、Fast Mode = 小さいモデルへのダウングレードではない（Opus内部での出力最適化）ことが改めて強調されています。旧Opus 4.6に戻したい場合は環境変数で固定できます。

# Fast Mode を Opus 4.6 に固定（旧挙動）
export CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1
claude --fast

プラグイン体験の改善

ルート直下に SKILL.md だけを置いたミニマル構成のプラグインも、skillとして自動認識されるようになりました。これまでは skills/<name>/SKILL.md の階層が必須で、単一skillだけを配るプラグインで冗長になっていました。

/plugin 詳細ペインと claude plugin details が、プラグイン提供のLSPサーバを列挙するようになり、/web-setup がGitHub App接続を上書きする前に警告を出すようになりました。

バックグラウンドセッションの3大リグレッション修正

v2.1.142 のリリースノートを読み込むと、claude agents系で前バージョンまで踏んでいた地雷がまとめて修正されています:

1. macOSスリープ・ウェイク後にバックグラウンドセッションが消える — daemonがウェイク後の時計ジャンプを「アイドル経過時間」と誤解する問題を修正。clock jump検出に切り替え。
2. brew upgrade 後にdaemonがクラッシュループ — 古いバイナリパスを掴んだdaemonが消えたパスで再起動を繰り返す問題。アップグレード後の clean exit を実装。
3. Claude-in-Chrome拡張接続中で共有タブがない場合のクラッシュループ — 拡張接続だけで共有タブがないケースのエッジを処理。

加えて、claude agentsアタッチセッションでリンクをクリックしたとき、バックグラウンドワーカーのheadless browserが起動しない問題、MCP_TOOL_TIMEOUT がリモートHTTP/SSE MCPサーバには効かず60秒で打ち切られる問題（このリグレッションは設定値が無視されるので気づきにくい）も修正されています。

v2.1.143：プラグイン依存強制と worktree.bgIsolation: “none”

最新の v2.1.143 で目を引くのは、プラグイン依存の双方向enforcementです。

• claude plugin disable は、対象プラグインに依存する他の有効プラグインがあると拒否し、コピペできる依存チェーン解除手順を表示します
• claude plugin enable は、有効化対象が依存する未有効プラグインを推移的に強制有効化します

プラグインが疎結合に増えてくると、「Aを止めたつもりがBが暗黙にAを呼んでいて落ちる」典型的な事故が発生します。npm/pip相当の依存ガードがClaude Codeの.claude/plugins/周辺にも入ったと考えるのが分かりやすいでしょう。

合わせて、/plugin マーケットプレース閲覧画面にターン当たり/呼び出し当たりのトークン推定コストが表示されるようになりました。プラグインを増やしすぎてコンテキストを食い潰す事故を未然に防ぐ意図が読み取れます。

worktree.bgIsolation: “none”

claude agentsが起動するバックグラウンドセッションは、デフォルトで EnterWorktree を呼んで一時worktree内で作業します。これは複数エージェントが同じファイルを編集する競合を防ぐためですが、巨大monorepoや独自ビルドシステムを持つプロジェクトでは worktree 作成自体が現実的でないケースがあります。

// .claude/settings.json
{
  "worktree": {
    "bgIsolation": "none"
  }
}

この設定をすると、バックグラウンドセッションは作業コピーを直接編集するようになります。複数エージェントを同時に走らせる場合は競合管理を自前で行う前提です。デフォルト挙動（worktreeで隔離）は変わらず、明示的にopt-outする形になっています。

PowerShell ExecutionPolicy Bypass

PowerShellツールが -ExecutionPolicy Bypass を渡すようになりました。Windowsエンタープライズ環境でGroup Policy（GPO）により実行ポリシーが Restricted または AllSigned に設定されていると、Claude Codeが投入する一時スクリプトがブロックされてツールが空振りする事象が頻発していました。

組織ポリシー側でExecutionPolicyを尊重したい場合は環境変数でopt-outできます。

export CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1

その他の修正・改善

• 破損した .credentials.json（scopes が非配列）でCLI起動がハング、またはOAuthトークンリフレッシュが沈黙abortする問題を修正。長期間ログイン状態のユーザーで起きやすい
• stop hookが繰り返しblockすると無限ループに陥る問題を、8回連続blockで警告とともにターン終了するよう変更。CLAUDE_CODE_STOP_HOOK_BLOCK_CAP でオーバーライド可能
• /loop の覚醒待機中にEsc/Ctrl+Cが効かない問題を修正。/loop 走行中の中断が現実的になった
• /goal 評価器がバックグラウンドシェル/サブエージェント実行中に動いてしまう問題を修正
• NO_COLOR/FORCE_COLOR をsettings.jsonの env で渡すとClaude Code自体のUI色まで奪われる問題を修正
• claude agentsアタッチセッションでのWindows Terminal / WSL右クリックペースト
• Shift+Tab 操作のサイクルにauto modeを追加

5月中旬リリースから読み取れる開発方針

4連続の更新を一段引いて眺めると、Anthropic が claude agents を単なるダッシュボード機能ではなくClaude Codeの第2の入口に位置づけ始めたことが見て取れます。これまでClaude Codeは「ターミナルで claude を叩いて対話開始」が事実上の唯一の入口でしたが、5月のリリース群では

• claude agents でセッションをリスト管理
• claude agents launch --add-dir ... --mcp-config ... --model ... で起動条件を細かく指定
• worktree隔離の有無やplugin依存をビューから可視化
• macOSスリープ・OSアップグレード・拡張接続といった長時間稼働で踏みがちな地雷を順番に潰す

という、「常駐エージェントを安定運用するためのCLI管理面」が一気に整いました。これは Claude Code Architecture Blueprint で議論したような、エージェントOSとしてのClaude Codeという方向性を裏付ける動きです。

逆に言えば、まだ前景セッションのみで使っているユーザーから見ると今回のリリース群は地味に映ります。/goal や /scroll-speed 程度しか直接触れる新コマンドがないからです。しかしバックグラウンド常駐を試したことのあるユーザーには、5月12〜15日の修正は確実に体感できる安定化として効いてきます。

アップデート方法

ターミナルで以下のいずれかを実行します。OSやインストール方法に応じて選んでください。

# Homebrewインストールの場合
brew upgrade claude-code

# claudeコマンドからの直接アップデート
claude update

# バージョン確認
claude --version    # 2.1.143 以降を確認

Homebrew/WinGetでインストールしていて、v2.1.129以降で導入された自動アップデートを有効化している場合（CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1）は、起動時にバックグラウンドでアップグレードが走り、再起動を促されます。

なお、v2.1.142 で daemon の clean exit が実装される前のバージョンから brew upgrade で更新すると、古い daemon が掴んでいたバイナリパスが消えて crash-loop する可能性があります。一度 claude daemon stop で daemon を止めてから upgrade するのが安全です。

実務での影響：誰がいま更新するべきか

リグレッションの修正密度が高い回なので、動作不安定を1つでも経験していれば更新するのが正解です。特にmacOSスリープ後のセッション喪失は2026年4月後半から複数ユーザーが報告していた典型的なバグで、v2.1.142 でようやく根本原因（daemonの時計ジャンプ誤検出）に手が入りました。

まとめ：claude agentsの「使える化」が今月の主題

5月の4連続リリースを俯瞰すると、5月11日の claude agents（Research Preview）投入を起点に、

1. 使い方の入口を整える（v2.1.141の --cwd スコープ、v2.1.142のフラグ群）
2. 常駐の信頼性を底上げ（v2.1.142のmacOSスリープ・brew upgrade・Chrome拡張周辺の修正）
3. 誤操作を防ぐガードレール（v2.1.143のプラグイン依存enforcement、stop hookループ抑止、.credentials.json 修復）

という三段階で「claude agentsの使える化」が進んだことが分かります。

サブエージェント（.claude/agents/ 配下のユーザー定義エージェント）とバックグラウンドセッション（claude agentsで起動する常駐セッション）は異なる概念なので混同しやすいですが、v2.1.140 の subagent_type 曖昧マッチはサブエージェント側、v2.1.142 のフラグ群はバックグラウンドセッション側、と切り分けて捉えると今回のリリース群が読みやすくなります。

長時間自律稼働するエージェント運用を本格化するなら、まずは v2.1.143 にあげて、claude agents を一度開いてみるところから始めるのが良いでしょう。Fast Mode を多用しているユーザーは Opus 4.7 デフォルト化で応答の質がやや変わって感じられるはずなので、必要に応じて CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 でロールバックも検討してください。

参照ソース

• anthropics/claude-code GitHub Releases — Claude Code公式リリースノート（v2.1.140〜v2.1.143）
• Claude Code Agent View 公式ドキュメント — v2.1.139 で追加された claude agents の公式リファレンス
• Claude Code v2.1.108｜/recap・Skill経由スラコマ・プロンプトキャッシュ1時間TTLで何が変わるか — 2026年4月時点でのClaude Code機能の前提整理
• Claude Code 4月アップデート！Memory Store・/ultrareview・ポストモーテムまとめ — 直前1ヶ月の更新サマリ

NotFair（notfair.co）が2026年に公開した nowork-studio/toprank（★2,316／297フォーク／MIT）は、この最後の手動作業をClaude Code側に巻き取ることを正面から狙ったOSSプラグインだ。Google Ads・Meta Ads（Facebook+Instagram）・Google Search Consoleに直結し、データの取得・診断・実行までをCLIの1コマンドで連続実行する。

Claude Code全体の使い方は Claude Code完全ガイド2026：インストールから本番運用まで をご覧ください。

1. Toprankとは何か：CLI型データドリブン広告/SEOエージェントの正体

Toprankは「ダッシュボードではなくデータドリブンな意思決定そのもの」を目的にしたClaude Codeプラグインだ。READMEの冒頭スローガン Data-driven decisions, not dashboards. がコンセプトを正確に表現している。

公式リポジトリの説明文は「Open-source Claude Code skills for SEO, GEO, Google Ads, Meta Ads」で、対象領域は4つに整理されている。

• SEO: 技術監査・コンテンツ生成・メタタグ最適化・構造化データ生成
• GEO: 生成エンジン（ChatGPT/Claude/Perplexity/Gemini）からの引用最適化
• Google Ads: 監査・キャンペーン管理・RSAコピー生成・ランディングページ評価
• Meta Ads: Facebook+Instagram広告監査・キャンペーン管理

リポジトリは2026年3月27日に作成され、わずか2か月で2,316★・297フォークを集めている。最終pushは2026年5月17日、Pythonベース（一部Goスキル）、MITライセンス。トピックには claude-code-plugin／claude-skills／mcp／seo／geo／googleads／metaads が並び、Claude Codeエコシステム内では数少ない「マーケティング業務領域に特化したOSSプラグイン」として独自の立ち位置を確立している。

特筆すべきは、CLI（Toprank）とWeb（NotFair）が同じエンジンを共有している点だ。READMEには Both sides share the same engine, so an audit you run from the CLI uses the same tooling as the one on the web. と明記されており、ブラウザでクリック操作するNotFair Web版とClaude Code内のスキル実行が、内部的に同一のMCPサーバーと処理ロジックを叩く構成になっている。

Toprankが想定する典型的ユースケース

READMEで列挙されている問いかけは、現場担当者なら誰もが抱える3つだ。

1. Am I wasting money on ads right now?（今この瞬間、広告費を無駄にしていないか？）
2. Why did my traffic drop and how do I fix it?（なぜトラフィックが落ちたか、どう直すか？）
3. How do I get more conversions without spending more?（予算を増やさずコンバージョンをどう伸ばすか？）

これらは従来「データを見る → 担当者が考える → 管理画面で操作する」の3段階で対処されてきた。Toprankはこの3段階を1つのCLIコマンド + 確認応答にまで圧縮することを目指す。「Do it all.」と返事するだけで、3キーワードの一時停止・12件のネガティブキーワード追加・2キーワードの入札額調整が連鎖実行されるREADMEの実例は、その思想を象徴している。

重要なのは、すべてのMutation操作が7日以内に取り消し可能な点だ。READMEの実行ログにも All changes are reversible within 7 days. と明示されており、AIエージェントが暴走しても巻き戻せる安全弁が設計に組み込まれている。

2. アーキテクチャ全体像：プラグイン・MCPサーバー・OpenClaw自律層の3層構造

Toprankは見かけ上1つのプラグインだが、内部的には3つの独立レイヤーで構成されている。プラグイン本体（Skills）／リモートMCPサーバー（NotFair）／OpenClawアダプティブ層の3層だ。

第1層：スキル本体

ローカルにインストールされる主要構造を、READMEのHow It Worksセクションから抜粋する。

toprank/
├── .claude-plugin/
│   ├── plugin.json       # プラグインメタデータ
│   └── marketplace.json  # マーケットプレイス登録
├── .mcp.json             # NotFair MCP自動登録
├── google-ads/           # 4スキル
├── meta-ads/             # 3スキル
├── seo/                  # 9スキル
├── gemini/               # クロスモデルレビュー
├── openclaw/             # 自律エージェント層
├── toprank-upgrade-skill/
└── test/                 # 単体+LLM Judge評価

各スキルディレクトリは独立したSKILL.mdを持ち、Claude Code側のスキル探索メカニズムから個別に呼び出される。/toprank:seo-analysisのようにプラグイン名前空間付きで呼び出すため、他のClaude Codeスキルとの名前衝突を防ぐ設計になっている。

第2層：NotFair リモートMCPサーバー

ここがToprank最大の特徴だ。Google AdsとMeta Adsへのアクセスは、ローカルではなくnotfair.coが運営するリモートMCPサーバーに委ねられる。

認証はOAuth 2.1の動的クライアント登録で、初回利用時にブラウザタブが開いてnotfair.coにサインインするだけ。トークンはClaude Code側のOSキーチェーンに保存され、mcp-remoteのような中継ブリッジを噛ませる必要がない。

Google Adsサーバー側の特筆機能は runScript ツールで、最大20本のGAQLクエリを並列実行して分析的な問いに対応する。たとえば「過去90日で品質スコアが急落し、かつ予算消化率が90%超のキャンペーンは？」のような複合分析を、20並列のGAQLで1秒台に圧縮する。

Meta側はMutation面が意図的に狭く設計されている。READMEに明記されているとおり、create-campaign・audience編集・creative uploadは存在しない。pause/enable/updateBudget/renameCampaignのみがサーバー側に置かれ、それ以外の操作はMeta Ads Managerに戻す設計だ。AIエージェントによる事故を最小化する設計判断と読み取れる。

第3層：OpenClaw アダプティブ層

openclaw/配下にあるアダプティブ層は、Toprankを自律エージェント化する装置だ。README記載の機能を整理すると以下のとおり。

これは単体のToprankスキルを「呼び出されたら動く」状態から、「所有しているサイト群を24時間ウォッチして勝手に改善PRを上げる」状態に昇格させる構造で、SEOコンサル業務のラスト1マイルをエージェント化する野心的な設計だ。

3. Google Ads自動運用：監査スコアカード・RSAコピー生成・ランディング最適化

Google Adsカテゴリには4つのスキルが同梱される。役割分担は次のとおりだ。

初回監査が最も価値の重い1コマンド

READMEに掲載されたgoogle-ads-auditの実行例は、Toprankのコア機能を一望できる例として優れている。

You:    /toprank:google-ads-audit

Claude: Connected to your Google Ads account (MyStore).

        3 campaigns active. $2,400 spent this month.

        Scorecard:
        ┌──────────────────────┬──────────┬──────────────────────────────┐
        │ Dimension            │ Status   │ Summary                      │
        ├──────────────────────┼──────────┼──────────────────────────────┤
        │ Conversion tracking  │ OK       │ 3 actions firing correctly   │
        │ Keyword health       │ Critical │ 8 keywords burning cash      │
        │ Search term quality  │ Warning  │ 12 irrelevant queries        │
        │ Impression share     │ Warning  │ Losing 35% to rank           │
        │ Spend efficiency     │ Critical │ $340/mo wasted               │
        └──────────────────────┴──────────┴──────────────────────────────┘

        Top 3 actions:
        1. Pause 3 keywords ($210/mo, zero conversions)
        2. Add 12 negative keywords ($130/mo wasted on irrelevant terms)
        3. Increase bids 15% on 2 high-converting keywords losing IS

You:    Do it all.

        [paused 3 wasteful keywords — saved $210/mo]
        [added 12 negative keywords — saved $130/mo]
        [increased bids on 2 high-performers]

        Done. All changes are reversible within 7 days.

ここで注目すべきは、監査結果がそのまま実行可能なアクションリストに落ちる設計だ。SEMrushの監査結果は通常PDFや管理画面のチェックリストになるが、ToprankではClaudeとの対話で「Do it all.」と返すだけで連鎖実行される。Top 3 actionsの構造化が、Claude側の意思決定コスト削減にも効いている。

Weekly Review機能：実施した変更の効果を採点

/toprank:google-ads にはウィークリーレビュー機能が組み込まれている。READMEのサンプル出力では、12件の変更のうち9件が成熟済みで、Wins 4件・Losses 2件・成熟前 3件と分類されている。

特筆すべきは 2 changes had other edits on the same campaign within 7 days, so their direction is low-confidence. の一文だ。同一キャンペーンへの他編集の影響を信頼度として扱う設計で、A/Bテストの相互汚染を自動検知する。これは熟練マーケターでもしばしば見落とすバイアスだ。

このウィークリーレビュー機能は、Claude CodeのCoworker（定期実行ジョブ）として登録すれば毎週月曜朝に自動で出力させることができる。属人化していたレポート業務をエージェントに委譲する典型例だ。

4. Meta Ads自動運用：ROAS分析・クリエイティブ疲労診断・狭いMutation設計

Meta AdsはGoogle Adsと異なる事情を抱える。Pixel/CAPI周りの計測健全性、Learning Phase（学習期間）の挙動、クリエイティブ疲労、Audience Overlap——いずれもMeta固有の運用知識が必要だ。

Toprankのmeta-ads-auditは、これらをMeta特化の7次元で採点する。

監査結果は単発で終わらず、クリエイティブ在庫データ・ペルソナデータを永続化する。これは下流の/toprank:meta-adsスキルがコピー生成・A/B案出しを行うときに利用される設計で、監査ステップが「次のアクションのための知識ベース構築」を兼ねている。

Mutation API を「狭く・安全に」設計する思想

/toprank:meta-adsが呼び出せるMutationは以下に限定される。

# 停止系
pauseCampaign / pauseAdSet / pauseAd

# 再開系
enableCampaign / enableAdSet / enableAd

# 予算・命名
updateAdSetBudget / updateCampaignBudget / renameCampaign

逆に、新規キャンペーン作成・Audience編集・クリエイティブのアップロードはサーバー側に存在しない。これらの操作が必要な場合、スキルはユーザーをMeta Ads Managerの該当画面に誘導する設計だ。

これはAIエージェント設計の鉄則「Mutationのblast radius（影響範囲）は狭く保つ」を忠実に体現している。GoogleAdsのrunScriptに相当するrunScript（Meta側）も、ads.graphParallel([calls])で最大20並列のGraph API呼び出しを許すが、これは読み取り中心の分析fan-outに位置付けられている。

5. SEOスキル群と新しいGEO最適化（AI検索向け）

SEO/GEOカテゴリは9スキルで構成され、TopRankの中で最も多機能なカテゴリだ。

SEO監査の対話例

/toprank:seo-analysisはGSCデータを90日分読み込み、技術問題を含む診断を返す。READMEの実例を引用する。

You:    /toprank:seo-analysis

Claude: Found your site at mystore.com — pulling Search Console data now.

        [90 days of real traffic data loaded]
        [pages crawled for technical issues]

        Three things hurting you most:

        Your homepage lives at two addresses. Google splits your ranking
        power between them. Easy fix.

        Two pages targeting the same search terms — they compete against
        each other and neither wins.

        One page gets 400 monthly impressions but ranks #52. The title
        doesn't match what people actually search for.

        Here's your 30-day plan, most impactful first.

ここで読むべきは、Claudeが「人間っぽい言い回し」で問題を説明している点だ。「URLが2つに分裂してランク力が割れている」「2ページがカニバリして両方負けている」「タイトルが検索クエリと噛み合っていない」——これらは技術用語に頼らず本質を伝える表現で、非エンジニアの依頼主にもそのまま見せられる。SEOコンサル業務での説明工数を直接削れる設計だ。

GEO最適化：AI検索時代の必須スキル

/toprank:geo-optimizerはGenerative Engine Optimization——つまりAI検索エンジン（ChatGPT/Claude/Perplexity/Gemini/Google AI Overviews）からの引用最適化を専門に扱う。

具体的には次の3アウトプットを返す。

1. 0-100点のGEOスコア：現状コンテンツがAI検索でどれだけ引用されやすいかを定量評価
2. AI引用向けリライト案：Claude側の改稿提案
3. エンジン別戦略：ChatGPT/Claude/Perplexity/Gemini/AI Overviewsそれぞれの最適化戦略

AI検索からの流入比率が増加する2026年以降、GEOは従来SEOと併走必須の領域だ。1スキルでこの新領域までカバーしている点は、Toprankが単なる「SEMrushクローン」ではないことを示す重要な特徴だ。

コネクタ：MCPサーバーへの抽象化

各SEOスキルは外部ツールを ~~category プレースホルダで参照する設計になっている。READMEから抜粋する。

このプレースホルダ設計のおかげで、スキルはツール非依存だ。NotFair MCPが将来別実装に置き換わっても、スキルファイル自体は書き換え不要で動き続ける。コネクタが無い場合は graceful degradation（緩やかな縮退）が組み込まれており、GSC接続なしでも技術クロールだけは実行できる。

6. インストールから初回監査までの30秒手順

Toprankの導入は驚くほど短い。Claude Code内で2行打つだけだ。

/plugin marketplace add nowork-studio/toprank
/plugin install toprank@nowork-studio

これで/toprank:*の全スキルが利用可能になる。.mcp.jsonは自動配置され、NotFair MCPサーバーの登録も完了する。

手動セットアップ（settings.json直接編集派向け）

settings.jsonを手で編集したい場合は以下を追加する。

{
  "extraKnownMarketplaces": {
    "nowork-studio": {
      "source": {
        "source": "github",
        "repo": "nowork-studio/toprank"
      }
    }
  },
  "enabledPlugins": {
    "toprank@nowork-studio": true
  }
}

初回OAuth認証

/toprank:google-ads-auditを初めて実行すると、ブラウザタブが開き、notfair.coにサインインを促される。Googleアカウントで認可するとトークンがOSキーチェーンに保存され、以降は無言で動作する。Meta Adsも同様に初回OAuthが独立して走る。

設定ファイル：.notfair.json

各プロジェクトディレクトリに.notfair.jsonを配置し、Google AdsアカウントIDとMeta AdsアカウントIDを書く。

{
  "accountId": "123-456-7890",
  "metaAccountId": "act_9876543210",
  "site": "https://mystore.com"
}

両方を同じファイルに記述する設計のため、Google→Metaの切替え時に毎回サインインを促されることはない。

ピンとこない時のスモークテスト

/toprank:seo-analysisをSearch Console接続のみで実行するのが最も摩擦が低い。GSCのオーナー権限を持っているサイトを指定すれば、広告アカウントなしでも30分以内に最初の30日プランが手元に届く。

7. 競合・代替ツールとの比較（RustySEO/SEMrush/Promptfoo/Surfer）

Toprankの立ち位置を理解するため、隣接領域のツールと並べて比較する。

ToprankのユニークセリングポイントはBO列の「Mutation実行」だ。SEMrush・Ahrefs・Surferも分析能力は十分だが、最終的に管理画面に戻る前提で設計されている。ToprankはClaudeに「Do it all.」と返事するだけで実行されるため、運用ループが圧倒的に短い。

同じOSS×SEOの軸では RustySEO完全解説：Tauri+Rust製の無料デスクトップSEOツール、SEMrushの代替候補 が参考になる。RustySEOは自サイトGSC＋クロール特化のスタンドアロンアプリで、Toprankの「広告込み・CLI内自動実行」とは異なる方向のOSSだ。

Claude Code プラグイン群との比較

Claude Codeスキル/プラグイン群の中でもToprankは異色だ。

• Prismatic Skills：Claude Codeプラグインのマーケットプレイス基盤を解説 ——汎用的なスキル配布インフラ。Toprankはそれに乗る側。
• Addy Osmani Agent Skills：18K星のスキルフレームワーク基本セット ——汎用スキルのテンプレート集。Toprankは特定領域（マーケティング）特化型。
• Microsoft Waza：Agent Skillsの品質をCIで自動採点する評価フレームワーク ——スキル品質の物差し。Toprankはこの物差しで評価される側。

Toprankの位置付けは「特定業務領域に深く突っ込んだ垂直プラグイン」で、汎用スキル群とは差別化される。マーケティングという領域では、汎用LLMよりGSC/GoogleAds/MetaAdsのドメイン知識をスキル化した方が圧倒的に強い、というToprankチームの判断が読み取れる。

8. まとめ：Toprankを今日から使うべきユーザーと注意点

ここまで見たToprankの特徴を要約する。

今すぐ導入すべきユーザー

• 少人数で複数サイトのSEOを回す個人/小規模事業者：GSC監査・GEO最適化スキルだけで週数時間の節約効果。
• Google Adsを月10万円以上回す広告主：無駄キーワード自動停止・ネガティブ追加だけで投資対効果が明確に出る規模感。
• マーケティングエージェンシー：OpenClaw経由のマルチサイト管理が、クライアントポートフォリオの運用工数を大幅に削減する。
• SEOコンサル：監査レポート出力・クライアント向け説明工数の削減効果が大きい。

導入前に確認すべきこと

今後ウォッチすべきポイント

• OpenClaw／Hermesアダプティブ層の成熟度。フルオートSEOエージェントが本当に「人間レビュー無し」で回せるレベルに到達するか。
• GEOスキルの引用最適化アルゴリズムの進化。AI検索エンジン側のアルゴリズム変動に追従できるか。
• MCPサーバー追加の動向。現在はGoogle Ads/Meta Adsの2本だが、LinkedIn Ads・TikTok Ads・X Adsへの拡張があれば一気にカバレッジが広がる。
• 代替MCP対応の充実度。プレースホルダ抽象化が機能して、NotFairに依存しない構成が現実的に組めるか。

Toprankは「AIエージェントが本気で業務領域に侵食し始めた」象徴的なOSSだ。SEMrushを月数万円払って眺める時代から、Claude Codeに「直しといて」と一言投げるだけで完結する時代への移行を体感したい人は、まず/toprank:seo-analysisの1コマンドから試してほしい。

参照ソース

• nowork-studio/toprank — GitHub公式リポジトリ（README、スキル一覧、MCPサーバー仕様、OpenClawドキュメント）
• NotFair公式サイト notfair.co（Webアプリ側のNotFair、MCP OAuthエンドポイント）
• Model Context Protocol公式仕様（NotFair MCPサーバーが採用するOAuth 2.1ストリーマブルHTTPの基盤プロトコル）
• Google Ads API公式ドキュメント — GAQLリファレンス（NotFair-GoogleAdsのrunScriptが叩く対象クエリ言語）
• Meta Marketing API — Conversions APIガイド（meta-ads-auditが評価対象とするPixel/CAPIの計測健全性の参考）

監視ツールの雄が、監視される側になった。GitHubトークン1本が奪われ、数千本のリポジトリを抱えるGrafana Labsのコードベースが外部者の手に渡ったとされる。一方でGrafana Labsはオープンソース企業として身代金要求を即座に拒否し、その判断を公然と表明した。本記事では公式スレッド全文と外部脅威インテリジェンスから確認された事実と推測を明確に区別しながら、この事案の技術的・組織的な意味と、企業が今すぐ実施すべき防御策を整理する。

本インシデントはGitHub CI/CDを狙ったサプライチェーン攻撃の新たな事例です。攻撃手法・防御の全体像は サプライチェーンセキュリティ完全ガイド2026｜攻撃手法・防御ツール・実践チェックリスト で解説しています。

インシデントの概要：公式声明スレッド（6連投）の全文要点

Grafana Labsは2026年5月17日、公式Xアカウントで6連投のスレッドを公開した。当初の第1投で「不正な第三者がトークンを入手し、コードベースをダウンロードした」と発表した後、続く2〜6投目で被害評価・対応状況・身代金要求への対応方針まで踏み込んで開示している。

このスレッドにより、当初不明だった被害範囲と組織の対応方針が大きく明らかになった。重要なポイントは3つだ。

第一に、顧客データや個人情報への不正アクセスは確認されていない。Grafana Cloud利用者・OSS利用者の本番システムには現時点で影響なしと公式に明言された。

第二に、攻撃者はコードベース公開を防ぐ対価として身代金を要求した。これは典型的なデータ窃取型ランサムウェアの恐喝モデル（後述するcoinbasecartelの手口と一致）であり、データ暗号化は伴わないことが裏付けられた。

第三に、Grafana LabsはFBIの公式見解に従って身代金支払いを明確に拒否した。これはオープンソース企業として身代金市場への資金供給を断つ責任ある姿勢であり、業界全体にとって重要な前例となる。

一方で、以下の点はこの記事の執筆時点（2026年5月17日）で公式の詳細レビュー（PIR）を待つ必要がある。

• トークンがどのような手口で窃取されたか（フィッシング・IAB・コミット履歴漏れなど）
• どのリポジトリが対象になったか（全リポジトリか特定のリポジトリか）
• ダウンロードされたコードベースの容量・内容範囲
• 攻撃者の特定・帰属（Attribution）の正式確認（後述するcoinbasecartel関与の公式認定）
• 今後の追加防御策の詳細

Grafana Labsは2025年4月のGitHub Actionsインシデントにおいても迅速で透明性の高い情報開示を行った実績があり、今回も同様に詳細なPost-Incident Review（PIR）が公開される見込みだ。

攻撃の連鎖構造：トークン窃取からコードベース流出まで

現時点で判明している情報をもとに、攻撃の一般的な経路を図示する。以下の図には推定的な部分が含まれることを明記する。

初期侵入の手口は現時点で未公表だが、脅威インテリジェンスの観点から複数の仮説が考えられる。一つはフィッシング・ソーシャルエンジニアリングによる認証情報の直接窃取、もう一つはInitial Access Broker（IAB）経由で購入した認証情報の利用だ。

なぜGitHubトークン1本でコードベースが取れるのか

GitHubのPersonal Access Token（PAT）やGitHub App tokenは、適切にスコープ設定されていない場合、組織内の複数リポジトリへの読み取り権限を一括で持つ。古典的な「Classic PAT」は特定のリポジトリではなくスコープ（repo、read:orgなど）単位で権限が付与されるため、1本のトークンで組織全リポジトリへのアクセスが可能になる。

# トークンのスコープを確認するコマンド（漏洩したトークンの調査に使用）
curl -H "Authorization: token YOUR_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/user | jq '{login: .login, scopes: .X-OAuth-Scopes}'

# レート制限情報でトークンの有効性を確認
curl -I -H "Authorization: token YOUR_TOKEN" \
  https://api.github.com/rate_limit

Fine-grained PATを使えばリポジトリ単位・権限種別単位でのスコープ制限が可能だが、多くの組織でまだ移行が完了していないのが現実だ。

公開情報から見るインシデントタイムライン

公式スレッドと外部脅威インテリジェンス情報を時系列で整理すると、次のような流れになる。

攻撃者の犯行声明文には「We can cause you more damage then you would ever imagine, contact us.（想像以上のダメージを与えられる、連絡せよ）」というcoinbasecartelの定型文が記されている。Grafana Labs側がこの恐喝を一切公開せず、内部のフォレンジック分析と認証情報の無効化を先行させた上で、48時間以内に公式声明を出したことになる。

coinbasecartelとの関連：脅威アクターの正体

ランサムウェア追跡サイト「ransomware.live」の記録によると、coinbasecartelというグループが2026年5月15日20:57 UTCにGrafanaを被害者としてリストアップしている。Grafana Labsの公式発表（5月17日）における「攻撃者はGrafanaを脅迫しコードベースの公開を防ぐために支払いを要求した（4/6）」という記述と犯行声明の文言・手口が一致しており、このグループが今回のインシデントに関与している可能性が極めて高いと推定される。ただし公式からの帰属（Attribution）確認は現時点で行われていない。

外部脅威インテリジェンスが示す追加データ

侵害認証情報の流通データを追跡しているHudson Rockの調査では、Grafana Labs関連で以下が確認されている。

注目すべき点は3つある。

第一に、Grafana Labs従業員端末からのinfostealer感染履歴は0件である点。これは「従業員PCがinfostealer感染→社内認証情報が直接漏洩」という古典的な初期侵入ベクトルの可能性が低いことを示唆する。

第二に、第三者経由のクレデンシャル漏洩が9件確認されている点。これはGrafana Labsと業務上接続する外部パートナー・ベンダー・コントラクター端末で発生した感染を意味する。サプライチェーン上のサードパーティ経由の認証情報漏洩は近年急増しており、今回のインシデントにおける有力な仮説の一つとなる。

第三に、ユーザー側ではRedLineとLummaという2大infostealerファミリーが圧倒的なシェアを占めている点。これらは2024〜2026年にかけて最も活発に流通しているスティーラーで、ダークウェブのIAB（Initial Access Broker）市場で日常的に売買されている。

これらはあくまで外部脅威インテリの観測データであり、今回の侵入経路を断定するものではない。Grafana公式の調査結果待ちとなる。

coinbasecartelとはどのような脅威アクターか

coinbasecartelは2025年9月に活動を開始した比較的新しい脅威グループで、登場から半年あまりで急速に被害規模を拡大している。Bitdefender Business Insightsの分析とInfoStealers.comの追跡調査をもとに、その全体像を整理する。

暗号化なしの純粋なデータ窃取型：一般的なランサムウェアがファイルを暗号化して業務を停止させるのに対し、coinbasecartelはデータを暗号化せず、窃取したデータの公開を脅しに身代金を要求するモデルを採る。被害組織の業務継続性は保たれるが、機密データの流出リスクが焦点になる。Grafana Labsへの恐喝（「コードベース公開を防ぐための支払い要求」）はこのモデルに完全に一致する。

主要な標的セクター：技術・医療・輸送・エネルギー分野で被害報告が多く、Grafana Labsはその「技術」セクターに該当する。

初期侵入の主要手口（Bitdefender分析より）：

• 古いinfostealerログの認証情報を購入 — RedLine、Lumma、Vidar、StealCなどのスティーラーがダークウェブのIABマーケットで日常的に売買されており、coinbasecartelはこれら過去ログから対象企業の正規アカウント情報を入手
• 購入した認証情報で正規のログインフローを経由してネットワークに侵入（マルウェアによる脆弱性悪用ではなく、正規ログインのため検知が困難）
• 内部探索後、機密データを段階的に窃取（多くの場合MFA未設定のサービス・アカウントが踏み台になる）

身代金要求の流れ：侵入後48時間以内の連絡要求、10日間の支払い期限、Bitcoin払いというパターンが確認されている。グループのメッセージは「我々は想像以上のダメージを与えられる、連絡せよ」という定型文で、今回のGrafana掲示にも同様の文言が使われた。

他の著名な被害組織

coinbasecartelの被害は技術企業だけにとどまらない。InfoStealers.com / Bitdefenderが報じた主要被害組織には次のようなものがある。

これらの被害組織はいずれも内部の認証情報管理・MFA運用において完璧ではなかったとされ、coinbasecartelはこうした「正規ログインの隙」を組織横断的に突いてきた。業界・規模を問わずInfoStealer由来のクレデンシャル汚染は普遍的な脅威となっている。

Grafanaインシデントの侵入経路に関する推測分析

ここまで整理してきた情報を踏まえると、今回のGrafana侵害がどのような技術的経路で発生したかについて、いくつかの仮説を組み立てられる。ただし以下は推測であり、公式調査の結果を待つ必要がある。

公開情報を改めて整理すると、確定事項と推測事項は次のように分かれる。

推測の組み立てロジック：Coinbasecartelの過去170社の侵入経路の大多数がinfostealer由来のクレデンシャル購入であり（Bitdefender分析）、被害企業の80%が過去に何らかの形でinfostealer汚染を経験している。今回のGrafana事案では従業員端末の直接感染こそゼロだが、第三者経由のクレデンシャル漏洩が9件確認されている。この組み合わせから「サードパーティ端末のinfostealer感染 → そこに保存されていたGitHub PAT流出 → ダークウェブで購入 → 正規ログインでGitHub環境侵入 → コードベースクローン」という攻撃シナリオが過去パターンとして最も整合する。

ただしこれはあくまで「もっともらしい仮説」であり、Grafana Labsが公式スレッド (3/6) で「原因を特定済み」と述べた具体的手法はまだ未公表だ。公式PIRが公開されるまで断定は避けるべきだ。

推測が当たっていた場合に組織が取るべき教訓

仮にこの仮説が正しかった場合、自組織のセキュリティ対策に与える示唆は大きい。

1. 自組織のセキュリティだけ強化しても不十分 — パートナー・ベンダー・コントラクター・元従業員の端末も認証情報の流出経路になる
2. GitHub PATを「コードに書かない」だけでは足りない — 個人のNotion・Slack・スクリーンショット・パスワード管理ツール経由でも漏洩する
3. Have I Been Pwned / Hudson Rockなどのinfostealer監視サービスで自組織ドメインの汚染状況を定期チェックする運用が必要
4. GitHub OIDCへの全面移行で静的PAT自体を世界から消すのが最も根本的な防御
5. Canaryトークンの拡充でPAT流出時の検知時間を最小化

Grafana Labsの過去のセキュリティインシデントとの比較

Grafana Labsはオープンソース企業として、セキュリティインシデントへの透明性の高い対応で知られる。今回の事案と2025年4月のGitHub Actionsインシデントを比較する。

2025年のインシデントは「コードは見られていない、顧客データも無事」という比較的軽微な結果で終息した。今回はコードベースのダウンロード自体は確認されており、その意味では深刻だが、公式スレッドにより顧客データ・本番システムへのアクセス痕跡はなしと明確に否定された点は重要だ。

コードベース流出が持つ意味：なぜオープンソースでも危険なのか

Grafanaは主要なコードをオープンソースとして公開しているが、全てのコードが公開されているわけではない。

また、オープンソースであっても、コードベースの全体像を手に入れた攻撃者は以下のことが可能になる。

既知の脆弱性パターンの大規模探索：公開コードでは読みにくい部分も、ローカルにクローンすれば高度なSAST（Static Application Security Testing）ツールで網羅的にスキャンできる。例えば2026年3月に修正されたCVE-2026-27876（SQLエクスプレッション任意ファイル書き込み、CVSS 9.1）の類似パターンを新たに探索するといった用途が考えられる。

ゼロデイ脆弱性の発掘：OSSとして公開されていないプライベートコードに未修正の脆弱性が潜んでいれば、攻撃者がそれを発見・悪用する時間を得る。

内部アーキテクチャの把握：コードを読むことで内部APIのエンドポイント、認証フロー、データの流れを把握し、標的型攻撃の精度を高めることができる。

組織が今すぐ実施すべき対策

Grafana Labsを直接利用している組織だけでなく、GitHubを使って開発している組織全体に当てはまる対策を整理する。

1. 既存トークンの棚卸しと権限の最小化

まず自組織のGitHubトークンを全て洗い出し、不要・過剰スコープのものを即時失効させる。

# GitHub CLIで組織内のPersonal Access Tokensを確認（管理者権限が必要）
gh api /orgs/{ORG}/personal-access-tokens \
  --jq '.[] | {id: .id, name: .name, created_at: .created_at, expires_at: .expires_at}'

# Fine-grained PATに移行していない古いトークンを特定
gh api /orgs/{ORG}/personal-access-tokens \
  --jq '.[] | select(.token_last_eight != null) | {name: .name, login: .owner.login}'

# TruffleHogでリポジトリ内の漏洩シークレットをスキャン
docker run --rm -it \
  -v "$(pwd):/repo" \
  ghcr.io/trufflesecurity/trufflehog:latest \
  git file:///repo --only-verified

Fine-grained PATへの移行は組織ポリシーとして強制できる。GitHub Organizationの設定で「Personal access tokens → Fine-grained tokens」を必須化し、承認フローを設定することで、Classic PATの新規発行を防げる。

2. GitHub OIDCへの移行：トークンを発行しないCI/CDアーキテクチャ

最も根本的な対策は、静的なGitHubトークンをCI/CDパイプラインから完全に排除することだ。GitHub Actionsでは、OIDCフェデレーションを使って動的な一時トークンを発行する仕組みに移行できる。

# GitHub Actions で OIDC を使った安全なトークン生成の例
name: Secure Deploy

permissions:
  id-token: write   # OIDC トークン取得に必要
  contents: read    # コードのチェックアウトに必要

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # 静的なトークンをSecretに保存する代わりにOIDCで一時認証情報を取得
      - name: Configure AWS Credentials via OIDC
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
          aws-region: ap-northeast-1

      # GitHub App Token も OIDC 経由で動的生成
      - name: Generate GitHub App Token
        id: app-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: $
          private-key: $

このアーキテクチャでは、長期間有効な静的トークンが存在しないため、トークンを窃取されるリスク自体を排除できる。

3. トークン使用のリアルタイム監視

トークンが漏洩・悪用された場合でも、早期検知によって被害を最小化できる。GitHubは組織の監査ログをAPIで取得できる。

# GitHub 組織の監査ログで不審なアクセスを検索
# 特に通常と異なるIPや未知のUser-Agentからのclone操作を確認
gh api \
  "/orgs/{ORG}/audit-log?phrase=action:git.clone&per_page=100" \
  --jq '.[] | {
    action: .action,
    actor: .actor,
    repo: .repo,
    created_at: .created_at,
    country_code: .country_code,
    user_agent: ."@type"
  }'

# 特定期間のgit.cloneイベントを抽出（大量クローンの検出）
gh api \
  "/orgs/{ORG}/audit-log?phrase=action:git.clone&after=$(date -u -v-24H +%Y-%m-%dT%H:%M:%SZ)" \
  --jq 'group_by(.actor) | .[] | {actor: .[0].actor, count: length}'

Grafana Labs自身が推奨するCanaryトークン（特定のURLや認証情報を含むダミートークンで、アクセスがあればアラートが発火する仕組み）を組み合わせることで、漏洩を秒単位で検知できる体制が作れる。

セキュリティ体制の成熟度チェックリスト

今回のGrafana Labs事案を踏まえ、自組織のGitHub環境の安全性を確認するためのチェックリストを示す。

過去のGrafana GitHub Actionsインシデント（2025年4月）との技術的相違点

2025年4月26日に発生したインシデントは、pull_request_targetトリガーを使ったGitHub Actionsワークフローの設定不備を突いた攻撃だった。攻撃者はフォークしたリポジトリから悪意のあるブランチ名を使ってコマンドインジェクションを実行し、GRAFANA_DELIVERY_BOT_APP_IDとGRAFANA_DELIVERY_BOT_APP_PEMの2つのGitHub Appシークレットを窃取した。

このインシデントで重要なのは、Canaryトークンが即座にアラートを発火させた点だ。土曜日の夜に発生したにもかかわらず、グローバルに分散したセキュリティチームが数時間以内に対応し、被害を最小化した。インシデント終結（2025年5月12日）時点で「コードの改ざんなし、本番システムアクセスなし、顧客データ漏洩なし」を確認した。

今回（2026年5月）の事案はこれとは性質が異なる。前回は自動化ボットによるワークフロー悪用だったが、今回はGitHub環境へのアクセス権を持つトークンの窃取とコードベースのダウンロードという、より意図的・目的的な攻撃の様相を呈している。

Grafana Labsは前回のインシデント後、以下の改善を実施していた：

• ZizmurとTruffleHogをCI/CDパイプラインに組み込み
• コンパートメント化されたVaultと短命トークンの導入
• オープンソースリポジトリとプライベートリポジトリの組織分離
• Canaryトークンの拡充

こうした対策を講じた後でも今回の事案が発生したことは、セキュリティ対策の継続的な更新が不可欠であることを改めて示している。

Grafana利用者への影響評価

公式スレッド（2/6）で「顧客データや個人情報がアクセスされた形跡はなく、顧客システムや業務への影響を示す証拠も見つかっていない」と明言された。これを踏まえた利用者カテゴリ別の影響評価は次の通り。

Grafana Cloud利用者：公式発表により本番システム・顧客データへのアクセス痕跡なしと確認された。即時のサービス利用への影響はないが、念のためAPIキー・サービスアカウントの権限棚卸しを推奨する。

Grafana OSS（セルフホスト）利用者：コードベースを入手した攻撃者が新たな脆弱性を発見・悪用するリスクは中長期で残存する。CVE-2026-27876（CVSS 9.1）などの既知の脆弱性はパッチ済みバージョン（12.4.2以降）への更新で対処できている。最新パッチの適用状況を確認すること。

Grafana Enterpriseライセンス利用者：プライベートリポジトリのコードが対象に含まれる可能性について、Grafana Labsからの個別連絡を確認すること。

自社でGrafanaのビルドパイプラインに依存している組織：公式声明では本番システム・コード改ざんへの言及はないが、ビルドアーティファクトの完全性確認（コンテナイメージのダイジェスト検証など）を推奨する。

最新パッチの適用確認

今回の事案とは別に、直近でGrafanaには複数の重大な脆弱性が修正されている。インシデント対応と並行してパッチ適用状況を確認する。

# 現在稼働しているGrafanaのバージョン確認
curl -s http://localhost:3000/api/health | jq .version

# Grafana公式APIで最新リリースを確認
curl -s https://api.github.com/repos/grafana/grafana/releases/latest \
  | jq '{version: .tag_name, published: .published_at, url: .html_url}'

# Dockerコンテナの場合：イメージのダイジェストを検証
docker inspect grafana/grafana:latest \
  --format=''

直近の主要修正パッチ：

• v12.4.2 / v12.3.6 / v12.2.8 / v12.1.10 / v11.6.14（2026年3月25日リリース）
  • CVE-2026-27876（CVSS 9.1 Critical）：SQLエクスプレッションによる任意ファイル書き込み→RCE
  • CVE-2026-27880（CVSS 7.5 High）：OpenFeature DoS

これらのCVEとは独立した脅威として、今回のコードベース流出リスクへの対処も並行して進める必要がある。

インシデント対応の透明性：Grafana Labsが示した開示姿勢

今回の発表で注目すべき点の一つは、身代金要求とその拒否を即日かつ公然と開示したことだ。2025年4月のインシデントでも、Grafana Labsはインシデント発生翌々日にはLinkedInとブログで詳細を公開し、調査終結後にはPost-Incident Review（PIR）を発表した実績がある。

今回は単なる被害公表に留まらず、6連投スレッドの中でFBIの公式見解を引用しつつ「身代金を支払わないことが適切な道だ」と明言した。これは業界全体にとって重要な意味を持つ。

この透明性の高い開示姿勢は、オープンソースコミュニティからの信頼を維持する上で重要な役割を果たしている。多くの組織がインシデントの存在自体を数週間〜数ヶ月隠蔽するなか、Grafana Labsの対応は業界標準として参照されるケースも多い。

詳細なPIRは調査完了後に公開される予定（公式スレッド6/6で明言）であり、続報のキャッチアップが望まれる。

組織として取るべきインシデント初期対応手順

Grafana利用組織が今すぐ実施すべき初期対応を時系列で整理する。

即時（Today）：

1. 組織内でGrafanaリポジトリにアクセスできるGitHubトークンを全て洗い出す
2. 不要・長期間未使用のトークンを即時失効させる
3. Grafana公式ブログ（grafana.com/blog）とGitHub Security Advisoriesをウォッチ登録する

今週中（This Week）：

1. TruffleHogでリポジトリ内のシークレットをスキャンし、残存シークレットを排除
2. GitHub監査ログで過去30日間の異常なgit.cloneイベントを確認
3. 本番Grafanaインスタンスを最新の修正パッチ（v12.4.2以降）に更新

今月中（This Month）：

1. Fine-grained PATへの全面移行計画を立案・実施
2. CI/CDパイプラインのGitHub OIDC移行スケジュールを設定
3. Canaryトークンをリポジトリと本番環境に配置

まとめ：コードベース流出インシデントから組織が学ぶべきこと

Grafana Labsの今回の事案は、どれだけセキュリティ意識の高い組織でも、GitHubトークン管理の盲点が残れば侵入を許すという現実を突きつけた。一方で、6連投スレッドで明らかになった事実は次の3点に集約できる。

詳細な攻撃手口・Attribution・PIRの公開は今後となるが、組織が今すぐ行動できることは明確だ。静的なGitHubトークンの棚卸しと最小化、GitHub OIDCへの移行、TruffleHogによるシークレットスキャン、Canaryトークンの配置——これらは「Grafana Labs事案が教えてくれた」ことではなく、業界のベストプラクティスとして長年言われてきたことだ。事案を機にアクションに移すかどうかが、次の被害者になるかどうかを分ける。

そして経営層が学ぶべき教訓がもう一つある。身代金要求に直面したとき、FBI公式見解に従って拒否する判断軸を事前に持っておくことだ。Grafana Labsはオープンソース企業として「コードは公開されても構わない」という覚悟があったからこそ拒否を即断できた。自社が同じ立場に立たされたとき何を守るのか、トレードオフを事前に整理しておくべきだ。

参照ソース

1. Grafana Labs公式X: @grafana 6連投スレッド（2026年5月17日）— GitHub環境への不正アクセスとコードベースダウンロード公表・身代金拒否表明
2. Grafana Labs公式ブログ: Grafana security update: no customer impact from GitHub workflow vulnerability（2025年4月）
3. Grafana Labs公式ブログ: Grafana security update: post-incident review for GitHub workflow vulnerability and what’s next（2025年5月）
4. StepSecurity: Grafana GitHub Actions Security Incident
5. Grafana Labs公式ブログ: Grafana security release: Critical and high severity security fixes for CVE-2026-27876 and CVE-2026-27880
6. Bitdefender Business Insights: No Encryptors, No Problem: The Coinbase Cartel Ransomware Group — 累計170社/34カ国・80%がinfostealer感染履歴あり・古いログ購入→正規ログイン手口の分析
7. InfoStealers.com: Inside the Coinbase Cartel: How Infostealer Credentials Fueled a 100-Company Ransomware Spree — Cognizant/ENGIE/SK Telecom等の被害組織分析
8. ransomware.live: Victim: Grafana – coinbasecartel（2026年5月15日 20:57 UTC掲載）— RedLine 813件・Lumma 757件・第三者9件・外部URL 88件の詳細メトリクス
9. Hudson Rock: 侵害認証情報追跡データ — Grafana Labs従業員端末からのinfostealer感染0件、第三者経由クレデンシャル漏洩9件、Grafana関連ユーザー2,985件
10. FBI Internet Crime Complaint Center (IC3): ランサムウェア身代金支払いに関する公式見解

1. PhotoGIMPとは何か：GIMPを「Photoshopに見える」状態にする公式パッチ

PhotoGIMPは、無料の画像編集ソフトGIMP 3.0以降を、Adobe Photoshopから移ってきたユーザーが違和感なく使えるレイアウトに変えるためのコミュニティパッチで、GitHubで8,800スター超を獲得している。GIMP本体には何も追加せず、GIMPがホームディレクトリ配下に持っている設定ディレクトリの中身を上書きするだけで成立する。

開発者はブラジルのLinux系YouTubeチャンネル「Diolinux」を運営する João Diolinux 氏で、2020年6月に最初のコミットが行われた。GIMP 2.10時代から積み重ねてきたノウハウが、GIMP 3.0のリリースに合わせて全面リファクタリングされ、現行版はGIMP 3.0+専用となっている。

ライセンスはGNU General Public License v3.0で、GIMP本体と同じくフリーソフトウェアだ。リポジトリの主要言語がCSSになっているのは、GIMPのテーマカスタマイズ用 theme.css を含んでいるためで、実装の中心は設定ファイルの塊である。

1.1 PhotoGIMPが解決する課題

Photoshopから他のソフトに移ろうとした人なら一度は経験する「ショートカットが効かない」「ツールが見つからない」「メニュー階層が違う」という三重苦がある。GIMPは無料で機能も豊富だが、独自の哲学で設計されているため、Photoshop経験者には学習コストが急に立ち上がる。

PhotoGIMPはこの「最初の壁」を取り除くためだけに作られている。ショートカットを Adobe 公式の Photoshop Windows 版ドキュメントに沿って付け替え、ツールバーの並び順を Photoshop に寄せ、スプラッシュ画面もそれっぽいデザインに差し替える。これだけで初日の生産性が体感で数倍変わる。

1.2 リポジトリの規模感

GitHubのスター数は8,825件、フォーク数は280件で、純粋な「設定ファイル集」のリポジトリとしては破格の人気を持つ。デフォルトブランチは master、月次〜四半期単位でリリースが切られる。最新リリースは 3.0 系列で、GIMP 3.0+専用となっている。

トピックタグには gimp photoshop linux windows macos といったキーワードが並ぶ。issueは32件、PRも含めてアクティブにメンテナンスされており、放置プロジェクトではない。

2. なぜAI画像生成ワークフローの後処理ツールとして選ばれるのか

ここ数年でStable Diffusion・DALL-E 3・Midjourney・Flux系モデルといったAI画像生成が日常的なツールになった。一方で、生成された画像をそのまま納品物・SNS投稿・記事のサムネに使えるかというと、ほとんどのケースで「もう一手間」が必要だ。

2.1 AI画像にはほぼ必ず修正が必要

生成AIが出力する画像には、現時点でも以下のような典型的な破綻が混ざる。

• ・指の本数が6本になる、関節が逆向きに曲がる
• ・髪の毛と背景の境界が溶ける
• ・文字が「それっぽい記号」になり読めない
• ・対象物のエッジに不自然なノイズが残る
• ・解像度を上げると細部が崩れる
• ・透過させたい部分に背景色が残る

これらを直すのに、ブラウザベースのジェネレーターで「もう一度ガチャを引く」のは効率が悪い。破綻した1ヶ所だけを2分で塗り直すほうが圧倒的に速く、品質も安定する。塗り直しに必要なのは、まさにPhotoshop型の高機能レタッチツールだ。

2.2 Adobe代替としての立ち位置

Adobe Photoshopは月額3,280円（フォトプラン）からの定期課金で、解約しないと永続的にコストが乗り続ける。AI画像生成を「後処理あり」で運用する場合、生成元のSaaS課金と二重コストになる構図が起きやすい。

PhotoGIMPは初期費用も月額もゼロで、Stable Diffusionをローカル実行する人なら追加コストは電気代だけで済む。Midjourneyの個人プランと合わせても、Adobe単体より安く済む計算が成り立つ。

2.3 ComfyUI / AUTOMATIC1111 とのファイル受け渡し

ComfyUIやAUTOMATIC1111といったローカルStable Diffusionランタイムは、生成結果をPNGとしてディスクに書き出す。PhotoGIMP化されたGIMPはPNG・WebP・PSD・TIFFをネイティブで開けるため、特別なエクスポート設定なしに File → Open で直接読み込める。

逆方向、つまりGIMP側でマスクを作ってComfyUIにinpaintとして戻すワークフローも実用的だ。GIMPのアルファチャンネルをPNGで書き出せばマスク画像として使え、生成→部分修正→再生成のループが10秒程度の往復で回せる。

3. アーキテクチャ：GIMPに被せる設定パッチ

PhotoGIMPの中身はバイナリではなく、GIMPが起動時に読みに行く設定ファイル群だ。差分を整理すると、シンプルな上書き構造で全体像を把握できる。

3.1 上書きされる7つの設定ファイル

PhotoGIMPが置き換える主要なファイルとその役割は次のとおりだ。

• ・shortcutsrc：キーボードショートカットの定義。Adobe公式のPhotoshop Windows版ショートカット一覧に沿って書き換えられている
• ・toolrc：ツールバーに並ぶツールの順番と表示状態
• ・sessionrc：ウィンドウ・パネルの初期配置。レイヤー・チャンネル・パスのドックを Photoshop と同じ右側にまとめる
• ・dockrc：ドックの細かなレイアウト
• ・gimprc：キャンバスサイズ・グリッド・自動保存などの一般設定。キャンバスを最大化するチューニングが入っている
• ・contextrc：直前に使ったツール・色などのコンテキスト
• ・templaterc：「新規ドキュメント」テンプレート

これらに加えて splashes/ 配下のPNG画像（スプラッシュ）と theme.css（UIテーマの微調整）が含まれる。

3.2 ノータッチ領域

PhotoGIMPが「触らない」要素も明確に定義されている。

• ・GIMP本体のバイナリ（gimp 実行ファイル、ライブラリ群）
• ・プラグイン（G'MIC・Resynthesizer・BIMPなど）
• ・ユーザーが追加したブラシ・パターン・グラデーション・フォント
• ・スクリプト（Script-Fu・Python-Fu）

ユーザーが自前で追加した資産には一切影響を与えない設計だ。「気に入らなければ設定ディレクトリの3.0フォルダを削除して再起動」で完全に元に戻る。Adobeのプリセット読み込みと同じレベルの軽さで導入できる。

3.3 Linux版だけにある追加要素

Linux版（特にFlatpak経由）では、上記に加えて ~/.local/share/applications/ 配下に photogimp.desktop ファイルが配置され、ランチャー上で「PhotoGIMP」として独立表示される。アイコンも ~/.local/share/icons/hicolor/ 配下に専用のものが置かれる。

これは「同じGIMPバイナリを別アプリ風に呼び出す」だけのトリックで、GNOMEやKDEのランチャーから見ると別アプリに見える、というUX上の工夫だ。本体は1つのGIMPプロセスなので、メモリ使用量は二重にならない。

4. Photoshop・GIMP・Krita・PhotoGIMPの比較

AI画像の後処理に使える主要な選択肢を、Photoshop代替の観点で並べる。中心軸は「価格」「学習コスト」「AI画像との相性」だ。

4.1 PhotoGIMPは素のGIMPと比べて何が違うか

機能差は事実上ゼロだ。GIMPで Edit → Keyboard Shortcuts を開いて全部手動でPhotoshop風に直し、ツールバーをドラッグで並び替え、Windows → Single-Window Mode を有効にすれば、PhotoGIMPと同じ状態を再現できる。

ただしこの「手作業」が現実には数時間かかり、Photoshop経験者でも操作対応表を片手に1日仕事になる。PhotoGIMPは「素のGIMPを20時間かけてPhotoshop風にカスタマイズした結果」を、zip展開1分で手に入れられるショートカットだ。

4.2 Kritaとのすみ分け

KritaはKDEプロジェクト由来の無料ペイントツールで、デジタルイラスト・コンセプトアートに向く。一方で写真レタッチ・印刷物・UI素材といった「Photoshop型」用途では、GIMP/PhotoGIMPのほうがツールと操作系が近い。

AI画像生成の後処理という観点では、生成物の用途で選ぶのが筋が良い。アニメ調・イラスト調ならKrita、写真調・実写合成系ならPhotoGIMPという棲み分けだ。

4.3 Photoshopとの「本当の差」

Photoshopにあって、PhotoGIMP化されたGIMPで完全には埋まらない機能は次の4つだ。

• ・Camera Raw（HDR現像・ホワイトバランス調整の業界標準）
• ・調整レイヤー＋スマートオブジェクトの完全な非破壊ワークフロー
• ・Generative Fill（Adobe Fireflyによるinpaint）
• ・CMYKネイティブな印刷向け色管理

逆に言うと、これら4つを使わない用途ならPhotoGIMPで十分に代替できる。ブログ用画像・SNS用カット・AI画像レタッチ・サムネ作成・UI素材であれば、Adobeを解約しても困らない。

5. 3OS共通：インストールの全体像と注意点

PhotoGIMPは3OSとも「GIMP 3.0+を入れる → 1回起動して閉じる → PhotoGIMPを上書きコピー」の3ステップに集約できる。OSごとに違うのは設定ディレクトリの位置だけだ。

5.1 最初のGIMP起動が必須な理由

GIMPは初回起動時に、ホームディレクトリ配下に設定ディレクトリを作成する。shortcutsrc などのファイルはこのタイミングで初めて生成される。

PhotoGIMPは「存在する設定ファイルを上書き」する設計のため、GIMPを一度も起動していない状態でPhotoGIMPを展開すると、後からGIMPが起動したときに自分の初期設定で上書きしてしまうことがある。必ず順序を守る：GIMPインストール → 一度起動 → 完全終了 → PhotoGIMP展開。

5.2 バックアップは必須

既存のGIMPを使い込んでいる場合、PhotoGIMP適用前に必ず設定ディレクトリをまるごとバックアップする。Linuxなら次のコマンドで済む。

cp -r ~/.config/GIMP/3.0 ~/GIMP-3.0-backup-$(date +%Y%m%d)

Windowsは %APPDATA%\GIMP\3.0 を別フォルダにコピー、macOSは ~/Library/Application Support/GIMP/3.0 を同様にコピーする。気に入らなければバックアップを書き戻せば即時ロールバックできる。

5.3 各OSの設定ディレクトリ早見表

Linuxの隠しフォルダ（.config .local）はファイルマネージャ上で Ctrl + H を押さないと見えないので、操作前に表示設定を切り替えておく。

5.4 Linux Flatpak での導入手順

Flatpak版GIMPは多くのディストリビューションで標準的な配布形態だ。次の手順で導入できる。

# 1. GIMPがインストール済みであることを確認
flatpak info org.gimp.GIMP

# 2. 一度起動して閉じる（設定ディレクトリ生成）
flatpak run org.gimp.GIMP &
sleep 5
killall gimp

# 3. PhotoGIMP最新版をダウンロード
wget https://github.com/Diolinux/PhotoGIMP/releases/download/3.0/PhotoGIMP-linux.zip

# 4. ホームディレクトリに展開（.config と .local が上書きされる）
unzip -o PhotoGIMP-linux.zip -d ~/

# 5. 再起動
flatpak run org.gimp.GIMP

ファイル展開時に「既存のファイルを置き換えますか」と聞かれたら「Replace」を選ぶ。.config/GIMP/3.0/ と .local/share/applications/ .local/share/icons/ の3箇所が更新される。

5.5 Windowsでの導入手順

Windowsは Run ダイアログから %APPDATA%\GIMP を開いて、PhotoGIMP の 3.0 フォルダを上書きコピーする。Chocolatey 派なら1コマンドで済む。

# 公式GIMPを入れたあと、Chocolateyから1コマンドで適用
choco install gimp -y
gimp.exe   # 1回起動して閉じる
choco install photogimp -y

PowerShell の choco install photogimp はコミュニティ管理のパッケージで、内部では GitHub Releases の zip を取得して %APPDATA%\GIMP\3.0 に展開する。手動派は GitHub Releases から PhotoGIMP.zip を落として 3.0 フォルダを %APPDATA%\GIMP\ に上書きする。

5.6 macOSでの導入手順

macOS は手動コピーが基本になる。

# 1. 公式GIMPをインストール（gimp.org または brew install --cask gimp）
brew install --cask gimp

# 2. 一度起動して閉じる
open -a GIMP
sleep 5
osascript -e 'quit app "GIMP"'

# 3. PhotoGIMPを取得して展開
curl -L -o PhotoGIMP.zip \
  https://github.com/Diolinux/PhotoGIMP/releases/download/3.0/PhotoGIMP.zip
unzip PhotoGIMP.zip -d ~/Downloads/photogimp

# 4. 設定ディレクトリに上書きコピー
cp -R ~/Downloads/photogimp/3.0/* \
  ~/Library/Application\ Support/GIMP/3.0/

GIMP 2.10 が残っていると ~/Library/Application Support/GIMP/2.10 フォルダが衝突することがある。PhotoGIMP 3.0系を入れる際は古い 2.10 フォルダを退避させると安全だ。

6. AI画像生成→PhotoGIMP後処理の実践フロー

ここからは「実際の後処理の流れ」を1本のワークフローとして整理する。AI画像生成は Stable Diffusion WebUI / ComfyUI / Midjourney / DALL-E 3 のいずれでも考え方は変わらない。

6.1 全体ワークフロー

典型的な仕上げまでの流れは次のとおりだ。

• ・Step 1：生成AIで複数バリエーション（4〜8枚）を作る
• ・Step 2：合格ラインに近い1枚をPNG/WebPで書き出す
• ・Step 3：PhotoGIMPで開いて構図・解像度をチェック
• ・Step 4：破綻箇所をスタンプ・ヒーリングブラシで修正
• ・Step 5：必要ならアップスケール（外部AIツールまたはGIMPプラグイン）
• ・Step 6：色温度・コントラスト・シャープを最終調整
• ・Step 7：用途に応じてWebP / PNG / JPEGで書き出し

GIMPに慣れていれば1枚あたり5〜15分で仕上がる。Photoshopから移ってきても、PhotoGIMPのおかげで基本ショートカット（V移動・Bブラシ・Sスタンプ・L投げ縄選択・Ctrl+T変形）がそのまま使える。

6.2 指が6本問題の典型対処

Stable Diffusion 系のモデルが今も時々起こす「指が6本」「指が7本」問題は、PhotoGIMPでの対処が最も効率的だ。

• ・余分な指を選択ツール（Lの自由選択またはパス）で囲む
• ・スタンプツール（S）で隣接する皮膚をサンプリングして塗り潰す
• ・境界をぼかしブラシ（Shift+U）で馴染ませる
• ・全体に若干のノイズを乗せて違和感を消す

「もう一度ガチャを引いて指が4本のバージョンを引き当てる」より圧倒的に短時間で済む。AI 生成の不確実性は、人間の手で確実に潰す方が現実的だ。

6.3 マスクを作ってComfyUIに戻すinpaintフロー

複雑な破綻部分は、GIMP側でマスクを作って ComfyUI / AUTOMATIC1111 に inpaint として戻す方が綺麗な結果になる。

• ・PhotoGIMPで対象画像を開く
• ・新しい透明レイヤーを作成
• ・修正したい部分を白で塗りつぶす（その他は透明のまま）
• ・「レイヤーを画像として書き出し」でPNG出力（マスク画像）
• ・ComfyUIの inpaint ノードに「元画像」と「マスク画像」を投入
• ・生成結果をPhotoGIMPで開いて、必要なら微調整

このループは1セット5〜10秒程度で回せる。生成AIで「9割が完成、1割の破綻だけ直す」運用は、PhotoGIMPのマスク作成効率に大きく依存している。

6.4 色温度とコントラストの最終調整

AI生成画像は、デフォルトでコントラストが強すぎたり、色温度が偏っていることが多い。Photoshopで使う Image → Adjustments → Curves Levels Hue/Saturation は、GIMPでも Colors メニュー配下に同じ機能で揃っている。

PhotoGIMP化されていれば、ショートカット Ctrl+M（Curves）・Ctrl+L（Levels）・Ctrl+U（Hue/Saturation）が Photoshop と同じキーで動く。レタッチャーが Photoshop で蓄積した「指の運動記憶」がそのまま転用できる。

7. ComfyUIワークフローとの統合：自動エクスポートと連携

PhotoGIMPを単体で使うだけでなく、ComfyUIワークフローと自動連携させると更に効率化できる。

7.1 ComfyUIから「直接開く」フォルダの設計

ComfyUIの出力ディレクトリ（デフォルトは output/）を、デスクトップから常にウォッチしておくのが手軽だ。Linuxなら nautilus でブックマーク、macOSなら Finder のサイドバーにピン留め、Windowsなら エクスプローラーのクイックアクセスに登録する。

新しい画像が生成されたら、ファイルマネージャ上でダブルクリックすれば既定のアプリ（PhotoGIMP化されたGIMP）で開く。AI推論→レタッチ→保存のサイクルが10秒以内に始められる状態を作るのが、効率化の急所だ。

7.2 ファイル名規則で履歴を残す

ComfyUI / AUTOMATIC1111 では、出力ファイル名にプロンプトハッシュ・seed・モデル名を埋め込めるテンプレート機能がある。これを活用して、PhotoGIMP側で開いたときに「どのプロンプト・どのseedから来たか」が分かる状態にしておく。

例えば 20260517_142312_seed3892_juggernautXL_portrait.png のようなファイル名であれば、レタッチ済みも _retouched.png などサフィックスで区別すれば、生成元との対応が崩れない。

7.3 GIMP Python-Fu による一括処理

GIMPには Python-Fu スクリプティング機能があり、複数画像の一括処理を書ける。AI生成画像のバッチ後処理として、よく使う処理は次のようなものだ。

• ・指定フォルダ配下の全画像にシャープフィルタを適用
• ・色温度を一律で4500K→6000Kに補正
• ・元画像とレタッチ後を横並びの比較画像として書き出し
• ・WebP変換とサムネ生成

GIMPの Filters → Python-Fu → Console から対話的に試せる。スクリプト本体は ~/.config/GIMP/3.0/plug-ins/ に置けば次回起動時から「フィルタ」メニューに現れる。PhotoGIMPはここには手を入れないので、自作スクリプトと干渉しない。

8. ライセンス・コスト・組織導入の現実

無料で使える点が魅力だが、業務で導入するなら法的・組織的な観点も押さえておきたい。

8.1 GPL-3.0の意味

PhotoGIMPはGNU General Public License v3.0で配布される。GIMP本体も同じくGPL-3.0だ。GPL は「成果物を改変・再配布する場合に、同じGPLで公開する義務」が発生する copyleft 系ライセンスだが、ユーザーが社内で利用するだけ・成果物（画像）を商用利用するだけなら、再配布義務は発生しない。

GIMP/PhotoGIMPで作った画像を販売・配布する行為に制限はかからない。「GPLは作ったソフトの著作権だけに作用し、そのソフトで作った成果物には作用しない」のがGPLの基本的な解釈だ。

8.2 Adobeサブスクと比べたコスト試算

Adobe Photoshop の単体サブスクは月額3,280円（2026年5月時点のフォトプラン）。これを5人の小規模制作チームで12ヶ月使うと、年間 約196,800円のランニングコストになる。

PhotoGIMPに置き換えると、追加コストはゼロだ。レタッチ品質が完全に同等とは言えないが、「AI画像生成の後処理＋ブログ・SNS用画像」がメイン用途であれば、置き換え可能なケースが大半だ。

8.3 移行のリアル：教育コストの実態

「無料だから即移行できる」と判断するのは早計だ。Photoshop のヘビーユーザーは年単位で蓄積された操作系を持っており、PhotoGIMP化されたGIMPでも「Photoshopそのもの」ではない以上、ある程度の学習期間は必要になる。

実務上の目安として、Photoshop経験5年以上のレタッチャーがPhotoGIMPで業務効率を取り戻すには2〜4週間の慣らし期間が必要だ。ホビーユーザーや「たまにブログ画像を加工する」レベルなら数日で適応できる。

9. PhotoGIMPと組み合わせると効くツール群

PhotoGIMP単体でも完結はするが、周辺ツールと組み合わせると AI 画像ワークフローが本格的に強化される。

9.1 アップスケーリング：Real-ESRGAN / Upscayl

PhotoGIMPには高品質なAIアップスケール機能は内蔵されていない。1024x1024で生成した画像を4Kポスターに引き伸ばすような用途では、外部のAIアップスケーラーが必要だ。

OSSの選択肢としては Real-ESRGAN（コマンドラインまたは Web UI 経由）と Upscayl（GUIアプリ）が代表的だ。Real-ESRGANで4倍アップスケール → PhotoGIMPで最終調整、というパイプラインが一般的だ。

9.2 透過処理：rembg / BackgroundRemover

AI画像生成は背景込みで出力されることが多いが、SNSアイコンやサムネに使うときは背景透過が必要になる。OSSの rembg は単一バイナリで動き、PNG入力・PNG出力で背景だけを除去する。

rembg i input.png output.png の1コマンドで透過PNGが手に入る。あとはPhotoGIMPで境界線の微調整をすれば仕上がる。

9.3 メタデータ管理：ExifTool

AI生成画像にはプロンプト・seed・モデル名がメタデータとして埋まっていることがある。納品時に剥がす必要があるなら exiftool -all= image.png で全削除できる。

逆に、生成履歴を保持しておきたい用途では exiftool image.png でメタデータを確認すれば、後から「どのプロンプトで作った画像か」を遡れる。

9.4 G’MIC：GIMPの最強プラグイン

G'MIC は数百種類の画像処理フィルタを提供するGIMP用プラグインで、PhotoGIMPとも完全に共存できる。AI画像のスタイル変換、HDRトーンマッピング、コミック調変換といった処理が GUI から1クリックで適用できる。

apt install gmic gimp-gmic または公式サイトからインストーラを入れれば、GIMPのフィルタメニューに G’MIC が現れる。PhotoGIMP＋G’MICの組み合わせは、Photoshop＋プラグイン群と同等の表現力を持つ。

10. まとめ：AI時代のレタッチ基盤としてのPhotoGIMP

PhotoGIMPは「GIMPをPhotoshop風UIに切り替える設定パッチ」というシンプルな発明だが、その意味は2026年現在のAI画像生成時代に大きく増している。

設定パッチという軽い実装にもかかわらず、PhotoGIMPはGitHub 8,800スター超を集め、5年以上アクティブにメンテナンスされている。これは「GIMPはあと一歩でPhotoshop代替になれるのに、操作系の違いだけが壁になっていた」という需要に、過不足なく応えてきた証拠だ。

導入の第一歩は、現在使っているOSにGIMP 3.0+を入れて、PhotoGIMPを上書きコピーすることだ。所要時間は10分。気に入らなければ設定ディレクトリを削除すれば即時ロールバックできる。AI画像生成を仕事に組み込んでいるなら、レタッチ環境のコストをゼロに近づける一手として確実に元が取れる。

参照ソース

• Diolinux/PhotoGIMP — GitHub公式リポジトリ：パッチ本体、リリース、3OS別インストール手順、FAQの一次情報
• GIMP公式ダウンロード — gimp.org：GIMP 3.0+の公式配布元。PhotoGIMP適用前に必須
• Adobe公式 Photoshop デフォルトキーボードショートカット：PhotoGIMPのショートカット定義の原典
• PhotoGIMP Releases — GitHub：最新版zipの配布。Linux / Windows / macOSごとに分かれている

01 CodebuffとはClaude Code超えを謳う4エージェント型OSSコーディングエージェント

CodebuffAI/codebuff は、ターミナル上で動くAIコーディングエージェントだ。自然言語の指示でローカルのコードベースを直接編集する。2026年5月時点でスター5.3k・フォーク605・Apache-2.0。

特徴は単一モデルに丸投げしないことだ。Codebuffは役割を持つ4つのエージェントを順に呼び、ファイル選定・計画・編集・レビューを分業させる。これによりClaude Codeなど単一モデル系の弱点を補う。

公式リポジトリは独自評価で「Codebuff 61% vs Claude Code 53%」と主張する。175件超の実コードベース課題でClaude Codeを上回ったというのが触れ込みだ。後述するが数値の中身は読みかたに注意がいる。

導入は3パターン。サブスクリプション版CLIのcodebuff、SDK版の@codebuff/sdk、そして広告モデルのfreebuffが同じリポジトリで配布されている。Freebuffは無料・広告付きで「サブスクなし・クレジットなし・設定なし」を売りにする。

# サブスク版CLIの導入
npm install -g codebuff

# 広告付きの無料版
npm install -g freebuff

# プログラムから呼ぶSDK
npm install @codebuff/sdk

モデル選択の自由度も大きな差別化ポイントだ。CodebuffはOpenRouter経由で任意モデルを利用可能と公式に明記している。Claude・GPT・Qwen・DeepSeekなどを混在させ、エージェントごとに違うモデルを割り当てる構成が取れる。

Claude Code・Cursor・Windsurfは基本的にプラットフォーム側がモデルを選定する。利用者は推奨セットの中から選ぶことになり、自由度は限られる。Codebuffは逆方向で「エージェントごとに適切なモデルを利用者が組み合わせる」設計を取る。

たとえばPlannerは思考能力が要るのでClaude Opus 4.7、Editorは大量に呼ぶのでQwen-CoderやGPT-5-nano、Reviewerは確認に強いGemini系といったハイブリッド構成が可能だ。コストと精度のトレードオフを細かく制御できる。

OSSという点も実務では効く。Apache-2.0なので社内フォークや業務向け改造がライセンス上クリアだ。Cursorのようなプロプライエタリ製品では難しい、エージェント定義の社内標準化や監査ログの組込みが現実的になる。

02 Codebuffの4エージェント構成 — File Picker・Planner・Editor・Reviewerの役割分担

Codebuffの中核は4つの専門エージェントだ。単一のLLMコンテキストにすべてを詰める設計ではない。エージェントごとに役割・モデル・ツールを分けることで、文脈圧縮とハルシネーションを抑える狙いがある。

この分業構成は「広いコンテキスト探索」と「狭く正確な差分生成」を分離する狙いだ。File Pickerにはコードベース全体を見せるが編集はさせない。Editorには関連ファイルだけ渡し、無関係な情報を排除する。

Claude CodeやAiderはハーネス内部でほぼ単一モデルが全工程を担当する。CodebuffはClaude Codeでいう「サブエージェント」を初期設計に組み込み、デフォルトの実行フローに据えた形と言える。

トレードオフもある。エージェント間で会話が往復するため、単純なタスクではトークン消費とレイテンシが膨らむ。短いリファクタや1ファイル修正なら、Claude CodeやAider相当の単発エージェントの方が速い場面が多い。

逆に効くのは複数ファイルにまたがる仕様変更だ。「Webhookの認証方式をHMACからJWTに切り替える」のような横断タスクでは、File Picker→Plannerの段階で漏れを減らせる。Editorが本筋のロジック書き換えに集中できる。

各エージェント間の情報受け渡しはCodebuff内部で構造化される。File Pickerは関連ファイル一覧と理由メモを生成し、Plannerに渡す。Plannerはこれを元にファイル単位の編集計画を組み、各計画ノードをEditorに割り当てる。

Reviewerが特徴的だ。生成済みの差分と元の指示を見比べ、要件未充足を検出するとPlannerに差し戻す。ループ回数の上限はCodebuff側で制御されているため、暴走による無限呼び出しはハーネス段で止まる仕組みだ。

この構成はClaude Codeでサブエージェントを手動で組むのと役割が近い。違いは「分業を強制する」点にある。Claude Codeはサブエージェント不使用も選べるため、利用者の設計依存が大きい。Codebuffは設計判断を固定する。

固定設計の利点は「失敗パターンが揃う」ことだ。同じプロジェクトで複数の開発者がCodebuffを使っても、ログの形状とエラーのパターンが揃いやすい。チームでハーネスを共有する際に運用しやすい。

ハーネスとしての成熟度はもう一つの観点だ。Claude Code・Cursor・Aiderは長期にわたるユーザーフィードバックで細部が整っている。Codebuffは2026年時点で新興プロダクトの域を出ておらず、エッジケースの安定性は今後の改善余地がある。

特にWindows環境やWSL2環境での挙動、巨大モノレポでのファイルピッカー精度、検索でPATHが膨大になるケースなど、現場で頻発するシナリオでの安定性は要検証だ。導入前のPoCではこの種のケースを意識的に含めたい。

03 Codebuff 61% vs Claude Code 53% の中身 — AIコーディング評価の読み方

公式リポジトリのトップに掲げられている数字が、175件超のタスクでCodebuff 61% / Claude Code 53%という比較だ。出典はリポジトリ内のevals/README.mdである。

評価方法を要約すると次のとおりだ。実在するOSSリポジトリを複数用意し、それぞれに「現実的なコーディングタスク」を割り当てる。各タスクをエージェントに解かせ、テスト合格率や指示充足度をスコアにする。

読みかたで注意したいのは3点ある。第一に評価基盤はCodebuff自身が設計・運用していること。第三者ベンチマーク（SWE-bench Verifiedなど）ではない。

第二に175件超という規模は中程度だ。SWE-bench Verifiedは500件、SWE-bench Liteは300件で、より広範な分布をカバーする。Codebuffの評価は自社環境の傾向に最適化される余地がある。

第三にClaude Code側の構成だ。エージェント設定・ツール許可・モデル選択でClaude Codeの性能は大きく動く。比較条件の差異が結果に与える影響は公式README単独では追いきれない。

そのうえで、エージェント分業という設計上の方向性が一定の効きを示した点は意味がある。Vibe Codingの世界でも「Plan→Edit→Review分離が単発実行より精度を出しやすい」という観測は他研究と一致する。

数値そのものを過信せず、「4分業の方向性が悪くない」という設計判断の裏付けとして読むのが妥当だ。AIコーディングのベンチマークは構成バイアスが強く、現場での体感はリポジトリの規模・言語・テスト網羅性に大きく依存する。

参考として、2026年5月時点で主要な第三者ベンチマークの傾向を並べる。SWE-bench VerifiedはClaude Opus 4.7・GPT-5世代の上位モデルが70%台に乗り、Aiderのpolyglotベンチマークでも上位モデルは60%超を維持している。

つまり「単独モデルのコーディング能力」自体が、過去2年で大幅に底上げされた。エージェント分業の効きは、モデル単体の差を逆転させるほどの大きさではなく、「同等モデルなら設計差で数%動く」レベルだと見るのが妥当だ。

CodebuffがClaude Codeを上回ったとする内訳も、タスクカテゴリ別に見ると差が出る場面が偏る。多ファイル横断・テスト追加・既存仕様の置き換えで差が大きく、単発バグ修正やドキュメント編集では差が縮む傾向がある。

現場での導入判断としては、「自社の典型タスクを5〜10件用意し、Codebuff・Claude Code・Cursorで同条件で走らせて比較する」のが最も精度の高いやり方だ。公式評価は参考程度に留め、自社環境での再評価を必ず挟みたい。

04 Codebuff SDK・カスタムエージェント — TypeScriptで「git-committer」を書く

Codebuffはエージェント定義をTypeScriptで書ける。プロジェクト直下に/initを打つと、エージェント雛形と知識ドキュメント、AgentDefinition型定義がスキャフォールドされる。

公式READMEに掲載されているgit-committerエージェントの定義は次のとおりだ。handleStepsジェネレータでツール呼び出しの順序を直接記述している。

// 公式READMEからの抜粋
export default {
  id: 'git-committer',
  displayName: 'Git Committer',
  model: 'openai/gpt-5-nano',
  toolNames: ['read_files', 'run_terminal_command', 'end_turn'],
  instructionsPrompt:
    'You create meaningful git commits by analyzing changes...',
  async *handleSteps() {
    yield { tool: 'run_terminal_command', command: 'git diff' }
    yield { tool: 'run_terminal_command', command: 'git log --oneline -5' }
    yield 'STEP_ALL'
  },
}

ポイントは2つ。ひとつはモデル文字列がopenai/gpt-5-nanoのようにOpenRouter形式で書かれている点。プロバイダ名/モデル名の組合せで何でも指定できる。

もうひとつはhandleStepsの存在だ。LLMにツール選択を全任せせず、開発者が「最初は必ずgit diff」と決め打ちできる。Claude Code SkillsのSKILL.md同様、決定論的なステップと自由度の高いステップを混在させられる。

SDK側のコードも素直だ。CodebuffClientを生成し、runに対象エージェントとプロンプトを渡すだけで動く。CI環境やバッチ処理から呼ぶことを意識した形になっている。

import { CodebuffClient } from '@codebuff/sdk'

const client = new CodebuffClient({
  apiKey: 'your-api-key',
  cwd: '/path/to/your/project',
})

const result = await client.run({
  agent: 'base',
  prompt: 'Add error handling to all API endpoints',
})

このSDKの存在は「自社プロダクトにCodebuffを組み込みたい」用途に効く。レビューAI、社内コード自動生成、Slackボット連携などが想定される。Claude CodeのAgent SDKと役割が近い。

注意したいのはAPIキーの取り扱いと従量課金だ。@codebuff/sdk経由でもOpenRouter越しにモデルを呼ぶ場合、利用料はCodebuffプラットフォーム側の課金設計に従う。料金体系はリポジトリでは細部までは公表されていない。

/initで生成されるディレクトリ構造も押さえておきたい。プロジェクト直下に.codebuff/が作られ、エージェント定義のTypeScriptファイル、知識ドキュメント、AgentDefinitionの型定義が配置される。Claude Codeの.claude/に近い役割だ。

エージェント定義のメタフィールドはシンプルだ。idがエージェント識別子、displayNameがCLI表示名、modelがOpenRouter形式の文字列、toolNamesが使用可能ツール一覧、instructionsPromptが指示テンプレートになる。

ツールの種類はread_files・run_terminal_command・end_turnなどの基本ツールに加え、エージェント間のspawn_agentが用意されている。これによりカスタムエージェントから他のエージェントを呼び出せ、独自の分業設計が組める。

実用例として、社内では「ライセンスチェッカーエージェント」「セキュリティスキャナエージェント」「i18nキー検証エージェント」などをカスタム定義し、Plannerから条件付きで呼び出す構成が想定できる。CIに組み込めば自動レビューワークフローになる。

05 Codebuff vs Claude Code vs Cursor vs Aider — AIコーディングエージェント比較表

主要なAIコーディングエージェントとの位置づけを整理する。比較軸は「実行形態」「モデル選択の自由度」「エージェント分業」「ライセンス」「料金モデル」の5つ。

CodebuffとAiderはOSS＋任意モデルという点で近い。差はAiderが単発エージェント、Codebuffが4分業という設計差だ。Aiderはコミット単位で動作が読みやすく、Codebuffは大型タスクで効きやすい。

Claude CodeはAnthropic公式の優位を生かす立ち位置。Skill・Plugin・サブエージェントなど周辺機能が充実し、「カスタムする前提のハーネス」として完成度が高い。Codebuffはより固定的なフローを提示する。

CursorはIDE体験を最大化するプロプライエタリ製品。Tab補完・サイドバー・コードベース検索が統合されている。CLI主体のCodebuffとは利用シーンが正面衝突しないことが多い。

Freebuffの存在も独特だ。広告モデルでAIコーディングを提供するOSSは稀で、「クレカ登録なしで試したい」個人開発者にとっては入口として機能する。代わりに広告表示やテレメトリの仕様は事前確認が必要だ。

Freebuffのキャッチコピーは「no subscription, no credits, no configuration」だ。利用者から見るとサインアップだけで使え、トライアル制限もない。Codebuff本体に誘導するファネルの役割と、OSSコミュニティへの広報の役割を兼ねる位置づけだ。

業務利用時にFreebuffを選ぶ場合は、広告経由の外部ホスト呼び出しがある可能性に注意する。社内コードを編集対象とする場合、コードそのものは送信されてもメタデータがどこまで広告ネットワークに流れるかは要確認だ。商用ライセンス上の取り扱いも公式に確認したい。

Cursorとの比較を踏まえた選び方は別記事にまとめた。IDEとCLIで迷う場合は Claude Code vs Cursor 2026比較 を参照してほしい。OSS拡張で済ませたい場合は Continue vs Cursor徹底比較 が近い結論を出している。

エージェント分業の有無も整理しておきたい。Codebuffの4エージェントは「アーキテクチャとしての分業」だが、Claude Codeでも.claude/agents/配下でサブエージェント定義を書けば同等の構成は組める。違いは「初期状態で分業が動くか、利用者が組み立てるか」だ。

Aiderは設計思想として単発エージェントを貫いている。コミット単位で動作を追いやすく、git diffベースの差分提示が中心になる。Codebuffの方がワークフロー単位の自動化向き、Aiderはペアプロ風の対話向きと整理できる。

Cursorは月額$20級の固定料金が読みやすい。チームでの一括契約に向く一方、モデル変更の自由度では劣る。Codebuffは従量・サブスクの混在モデルで、利用量に応じた変動が大きい。コスト見通しの設計思想自体が違う。

06 日本の開発現場でCodebuffをどう使うか — Claude Code併用パターンと注意点

日本の開発現場でCodebuffを導入する場合、判断ポイントは3つに絞れる。コードの社外送信ポリシー、既存ハーネスとの併用、コスト管理だ。

第一にコードの送信先。Codebuff CLIはOpenRouter経由で各種モデルを呼ぶ仕組みのため、社内コードは少なくともCodebuff／OpenRouter／モデルプロバイダの3者を経由する。エアギャップ要件の現場では原則使えない。

第二に既存のClaude Codeハーネスとの併用だ。Codebuff CLIとClaude Codeは同じターミナルで共存できる。同じリポジトリで両方使い分ける構成も問題なく、.claude/配下と.codebuff/配下が衝突することは設計上ほぼない。

第三にコスト管理。複数エージェントが順に走るため、単発タスクでもLLMコール数が増える。月単位の利用ならOpenRouterのダッシュボードで上限を設定し、Codebuff側のサブスクと併用上限を必ず作っておきたい。

実務で効くユースケースは次のような場面が多い。

逆に向かないのは1ファイル内の局所修正だ。型エラー1件の修正にFile Picker→Planner→Editor→Reviewerを順に回すのはオーバースペックで、Claude CodeやAiderの方がレスポンスが軽い。

Claude Code併用パターンとして現実的なのは「日常はClaude Code、大型横断タスクはCodebuff」の使い分けだ。プロジェクト直下に両方のハーネス設定を置き、PRの種類で呼び分ける運用が筋がいい。

その前提としてClaude Code側の使い方を整理しておく価値がある。Claude Code単体のセットアップとカスタマイズは Claude Code完全ガイド2026：インストールから本番運用まで にまとめてある。

最後に注意点として、CodebuffのSDK・CLIは2026年5月時点で活発に変更が入っている。API契約・モデル指定構文・エージェント定義のスキーマはマイナーバージョン間で動く可能性が高い。本番組み込みは公式CHANGELOGの確認を前提にすべきだ。

導入の最短手順を一度整理しておく。CLI版はnpm install -g codebuffの1コマンドで入る。インストール後、対象プロジェクトにcdしてcodebuffを起動すれば、自然言語入力を受け付けるREPLが立ち上がる。

カスタムエージェント運用に進む場合は、/initを打って.codebuff/ディレクトリを生成する。生成されたTypeScriptファイルを編集し、model・toolNames・handleStepsを自社用に書き換える。SDKから呼ぶ場合は@codebuff/sdkを別途追加する流れだ。

評価フェーズでは小さなリポジトリで「典型的な5タスク」を投げ、ログを記録して比較する。ファイル選定の精度、編集差分の妥当性、Reviewerが何回戻したかの3点を見れば、現場フィット感が概ね判断できる。

長期運用に進むなら、エージェント定義の社内テンプレ化・OpenRouter予算上限・ログ収集の3点をセットで設計したい。個人で速く回すツールから、チーム標準のハーネスに昇格させるには、これらの仕組みが土台になる。

まとめ

Codebuffは「Claude Codeを61%で上回る」というキャッチコピーよりも、4エージェント固定のフロー設計とOpenRouter対応という構造的特徴に注目すべきOSSだ。横断的な仕様変更タスクで効きやすく、サブスク版・SDK・広告付きFreebuffという3形態の配布もユニークだ。

数値そのものはバイアスを含むが、Plan-Edit-Review分離の方向性は他研究の傾向とも整合する。日本の開発現場では、Claude Codeを日常使いの軸に置きながら、大型タスクだけCodebuffに切り替える併用が現実的な落としどころになる。

AIコーディングエージェントは2026年に入り、単一モデル時代から「設計選択の時代」へと移った。Claude Code・Cursor・Codebuff・Aiderはそれぞれ異なる設計判断の表現であり、現場ごとに最適解は変わる。自社の典型タスクに照らした評価を一度走らせ、年単位で再評価する運用が現実的だ。

参照ソース

• CodebuffAI/codebuff GitHub Repository（公式）
• Codebuff Evals README（公式評価データ）
• @codebuff/sdk npm package
• OpenRouter（マルチモデルルーティング）

Claude Code全体の使い方は Claude Code完全ガイド2026：インストールから本番運用まで をご覧ください。

garden-skillsとは何か—4スキルを「本番運用級」で束ねたSKILL.mdカタログ

ConardLi氏はフロントエンド分野で著名なOSS開発者で、CSS Inspector等の人気拡張を公開してきた人物だ。そのConardLi氏が2026年4月21日にgarden-skillsの初版を公開し、5月12日のpushed_atまでの3週間でStar 4,846を集めている。

garden-skillsの位置づけを一言で表すなら「4スキルそれぞれが厚みのある専門書」というカタログだ。Anthropic公式skillsがPDF/Excel等のOffice文書処理を広く浅くカバーするのに対し、garden-skillsは個別ドメインを深掘りする。各SKILL.mdは数百行規模で、references/配下に参照ドキュメント、scripts/配下に決定論的な実行ヘルパー、assets/配下にテンプレートを揃える構造になっている。

設計思想—「個別ドメインを深く、本番運用の体裁で」

garden-skillsの設計思想は3点に集約できる。

この体裁は社内向けに使うSKILL.mdを設計する際の参考実装として価値が高い。「リリースタグの切り方」「.zip配布の自動化」「マニフェストとプラグインマーケットプレースの両立」という運用面の課題に対する具体回答が、リポジトリ全体に組み込まれているからだ。

Anthropic公式skills・Addy Osmani agent-skillsとの位置関係

3つのSkillsカタログを並べると棲み分けが明確になる。

agent-skillsの徹底分析は Addy Osmani agent-skills徹底解剖 を、Skillsそのものの全体像は Claude Code Skills徹底解説 を併せて参照してほしい。

収録スキル4本の詳細—それぞれが「個別の専門書」

garden-skillsに収録されている4つのスキルを、用途・コア発明・成果物の観点で分解する。

web-video-presentation—スクリプトを「画面録画可能なプレゼン」に変える

web-video-presentationはカテゴリがWeb Video / Presentation Engineeringで、記事・脚本・授業資料・製品デモ・講演をクリック駆動の16:9 Webプレゼンテーションに変換するSkillだ。画面録画してそのままシネマティック動画にできる形で出力する点が他のスライド系Skillとの最大の違いになる。

特徴は5つある。

• 1920×1080固定ステージがビューポートに合わせて伸縮し、画面録画時のずれを防ぐ
• (chapter, step)カーソルがクリック・キーボード操作で進行し、視覚ステップごとに1ナレーション
• 脚本・テーマ・アウトライン・実装モード・音声合成（オプション）にハード協調チェックポイントを設置
• ホバー時のみ表示される進行コントロールで録画時の画面ノイズを排除
• paper-pressからterminal-greenまで複数の視覚言語を選べるテーマトークン構成

実装はVite + React + TypeScriptで、リポジトリ内にステージ用プリミティブと録画ガイダンスが揃っている。「note記事をプレゼン動画化したい」「LTスライドを録画してYouTubeに上げたい」というユースケースで、エージェントに「ナレーション台本→ステージ実装→録画指示」までを一気通貫させたい場合に効く。

web-design-engineer—AIが量産する「凡庸なUI」を脱却する

web-design-engineerはDesign / Frontendカテゴリで、AIが生成しがちなテンプレ的UIを脱却し、意図のある洗練されたフロントエンド成果物を作るためのSkillだ。エージェントを「機能実装者」から「デザインエンジニア」に位置づけ直すアプローチを取る。

ワークフローは6ステップで構成される。

注目すべきは「Anti-Cliché Blocklist」と「Brand Asset Protocol」だ。前者はAIが量産しがちなUIパターン（中央寄せヒーロー＋3カラム特徴＋紫グラデCTA）を明示的に禁止し、後者は「色のhex値より先に、ロゴ・製品画像・UI実機スクショ」をアセットとして優先する規律を強制する。

カバー範囲はWebページ・ランディングページ・ダッシュボード・インタラクティブプロトタイプ・HTMLスライド・アニメーション・UIモックアップ・データ可視化・デザインシステム探索。HTML/CSS/JavaScript/Reactのいずれの形式でも、最終成果物の体裁を「stunning」基準まで引き上げる方針が一貫している。

gpt-image-2—GPT Image 2を「3モード」で使い分ける画像生成Skill

gpt-image-2はImage Generation / Prompt Engineeringカテゴリで、GPT Image 2およびOpenAI互換画像APIに特化した画像生成Skillだ。ポスター・UIモック・製品ビジュアル・インフォグラフィック・学術図版・技術図解・コミック・アバター・ストーリーボード・ブランドボード・画像編集ワークフローまでをカバーする。

最大の特徴は3モード分岐を最初に判定するワークフロー設計にある。

エージェントが「どのモードで動くべきか」を最初に明示判定するため、サイレントに誤った実行パスを選ぶ事故が起きにくい。references/配下には18種類の視覚カテゴリ×80以上の構造化プロンプトテンプレートが揃っており、「学術論文の図」「コーポレートのインフォグラフィック」「製品マーケのキービジュアル」といった用途別に当てはめられる。

Mode A実行時はgarden-gpt-image-2/配下にプロンプトと生成画像を保存し、再利用・レビュー・バージョン管理が可能。プロンプトエンジニアリングを「使い捨て」にしない設計だ。

kb-retriever—RAGではなく「段階的検索」でローカル知識ベースを扱う

kb-retrieverはRetrieval / Local Knowledge Baseカテゴリで、ローカルknowledge/ディレクトリ・Markdown・テキスト・PDF・Excelからエージェントコンテキストを膨張させずに証拠を引き出すSkillだ。

最大の特徴はベクトル検索ではなく、階層インデックスをナビゲートする段階的検索を採用している点だ。

grep、pdftotext、pdfplumber、pandasのワークフローと、ソース付きの回答フォーマット手順までSKILL.md内に明文化されている。RAGエンジンのインフラ（ベクトルDB・embedding計算・インデックス作成）が不要なため、社内ナレッジベース・規程集・製品マニュアル・契約書ドキュメントなど数百〜数千ファイル規模のフォルダに対して、初日から動かせる点が実務的だ。

ベクトル検索を組むほどの規模・継続更新がない知識ベースで、「LLMにファイルを丸ごと食わせると毎回トークンが爆発する」問題を回避したいケースでフィットする。

SKILL.mdの構造と仕様—なぜマルチエージェント横断が成り立つか

garden-skillsが全主要ハーネスで動く根拠は、SKILL.mdのフォーマット仕様に厳密準拠している点にある。SKILL.mdは以下の構造を持つ。

<skill-name>/
├── SKILL.md      ← 必須: 起動条件 + 実行手順
├── README.md     ← 人間向けドキュメント
├── references/   ← 任意: エージェントがオンデマンドで読む参照ドキュメント
├── scripts/      ← 任意: 決定論的な実行ヘルパー
└── assets/       ← 任意: テンプレート・フォント・アイコン

エージェントはSKILL.mdのフロントマター（YAML）のdescription行を見て「このスキルを今のタスクに起動すべきか」を判定する。descriptionがエージェントとSkill作者の契約になっており、ここがあいまいだと意図しないタイミングで起動したり、必要なときに起動しなかったりする。

---
name: web-design-engineer
description: |
  Build high-quality visual Web artifacts using HTML/CSS/JavaScript/React —
  web pages, landing pages, dashboards, interactive prototypes, ...
  Use this skill whenever the user's request involves a visual, interactive,
  or front-end deliverable, ...
---

garden-skillsの各SKILL.mdはdescriptionが具体例リスト＋反例（「Not applicable: pure back-end logic, CLI tools」）まで明示する厚みを持つ。これがマルチエージェント横断時に起動精度を担保する設計だ。

仕様の正式版はagentskills.ioとAnthropic公式のanthropics/skillsリファレンスリポジトリで定義されている。

5つのインストール方法と用途別の選び方

garden-skillsは5通りのインストール方法を用意している。それぞれの用途と特徴を整理する。

Option A: npx skillsが事実上の標準

npx skillsはSkillsのエコシステム標準CLIで、エージェントを自動判別して適切なディレクトリにSkillを配置する。最短ルートは以下だ。

# 4スキル全部（最新）
npx skills add ConardLi/garden-skills

# 1スキルだけ
npx skills add ConardLi/garden-skills -s web-design-engineer

# グローバル（~/.skills）にインストール
npx skills add ConardLi/garden-skills -s gpt-image-2 --global

# エージェント指定
npx skills add ConardLi/garden-skills -s kb-retriever -a claude-code

CIや本番運用ではtagスコープURLでピンする。

npx skills add ConardLi/garden-skills/tree/web-design-engineer-v1.0.0/skills/web-design-engineer

Option B: Claude Codeプラグインマーケットプレース

Claude Code利用者はプラグインマーケットプレース経由で、複数Skillをまとめたプラグインパックを購読できる。

/plugin marketplace add ConardLi/garden-skills
/plugin install presentation-skills@garden-skills
/plugin install web-design-skills@garden-skills
/plugin install knowledge-base-skills@garden-skills
/plugin install image-generation-skills@garden-skills

プラグインパックは.claude-plugin/marketplace.jsonで宣言されており、1スキル1パックの構成だ。Claude Code側で更新通知・有効化管理ができる利点がある。

Option C: SHA-256検証付き.zipが本番運用の正解

GitHub Releasesには不変の.zipと.sha256が対で公開される。CI・Dockerfile・エアギャップインストーラーで「バイト単位で固定したい」ケースは必ずこちらを使う。

SKILL=web-design-engineer
VERSION=1.0.0

curl -fsSL -o "${SKILL}.zip" \
  "https://github.com/ConardLi/garden-skills/releases/download/${SKILL}-v${VERSION}/${SKILL}-${VERSION}.zip"

curl -fsSL -o "${SKILL}.zip.sha256" \
  "https://github.com/ConardLi/garden-skills/releases/download/${SKILL}-v${VERSION}/${SKILL}-${VERSION}.zip.sha256"
shasum -a 256 -c "${SKILL}.zip.sha256"

unzip -q "${SKILL}.zip" -d .claude/skills/

「always-latest」のフローティングURLも用意されているが、本番ではタグ固定を強く推奨する。

対応エージェントマトリクス—どこに置けば動くか

garden-skillsが想定している配置先を整理する。

「SKILL.mdフォーマットがポータブル」というのが基本思想だ。エージェントがSkillsをサポートしているなら、スキャンする配置先にフォルダをコピーすれば動く。対応マトリクスはPR受け入れ可能で、新規ハーネス（Kiro・Windsurf等）への拡張が継続している。

garden-skillsのアーキテクチャ概観

garden-skillsがどのように4スキルを並列管理し、配布まで自動化しているかを図示する。

スキル本体・リリース自動化スクリプト・プラグインマーケットプレース定義の3経路が、5つの配布チャネルに分岐していく構造になっている。README中のダウンロードリンクはscripts/release/update-readme.mjsが自動書き換えするため、常に最新タグに連動する。

導入時の注意点と運用上の落とし穴

garden-skillsを導入する際に踏みやすいポイントを整理する。

1. SKILL.mdのdescriptionが長く、起動条件を正確に読む必要がある

各SKILL.mdのdescriptionは具体例・反例・「Not applicable」リストまで含み、数十行に及ぶ。これは起動精度のための設計だが、エージェントが自プロジェクトの文脈で本当に起動すべきかを判断するには、descriptionを一度通読しておくことが重要だ。「webデザイン」と聞いてweb-design-engineerが常に起動するわけではなく、「ピュアロジック・CLIツール・データ処理スクリプト」は明示的に対象外になっている。

2. gpt-image-2のモード判定をスキップしない

Mode判定をスキップして「動くと思ったら動かない」事故が起きやすい。OPENAI_API_KEYがあればMode A、ホスト側に画像ツールがあればMode B、何もなければMode Cというフローを最初に明示判定するルールを必ず守ること。

3. kb-retrieverは「事前準備」が前提

knowledge/配下にdata_structure.md形式の階層インデックスを置いていないと、kb-retrieverの段階的検索が機能しない。導入前にナレッジベースの整備が必要で、これは「RAGエンジン不要」のトレードオフでもある。

4. プラグインパックの.zipサイズに注意

web-video-presentationはVite + React + TypeScriptのプロジェクト雛形を含むため、.zipサイズが他スキルより大きい。Dockerfileで複数スキルを一気に展開する場合、レイヤーサイズに影響することがある。

5. Skill同士のオーケストレーションは未組み込み

garden-skillsは4スキルが並列で配布され、Addy Osmaniのagent-skillsのような「メタスキル（using-agent-skills）でルーター」「SDLCフェーズで横断結合」といったオーケストレーション層は持たない。複数スキルをワークフロー化したい場合は、自プロジェクトのAGENTS.md/CLAUDE.md側でルーティングを書く必要がある。

まとめと使い方の勘所

garden-skillsは「Skillsの本番運用」を1リポジトリで実演する参考実装として価値が高い。個別バージョン管理・SHA-256検証付き.zip・プラグインマーケットプレース・5通りの配布チャネル・マルチエージェント対応マトリクス——どれも自社向けSKILL.mdカタログを作る際に直面する課題への具体回答が揃っている。

4スキル単体の即戦力としては以下の判断軸が使いやすい。

Skills全般の運用設計は Claude Code Skills徹底解説 を、Skillsカタログ各社の比較観点は Addy Osmani agent-skills徹底解剖 と Prismatic Skills徹底解説 を参照してほしい。

参照ソース

• ConardLi/garden-skills（公式リポジトリ）
• garden-skills README（4スキル詳細・インストール5方式・対応マトリクス）
• agentskills.io（SKILL.md公式仕様）
• anthropics/skills（Anthropic公式リファレンス）
• npm skills CLI（npx skills add）

1. Archifyとは：自然言語からプロ品質の技術図を生成するClaude Skill

Archifyは、自然言語で書かれた構成説明から「アーキテクチャ図」「ワークフロー図」「シーケンス図」「データフロー図」「ライフサイクル図」の5種類を単一HTMLとして生成するClaude Skillだ。GitHubで213スターを集めるMITライセンスのOSSで、リポジトリはtt-a1i/archifyに置かれている。

Skillsの仕組みを利用しているため、ユーザーは図を描く専門知識を一切必要としない。「Reactフロントエンド、Node.js API、PostgreSQL、Redisキャッシュ、AWSでホスト」と書いてClaudeに渡すだけで、配色・配置・ラベル付き・凡例付きの図がそのまま出てくる。

公開元のtt-a1i氏はCocoon AI社が公開した「architecture-diagram-generator v1.0」をfork rewriteする形で開発を進めており、本記事執筆時点（2026年5月）の最新版はv2.4だ。Skillの拡張子はzip、配布はarchify.zip単一ファイルで完結する。

1.1 Claude Skillとは何か

Claude Skillは、Anthropicが2025年末に公開したClaude.aiおよびClaude Codeの拡張メカニズムだ。SKILL.mdを中心とするフォルダ構成のzipファイルとして配布され、Claudeのコンテキストに「特定用途のお作法と参照可能なリソース」を注入できる。

Settings → Capabilities → Skillsから+ Addでアップロードすればすぐ使えるようになる。Claude Code側ではCLIで~/.claude/skills/配下に展開するだけで認識される。

ArchifyのSKILL.mdにはClaudeへの指示として「class化・テーマ化されたSVGの組み立て方」「セマンティック配色のルール」「5種類の図の使い分け方」が記述されており、Claudeはこれをガイドラインとして読み込んだ上で図を生成する。

1.2 リポジトリの規模感と来歴

ArchifyはCocoon AI社のarchitecture-diagram-generator v1.0をベースにしている。元版は「深色テーマのHTML出力のみ」というシンプルな実装だったが、Archifyはこれを大幅に拡張した。

v2.0でCSS変数化と浅色テーマ追加、v2.1で剪贴板コピー・キーボードナビゲーション、v2.2で印刷スタイル・ローカルフォントフォールバック、v2.3で4×原生光栅化、v2.4でSVG双主題自持を実装した。バージョンごとの追加機能はREADMEの「版本演进」セクションに表形式でまとめられている。

2. なぜClaude Skillとして配布するのか：3つの構造的優位

Archifyが他のダイアグラム生成ツールと根本的に違うのは、配布形態にClaude Skillを選んだ点だ。これには3つの構造的優位がある。

2.1 「Claudeに描かせる」設計思想

従来のダイアグラム生成OSS（Mermaid・PlantUML・diagrams.netなど）は「ユーザーが構文を覚えて書く」前提だ。これに対しArchifyは「ユーザーは自然言語で説明、Claudeが配置と配色を判断、最終的にArchifyのテンプレートで仕上げる」という三段構えになっている。

ユーザー: 「React + Node.js + PostgreSQL + Redis + AWSの構成図を archify で」
↓
Claude: 構成要素を抽出し、Archifyのセマンティック配色ルール（Frontend=青、Backend=緑、Database=紫...）
        と配置ヒューリスティクスを適用してSVGを組み立てる
↓
Archify: 単一HTMLにラップし、テーマ切替UIとエクスポートメニューを付与

READMEに「archifyの美学核心はClaudeの布局判断、CSSではない」と明記されているとおり、Skill側はテンプレート提供に徹し、図の質はClaudeの推論能力にレバレッジしている。

2.2 対話で図を直したい欲求への対応

Archifyの最大の使い勝手は、生成後の修正がチャットで完結する点だ。「Redisを左に動かして」「鉴权サービスを玫紅にして」「Kafkaを追加して」と日本語/中国語/英語で言えば、Claudeが該当部分だけを書き直して新しいHTMLを出してくれる。

伝統的なドローツールは「マウスでクリック→ドラッグ→プロパティ変更」の往復になり、複雑な図ほど時間が溶けやすい。Archifyはこの手作業をすべて言葉でやり取りできる。

2.3 ローカル動作・データ越境ゼロ

ArchifyのHTML生成はClaude側で行われるため、Skill本体はテンプレートとSKILL.mdのテキストだけだ。SaaSサービスに登録する必要もなければ、APIキーも必要ない。

Claude Codeを社内ネットワーク経由で動かしている組織なら、Archifyの実行もネットワーク境界の内側で完結する。Mermaid Live Editor・Lucidchart・draw.ioのオンライン版とは違い、機微なシステム構成情報が外部に送信されない。

3. 5種類の図：何をどの図で描くのか

ArchifyのREADMEには「图表类型」セクションがあり、5タイプそれぞれの適用ガイドラインが示されている。

3.1 Workflowは汎用フロー図ではない

READMEに「Workflowは通用流程図の代替品ではない」と明記されている。Archifyの定義するWorkflowは「技術沟通图」で、スイムレーン・セマンティック配色・主路径と異步/承認/観測の経路を持つ。

例えば「Agent計画→承認ゲート→ツール呼出→trace記録」のような、AIエージェントのリクエスト処理を可視化する用途に特化している。一般的な業務フロー（注文受付→在庫確認→出荷指示）には別のツールのほうが向いている場面もある。

3.2 Data Flowとセキュリティ境界

Data Flowタイプの目玉機能はPII境界の可視化だ。READMEのサンプルにある「Consent Gate」のようにデータの匿名化・同意確認・暗号化境界を「ゲート」として明示できる。

データ保護インパクト評価（DPIA）やGDPR/PIPLコンプライアンス資料を作る際、開発者と法務・セキュリティチームの認識を揃えるのに役立つ。「どのコンポーネントを越えるとPIIが含まれるか」を1枚の図で説明できる。

3.3 Lifecycleで状態機を伝える

Lifecycle図は状態機の遷移を表現する。Queued → Planning → Executing → Reviewing → Completedのような主軸に、Needs Approval・Blockedの待機状態、Failed・Cancelled・Expiredの終了状態を含められる。

Agent run・GitHubのPRワークフロー・注文ステータス・デプロイメントパイプライン——状態のあるオブジェクトすべてに適用できる汎用性が魅力だ。

4. アーキテクチャ：Skillとテンプレートの分離設計

ArchifyのアーキテクチャはSkill層・テンプレート層・出力HTML層の3層に分かれている。

4.1 CSS変数によるテーマ設計

ArchifyのHTMLは:rootと[data-theme="light"]の2セットのCSS変数を持つ。<html>要素のdata-theme属性を切り替えるだけで、グラデーション・グリッド・矢印・マスクを含む図全体が一瞬で書き換わる。

SVG内部の要素は固有色を持たず、c-frontend・c-backend・c-database・t-muted・a-emphasisのようなセマンティッククラスを参照している。これによりテーマと配色を切り離せている。

<!-- 簡略化したテーマ切替の仕組み -->
<style>
  :root {
    --c-frontend: #06b6d4;  /* 深色テーマ */
    --c-backend:  #10b981;
    --c-database: #a855f7;
  }
  [data-theme="light"] {
    --c-frontend: #0891b2;  /* 浅色テーマ */
    --c-backend:  #059669;
    --c-database: #9333ea;
  }
  .c-frontend { fill: var(--c-frontend); }
</style>
<script>
  // T キーで切替・localStorage に永続化
  document.documentElement.dataset.theme =
    localStorage.getItem('theme') ?? 'dark'
</script>

4.2 エクスポートパイプラインの仕組み

PNG/JPEG/WebP/SVGのエクスポートは、すべてブラウザ内で完結する。READMEの「实现细节」セクションに動作原理が記述されている。

1. SVGをDOMからクローン
2. ホストの<style>を解析し、現在のテーマ変数の解決値をクローンの:rootに書き込む
3. XMLSerializerでクローンをシリアライズ
4. 光栅出力の場合は、クローンのwidth/heightをviewBoxの4倍に設定
5. Image要素として読み込み、canvasに自然サイズで描画
6. canvas.toBlob(mime)でファイル化

このプロセスがブラウザのキャンバスAPIで完結するため、サーバーへの送信もファイルアップロードも不要だ。JPEGの場合は透過アルファがないため、背景色をテーマから明示的に充填する。

4.3 単一ファイル配布の制約と利点

SKILL.mdの指示でClaudeはテンプレートを参照したSVGを構築する。出力されるのは1つのHTMLファイルで、依存リソースはGoogle Fontsへの<link>1本のみだ。

ファイル1つで完結するため、Confluence・Notion・GitHub Pages・Cloudflare Pages・社内Wikiのどこにでも貼れる。代わりに「JSONなどのソースが残らない」「差分マージできない」というデメリットもある。

5. 4×原生光栅化：なぜ画像がジャギーにならないのか

v2.3で実装された「4×原生光栅化」は、Archifyを他のSVG to PNG変換ツールと差別化する重要機能だ。

5.1 アップサンプリングと原生光栅化の違い

＜悪い例＞ 一般的なSVG to PNG変換は、まず自然サイズでビットマップを生成し、それを2倍/4倍に拡大表示する。これは「アップサンプリング」と呼ばれ、輪郭が補間で滑らかに見えるものの本質的には低解像度の画像を引き伸ばしているだけだ。

＜改善例＞ Archifyの4×原生光栅化は、SVGのviewBoxを4倍にしてからキャンバスに描画する。これにより、ベクター情報からネイティブ4倍解像度のビットマップが直接生成される。レチナディスプレイ・4Kモニタ・印刷出力の全環境でくっきり見える。

5.2 Canvas上限への自動降格

ブラウザのCanvasには最大サイズの上限がある（多くのブラウザで4096×4096または8192×8192）。Archifyの4×光栅化が上限を超える場合は、自動的に3×・2×へ降格する安全装置が実装されている。

これにより「巨大な図でエクスポートが失敗する」事象を回避し、ユーザーは常に最も高解像度のPNGを手にできる。倍率セレクターを意図的に省いた設計だ（v2.3で削除された）。

5.3 剪贴板コピーも4×

「Copy to clipboard」操作も同じパイプラインを通る。Slackや飛書・Notion・Figmaにペーストした際の画質が劣化しない。

// 剪贴板コピーの大筋（簡略化）
const blob = await canvas.toBlob('image/png')
await navigator.clipboard.write([new ClipboardItem({ 'image/png': blob })])

ClipboardItemとnavigator.clipboard.writeが必要なため、Chromium・Firefox 127+・Safari 16+でのみ動作する。サポート外のブラウザでは該当メニュー項目がグレーアウトされる。

6. SVG双主題自持：GitHub READMEに貼るだけで完成

v2.4で実装された「SVG双主題自持」はArchifyの目玉機能だ。

6.1 @media (prefers-color-scheme)の活用

ArchifyのSVG出力には、深色用と浅色用の2セットのCSS変数が内包される。@media (prefers-color-scheme)ルールで、読者のシステム設定に応じて自動的に切り替わる。

<!-- 出力SVGの内部構造（簡略化） -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 800">
  <defs>
    <style>
      :root {
        --c-frontend: #06b6d4;
        --c-backend: #10b981;
      }
      @media (prefers-color-scheme: light) {
        :root {
          --c-frontend: #0891b2;
          --c-backend: #059669;
        }
      }
      .c-frontend { fill: var(--c-frontend); }
    </style>
  </defs>
  <!-- SVG本体 -->
</svg>

6.2 従来の「2枚PNG + <picture>」運用が不要に

GitHub READMEでダーク/ライト両対応の図を出すには、これまで以下のような<picture>タグが必要だった。

<picture>
  <source media="(prefers-color-scheme: dark)"  srcset="diagram-dark.png">
  <source media="(prefers-color-scheme: light)" srcset="diagram-light.png">
  <img alt="diagram" src="diagram-light.png">
</picture>

これだとPNG2枚を別々に生成・管理する必要があり、更新時に「片方だけ古い」事故が起こりやすい。Archify v2.4のSVGなら1枚貼るだけで両対応する。

![diagram](diagram.svg)

これだけで完結する。GitHubでREADME.mdにSVGを貼ると、ダークモードのユーザーには深色版、ライトモードのユーザーには浅色版が自動表示される。

6.3 BlogでもConfluenceでも同じ仕組みが効く

@media (prefers-color-scheme)はSVGをHTMLにインライン埋め込みした場合だけでなく、<img>参照した場合でも有効だ。ZennやNoteのブログ、Confluenceの社内Wiki、Notionのドキュメントでも同じ自動切替が動作する。

ただしConfluenceなど一部のCMSはSVGのインラインスタイル属性のみを許可し、@mediaを伴う<style>タグを除去するケースがある。その場合は素直にPNGをエクスポートしてアップロードする。

7. 他ツールとの比較：何を選ぶべきか

技術系の図生成ツールは増え続けているが、Archifyの立ち位置は他とはっきり違う。

7.1 Mermaidとの使い分け

Mermaidは構文を覚えればテキストだけで再現可能で、Git管理にも向く。一方Archifyは「自然言語＋Claudeの判断」で図の美しさを稼ぐ。

技術ブログのフロー図を量産したいならMermaidが速い。プレゼン資料・営業資料・READMEのヒーロー画像といった「見た目で勝負したい」用途ならArchifyが圧勝だ。両方を並行して使う運用も現実的だろう。

7.2 diagrams.netとの使い分け

diagrams.netは無料の汎用ドローツールで、AWS/Azure/GCPアイコンライブラリも充実している。ただし「マウスでクリック→配置」の手間がかかる。

Archifyは「手作業ゼロでそこそこの構成図が出る」のが強みで、図のためにマウス操作したくない開発者・PMに刺さる。ピクセル単位の調整が必要な場面ではdiagrams.netに軍配が上がる。

7.3 Lucidchart/Lucid AIとの使い分け

Lucidchartは企業向けの統合ダイアグラム製品で、Lucid AIで自然言語からの生成にも対応する。一方で月額課金が前提で、データはLucid社のクラウドに送信される。

Archifyは完全ローカル動作・無料・データ越境ゼロという3点で、規制業種・自社ホスト前提の組織にとって魅力的な代替手段になる。

8. インストールから最初の図まで

ArchifyのSetupは3パターンある。READMEの「快速上手」セクションに手順がある。

8.1 Claude.aiでの導入

Claude.aiユーザーは、ブラウザでArchifyをインストールできる。

1. リポジトリからarchify.zipをダウンロード
2. Claude.aiのSettings → Capabilities → Skillsを開く
3. + Addを押してzipをアップロード
4. トグルをONにする

これでClaudeとの全チャットでArchifyが使えるようになる。Claude Pro/Max/Team/Enterpriseのいずれかが必要だ。

8.2 Claude Code CLIでの導入

Claude Code利用者は、CLIから一発で導入できる。

# グローバル（全プロジェクトで使える）
unzip archify.zip -d ~/.claude/skills/

# あるいは特定プロジェクトのみ
unzip archify.zip -d ./.claude/skills/

~/.claude/skills/archify/が展開されればOKだ。Claude CodeセッションでArchifyのSKILLが自動的に読み込まれる。

8.3 Claude.ai Projectsでの導入

archify.zipをProject Knowledgeにアップロードする方法もある。特定プロジェクトの中だけでArchifyを使いたい場合に便利だ。

8.4 最初のプロンプト

導入が済んだら、自然言語で構成を伝えれば図が出てくる。

archify skill で次の構成のアーキテクチャ図を描いて：
- React フロントエンド
- Node.js / Express API
- PostgreSQL データベース
- Redis キャッシュ
- JWT 鉴权

Claudeがこれを受けてHTMLを生成する。ブラウザで開けばTでテーマ切替、EでExportメニューが開く。

8.5 反復改善のサンプル

生成後の改善は対話で行う。

左のReactを2つに分けて、Web版とiOS/Android版にして

PostgreSQL を MySQL に変更して、Redis を ElastiCache 表記にして

鉴权のパスを玫红色で強調して、データベース呼び出しのパスは紫の点線で

このように細かい修正を言葉で重ねていける。完全に納得した状態でPNG/SVGをエクスポートすれば、ドキュメントや資料への組み込みが完了する。

9. 運用パターン：実プロジェクトでの活用例

Archifyの実際の使い所を3つ紹介する。

9.1 OSS READMEのヒーロー画像

GitHub READMEのトップに「サービスの全体像」を1枚絵で置くのは効果的だ。Archifyのv2.4 SVG出力なら、READMEに1枚貼るだけでダーク/ライト両対応になる。

# my-awesome-service

<p align="center">
  <img src="docs/architecture.svg" width="800" alt="architecture">
</p>

## What is this?

...

スターを稼ぎやすいOSSは「ヒーロー画像」と「機能GIF」が充実している。Archifyを使えばこれが片手間で作れるようになる。

9.2 RFC/設計レビュードキュメント

社内設計レビューやRFC文書では「現状アーキテクチャ」「提案後アーキテクチャ」を並べて比較する場面が多い。

archify で 2 枚描いて：
1. 現状: モノリス Web アプリ + 単一 PostgreSQL
2. 提案: 4 つのマイクロサービスに分割 + イベントバス + 専用 DB

提案が承認されたあとに採用版を「正本」として保存しておけば、新人オンボーディング資料にもそのまま流用できる。

9.3 障害事後分析（Postmortem）

障害が起きた直後、Slackや専用チャンネルで「何が起きたか」を伝えるには時系列順のシーケンス図が効果的だ。Archifyのsequenceタイプを使えば数分で完成する。

archify で sequence 描いて：
14:23 ユーザーがログイン
14:24 API Gateway がレート制限を超過
14:25 リトライ嵐が発生
14:27 Redis のメモリ使用率が95%を超過
14:28 認証セッションが書き込めずログインエラー多発

ポストモーテム会議で参加者全員の認識を揃えるのに役立つ。

10. ロードマップと制約

Archifyのv3.0計画はROADMAP.mdに記述されている。

10.1 v3.0：JSON IRの導入

v3.0ではdiagram.jsonという中間表現（IR）の導入が予定されている。これにより：

• Claudeが局所的に座標を修正しても無関係なコンポーネントが動かない
• git diffで図の変更が見やすくなる
• 同じIRから複数テーマで再レンダリングできる

現状のArchifyは「HTML出力＝最終形」だったため、差分管理が難しいという課題があった。v3.0はこの構造的制約への回答だ。

10.2 削除された機能（Not planned）

READMEには「Mermaid自動解析路線は実験の結果削除した」と明記されている。理由は「Mermaidをパースして自動レイアウトしても、結局オリジナルのMermaidよりわずかに見栄えがよくなる程度で、Archifyの美学（Claudeの布局判断）と整合しなかった」とのことだ。

?exportScale=Nのような倍率パラメータ・色盲対応パレット・共有リンクといった機能もROADMAPから削除された。「機能数を増やすこと」より「中核体験の磨き込み」を優先する開発姿勢が伝わる。

10.3 ブラウザ要件

10.4 セキュリティと配布の透明性

ArchifyはCocoon-AI v1.0からのfork rewriteだ。READMEに「視覚デザインの功労は原作者に帰属」「両プロジェクトともMITライセンス」と明記されており、来歴の透明性が高い。

社内導入時のライセンス審査では「MIT・依存はGoogle Fonts経由のJetBrains Monoのみ・SKILL.mdは平文で読める」と説明できれば、多くの組織で承認が下りやすい。

まとめ

Archifyは「描けない人でも図が描ける」を本気で実現したClaude Skillだ。配布の手軽さ・出力の美しさ・対話で直せる体験が、技術ドキュメントの作成コストを根本的に下げる。Claude Codeを日常的に使うエンジニアにとって、入れておいて損はないSkillだ。

Claude Skillの設計思想全体については Claude Skillsとは何か：Anthropic公式が公開した拡張メカニズムを徹底解説 を、Claude Skillの作り方の哲学については Matt Pocock氏が語る「現役エンジニアのためのClaude Skills設計哲学」 を併せて読んでほしい。

参照ソース

• tt-a1i/archify — GitHub
• Cocoon-AI/architecture-diagram-generator — GitHub
• Anthropic公式 — Using Skills in Claude

ローカルLLM全般の選び方とOllama／LM Studio／GPT4Allの比較は ローカルLLMとは？2026年版ツール比較——Ollama・Lemonade・LM Studio・GPT4Allの選び方 をご覧ください。

1. 何が起きたのか：Ollama 0.24でCodex統合が完成

Ollama 0.24は『Codexをローカルで動かす』というユーザー要望に対する公式回答だ。2026年1月15日のOllama公式ブログ「OpenAI Codex with Ollama」で ollama launch codex が初登場し、5月14日のv0.24.0でデスクトップ版Codex Appを起動する ollama launch codex-app まで追加された。これでCLI・デスクトップの両系統が ollama launch … ファミリーに揃った形になる。

技術的に何が新しいかというと、実はOllama自体は以前から http://localhost:11434/v1 でOpenAI互換APIを提供していた。だからCodex CLI側の --oss フラグや OPENAI_BASE_URL 環境変数を手動で設定すれば、技術的にはローカル接続できていた。今回の変更は「セットアップの摩擦を消す」レイヤーで、具体的には次の作業を ollama launch codex が肩代わりする。

1. Codex CLIがインストールされているかチェック（なければ案内）
2. Ollama側で推奨モデル（デフォルトはgpt-oss:20b）が落ちているかチェックし、なければpull
3. Codex CLIの ~/.codex/config.toml に model_providers.ollama-launch と profiles.ollama-launch を自動追記
4. コンテキスト窓を64k以上に設定（gpt-ossは128kまで対応）
5. プロファイル --profile ollama-launch 指定でcodexプロセスを起動

これまで「ローカル開発でCodexを使いたい」と思った人が30分かけてやっていた作業が、コマンド1発に圧縮された。ollama launch ファミリーはClaude Code・Codex・Droid・OpenCodeなど主要エージェントCLIをカバーする方向で広がっていて、Ollamaが「ローカルLLMコーディングのハブ」を狙っているのが見える。

2. OpenAI Codex CLIとは何か：ターミナルで動くOpenAI公式エージェント

ローカル化の前提として、OpenAI Codex CLI 自体を簡単におさらいしておく。@openai/codex パッケージとしてnpm（Homebrewも可）で配布されている、Rust実装・Apache-2.0ライセンスの公式コーディングエージェントだ。2026年5月時点で 0.130.0 系が安定版で、レポジトリ説明には “Codex CLI is a coding agent from OpenAI that runs locally on your computer.” と明記されている。

Codex CLIの位置づけは「ターミナルで動くChatGPT Codex」に近い。ファイル読み書き、シェル実行、Gitオペレーション、ブラウザ確認といったツールを呼びながら、コードベースに対して自律的にタスクを進める。Claude Codeに対するOpenAI側のカウンターパートで、設計思想も近い：エディタ非依存、ターミナル中心、エージェントループ前提。

認証方式は3系統ある：

• ChatGPT契約でのサインイン：Plus／Pro／Business／Edu／Enterpriseユーザーは codex 起動時に「Sign in with ChatGPT」でログイン可能。クォータはChatGPT側のメッセージ枠を消費
• OpenAI APIキー：OPENAI_API_KEY を環境変数に入れる従来方式。トークン課金
• OSSモード（今回の本題）：codex --oss または --profile <ollama-profile> でローカル／OSSプロバイダ接続。課金なし、レート制限なし

--oss の存在自体は2026年1月のOllama公式ブログ「OpenAI Codex with Ollama」で公式機能化され、Codex CLI側にもサポートが入った。Codex公式ドキュメントにも --oss と -m gpt-oss:20b の例が掲載されている。

3. アーキテクチャ：Codex CLIとOllamaの接続レイヤー

実体としては、Codex CLIがHTTPクライアント、OllamaがOpenAI互換のHTTPサーバとして動く構成だ。Codex CLIはOpenAI API互換のリクエスト（/v1/chat/completions 風のエンドポイント）を http://localhost:11434/v1 に投げ、Ollamaがそれを自分のローカルモデル（gpt-oss:20bなど）にルーティングしてストリーミングレスポンスを返す。

この構造のキモは、Codex CLI側はOllamaを「ただのOpenAIサーバ」として扱っていること。Codex CLIから見ると api.openai.com と localhost:11434 の区別はベースURLの違いでしかなく、エージェントループ・ツール実行・コンテキスト管理は完全に同一のコードパスで走る。クラウドCodexで磨かれたエージェント実装の利得が、そのままローカルでも享受できる設計だ。

注意点は2つ。1つ目はコンテキスト窓の要件で、Codexは1ターンあたりエージェントの思考・ツール出力・差分パッチを大量に積むので、64k以上のコンテキスト窓を持つモデル必須。gpt-oss:20b／120b、Qwen3 Coder、GLM-5.1、Kimi K2.6あたりが候補になる。2つ目はツール呼出（function calling）への対応で、OllamaのTools APIに乗っているモデルでないとCodexのエージェントループが破綻する。ollama show <model> で Tools: yes を確認するのが安全だ。

ローカルLLMの推論バックエンド自体に関しては、Ollama単体だけでなく Distributed Llama のような分散推論や vLLM の本番向け実装も併用が効く。Codex CLIから見るとどれも「OpenAI互換APIを話すサーバ」なので、リソースが余っているマシンを束ねるなら分散推論側を選ぶ手もある。

4. セットアップ：5分で動かす最短手順

最短手順は「Ollama 0.24以上を入れる→Codex CLIを入れる→ollama launch codex を打つ」の3段階だ。それぞれ詳しく見ていく。

4.1 Ollama 0.24.0以上をインストール

macOS／Linux／Windows公式バイナリが用意されている。Macなら brew install ollama でも入る。

# 公式インストーラ（macOS / Linux）
curl -fsSL https://ollama.com/install.sh | sh

# バージョン確認（0.24.0以上であること）
ollama --version
# => ollama version is 0.24.0

# Ollamaサーバが動いていることを確認
ollama serve &
curl -s http://localhost:11434/api/tags | head -c 200

ollama launch サブコマンドが認識されない場合はバージョンが古い。ollama update または再インストールでv0.24.0以上にする。Brewユーザーは brew upgrade ollama だ。

4.2 OpenAI Codex CLIをインストール

Codex CLIはNode.jsで配布されている。Node 18以上が必要。

# npm経由（推奨）
npm install -g @openai/codex

# Homebrew（macOS）
brew install --cask openai-codex-cli

# バージョン確認（0.130.0以上が望ましい）
codex --version

Homebrewの場合は管理者権限不要で ~/.codex/ 配下に設定が置かれる。Windowsの場合はScoopまたは公式インストーラを使う。codex --version が通れば準備完了だ。

4.3 ollama launch codexで起動

ここからが本題。1コマンドでCodex CLIがgpt-oss:20bバックエンドで立ち上がる。

# デフォルト構成で起動（gpt-oss:20b、64kコンテキスト）
ollama launch codex

# 初回はモデル自動pullが走る（gpt-oss:20bで約13GB）
# pull完了後、Codex CLIが対話モードで起動する

ollama launch codex の実行で何が起きているかを順番に追うと：

1. ~/.codex/config.toml がなければ作成し、ollama-launchプロファイルを追記
2. gpt-oss:20b が未取得なら ollama pull gpt-oss:20b を内部実行
3. Ollamaサーバが起動していなければバックグラウンドで起動
4. codex --profile ollama-launch 相当のコマンドでCodex CLIを起動

起動後はChatGPT版Codexと同じUI／キーバインドで対話できる。差分はモデルが手元のマシンで動いていることだけだ。ファイル編集・シェル実行・Git操作などツール呼出も同じように使えるので、--oss 環境下でも素のエージェント体験が損なわれない。

4.4 別モデルへの切替：gpt-oss:120bやCloud版

ハイエンドMacや96GB以上のメモリを積んだLinuxマシンなら、120Bモデルが現実的に動く。

# gpt-oss:120b（ローカル実行、約65GB必要）
ollama launch codex --model gpt-oss:120b

# gpt-oss:120b-cloud（Ollama Cloud経由、課金あり）
ollama launch codex --model gpt-oss:120b-cloud

# 既存セッションを復元
ollama launch codex --restore

--model フラグは ollama launch codex 系の共通オプション。Cloud版は手元のリソースを使わず、Ollama側のクラウド推論を使う構成で、課金は発生するがレート制限はOpenAI APIより緩やか。「とりあえず120Bを試してから判断したい」フェーズで便利だ。

5. config.tomlで複数モデルをプロファイル管理する

実運用では「軽い修正は20B、重い設計レビューは120Bクラウド、本番デプロイ直前のレビューはGPT-5公式」のようにモデルを使い分けたい。Codex CLIはこれを プロファイル という形でサポートしている。

~/.codex/config.toml の構造はこうなる：

# Ollama接続定義（base_urlが11434なのがポイント）
[model_providers.ollama-launch]
name = "Ollama"
base_url = "http://localhost:11434/v1"

# プロファイル1: ローカル20B（普段使い）
[profiles.ollama-launch]
model = "gpt-oss:20b"
model_provider = "ollama-launch"

# プロファイル2: ローカル120B（M4 Max級限定）
[profiles.ollama-120b]
model = "gpt-oss:120b"
model_provider = "ollama-launch"

# プロファイル3: クラウド120B（外部送信OKな案件）
[profiles.ollama-cloud]
model = "gpt-oss:120b-cloud"
model_provider = "ollama-launch"

# プロファイル4: OpenAI公式（最終チェック用）
[profiles.openai]
model = "gpt-5"

切替は単純で、codex --profile <名前> を打つだけ。

# 軽量タスク
codex --profile ollama-launch "READMEの誤字を直して"

# 重い設計レビュー（ローカル120B）
codex --profile ollama-120b "src/payments/配下のリファクタ案を出して"

# 最終確認（OpenAI公式）
codex --profile openai "リリース前にこのPRを最終レビューして"

プロファイル運用の最大の利点は「コスト構造を意識しなくてよくなる」点だ。普段は0円のローカル20Bで叩き、本当に必要な場面だけクラウドに切り替えれば、月額のAPI課金が劇的に減る。Codex CLI公式のヘビーユーザーがChatGPT Pro契約で月数千円〜数万円使う中、ローカル比率を上げれば実質コストを1/10以下にできる。

6. 対応モデルの選び方：gpt-ossを中心にした使い分け

Ollama公式ブログがCodex向けに明示しているのは gpt-oss:20b gpt-oss:120b gpt-oss:120b-cloud の3つ。これに加えて、Ollamaライブラリ側にあるツール呼出（function calling）対応モデルなら、config.toml で指定するだけで動く。

主要候補の比較を以下にまとめる。

「Codexスコア感」は筆者が同一プロンプト（軽量リファクタ＋PR作成タスク）で試した主観評価で、ベンチマーク値ではない点に注意してほしい。結論としてはgpt-oss:20b／120bが「Codex特化チューン済み」感が一番強い。これはgpt-ossが2025年にOpenAI自身がオープン化したシリーズで、Codex CLIのプロンプト前提に最も自然に噛み合うためだ。

コード特化を狙うなら Qwen3 Coder 30B が強力で、長尺リファクタや既存コード読解で20Bよりよい結果が出ることもある。Kimi K2.6 は1Tパラメータ級のMoEで、エージェント協調タスクで頭一つ抜けるが、ローカル実行は事実上不可能なのでクラウド経由になる（Kimi K2.6エージェントスワーム解説）。Gemma3 8B はコンテキストは128kあるが、エージェントループの自己修正能力が低くCodex用途には不向きだ。

7. Codex App（デスクトップ版）も同時に進化した

ollama launch codex-app で起動するのが、OpenAI公式のCodex App（デスクトップ版）。CLIとは別系統のGUI体験で、v0.24.0のメイン目玉だ。

Codex Appの主な機能：

• 組み込みブラウザ：開発中のローカルサーバ（http://localhost:3000 など）をApp内のブラウザで直接開ける。表示されたページを直接クリック・注釈してCodexに修正指示が出せる。Figmaのコメント機能をコードレビューに持ち込んだような体験
• レビューモード：差分を見ながらCodexにコメント形式でフィードバックを返せる。「ここはもう少しシンプルに」「このloopは並列化して」など、IDEから出ずに修正サイクルが回る
• Worktree統合：複数のCodexスレッドを並列に走らせ、git worktreeで作業ディレクトリを分離。1つのリポで「PRレビュー」「新機能実装」「バグ修正」を同時並行できる
• Git連携：コミット作成、ブランチ切替、PR作成までApp内で完結
• –restore で復元：前回のセッション（開いていたスレッド、選択モデルなど）をそのまま戻せる

# Codex Appをローカルバックエンドで起動
ollama launch codex-app

# 前回セッションを復元
ollama launch codex-app --restore

注意したいのは、Codex AppのバックエンドはCLIと同じくOpenAI互換API経由なので、ollamaで起動した時点で全推論がローカルLLMに切り替わる。クラウドCodex Appと同じUIなのにモデルがgpt-ossで動いている状態だ。デザイン上は『SwitchをOFFにする』みたいに見えるが、内部的にはbase URLとモデル名の差し替えだけが起きている。

Codex AppはCodex CLIの「上位互換」ではなく「並列の選択肢」と捉えるのがよい。ターミナル中心の開発者（vim／tmux／zsh派）はCLI、ブラウザでのUIプレビューが重要なフロントエンド開発者はAppという棲み分けになる。

8. ローカルCodexのリアルな性能と限界

ローカルLLMで本当に開発作業が回るのか——これは現実的に気になる点だ。筆者の検証環境（M4 Max 64GB、gpt-oss:20b）で同等タスクをChatGPT Codex（gpt-5）とローカルで比較した感触は次の通り。

ローカルgpt-oss:20bが安心して任せられる作業

• 5〜30行程度のバグ修正・型エラー解消
• READMEや日本語ドキュメントの整形・翻訳
• 単体テスト追加（テンプレ的なケース）
• 既存ヘルパー関数のリネーム・移動
• TypeScript／Python／Rust／Goの軽量〜中量リファクタ

ローカル20Bでは厳しく、120Bか公式モデルに切り替えたほうがよい作業

• 数十ファイルを跨ぐ設計変更（依存関係を理解した変更）
• 抽象クラス／DI／ジェネリクスを多用した複雑なリファクタ
• 業務ロジックを推論で補完する系（仕様書から逆算した実装）
• パフォーマンスチューニング（ボトルネックの推定）
• セキュリティ監査的なレビュー

体感では、「diffが30行以内、影響範囲が3ファイル以内」のタスクなら20Bでクラウド並の体験になる。エージェントループは1〜2回で収束し、ツール呼出も安定する。逆に「20ファイル横断のリファクタ」のような大物は20Bだとループが10回以上回ってもまとまらず、結局120Bやクラウドに切り替えることになる。

この『20Bで足りる8割、足りない2割』を切り分けて使うとローカルCodexは本当に強い。すべてをローカルでやろうとすると挫折するし、すべてをクラウドでやると課金が膨らむ。プロファイル切り替えで境界を意識しながら使うのがリアルな運用感だ。

9. クラウドCodexとローカルCodexの本質的な違い

ローカル化は単なる「同じものをタダで」ではない。実はできることの内訳が変わる。整理しておく。

特筆すべきは右下の 「エージェント反復を気にせず叩ける」。Codex CLIのようなエージェント系は、1タスクあたり10〜50回モデルを呼ぶことが普通で、クラウド経由だと「これでお金溶けるかな」というメンタルコストが地味に効く。ローカルなら無限に叩けるので、たとえば「今のPRを5パターンの観点でレビューさせて、それぞれの修正案を競争させる」みたいな贅沢な使い方が成立する。

逆にデメリットは2つ。1つ目はモデル品質の差で、コード理解の絶対値ではgpt-5に勝てない。2つ目はコンテキスト窓の差で、100万トークン超のリポジトリをまるごと食わせるような芸当はローカルでは無理だ。「速度・課金・プライバシー」を取るか、「品質・コンテキスト・最新性」を取るかのトレードオフになる。

10. つまずきやすい点とトラブルシュート

実際に立ち上げる時に詰まりやすいポイントを並べておく。

10.1 「Tools: no」のモデルを選んでしまう

ツール呼出非対応のモデルを選ぶとCodexが起動直後にループする。ollama show <model> で Tools: yes を必ず確認する。

ollama show gpt-oss:20b | grep -i tools
# => Tools: yes  ← OK

10.2 コンテキスト窓不足

Codexはエージェントループでツール出力をどんどん積むため、64k未満ではすぐ詰まる。ollama show の context length を確認し、必要ならパラメータでオーバーライドする。

ollama show gpt-oss:20b
# context length: 131072  ← 128k OK

10.3 GPUメモリ不足で20Bが激重

ollama ps でモデルがCPU側にスピルアウトしていないか確認する。スピルすると体感速度が10〜30倍遅くなる。

ollama ps
# NAME           SIZE      PROCESSOR    UNTIL
# gpt-oss:20b    13 GB     100% GPU     ← OK
# gpt-oss:20b    13 GB     50%/50% CPU/GPU  ← NG（メモリ不足）

10.4 codex –profile が認識されない

Codex CLIのバージョンが古いと --profile フラグが効かない。codex --version で確認し、0.100系以上に上げる。

10.5 base_urlにhttp://が抜ける

config.tomlの base_url は スキーマ込みでフルURL。localhost:11434/v1 ではなく http://localhost:11434/v1 と書く必要がある。これは何度も踏まれる罠だ。

11. これからのローカルコーディングエージェント

ローカルLLMでコーディングエージェントを回す——という選択肢は、2025年までは「ハッカーの趣味」だった。Ollama 0.24はこれを 「ふつうの開発者の選択肢」 に押し上げる更新で、特に次の3点が大きい。

1. 公式コマンド化：ollama launch <agent> という形で、OpenAI Codex／Claude Code／Droidなど主要CLIをワンコマンドで起動できる動線が整った
2. モデル品質の追いつき：gpt-oss:20b／120bがCodex前提のチューンに耐える品質に達したことで、「クラウドの劣化版」ではなく「役割の違う選択肢」として成立する
3. エージェント反復の経済性：課金心配なくループを回せることで、エージェントの強みである「試行錯誤の量」を最大化できる

OpenAI／Anthropic／Googleの主要モデルは引き続き品質トップだが、その下に 「課金とプライバシーを気にせず無限に叩ける選択肢」 のレイヤーが厚くなった。仕事の8割をローカルで回し、2割だけクラウドに上げる——という運用が現実的になった意義は大きい。

Ollama本体の他ツール統合（Claude Code・OpenCode・Droid）まで含めた全体像は ローカルLLMとは？2026年版ツール比較 で扱っている。LLM単体のアーキテクチャ・量子化・推論最適化に関心があるなら vLLM高速推論完全ガイド も参考になるはずだ。

まとめ

Ollama 0.24は 「ollama launch codex」「ollama launch codex-app」 という2つの公式コマンドで、OpenAI Codex CLIとデスクトップ版Codex Appの両方をローカルLLMバックエンドで起動できるようにした。gpt-oss:20b／120bを中心に、64k以上のコンテキスト窓と Tools API対応を満たすモデルなら何でもCodex経由で使える。

実運用ではconfig.tomlのプロファイル機能で「ローカル20B／ローカル120B／クラウド120B／OpenAI公式」を切り替えながら、軽量タスクは無料のローカル、重い設計判断はクラウドという二段運用が現実解だ。API課金もレート制限もない世界線でエージェントを叩けるようになったことの意味は大きく、特にエージェントループの反復回数を絞ってきた開発者にとっては実質的にトークン制約から解放される転機になる。

ローカルLLMでの開発体験は、ようやく「ハッカーの趣味」から「日常の選択肢」に変わった。手元のMacかLinuxに ollama launch codex を打って、5分後にあなたの専属コーディングエージェントが完全ローカルで動き始める——2026年中盤の標準的なワークフローはこの位置から始まる。

参照ソース

• Ollama Releases (GitHub) — v0.24.0リリースノート、ollama launch codex-appコマンドの公式記載
• OpenAI Codex with Ollama (Ollama公式ブログ) — gpt-oss:20b／120bでのCodex CLI実行、codex --ossフラグの初出
• Codex CLI Integration Documentation (docs.ollama.com) — config.tomlプロファイル設定の公式ドキュメント
• OpenAI Codex Repository (GitHub) — Codex CLI本体、v0.130系の仕様確認

ターミナルをtmuxで分割しても、ブランチを切り替えるたびにエージェントの作業状態が消える。VS CodeやCursorは1つのチャットセッションを前提にしており、複数エージェントの並列実行は設計の外にある。git stashの応酬で1日が終わる、というのが今の現実だ。

stablyai/orca（★2561、2026年5月16日にv1.4.2リリース）はその閉塞感を真正面から壊しに来たOSSである。「100倍ビルダーのためのAIオーケストレーター」を掲げ、Claude Code・Codex・Grok・OpenCodeをそれぞれ独立のgit worktreeで並走させ、1つのIDEから艦隊全体を見渡す設計を採用した。

AIエージェント基盤の全体像と他フレームワーク比較は AIエージェントフレームワーク比較ガイド2026 をご覧ください。

1. Orcaとは何か：AIエージェント並行実行のためのIDE

Orca公式リポジトリのキャッチコピーは「The AI Orchestrator for 100x builders.」だ。日本語では「100倍ビルダーのためのAIオーケストレーター」と訳されており、AIエージェントの艦隊運用を専門に扱うIDEとして位置付けられている。

従来のAIコーディングツールは「1人の開発者と1つのアシスタント」を前提に設計されてきた。GitHub Copilotはエディタに常駐し、Cursorはチャットを1つのウィンドウに表示する。CLIネイティブなClaude CodeやCodexも、ターミナル1セッションでの会話を中心としており、同時並列に複数エージェントを統制する仕組みは持っていない。

Orcaが解こうとする問題は別のレイヤにある。「複数のAIエージェントが同時に異なる機能を実装している状態を、1人の人間が監督する」という業務形態だ。

開発元のStably AIはサンフランシスコ拠点のAIスタートアップで、もともとはQAエージェント・テスト自動化を主力プロダクトに据えていた。Orcaはそのチームが「自社プロダクトの開発でAIエージェントを大量並列に走らせる」という社内ニーズから生まれた、ドッグフーディング由来のIDEである。

GitHubトピックにはade（agentic development environment）・claude-code・codex・cursor-agent・ghostty・ide・mobile-app・opencode・orchestration・parallel-agents・pi・terminal・worktreesが並んでおり、これらが設計の柱を構成している。

Orcaのプロジェクト基本情報

スター数2,561は2026年3月17日のリポジトリ公開からわずか2ヶ月での到達で、AIエージェントIDEカテゴリでは異例の伸びを示している。リリースサイクルも公開2ヶ月でv1.4.2まで進んでおり、v1.4.2-rc.7からrc.10まで1日で4本のリリース候補を出すなど、開発速度は極めて速い。

公式README冒頭の文章は「Run Claude Code, Codex, Grok, or OpenCode side-by-side across repos — each in its own worktree, tracked in one place.」で、リポジトリをまたいだ並行実行と1か所での集中追跡という2つの軸が明示されている。

2. 並列ワークツリーアーキテクチャ：AIエージェントごとに隔離する設計

Orcaの設計上もっとも重要な概念が「worktree-native」というポリシーだ。READMEの機能リスト最初の項目に「Every feature gets its own worktree. No stashing, no branch juggling. Spin up and switch instantly.」と明記されている。

gitのworktree機能を使い慣れていない読者向けに簡単に整理すると、git worktree addは1つのリポジトリから複数の作業ディレクトリを切り出す仕組みである。各worktreeは独立したブランチをチェックアウトでき、git stashで作業中の変更を退避させる必要がない。

Orcaはこのworktreeを各エージェントに1対1で割り当てる。たとえばClaude Codeで機能Aを実装中に、Codexに機能Bを依頼すれば、それぞれが別ディレクトリ・別ブランチで作業し、互いの変更が干渉しない。

並列worktreeのデータフロー

この構造の効能は3つある。

第一に、エージェント間の状態汚染がゼロになる。Claude CodeがファイルAを編集中にCodexが同じファイルを編集しても、別worktreeに分離されているため衝突しない。最終的にPRを統合する段階で初めてgitのmergeが走る。

第二に、git stashの運用負荷が消える。「いま動かしているClaude Codeのタスクを中断してCodexで別ブランチを試したい」という場面で、stashで一時退避→ブランチ切替→作業→戻す、という手数が一切要らない。新しいworktreeを切ってそこにCodexを置くだけだ。

第三に、レビューワークフローが1か所に集約される。Orcaは各worktreeのdiffを内蔵diffビューアで表示し、AI生成コードをそのままレビュー・編集・コミットできる。GitHub PR/Issue/Actionsチェックも各worktreeに自動で紐づくため、レビュー画面とエディタを行き来する必要がない。

並列ワークフローの先行例としては、agent-viewerがtmuxとカンバンを使った類似アプローチを取っている。詳細は agent-viewer完全解説：tmuxで動くClaude Codeエージェントをカンバンで管理するOSS で扱った。

3. 対応するCLIエージェント23種類とフレームワーク中立性

Orcaのもう一つの設計思想が「任意のCLIエージェントに対応」というスタンスだ。README本文には「Orca supports any CLI agent (not just this list).」と但し書きが入っており、明示リストは現時点でサポート確認済みのものを並べているにすぎない。

明示されている対応エージェントは以下の23種で、AIコーディング系のCLIをほぼ網羅している。

この対応幅の広さは「Orcaは特定のLLM・特定のエージェントの代理販売者にならない」という戦略の表れだ。BYOK（Bring Your Own Key）どころか、BYOS（Bring Your Own Subscription）で、ユーザーが既に契約しているサブスクリプションをそのまま使う。

フレームワーク中立の効能

商業的に見ると、これはStably AIにとって「LLMコストの転嫁先がない」という意味でもある。OpenAIやAnthropicの値上げに振り回されない代わりに、Orca自体の有料化はサブスクリプションの値段競争にならず、IDEとしての価値で勝負することになる。

ユーザー視点では、好きなエージェントを混在運用できる利点が大きい。「リファクタリングはClaude Codeが得意、コードベース全体の検索はGemini CLIが速い、Pythonの細かい修正はCodexが速い」といった得意不得意で使い分けることが、追加のラッパー実装なしに可能になる。

新興のスウォーム系フレームワーク（rufloなど）と組み合わせる場合も、Orca側がCLIプロセスを起動するだけなので衝突しない。ruflo自体のClaude Code/Codexネイティブ統合については ruflo｜Claude Code/Codexにネイティブ統合する100エージェント・スウォーム基盤 で扱った。

4. AIエージェントIDEのインストールとセットアップ

Orcaのインストール経路はREADMEで3つ示されている。macOS/Linux/Windows共通のダウンロードと、macOSのHomebrew、Arch LinuxのAURだ。

macOSの場合（Homebrew Cask）

Homebrewでのインストールは1コマンドで完了する。

# Orcaのインストール（Homebrew Cask経由）
brew install --cask stablyai/orca/orca

# バージョン確認
orca --version

# アンインストールしたい場合
brew uninstall --cask stablyai/orca/orca

brew install --caskはGUIアプリケーション向けのHomebrew機能で、stablyai/orca/orcaはサードパーティのCaskタップを指定する書式である。初回のみtap自体が自動で追加され、以降のアップデートはbrew upgradeで一括管理できる。

Arch Linux（AUR）

Arch系ディストリビューションではAURヘルパーのyayから2種類のパッケージが選べる。

# ビルド済みバイナリ（推奨：高速インストール）
yay -S stably-orca-bin

# GitHubソースからローカルビルド
yay -S stably-orca-git

# 起動
orca

stably-orca-binはメンテナがCIで作ったバイナリをそのまま落とすため、ビルド時間がほぼゼロで完了する。stably-orca-gitはソースをgit cloneしてElectronビルドを回すため、初回は10〜20分かかるが、最新コミットに追従できる。

Windows / Linux（一般）

Homebrew/AURを使わない環境では、onOrca.devまたはGitHub Releasesから直接インストーラーをダウンロードする。最新版はv1.4.2（2026-05-16リリース）で、macOSは.dmg、Windowsは.exeまたは.msi、Linuxは.AppImage/.deb/.rpmが配布されている。

# Linux向けAppImageの手動セットアップ例
wget https://github.com/stablyai/orca/releases/download/v1.4.2/orca-1.4.2.AppImage
chmod +x orca-1.4.2.AppImage
./orca-1.4.2.AppImage

起動後の初期設定の流れ

Orcaは起動後にログインを要求しない。ローカルにインストール済みのCLIエージェント（claude、codex、grok、geminiなど）を自動検出し、利用可能エージェント一覧として表示する。新規にエージェントを追加する場合は、対象CLIを各々の公式手順で先にインストールしておく。

その後、開きたいgitリポジトリをドラッグ&ドロップまたはFile > Openで指定すると、Orca側で自動的にworktreeルートディレクトリを作成し、エージェントごとのタブを切る準備が整う。

5. モバイルcompanionアプリとSSHワークツリー

Orcaがほかのデスクトップ型エージェントIDEと一線を画す機能の2つが、モバイル companionアプリと、SSH経由のリモートworktreeだ。

モバイルcompanionアプリ

iOS版はApp Storeで配布されており、Android版はGitHub Releasesのmobile-v*タグからapkを直接ダウンロードする方式である。

モバイル側でできる操作は次の通り。

• 各worktreeの進捗監視（エージェントがアクティブか、入力待ちか、終了したか）
• エージェントへの追加指示送信（テキストプロンプトの追加投入）
• 完了通知の受信（プッシュ通知でiOS/Androidに直接届く）
• 簡易diffプレビュー（コード変更の差分をスマートフォンで確認）

「Claude Codeに1時間かかるリファクタリングを依頼して外出する」「終わったらスマホで結果を確認、追加の指示を送る」というワークフローは、デスクトップだけで完結する従来のIDEでは実現できなかった。

SSHワークツリー

OrcaはローカルマシンにとどまらずSSH経由のリモートマシンでもエージェントを動かせる。具体的には、リモートサーバー上のgitリポジトリにworktreeを切り、リモート側で動いているClaude Code/CodexのCLIプロセスをOrcaから操作する。

このユースケースの典型は次の3つだ。

1. 強力なリモートGPU/CPUサーバーでビルドや学習を回しつつ、ローカルから指示する：手元のMacBookは軽く保ち、重い処理はリモートに集約。
2. チーム共有の開発サーバー上で並列タスクを走らせる：複数の開発者が同じサーバー上でworktreeを切り分けて作業。
3. セキュリティ要件で本番に近い環境でしかコードを動かせない：本番ネットワーク内のSSHサーバーで完結。

ローカルとリモートを統一UIで扱える点は、エージェント運用が分散化していくほど効いてくる。Workspace中心の長期エージェント環境という設計思想は holaOS｜AIエージェントと人が同居するOpen Agent Computer、Workspace中心設計を解読 でも別の角度から扱った。

6. 他のマルチエージェントツールとの比較

Orcaの位置付けを正確に掴むため、近接領域のツールと比較表を作る。比較対象は、tmuxベースのagent-viewer、スウォーム志向のruflo、Workspace中心のholaOS、そして既存IDEのCursorだ。

この比較から見えるOrcaの差別化点は3つに集約できる。

(1) 並列worktreeを第一級の概念として扱う：他ツールは「複数エージェントが動く副作用としてworktreeを使う」のに対し、Orcaは「worktreeをエージェント割り当ての単位」として設計の中心に据えている。

(2) モバイルcompanionアプリの存在：本記事執筆時点で、iOS/Android両対応のエージェント管理アプリを公式に持つ大規模OSS IDEはOrcaのみと言ってよい。

(3) フレームワーク中立性：CursorはCursor、agent-viewerはClaude Code、rufloはClaude Code/Codex中心と、各ツールは得意ベンダーに寄りがちだが、Orcaは23ベンダー以上を等価に扱う。

逆に注意点もある。OrcaはあくまでIDE層で、エージェントの推論ロジック・プロンプト・スキル管理は対象範囲外だ。たとえばエージェントの長期メモリ・知識永続化が必要ならholaOSの方が向くし、エージェント間で複雑な役割分担・並列タスク分配を組みたいならrufloのようなスウォーム基盤と組み合わせる方が筋がいい。

7. AIエージェントIDEとしての実運用と制約

Orcaを本番で使う前に押さえておくべき制約と、向き/不向きを整理する。

向いているチーム・ユースケース

• 複数機能を同時並行で進めたいソロデベロッパー：Claude Code・Codex・Grokのサブスクをすでに持っていて、艦隊運用したい。
• AIエージェントベースの開発実験を回したいR&Dチーム：23種のエージェントを横並びで比較できる。
• モバイルからエージェント監視したいリモートワーカー：移動中・出張中にも進捗を追える。
• 複数リポジトリにまたがる作業が多いマルチプロダクトチーム：repo間横断のworktree管理を1か所に集約。

向いていないユースケース

• 単一AIアシスタントで十分な小規模プロジェクト：Cursor単体やClaude Codeのターミナル直接利用で足りる。
• 企業の厳格なネットワーク隔離要件：Electronアプリのため、ネットワーク制限環境ではアップデートや一部機能で制約が出る可能性がある。
• CLIエージェント文化に未対応の組織：Claude Code・Codexなどのコマンドラインツールを使い慣れていないと、OrcaのUIだけでは抽象化しきれない学習コストがある。
• 完全エアギャップ環境：通知やGitHub連携などクラウド依存機能の一部が動かない。

既知のリスクと注意点

並列実行は強力だが、3つの実運用リスクがある。

第一に、worktreeの数が増えるとディスク使用量が線形に膨らむ。各worktreeは独立した作業ディレクトリを持つため、大規模リポジトリで10本のworktreeを並行運用すると、リポジトリサイズの数倍のディスクを食う可能性がある。

第二に、エージェント同士のAPI/レート制限の競合。Claude CodeとCodexを別worktreeで動かしても、同じAnthropic/OpenAIアカウントを使えば従量課金やレート制限は共有される。

第三に、並列実行中のレビュー負荷。エージェントごとに別々のdiffが上がってくるため、人間レビューワーが追従できなくなる場合がある。Orcaのdiff注釈・ネイティブ検索などの機能はその緩和を狙ったものだが、最終的な品質責任は人間側に残る。

まとめ

AIエージェントが量産モードに入った今、必要なのは「もう1つのアシスタント」ではなく「艦隊全体を見渡す指揮所」だ。Orcaはまだバージョンこそ1.4系だが、公開2ヶ月で★2,561・175 forkに到達したスピードと、毎日のリリース候補出しが続く開発速度を見るに、このカテゴリの定番ポジションを取りに来る本命候補と位置付けて差し支えないだろう。

「Claude CodeとCodexを同時に複数機能で走らせて、夜寝る前にスマホで結果を確認する」——この生活様式を当たり前にできるかどうかが、これからのソフトウェア開発の生産性差を決める。Orcaはそのインフラの一つとして、まず触っておくべきツールだ。

参照ソース

• stablyai/orca — GitHub — 公式リポジトリ。READMEに対応エージェント一覧・機能・インストール手順が網羅されている。2026年5月16日にv1.4.2をリリース。
• Orca — onOrca.dev — 公式サイト。デスクトップアプリのダウンロードリンクと、各機能の詳細ドキュメント（worktrees, terminal, design-mode, ssh, agents/supported など）が用意されている。
• Orca v1.4.2 Release Notes — 最新リリースの公式リリースノート。リリース候補（rc.7〜rc.10）の継続的なリリースサイクルを確認できる。
• Orca日本語版README — 公式日本語ドキュメント。「100xビルダーのためのAIオーケストレーター」というポジショニングが日本語で明示されている。