ワークフローと自動化
この章では、AIハーネスのワークフロー自動化を取り上げます — /syncコマンド、Git/GitHub PR、フック、CI/CDの基礎、そしてdev-sync.tsの動作について解説します。
- 自動化がなぜ重要か
- /syncの動作
- GitとGitHub PRの基礎
- フックの概念
- CI/CDの基礎
- dev-sync.tsの内部構造
- 演習: フルワークフローを体験する
自動化とは
すべての衣類を手で洗うことを想像してみてください — 各アイテムを個別にこすり、すすぎ、絞る必要があります。毎週何時間もかかるでしょう。そこで誰かが洗濯機を発明しました: 衣類を入れ、ボタンを押すと、洗濯機がサイクル全体を自動的に処理します。これが自動化です — 反復的な手動ステップを代わりに実行するシステムに置き換えること。
同じ原則がソフトウェア開発とAIエージェントのワークフローにも適用されます。前の章では、エージェントがどのように協力してリサーチ、スライドデッキ、ハンドブックを生み出すかを学びました。しかし、エージェントが作業を終えた後はどうなるでしょうか？変更はどのように保存、検証、共有されるのでしょうか？そこがワークフロー自動化の出番です。
手動 vs. 自動
自動化の有無による典型的なワークフローの違いを比較してみましょう。
自動化なし（手動）
- 監査チェックを自分で実行
- バージョンファイルを手動で更新
- gitコマンドでコミット
- GitHubに手動でプッシュ
- ウェブUIでPull Requestを作成
- 共有の変更を各バリアントプロジェクトに手動でコピー
- リスク: ステップの忘れ、タイポ、不整合なバージョン
自動化あり（/sync）
- 監査が自動実行
- バージョンファイルが自動更新
- コミットメッセージが自動生成
- プッシュがパイプラインの一部として実行
- PRが1つのコマンドで作成
- L0の変更がすべてのバリアントに自動伝播
- 結果: 一貫性があり、信頼性が高く、再現可能
洗濯機の例え
/syncコマンドをプロジェクトの洗濯機と考えてください。作業後のワークフローの各ステップ（監査、バージョン更新、コミット、プッシュ、PR作成）を手動で行う代わりに、1つのコマンドを実行するだけでシステムがサイクル全体を処理します。「衣類」（変更されたファイル）を入れ、ボタン（/sync）を押すと、残りの処理は洗濯機が行います。
この例えはさらに拡張できます: 洗濯機には異なるコース（デリケート、重い洗い）があるように、自動化パイプラインも異なるシナリオに設定できます。そして洗濯機が常に一貫して衣類をきれいにするように、自動化はプロジェクトが常に一貫して維持されることを保証します。
/syncコマンドの理解
/syncコマンドはAIハーネスの中心的な自動化コマンドです。作業後ワークフロー全体を単一の呼び出しにカプセル化します。ファイルを変更するタスク（エージェントの追加、スキルの更新、スクリプトの変更など）を終えるたびに、/syncを実行して作業を適切に確定します。
5ステップ同期パイプライン
/syncを呼び出すと、システムは5つのステップを順番に実行します。各ステップは前のステップが正常に完了することに依存しています。
-
ライフサイクル更新 — システムはライフサイクル追跡の成果物（エージェント、スキル、スクリプト、ガバナンスファイル）が変更されたかどうかを確認します。変更があった場合、関連するライフサイクル記録と
CHANGELOG.mdを更新して変更を反映します。 -
監査 —
scripts/audit.tsスクリプトがワークスペースの包括的なチェックを実行します。ファイル構造、命名規則、フロントマターの完全性、相互参照、コントラクトコンプライアンスを検証します。エラーは報告され、先に進む前に修正する必要があります。 - 公開（L0→L1） — L0ワークスペースルートレベルで変更が行われた場合、それらの変更はL1コモンテンプレートに下方向に公開されます。これにより、すべてのバリアントが最新の標準を継承することが保証されます。
- コミット — すべての変更がコンベンショナルコミットメッセージでgitにコミットされます。メッセージにはタイププレフィックス（feat、fix、docsなど）、スコープ、変更内容の説明が含まれます。
- プッシュ + PR — コミットがリモートリポジトリにプッシュされ、Pull Requestが自動的に作成（または既存のものが更新）されてレビュー用に提出されます。
/syncコマンドは引数としてコンベンショナルコミットメッセージを受け取ります。例: /sync "feat(pm): ミーティングファシリテーションスキルを追加"。システムはこのメッセージをgitコミットに使用するため、明確で説明的なメッセージを書くことが重要です。形式はtype(scope): descriptionのパターンに従います。
/syncの追加安全ゲート（2026-08-24時点）— 上記の5ステップに加えて、パイプライン内で以下のチェックが自動的に実行されます。ユーザーは通常、プロンプトが表示されたら答えるだけで大丈夫です。
- 言語ゲート — コミットメッセージとPRタイトルが英語ルールに合っているか検査します。
- スペックレジストリチェック —
audit.ts --spec-check: 今回の作業がdocs/specs/registry.jsonに登録された設計ドキュメント（スペック）と紐付いているか確認し、なければ同期を中断します（FATAL）。タイポ修正などの軽微な変更は、例外コードE1〜E5（--spec-exemptまたはSYNC_SPEC_EXEMPT）で免除できます。 - ガバナンス反映ゲート（ADR-0059） — 変更内容が関連するADR（設計決定記録）と紐付いているか検査します。
- スキルグラフゲート（ADR-0060） — スキル間の依存関係グラフを作成・検証し、循環参照などの問題を早期に発見します。
- VERSION_MANIFEST再生成 —
docs/VERSION_MANIFEST.mdのバージョン一覧を最新状態で作り直します。
いつ/syncを実行するか
プロジェクトファイルを変更した作業セッションの終わりに/syncを実行する必要があります。具体的には:
- エージェントを追加、変更、非推奨化した後
- スキルを作成、更新、削除した後
- スクリプトやそのステータスを
SCRIPTS.mdで変更した後 - ガバナンスファイル（
AGENTS.md、CLAUDE.md、GEMINI.md）を変更した後 common-contract.jsonやテンプレートファイルへの変更後
Git & GitHub PR
自動化パイプラインがどのように機能するかを理解するには、GitとGitHub Pull Requestの基本的な理解が必要です。これらは監査後の同期パイプラインのすべてのステップを支えるツールです。
Gitの基礎
Gitはプロジェクト内のファイルに対するすべての変更を追跡するバージョン管理システムです。プロジェクトの歴史の詳細な日記と考えてください。変更のセットを保存するたびに、Gitは誰がいつ何を変更したかを記録します。
AIハーネスのワークフローで遭遇する基本的なGitコマンドは以下の通りです。
# 変更されたファイルを確認
git status
# 変更の実際の差分を表示
git diff
# 「ステージングエリア」に変更を保存（コミットの準備）
git add <filename>
# ステージされた変更をメッセージとともに記録
git commit -m "type(scope): description"
# コミットをリモートリポジトリ（GitHub）に送信
git push
# リモートの最新の変更をダウンロード
git pull
# 新しいブランチを作成（並列の作業ライン）
git checkout -b feature/my-new-feature
# コミット履歴を表示
git log --onelineGitHubの基礎
GitHubはGitリポジトリをホストするウェブプラットフォームです。Gitの上にチームアクセス管理、コードレビューツール、イシュートラッキング、Pull Requestなどのコラボレーション機能を追加します。あなたのAIワークスペースはGitHubにあり、同期パイプラインは変更をプッシュし、PRを作成するためにGitHubと対話します。
Pull Request（PR）
Pull Request（PR）は、あるブランチの変更を別のブランチにマージする提案です。コラボレーティブプロジェクトにおけるコードレビューの標準的なメカニズムです。仕組みは以下の通り:
- ブランチを作成 — 新しいブランチ（コードの並列コピー）を作成し、そこで変更を行います。これにより作業中もメインブランチが安定に保たれます。
- 変更とコミット — ファイルを編集し、新しいエージェントやスキルを追加し、ブランチ上で変更をコミットします。
- PRを開く — 「これらの変更をレビューしてメインブランチにマージしてください」というPull Requestを作成します。
- レビュー — チームメンバー（または自動チェック）が変更をレビューし、コメントを残し、必要に応じて修正を要求します。
- マージ — 承認されると、PRはメインブランチにマージされ、変更が公式プロジェクトの一部になります。
/syncを実行すると、パイプラインがステージング、コミット、プッシュ、PR作成を処理します。すべてのGitコマンドを暗記する必要はありません。ただし、概念を理解すること（コミットとは何か、ブランチとは何か、PRは何をするか）は、自動化が背後で何をしているかを理解するのに役立ちます。
フック
フックは、特定のイベントが発生した時に自動的に実行されるスクリプトです。「フック」という言葉は釣りに由来しています: 魚が泳ぎ通りかかると魚針が魚を捕まえるように、コードフックはイベントを捕まえてスクリプトを実行します。
フックの仕組み
AIハーネスでは、フックは重要な瞬間にルールの強制とチェックの自動化に使用されます。開発者が手動でチェックを実行することを覚えていることに頼るのではなく、フックは関連するイベントが発生するたびに自動的にチェックを保証します。
最も一般的なタイプのフックはGitフックで、特定のGit操作の前後にGitが自動的に実行するスクリプトです。
# pre-commit — コミットが確定される前に実行
# 用途: シークレット検出、リント、ファイルフォーマット
# commit-msg — コミットメッセージが書き込まれた後に実行
# 用途: コミットメッセージ形式の検証
# pre-push — リモートにプッシュする前に実行
# 用途: テスト実行、ビルド確認
# post-merge — ブランチがマージされた後に実行
# 用途: 依存関係のインストール、ロックファイルの更新警報システムの例え
フックをビルの警報システムと考えてください。毎晩すべてのドアと窓を手動でロックすることを覚えておく必要はありません — 警報システムが自動的に監視します。認証なしでドアが開かれると、警報が即座に作動します。同じように、フックはあなたのワークフローを自動的に監視します:
pre-commitフックは、建物を出る前に荷物をチェックする警備員のようなものです。pre-pushフックは、商品が顧客に出荷される前の最終検査のようなものです。毎回自分でこれらのチェックを行うこともできますが、フックがあれば、急いでいる時や忘れた時でもチェックがスキップされることはありません。
AIハーネスでは、フックはツールレベルでも定義できます。例えば、Claude Codeのフックは、AIエージェントがファイルを編集しようとした時にスクリプトをトリガーでき、Gitフック以上の追加の強制レイヤーを提供します。
簡単に言えば、ツールレベルのフックはAIエージェントのための自動安全装置です。エージェントがファイルを編集しようとする瞬間や、別のエージェントを呼び出す瞬間に割り込んで、問題が大きくなる前に捕まえます。実際にこのワークスペースの.claude/settings.jsonには、以下のようなツールフックが登録されています（2026-08-24時点）。
| フックスクリプト | 実行タイミング | 役割 |
|---|---|---|
gateguard-fact-force.ts |
PreToolUse · Edit/Write/MultiEdit | 事前検証ゲート — ファイルを編集する前に、そのファイルが使われている場所と変更の事実関係を先に確認します。 |
agent-model-gate.ts |
PreToolUse · Agent | モデル等級の強制 — エージェントを呼び出す際に、タスクの難易度に合ったモデル等級（High/Medium/Low）を使っているか検査します。 |
post-write-lifecycle-check.ts |
PostToolUse · Write/Edit + TeammateIdle | 事後ライフサイクルチェック — ファイル変更の後、バージョン記録やCHANGELOGの更新が必要かどうかを確認します。 |
audit.ts |
TaskCompleted | タスク完了時のQA監査 — エージェントのタスクが終わるたびに、ワークスペース全体の監査を自動実行します。 |
git config core.hooksPath .githooks |
SessionStart / WorktreeCreate | Gitフックの接続 — セッションやワークツリー（worktree）の開始時にGitフックフォルダ（.githooks）を接続し、pre-commitなどのGitフックが常に動くようにします。 |
CI/CDの基礎
CI/CDは継続的インテグレーション / 継続的デリバリーの略です。コード変更のテストとデプロイのプロセスを自動化するプラクティスです。CI/CDはソフトウェアエンジニアリングの広いトピックですが、基本的な概念を理解することで、AIハーネスが品質をどのように保証するかを理解できます。
継続的インテグレーション（CI）
継続的インテグレーションは、誰かが変更をプッシュするたびにコードのビルドとテストを自動的に行うことを意味します。指定された「テストの日」を待つのではなく、すべての変更がすぐにテストされます。これにより、修正が最も簡単な早期にバグや問題を発見できます。
AIハーネスの文脈では、CIはPull Requestが作成または更新されるたびに監査スクリプト、検証チェック、テストを自動的に実行することを意味します。
継続的デリバリー（CD）
継続的デリバリーは、コード変更をリリース用に自動的に準備することを意味します。テストに合格すると、システムは最小限の手動介入で変更を本番にデプロイできます。キーワードは「デリバリー」 — 変更は出荷の準備ができていますが、最終リリースは人間が承認します。
AIハーネスでは、CDはPRが承認されマージされると、更新されたワークスペースが自動的にすべてのチームメンバーとバリアントで利用可能になることを意味します。
GitHub Actionsの例
GitHubで最も一般的に使用されるCI/CDツールはGitHub Actionsです。概念的なCIワークフローの例:
# PR作成時に自動実行
on: pull_request
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: bun install
- run: bun scripts/audit.ts # ワークスペースを検証
- run: bun scripts/validate-skills.ts # スキルをチェック
security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: gitleaks detect # シークレットをスキャンdev-sync.tsの動作
scripts/dev-sync.tsスクリプトは同期パイプラインを駆動するTypeScript実装です。/syncコマンドの背後にあるエンジンです。内部で何を行っているか見てみましょう。
目的
dev-sync.tsは3層継承階層にわたって変更を同期させます。L0ワークスペースルートまたはL1コモンテンプレートでファイルを変更すると、dev-sync.tsはそれらの変更がすべてのダウンストリームバリアントプロジェクト（L2）に正しく伝播することを保証します。これは、L2バリアントが基本構造をL0とL1から継承するため重要です — 同期がなければ、上位の変更はそれに依存するバリアントに届きません。
4ステッププロセス
- 変更検出 — スクリプトはL0とL1ファイルの現在の状態を最後の既知の状態と比較します。前回の同期以降に追加、変更、または削除されたファイルを特定します。
- コントラクト検証 — 何かを伝播する前に、スクリプトは変更がコモンコントラクトに準拠しているか確認します。変更がコントラクトを破る場合（例: 他のプロジェクトが依存するファイルの名前変更）、スクリプトは違反を報告して停止します。
- 変更公開 — 検証された変更がL0からL1（またはL1からL2バリアント）にコピーされます。スクリプトは共有の更新を適用しながら、バリアント固有のカスタマイズを保持します。
- 完全性検証 — 公開後、スクリプトは最終検証を実行し、すべてのダウンストリームプロジェクトが有効な状態であることを確認します。これには、すべての継承ファイルが存在し、競合が存在しないことの確認が含まれます。
git statusを実行してワーキングディレクトリがクリーンであることを確認するか、同期を開始する前にすべての保留中の変更をコミットしてください。
dev-sync.tsの手動実行
/syncがパイプライン全体を自動的に実行しますが、より詳細な制御が必要な場合はdev-sync.tsを直接実行することもできます。
# 同期スクリプトを直接実行
bun scripts/dev-sync.ts
# スクリプトは以下を行います:
# 1. L0とL1の変更を検出
# 2. コモンコントラクトに対して検証
# 3. ダウンストリームバリアントに変更を公開
# 4. すべてのプロジェクトの完全性を検証
# ヘルプと利用可能なオプションを確認
bun scripts/dev-sync.ts --helpdev-sync.tsスクリプトはコア同期ツールであり、すべてのテンプレートとバリアントで標準化され同一でなければなりません。L3プロジェクトでのこのコアスクリプトの直接変更は厳しく禁止されています。バリアントがカスタム検証チェックを必要とする場合、別のプラガブルフックスクリプトscripts/audit-variant.tsに実装してください。
演習: ワークフローを体験する
では、すべてを組み合わせて、現実的なワークフローを最初から最後まで体験してみましょう。目標: ファイルを変更し、コミットし、/syncを実行して完全な自動化パイプラインを完了させる。
git branchでどのブランチにいるかを必ず確認してください。mainで直接ではなく、フィーチャーブランチで作業していることを確認してください。mainで直接作業するとPRレビュープロセスがバイパスされ、不安定性を導入する可能性があります。
-
フィーチャーブランチを作成する。 作業用に新しいブランチを作成します。これにより、メインブランチから変更が分離され、マージ前のレビューが可能になります。
git checkout -b feature/update-agent-tier - 変更を行う。 必要なファイルを編集します。例えば、エージェントのティアをMarkdownファイルで更新したり、新しいスキルを追加したり、ドキュメントのエラーを修正したりします。編集前にVersion Agentでスナップショットを取得してください。
-
変更をレビューする。 コミット前に、何を変更したかを確認してすべてが正しいことを確認します。
git status # 変更されたファイルを確認 git diff # 実際の差分を表示 -
変更をコミットする。 明確なコンベンショナルコミットメッセージでステージングとコミットを行います。
git add agents/my-agent.md git commit -m "feat(agent): update tier from low to medium" -
/syncを実行する。 説明的なメッセージとともに同期コマンドを実行します。パイプラインが監査を実行し、ライフサイクル記録を更新し、コミットをプッシュし、PRを作成します。
/sync "feat(agent): update tier from low to medium" - PRをレビューしてマージする。 PRが作成されたら、GitHubでレビューします。自動チェックに合格し、変更が正しければ、PRをメインブランチにマージします。
舞台裏で何が起きているか
このワークフローに従うと、システムは各ステップで以下を行います:
docs/lifecycle/agents/のエージェントライフサイクル記録を更新
audit.tsを実行 → ファイル構造、フロントマター、命名規則を検証 → すべてのチェックに合格
/syncコマンドで