第8章 §2

ライフサイクル管理

エージェント、スキル、スクリプトのそれぞれが生成から廃棄までどのような段階を経るのか、そしてこれらの段階が実際のワークスペースでどのように管理されているのかを扱います。

この節で扱う内容
  • エージェントのライフサイクル: create → verify → operate → improve → deprecate
  • スキルのライフサイクル: define → test → deploy → version → retire
  • スクリプトのライフサイクル: write → lint → test → register → deprecate
  • 状態（State）とライフサイクル（Lifecycle）の区別
  • ライフサイクル管理がなぜ必要なのか

ライフサイクル管理が必要な理由

マルチエージェントシステムを運用していると、ワークスペース内のエージェント、スキル、スクリプトは増え続けます。新しいものを作るだけでは十分ではありません。各コンポーネントがどの段階にあるかを明確にする必要があります。そうすることで、次のような問題を回避できます。

  • 未検証のコンポーネントが本番に投入される問題。 エージェントが agent:verify を通過せずにデプロイされると、フロントマターの欠落フィールドや誤った役割定義により、実際のセッションでエラーが発生します。
  • 廃止対象が依然として呼び出される問題。 有効でなくなったスキルがレジストリに残っていると、エージェントが意図せずそのスキルを選択して失敗します。
  • バージョンの不一致による再現不能の問題。 スクリプトが更新されたのに、あるvariantでは旧バージョンを参照したままだと、同じ入力に対して異なる結果が生じます。

こうした問題を体系的に防ぐため、ai-workspace-standards はエージェント・スキル・スクリプトそれぞれについて名前付きの段階（named stages）を定義し、各段階で実施すべき検証と遷移条件を規定しています。この節では、この3つのライフサイクルをそれぞれ説明し、ワークスペースで実際にどのように管理されているかを扱います。

エージェントのライフサイクル

エージェントは agents/ ディレクトリ配下に .md ファイルとして定義されます。エージェントは誕生してから運用され、最終的に廃止されるまで、次の5段階を経ます。

