単発のエージェントタスクを再利用可能なワークフローに変える

AIエージェントによる複数ステップのタスクを再利用可能にするには、その手順を型付きのモデル定義と宣言型のワークフローファイルとしてリポジトリに保存します。そうすれば、次のセッションではプロンプトから手順を組み立て直すのではなく、保存済みのプロセスを実行できます。

こんな経験はないでしょうか。エージェントがテスト、ビルド、スモークテストを正しい順序で実行し、きれいなリリースチェックを完了させた。ところがセッションを閉じると、そのプロセスも一緒に消えてしまう。翌日もう一度説明すると、少しだけ違うバージョンが出てくる。

本記事では、Swampを使ってそのプロセスを残す方法を紹介します。何が再利用可能になり何がならないのか、小さなリリースチェック用ワークフローの例、そして同じワークフローをClaude Code、Cursor、OpenCode、Codexの各環境で実行する方法を解説します。

うまくいったエージェントの実行がなぜ消えてしまうのか

エージェントのセッションは、作業プロセスを会話コンテキストの中にしか保持しません。そのため、セッションが終わればプロセスも消えます。実行したコマンド、選んだ順序、追加したチェックは、次のセッションが実行できる場所には一切保存されません。残るのはチャットの履歴と、たまたま変更されたファイルだけです。

解決策は、エージェントのプロセスを、実行可能なファイルとしてリポジトリに置くことです。手順がリポジトリに存在するようになれば、毎回タスクを説明し直す必要がなくなり、エージェントは手順の再構築ではなく変更作業そのものに時間を使えるようになります。

Swampによる再利用可能なAIエージェントワークフロー：残るものと残らないもの

Swampは、エージェントが構築した実用的な自動化処理を、型付きモデル、YAML定義、ワークフロー、バージョン管理されたデータ、Vault参照として、Gitリポジトリ内の .swamp/ ディレクトリに保存するコマンドラインツールです。Swamp README では6つのコアコンセプトが挙げられています。外部システムを型として記述する「モデル」、あるモデル型の1つの用途を設定するYAMLファイルである「定義」、そして「ワークフロー」「データ」「Vault」「タグ」です。

Swampが再現可能にするのはプロセスであり、推論ではありません。エージェントの手順がモデル定義とワークフローファイルとして保存されると、以降の実行ではその保存済みの手順が実行されます。ただし、エージェントがそれらを作成・編集する際の出力は、セッションごとに異なる可能性があります。

SwampとMCPは役割が異なります。MCPエコシステムに関する開発者ガイドで説明されているとおり、MCPはエージェントをツールに接続するものです。一方Swampは、エージェントがそれらのツールを使って構築した自動化処理を保存・実行するもので、両者は併用できます。Swampはローカルマシン上で動作し、使用する認証情報はすべて、Swampを起動したシェルの環境から取得されます。

ハーネスに合わせたSwampのセットアップ

公式スクリプトでバイナリをインストールし、使用するハーネスに合わせてリポジトリを初期化します。公式インストールスクリプトはmacOSとLinuxに対応しており、Windows向けにもリリースバイナリが公開されています。

curl -fsSL https://swamp-club.com/install.sh | sh

swamp repo init                    # Claude Code (default)
swamp repo init --tool cursor      # or: opencode, codex

Claude CodeはSwampのスキルを .claude/skills/ から、指示を CLAUDE.md から読み込みます。Cursorは .cursor/skills/ と .cursor/rules/swamp.mdc を使用します。OpenCodeとCodexはどちらも .agents/skills/ と AGENTS.md を使用します。

Swampはスキルをバイナリに同梱しており、init実行時にそれらを書き出します。そのため、エージェントは追加のセットアップなしでスキルを見つけられます。シェル補完は swamp completions <shell> で利用できます。

リリースチェック用ワークフローを一通り作る

Swampのワークフローは、ジョブをDAGとして定義するYAMLファイルで、各ステップはモデル定義のメソッドを呼び出します。How Swamp Works で説明されているとおり、各ジョブは依存先のジョブの完了を待ち、同じジョブ内のステップは互いに依存しない限り並行して実行されます。

