この AI Software Factory リポジトリは、製品のミッションと課題から、Archon が作るプルリクエストまでの流れを説明しています。インストールとワークフロー検査は出発点にすぎません。保守者の最初の1時間のガイドでは、実環境での一連の検証は今後必要だとしています。本稿の対象はファクトリーのコミット 9e2d85298b45497031009597a6ae0811b66fe6d6 と、そこで固定された Archon のリビジョン fad09169ea1b43512bc7ee88470d47f960a3e0f8 です。資料とコードを読んだ解説であり、BIG CHANGE が導入・実行した報告ではありません。

対象は、アプリのリポジトリまたは PRD、GitHub の権限、モデル提供元のアカウントを管理するチームです。保守者は、ファクトリーを複製し、自分のリポジトリに導入する手順を明記しています。固定版のファクトリーのツリーにはライセンスや通知ファイルがなく、このガイドはそれ以上の再利用・再配布の権利を示しません。Archon の MIT ライセンスは別の Archon ソースに適用されます。提供元の秘密情報を課題文、プロンプト、ログ、レビュー記録に含めないでください。

大きな変化

  • 変わること： この実装は固定 Archon ワークフローパックで、製品範囲、課題計画、コーディング、独立レビュー、実行時検査を結び付けます。ファクトリーがプロジェクト入力と起動器を提供し、共通パックが AI の各工程を担います。
  • 重要な理由： チームは課題から特定の差分、CI 結果、実行中の候補までたどって、マージを判断できます。導入検査だけでは追跡は不完全であり、保守者も実際の統合検証が残ると述べています。
  • 注目点： 最初の有用な証拠は、実際の課題の納品版が意味のある利用手順と独立ケースに合格し、チームが費用とレビュー記録を確認できることです。定期実行とデプロイはその後も別の判断です。

1. リポジトリ、権限、固定版のソースを確認する

保守者のセットアップ手順が挙げる要件は Git、Python 3.10 以降、認証済みの gh（workflow スコープ付き）、GitHub リモート、コーディングエージェント、Bun、uv です。Git もワークフローファイルをプッシュできる必要があります（gh auth setup-git）。エージェントを起動する前に、既存のテスト・起動・CI コマンド、ブランチ保護、GitHub アクセス、提供元認証、モデル料金を確認します。リポジトリとワークフローには必要な権限だけを付与してください。

アプリのリポジトリの外にファクトリーを複製し、指定コミットをチェックアウトします。資料にあるインストールコマンドは、アプリのルートから実行します。

Terminal
git clone https://github.com/coleam00/ai-software-factory ~/ai-software-factory
git -C ~/ai-software-factory checkout 9e2d85298b45497031009597a6ae0811b66fe6d6
python ~/ai-software-factory/bin/factory.py init

必要なら python3 を使います。インストーラーはファクトリーとプロジェクトのテンプレートをコピーし、pack.json に指定された Archon のソースを導入します。このコミットの README とパックは、どちらも fad09169ea1b43512bc7ee88470d47f960a3e0f8 を指定しています。提供元認証、モデル階層の選択、スケジュール開始は行いません。変更をリポジトリに受け入れる前に、実際のファイル差分を調べてください。

導入済み Archon の設定資料に従って、選んだ提供元と対応モデルの識別子を設定します。実際の静的検査・単体テストコマンドを harness/harness.config.json に記入します。GitHub がブランチ保護を報告できない場合、マージに必要な CI ジョブを required_checks に指定します。protected_paths を確認し、ミッション、検証基盤、ファクトリーポリシーの変更には人が関与するようにします。テンプレートでは通常の検査コマンドと required_checks は空欄です。コピーしただけでは利用可能な受け入れ基準になりません。

2. 現在の製品に合わせてミッションと検証を書く

文書 MISSION.md に製品の目的、厳守する制約、あり得る範囲外の要求を書きます。harness/END-TO-END.md には、現時点のアプリが実際に完了できる利用手順を2～5件、利用者に見える価値とともに記述します。未実装機能を必要とする手順は初回の納品を妨げます。.factory/holdout/HOLDOUT.md には、動作の組み合わせや境界条件を試す別の検証ケースを書きます。このディレクトリ名で、同じ作業コピーにアクセスできる実装者からケースが隠れるわけではありません。本当に非公開のケースは作業コピーの外に置き、検証側だけに渡します。

PRD だけのリポジトリでは、README はその文書からミッション、予定する利用手順、検証コマンドを作るよう求めています。最初の課題案は製品を実行可能にし、起動コマンド、稼働状態とビルド識別の確認パス、テスト、CI を示す必要があります。課題の公開を許可する前に案をレビューしてください。