Create agents/*.md 作成 Verify agent:verify Operate セッションで実行 Improve フィードバック反映 Deprecate 利用停止 再検証ループ

Create — エージェントの生成

エージェントのライフサイクルは、agents/ ディレクトリに新しい .md ファイルを作成することから始まります。このファイルには、フロントマター（name、role、model などのフィールド）と本文（system prompt）が含まれます。生成時には次の点を確認します。

  • ファイル名がエージェントの役割を明確に示しているか（例: pm.md、reviewer.md）
  • フロントマターに name、role、model、status フィールドがすべて含まれているか
  • 本文に当該エージェントの動作原則と制約条件が明示されているか

初期の status フィールド値は draft に設定します。この状態では、エージェントは運用セッションで自動的に選択されません。

Verify — エージェントの検証

生成されたエージェントファイルがワークスペースの規格に適合しているかを bun run agent:verify で検証します。このコマンドは次の点を確認します。

  • フロントマターフィールドの欠落や型の不一致がないか
  • AGENTS.md に当該エージェントが正しく登録されているか
  • 参照しているスキルやスクリプトが実際に存在するか
  • 他のエージェントと役割が重複していないか

検証に合格すると、status を active に変更します。合格しない場合は draft の状態を維持し、エラーメッセージをもとに修正して再検証します。

Operate — エージェントの運用

active 状態のエージェントは実際のセッションで呼び出されるようになります。運用段階では、エージェントの実際の動作を観察し、セッションログで次の点をモニタリングします。

  • エージェントが定義された役割どおりに動作しているか
  • 他のエージェントとの協働において干渉や衝突がないか
  • 応答品質が期待水準に達しているか

運用中に発見された問題は記録し、Improve 段階の入力として使用します。

Improve — エージェントの改善

運用フィードバックをもとにエージェントファイルを更新します。改善内容は次のとおりです。

  • system prompt の曖昧な指示を明確に修正する
  • 欠落していた制約条件や例外処理ルールを追加する
  • モデル変更（model フィールド）が必要な場合は更新する

ファイルを修正した後は、必ずもう一度 bun run agent:verify を実行して再検証する必要があります。この Verify 段階に戻るループは、エージェントのライフサイクルにおける中核的なフィードバックサイクルです。検証に合格すると、再び Operate 段階に入ります。

Deprecate — エージェントの廃止

エージェントが不要になった場合、status を deprecated に変更します。廃止時には次を実施します。

  • AGENTS.md から当該エージェントの項目を削除するか、コメントアウトする
  • 当該エージェントを参照していたvariantやスクリプトから依存関係を除去する
  • ファイル自体は削除せず、status: deprecated として保存する（必要に応じて復元可能）

一定期間（例: 30日）が経過し、参照が残っていないことが確認できたら、ファイルをアーカイブディレクトリへ移動するか、最終的に削除します。

bun run agent:verify は、エージェントのライフサイクルにおける Verify 段階の中核となるツールです。このコマンドは単なる文法チェックにとどまらず、エージェントがワークスペースの他のコンポーネントと整合的に連携しているかまで確認します。CI/CDパイプラインにこの検証を組み込むことで、未検証のエージェントが本番に投入されることをシステム的に防止できます。

スキルのライフサイクル

スキルは、エージェントがセッション中に呼び出せる再利用可能な動作単位です。SKILL.md ファイルとして定義され、プラグインやワークスペースの .claude/skills/ に配置されます。スキルのライフサイクルは次の5段階で構成されます。

Define SKILL.md 作成 Test validate-skills.ts Deploy レジストリ登録 Version バージョン管理 Retire 利用停止 更新後の再テスト

Define — スキルの定義

スキルは SKILL.md ファイルとして定義されます。このファイルには、フロントマター（name、description、triggers など）とともに、スキルが実行する動作の説明が含まれます。定義時には次の点を明確にします。

  • name: スキルの一意な識別子
  • description: エージェントがこのスキルをいつ選択すべきかを決定する説明
  • triggers: スキルが自動的に有効化される条件
  • 本文: スキル実行時にエージェントが従うべき手順

初期状態では status: draft としておき、エージェントが実際にこのスキルを自動選択できないようにします。

Test — スキルの検証

スキル定義が正しいかを validate-skills.ts で検証します。このスクリプトは次の点を確認します。

  • フロントマターフィールドの完全性および形式の一致
  • トリガー条件が他のスキルと曖昧に重複していないか
  • 参照しているツール（MCP tool など）が現在の環境で使用可能か
  • スキルの説明がエージェントに正しく理解される程度に具体的か

検証に合格すると、Deploy 段階へ進む準備が整います。

Deploy — スキルの配備

検証済みのスキルを、エージェントが実際に呼び出せる環境に配備します。配備とは、具体的には次のことを意味します。

  • status を active に変更し、エージェントの自動選択対象に含める
  • 必要に応じてワークスペースの .claude/skills/ やプラグインレジストリに登録する
  • 当該スキルを使用するエージェントのフロントマターに依存関係を明示する

配備後は、エージェントのセッション内でスキルが正常にトリガーされ実行されるかを確認する手動レビューを実施します。

Version — スキルのバージョン管理

運用環境で使用中のスキルに変更が必要になった場合、バージョン管理によって安全に更新します。

  • スキルファイルの変更履歴を SKILL.md のヘッダーコメントや changelog に記録する
  • 互換性を損なう変更（breaking change）の場合は、既存のスキルを維持したまま新バージョンとして複製してから更新する
  • 変更後は必ず validate-skills.ts で再検証する

Version 段階から Test 段階に戻るこのループは、スキルのライフサイクルにおける中核的なフィードバックサイクルです。更新されたスキルが検証に合格すると、再び Deploy 段階に入ります。

Retire — スキルの廃止

スキルが使用されなくなったり、他のスキルに置き換えられたりした場合は廃止します。

  • status を retired に変更し、エージェントの選択対象から除外する
  • 当該スキルを参照していたエージェントのフロントマターから依存関係を除去する
  • ファイルは保存したうえで retired 状態として明示し、再利用時に元の内容を参照できるようにする
validate-skills.ts は、スキルのライフサイクルにおける Test 段階の中核となるツールです。このスクリプトは単純な形式チェックだけでなく、スキル間のトリガー衝突や参照の整合性まで点検します。新しいスキルを追加したり既存のスキルを修正したりするたびに必ず実行する必要があります。エージェントの agent:verify と同様に、CI/CDパイプラインに組み込むことで、未検証のスキルが配備されることを自動的に防止できます。

スクリプトのライフサイクル

スクリプトは scripts/ ディレクトリ配下に .ts ファイルとして管理されます。エージェント生成の検証、テンプレートの発行、プロジェクトのスキャフォールディングなど、ワークスペースのインフラを自動化する実行可能なコードです。スクリプトのライフサイクルは次の5段階で構成されます。

Write scripts/*.ts 作成 Lint 静的解析 Test 単体・統合テスト Register package.json 登録 Deprecate 利用停止 修正後の再検証

Write — スクリプトの作成

新しいスクリプトは scripts/ ディレクトリに .ts ファイルとして作成します。作成時には次の点を遵守します。

  • ファイル名がスクリプトの目的を明確に示していること（例: propagate-to-templates.ts、validate-skills.ts）
  • スクリプトの冒頭に目的、使用法、引数の説明をコメントとして記録する
  • 型定義を明確にし、外部依存を最小化する
  • エラー処理を含め、失敗時に意味のあるメッセージを出力する

作成直後のスクリプトは draft 状態とみなされます。

Lint — 静的解析

作成されたスクリプトに対して静的解析（lint）を実施します。TypeScriptベースのワークスペースでは、bun run lint または tsc --noEmit を使用して次の点を確認します。

  • 型エラーがないこと
  • 使用されていない変数やインポートがないこと
  • コードスタイルの一貫性
  • 潜在的なランタイムエラー（例: null参照）への警告

静的解析で発見された問題はすべて修正しないと次の段階へ進めません。

Test — テスト

静的解析を通過したスクリプトに対して単体テストおよび統合テストを実施します。スクリプトがファイルシステムやネットワークに依存する場合は、モック環境でテストします。

  • 正常経路（happy path）: 想定した入力に対して正しい出力が得られるか
  • 例外経路: 不正な入力、ファイル不存在、権限エラーなどに対して適切にエラーを処理するか
  • 統合テスト: 実際のワークスペース環境で他のスクリプトやエージェントと連携した際に正常に動作するか

テストに合格したスクリプトのみが Register 段階へ進むことができます。

Register — スクリプトの登録

テストに合格したスクリプトを package.json の scripts セクションに登録し、bun run <name> の形で実行できるようにします。

  • package.json に適切なスクリプト名と実行コマンドを追加する
  • スクリプトの説明書（本ハンドブックまたは別のREADME）に使用法を記録する
  • 他のスクリプトやエージェントがこのスクリプトを呼び出す場合、その依存関係を文書化する

登録完了後、bun run <name> が正常に実行されるかを最終確認します。

Deprecate — スクリプトの廃止

スクリプトが不要になったり、他のスクリプトに置き換えられたりした場合は廃止します。

  • package.json から当該スクリプトの項目を削除する
  • このスクリプトを呼び出していた他のスクリプトから依存関係を除去し、代替パスへ更新する
  • ファイル自体は scripts/_deprecated/ のようなアーカイブディレクトリへ移動するか、コメントに @deprecated を明示して保存する
スクリプトのライフサイクルにおいて、人が直接行う手動レビュー（manual review）は、Lint と Test の間、および Test と Register の間でそれぞれ一度ずつ推奨されます。自動化された検証がすべての問題を捉えられるわけではありません。特にスクリプトがワークスペースのファイル構造を変更する場合（例: propagate-to-templates.ts）、人が実際の結果を目視で確認する過程が不可欠です。

3つのライフサイクルに共通する原則と相互依存関係

状態（State）とライフサイクル（Lifecycle）の区別

ここまで、3種類のライフサイクルをパイプラインとして説明してきました。ここで混同してはならない区別が一つあります — ライフサイクル（lifecycle）と状態（state）は異なる概念です。

  • ライフサイクルとは、コンポーネントが経る一連の段階全体を指します。エージェントであれば、Create → Verify → Operate → Improve → Deprecate という5段階のパイプライン自体がライフサイクルです。
  • 状態とは、特定の時点でそのコンポーネントがどこにあるかを示すスナップショットです。YAMLフロントマターの status フィールド（draft、active、deprecated、retired）が、まさにこの状態の値を保存する仕組みです。

たとえるなら、ライフサイクルは「地下鉄の路線図」であり、状態は「現在、列車がどの駅にいるか」を示すリアルタイム表示板です。列車がどこへ向かうべきか（路線）は固定されていますが、今どこにいるか（駅）は刻々と変化します。

ワークフロー実行レベルの状態 — 例えば、第9章でPMが定義する Phase Pipeline（Phase 0: 要求受領 → Phase 1: 設計 → … → Phase 6: 同期完了）— は、個々のコンポーネントの status フィールドとはまた別の次元の状態です。前者は「作業がどの段階にあるか」であり、後者は「このコンポーネント自体がライフサイクルのどこにあるか」です。

エージェント・スキル・スクリプトのライフサイクルはそれぞれ独立して定義されていますが、実際のワークスペースでは密接に結びついています。

エージェント・スキル・スクリプトのライフサイクルはそれぞれ独立して定義されていますが、実際のワークスペースでは密接に結びついています。

検証ツール 関連するライフサイクル 役割
bun run agent:verifyエージェントエージェントファイルの構造、参照の整合性、AGENTS.mdへの登録状況を検証
validate-skills.tsスキルスキルのフロントマター、トリガー衝突、ツール参照の有効性を検証
手動レビューすべてのライフサイクル自動検証では捕捉できない意味的正確性、使いやすさ、影響範囲を確認

3つのライフサイクルは、次の3つの共通原則を共有しています。

  • 段階の明示: すべてのコンポーネントは、status フィールドやファイルの配置場所を通じて現在の段階を明確に示さなければなりません。draft 状態のものは運用に投入されず、deprecated/retired 状態のものは新規の呼び出し対象から除外されます。
  • 検証ゲート: ある段階から次の段階へ移行する前に、定義された検証を必ず通過しなければなりません。検証に失敗した場合は前の段階に戻り、修正してから再検証します。
  • 廃止後の保存: 廃止されたコンポーネントは即座に削除せず、一定期間保存します。これにより、必要な場合に復元が可能となり、廃止決定の根拠を追跡できます。

次節（§3 アーキテクチャ深掘り）では、ライフサイクル管理の原則が実際の高度化の方向性（コンテナ化、メモリ管理、variant配布パイプライン）とどのように結びつくかを扱います。

参考動画