通常は、run-tests、build-artifact、smoke-test の各定義の作成をエージェントに依頼します。それでも、生成されたワークフローには必ず目を通してください。承認するのはそのファイルだからです。以下の構成はワークフローリファレンスに準拠しています。<method> プレースホルダーは意図的に残してあるので、実際の定義が公開しているメソッド名に置き換えてください。

id: <keep the generated id>
name: release-check
tags:
  purpose: release
jobs:
  - name: checks
    description: Run tests and build in parallel
    steps:
      - name: tests
        task:
          type: model_method
          modelIdOrName: run-tests
          methodName: <method>
      - name: build
        task:
          type: model_method
          modelIdOrName: build-artifact
          methodName: <method>
  - name: smoke
    dependsOn:
      - job: checks
        condition:
          type: succeeded
    steps:
      - name: smoke
        task:
          type: model_method
          modelIdOrName: smoke-test
          methodName: <method>
version: 1

このリリースチェック用ワークフローでは、テストとビルドが同時に実行されます。condition.type: succeeded により、smokeジョブは両方が成功するまで待機します。swamp workflow validate release-check でファイルを検証してから、実行します。

swamp workflow run release-check
swamp workflow run release-check --tag env=staging
swamp data query 'attributes.ok == false'   # example query from the Swamp manual

swamp workflow run は、実行が完了する（成功、失敗、キャンセルのいずれか）か、manual_approval ゲートで一時停止するまで待機します。成功時は終了コード0、それ以外は0以外の値で終了するため、CIでのゲート判定に利用できます。--tag フラグを使うと、実行時にタグを上書きできます。各実行の出力は、後から変更できないバージョン管理されたデータとして保存され、タグで再検索できます。そのため、後のセッションではチャット履歴から再構築するのではなく、何が起きたかを直接読み取れます。data query の式はHow Swamp Worksに掲載されている例なので、自分のモデルのフィールドに合わせて調整が必要です。

スモークステップが成功しても、証明されるのはエンドポイントが応答したことだけです。ページが正しくレンダリングされたことや、ユーザーが一連のフローを完了できたことまでは証明されません。この種のフロントエンドのリグレッションは、ステージング環境のビルドでセッションをリプレイすることで可視化できます。

同じワークフローを複数のハーネスで使う

チームがSwampのワークフローを複数のハーネス間で利用する際、共有するのはモデル、定義、ワークフローの各ファイルです。各ハーネスのskillsディレクトリはgitignoreされ、Swamp自身が書き出します。開発者は swamp repo upgrade --tool <name> でハーネスを切り替えたり、複数のハーネスを併用したりできます。READMEにも、ツールごとに専用のskillsフォルダが用意され、Gitの管理対象外になると記載されています。

たとえば、リポジトリがClaude Code向けに初期化されていて、チームメンバーがCursorを使っているとします。エージェントハーネスは変わりますが、ワークフローファイルは同じままです。

# same checkout, teammate on Cursor
swamp repo upgrade --tool cursor
swamp workflow run release-check

swamp workflow run は、どのエージェントから呼び出されたかに依存しません。エージェントの役割は定義の作成と編集であり、その部分がハーネスによって変わります。OpenCodeとCodexは .agents/skills/ と AGENTS.md を共有しているため、両ツールは同じ場所のスキルを読み込みます。

デフォルトでは、Swampはモデルデータ、ワークフローの実行履歴、出力、監査ログなどの実行データを .swamp/ に保存します。複数のマシンで同じ状態を共有する必要があるチームは、共有ファイルシステムのパスやS3など、別のデータストアバックエンドに切り替えられます。チェックアウトしたリポジトリもそのまま持ち運べます。エージェント型コーディング向けにセットアップしたリモートマシン上でも、そのシェルがモデルに必要な認証情報を持っていれば、同じワークフローが動作します。カレントディレクトリ以外のリポジトリをSwampに指定するには、--repo-dir または SWAMP_REPO_DIR を使用します。

Swampの成熟度と制約

Swampはまだ初期段階のツールです。swamp-clubのリポジトリで活発にメンテナンスされており、日付付きのリリースが継続的に公開されています。今後の変更を前提に計画を立ててください。

