パターン作成のオートフロー
$pattern-autoflowは、このリポジトリへ既存の実装を持ち込み、対応する説明と利用可能なZIPを整える入口です。計画・実装・検証・AIレビューは同梱のautoflowが進め、人は設定・重要な判断・最終成果物を確認します。文書だけの修正など依頼が限定されている場合は、その範囲に従います。
準備と呼び出し
運用ルールはAIの判断と出力を安定させるためのものです。利用者に開始前のコミットや退避を求めず、AIと実行基盤が既存変更を保護し、今回の成果物を切り分けます。
Python 3.9以上、Git、利用可能なCodexとサブエージェント機能、Node.js 22以上とサイトの依存関係が必要です。ルートでnpm ciを実行し、E2E用にnpx playwright install chromiumでブラウザーを用意します。準備に失敗したら後続の検証へ進みません。各パターンの検証環境はREADMEとci.jsonに従って別途用意します。
スキルはCodexのリポジトリ内の探索先である.agents/skills/に配置し、$pattern-autoflowで呼び出します。配置と呼び出し方法はCodexのスキル仕様に従います。計画・実装・レビューには、現在のCodex環境のサブエージェント機能を使います。Claude Codeのカスタムエージェント登録は不要です。
プロジェクト直下の.autoflow/には、CLIの入口、Pythonの実行基盤、プロンプト、参照文書、プロファイルをまとめています。実行時にpatterns/内のキットを読み込まないため、配布用パターンを移動・削除してもオートフローの基盤は動きます。検証する対象のコードと、プロファイルが指定する検査コマンド・レビュー文書は、作業するプロジェクトに用意します。
.autoflow/
autoflow.py # CLIの入口
autoflow_kit/ # 段階管理・検証・レビュー・承認の実行基盤
templates/prompts/ # 各役に渡すプロンプトのひな形
references/ # プロファイル・関所・課題取得の説明
profile.json # このプロジェクトの設定
実行基盤はautoflow-kitから導入したローカルのコピーです。基盤を更新するときは、対応するプロンプト・参照文書・検証も同じ変更で確認します。結合テストは.autoflow/だけを一時Gitリポジトリへコピーし、patterns/がない状態で承認・計画・実装報告・検査・レビュー・コミットまで確認します。実モデルの出力はfixtureに置き換えています。
ルートのAGENTS.mdから、計画・実装役がこの手順とpattern-maintenanceを読みます。レビュー役にはprofileのreview.guide_filesに指定した文書の開始時点の写しを渡します。元キットの出力にあるAgent・AskUserQuestionは、スキルがCodexのサブエージェントと人への確認へ読み替えます。役名は論理名として扱い、指定のプロンプト・JSON形式は保ちます。レビューの探索と投票は別の担当にし、同時実行枠に収まらなければ順に起動して全員の完了を待ちます。委任機能がない場合は独立レビューを代作せず、その段で停止します。
最初とプロファイル変更時は$autoflow-setupで設定を確認します。現在の設定に対応する承認がなければH0で承認し、承認済みならそのまま依頼を開始します。H0は検証条件への承認です。Codexのサンドボックス・実行権限は現在の環境の設定に従います。元キットの--allowはClaude Code専用なので、この入口では拒否します。権限設定ファイルは生成しません。
開始時に未コミットの編集や未追跡の移行元があっても保持します。CLIは利用者のステージングを変えずに作業ツリーを記録し、その状態から増えた差分を計画・レビュー・最終承認の対象にします。最終承認後のコミットにも開始後の差分だけを含め、開始前の編集とステージングは残します。同じファイルへの変更が競合して分離できない場合は、実ファイル・ステージング・HEADを保持し、AIが該当箇所と対応案を示します。
$pattern-autoflow <移行元>の実装を<分野>/<分類>/<パターン>へ移行し、説明文書を作成してください
$pattern-autoflow github <Issue番号>
$pattern-autoflow resume <実行ID>
文章では移行元のパスまたはURL、対象パターン、維持したい動作を伝えます。再開では同じ実行IDを使います。実行を始められなければ、エラーと必要な対応を示して停止します。
初期配置したprofile.jsonは設定案です。初期状態ではH0承認記録を生成しないため、実際の設定をsetup-checkで確認して承認するまではstartできません。
python3 .autoflow/autoflow.py setup-check
実行は.autoflow/runs/へ記録され、Git管理から除外されます。プロファイルはGitで管理し、H0承認記録はGitの共通管理領域のautoflow/profile-approvals/<設定のハッシュ>.jsonへ保存します。同じリポジトリの別タスク・別ブランチ・別worktreeでも、設定が一致すれば承認を引き継ぎます。タスクが変わったことを理由に再承認・記録のコミット・削除を求めません。現在の設定に対応する承認がない場合にH0を確認します。別のcloneにはローカル記録を共有しません。
従来の.autoflow/profile-approval.jsonがある場合は、setup-checkまたはstartが設定との一致を確認し、回答原文・記録者・日時を保って共通管理領域へ写します。旧ファイルはGit管理から除外し、新しい承認記録は作業ツリーへ生成しません。移行のために人へ同じ承認を求めません。
移行元から計画へ
計画役は移行元の実ファイルと文書を読み、取得元・版・ライセンス・依存関係・既存検証・必要な隠しファイルを確認します。外部の取得元が読めなければ、推測で再現せず不足を示します。リポジトリ内の実装を正規配置へ移行する依頼では、移行元の片付けも計画範囲と受け入れ条件に含めます。AIは移行先・ZIPとの内容対応と単体動作を確認し、移行先へ含めない固有の記録を作業ツリー外へ保全してから、不要になった移行元を取り除きます。開始前からあったことを理由に移行元を残さず、明示されたコピー依頼・保持指定・リポジトリ外の参照元はその指定に従います。依頼と無関係な既存変更は保持します。
配置はdocs/<分野>/<分類>/<パターン>/index.mdとpatterns/の同じ相対パスです。元実装と変更箇所を対応付け、構造・動作を維持する範囲と、サイトの依存から分離するために変える範囲を計画します。公開済みslugの変更や改名では参照元と古いZIPへの影響も含めます。判断で結果が変わる未決事項はopen_questionsに書き、H1で確認します。
受け入れ条件には、説明と実装の対応、ZIP単体での準備・検証、実際の対象ページの表示確認を含めます。対象実装が既に存在する文書作成依頼では、その実装を根拠に説明を作ります。存在しない実装の動作を確認済みとして書きません。
実装と説明をそろえる
作成・更新の詳細は追加・更新手順、レビュー項目、検証とZIP配布を正とします。新規文書とREADMEはそれぞれのテンプレートから始め、未置換の記入欄を残しません。
本文は全体像から具体的な設定・構造へ進み、実ファイル名と親キーを含むコードから、意味・入力と結果・他の処理との関係・採用理由を説明します。理由が未特定なら、確認済みの動作と分けます。READMEにはZIPだけで使える環境・依存・配置・実行場所・準備・検証・期待結果を記載します。個別のスクリプトとテストは対象パターン内に収録し、ci.jsonで実行方法を指定します。
説明用PNGは必要な場合だけ文書のimagesへ配置します。title・description・slug・紹介情報・ZIPリンクを実装と照合し、生成物を手編集しません。
設定とレビュー範囲
verify.commandsは、配置確認、文書確認、共通テスト、型検査、ビルド、E2Eの順で実行します。各コマンドの上限は600秒です。ビルド前の配置・文書確認を個別に記録し、ビルドが最新のZIPを生成してから対象の検証へ進めるため、この順序にします。
risk.always_humanにはスキル・実行基盤・運用文書・共通スクリプト・サイト実装・CIを含めます。これらは多くのパターンや判定条件に影響するため、計画で対象になるとH1、変更差分に含まれるとH3で人が確認します。依存定義などはhigh、説明文書中心の変更はlowの候補とし、最終的な段は差分と規則で決めます。
limitsはキットの既定値を維持し、検査失敗3回、Importantが残るレビュー3回でH2、計画の範囲20ファイル超でH1、差分400行超でmedium以上、1000行超でhighとします。新規移行ではファイル数が増えるため、広い計画を実装前に確認できます。実行開始時にプロファイルを写し、その実行中には変更しません。
検証から人間の確認へ
プロファイルのverify.commandsは、ルートの配置・文書検査、テスト、型検査、ビルド、E2Eの6コマンドです。ビルドがZIPを生成した後、計画のcommand型の受け入れ条件で対象ZIPの検証を実行します。補助CLIが両方の終了コードとログを差分の版に結び付けます。
npm run verify:patterns -- --id <分野>/<分類>/<パターン> --ci --timeout-ms 1200000
対象が複数なら各対象を計画に列挙します。共通のZIP処理の変更なら全件を対象にします。依存導入などの準備が失敗した場合は個別検証を続けず、失敗または未実施を報告します。command型の受け入れ条件の実行上限はキット既定の600秒です。600秒を超える検証ではこの制限を計画時に示し、手動実行のログと確認をhuman条件に含めます。コマンド末尾の時間設定だけでキットの上限も延びるとは扱いません。
実際の対象ページの本文・コード・PNG・サイト内導線・ZIP取得も確認します。共通E2Eのfixture成功を、対象パターンの表示や動作の確認へ置き換えません。対象文書に確認日・環境・期待結果・実際の結果・未確認事項を残します。
AIレビューは説明の正しさと実装の対応を確認します。人が常に読むパスはプロファイルのrisk.always_human、差分と失敗回数の上限はlimitsで管理します。H1は重要な未決事項や広い計画、H2は行き詰まり、H3は毎回の最終確認です。H3では文書・README・対象サイト・ZIPと検証ログを提示し、人間が説明の分かりやすさや未確認事項を判断します。
回答がなければ承認せず停止します。H3で承認した差分の版のままの場合だけ、共通autoflowが作業ブランチへコミットします。Issueへの投稿・クローズ、push、公開は明示された依頼の範囲でのみ行います。報告書と検査ログは.autoflow/runs/<実行ID>/に残ります。