利用手順を Archon の実行ワークフローが期待するシナリオ入力に変えます。導入された factory/RUNTIME_HOST.md に従い、納品コミットからのアプリのスナップショット、新しい状態、稼働状態とビルド識別の検査、許可された Python または Node の起動コマンドを用意します。資料のホストは、リモートデータベース、コンテナー、クラウド資源を自身が管理する実行資源として扱いません。それらを使うアプリには、別途根拠のある検証構成が必要です。ローカルホストでの合格はそれらの隔離を証明しません。

評価器を信頼する前に、実際の利用価値を試す正常な基準テストを合格させ、関連する意図的な不具合で失敗すること、候補の識別情報が違うと判定不能になることを確認します。ホスト資料にはテスト群の入力と正確な期待フィールドがあり、expectations_passed: true と baseline_verified: true も含まれます。実際のネイティブ応答と候補の識別情報を証拠として保存します。ページが表示されるだけの確認や、テストの最終状態を直接作る方法では不十分です。

3. インストールを確認し、1件の作業を選ぶ

アプリのルートから実行します。

Terminal
python factory/consumer.py doctor
python factory/consumer.py list

doctor は固定ソース、コマンドの機能、使用可能なワークフローを検査します。list は見つかったワークフローを表示します。どちらも提供元が課題を完了できること、CI の合格、アプリの動作を証明しません。納品前に報告された問題を解決し、スケジュールは無効のままにします。

既存コードでは、結果と受け入れ検査が明確な小さな課題を1件書きます。README は、分類、納品、レビューを経てプルリクエストに至る次のコマンドを説明しています。

Terminal
python factory/consumer.py run archon-ship --input target=https://github.com/OWNER/REPO/issues/1 --input discovery_publication=preview --detach --json

課題 URL を管理下のものに差し替えます。discovery_publication=preview を明示すると、レビュー中に見つかった関連事項を課題として公開しません。固定版の archon-ship は省略時に auto を使います。archon-lifecycle は実行シナリオと独立検証用の入力がそろってから使います。課題を target、入力パスを scenario と holdout で渡し、merge_mode=approve と discovery_publication=preview を指定します。プロジェクトが認めた merge_method も必要です。値は merge、squash、rebase のいずれかです。例えば merge_method=squash はリポジトリが許す場合だけ使います。このワークフローには実行時・独立ケースの検証、修復、マージ前の関門があります。承認モードでもマージ前に人が決定します。ワークフローの準備完了表示はその決定ではありません。ファクトリーの実行ホストの文書化された --runtime-host は前面実行のみで、--detach や --resume と併用できません。

PRD に対する文書化されたバックログ作成コマンドは次のとおりです。

Terminal
python factory/consumer.py run archon-backlog --input 'prd=docs/PRD.md' --input publication=approve

引用符付きの docs/PRD.md を、アプリの作業コピーからの実際の相対 PRD パスに置き換えます。公開前に課題案と順序をレビューします。最初の課題が宣言するアプリ起動方法と識別契約に従って実行ホストを接続し、用意した利用手順と独立ケースで archon-lifecycle を実行します。最初の課題も後の作業と同じ厳しさで調べてください。

4. 承認前に差分と動作結果を評価する

返された実行 ID を保存します。制御プログラムには進行と証拠を調べる get <run-id> --json --events と status --all --json があります。課題と計画を MISSION.md と照合し、実際の PR 差分と最新リビジョンの独立レビューを読み、必須 CI と保護パスの報告を確認します。納品リビジョンに対して製品の利用手順を実行し、候補の識別情報を含むネイティブの実行・独立ケースの結果を調べます。観測した利用者の結果を受け入れ基準と比べます。不十分な PR は修復のため差し戻します。README は、マージ待ちで保留された納品実行向けに archon-deliver --adopt <run id> を説明しています。

検査合格後も、マージを承認するのはリポジトリ権限を持つ人だけです。デプロイにはプロジェクト固有のデプロイ・稼働状態・識別コマンドと、デプロイ後のリビジョン再確認が必要です。PR のマージだけではデプロイを証明しません。初回課題の間はスケジュールを無効にし、定期実行を有効にするかは別途決めます。

保守者の費用の説明には実行ごとの固定価格はありません。初日からトークンを計測し、ループを有効にする前に小さな課題1件でモデル呼び出しを観察するよう勧めています。料金は提供元、モデル、アカウント条件次第です。BIG CHANGE はこのファクトリーの支出を測定していません。

実行中の処理にも明示的な停止判断が必要です。制御プログラムのコードでは、halt が新規起動と続行を阻止し、cancel <run-id> が実行中の作業を対象にします。pause はタイマー起動を止めますが、進行中の作業の再起動通知は許します。どのコマンドも現在の実行状態とリモートリポジトリの変化の確認に代わるものではありません。

出典と参考資料