• 外部からのコントリビューションは受け付けていません。 SwampのコードはElder Swamp Clubのスタッフのみが書いています。フォークからのプルリクエストは自動的にクローズされるため、バグ報告や機能要望は swamp issue bug または swamp issue feature で送信し、採用されたものをメンテナーが実装します。
• テレメトリ。 Swampは、無効化しない限り使用状況のテレメトリを収集します。単一のコマンドでは --no-telemetry、シェル単位では SWAMP_NO_TELEMETRY=1、リポジトリ単位では .swamp.yaml に telemetryDisabled: true、マシン上のすべての実行に対しては swamp config set telemetry.collection disabled で無効化できます。最後の方法では、設定が ~/.config/swamp/telemetry.yaml に書き込まれます。
• 適用範囲。 1行のスクリプトやcronジョブに、モデル、DAG、バージョン管理されたデータは必要ありません。Swampが真価を発揮するのは、タスクが複数のシステムにまたがる場合、履歴が必要な場合、あるいはチームで共有する場合です。
• 拡張機能はコードを実行します。 サードパーティの拡張機能は、信頼する前にレビューしてください。
• ライセンス。 AGPL-3.0（Swamp Extension and Definition Exception付き）。

決定論的なランナーは、良いワークフローと同じく、悪いワークフローも忠実に繰り返します。アサーションや人間によるレビューは引き続き必要です。

まとめ

Swampが保持するのは手順であり、エージェントの思考ではありません。保存された定義とワークフローによって、毎回同じ手順と同じゲートで実行できる一方、エージェントはそれらを作成・変更するたびに自由に（そしてばらつきをもって）振る舞います。次の一歩としては、リリースチェックやレビューなど、エージェントがすでにうまくこなしているプロセスを1つ選び、それをSwampのワークフローとして保存するよう依頼してみるとよいでしょう。YAMLをレビューしてコミットし、別のハーネスからも実行して、そちらでも動作することを確認してください。

よくある質問

GitHub ActionsのCIでSwampのワークフローを実行するにはどうすればよいですか？

公式のGitHub Actionであるswamp-club/setup-swampを使用します。このActionは公式インストールスクリプトでSwampをインストールし、api-key入力を渡せばswamp.clubへのサインインも行えます。repo-initをtrueに設定すると、インストール後にswamp repo initが実行されます。後続のステップでワークフロー名を指定してswamp workflow runを呼び出します。実行が失敗するとコマンドが0以外の値で終了し、ジョブも失敗します。なお、このActionはまだv0.1の初期リリース段階です。

Swampのワークフローで使うシークレットはどこに保存すべきですか？

Swamp Vaultに保存し、定義やワークフローからは名前で参照します。Swampはステップの実行時点で実際の値を取得します。これにより、値がYAMLファイルや.swampのデータに含まれることはなく、次回の実行にも何も残りません。組み込みのローカル暗号化プロバイダーは追加のセットアップなしで利用できます。その他のVaultプロバイダーを使えば、AWS Secrets Manager、Azure Key Vault、1Passwordなどの外部サービスにシークレットを保管できます。

Swampのワークフローの実行にAIエージェントは必要ですか？

いいえ。swamp workflow runは通常のCLIコマンドなので、開発者、CIジョブ、スクリプトのいずれからでも、エージェントなしで保存済みのワークフローを実行できます。エージェントが必要なのは、モデル、定義、ワークフローを作成・編集するときだけです。手動で起動しない実行については、swamp serveを使えばcronトリガーでワークフローを実行できます。また、GitHub、Jira、Linear、Stripe、Slack、または汎用エンドポイントから署名付きWebhookを受信したときに実行することもできます。

SwampはWindowsにインストールできますか？

はい。swamp-club/swampのGitHubリリースページには、macOS版とLinux版に加えて、swamp.exeを含むswamp-windows-x86_64.zipアーカイブが公開されています。curlのワンライナーはインストールスクリプトをshにパイプするため、Windowsでは動作しません。Windowsユーザーはリリースアーカイブをダウンロードしてswamp.exeを展開し、PATHの通ったディレクトリに配置してください。