このリポジトリの開発手順(factory-dev)

このリポジトリで開発するときの手順を定める。環境の作り方、変更の進め方、E2Eでの確かめ方を書く。

環境を作る

手順はセットアップにある。資格情報の取得手順はセキュリティにある。miseタスクの一覧はREADMEにある。

ホストに要るのはDockerとmiseだけである。ほかのツールはmise run setupで入る。
秘密値は人が投入する。Claudeはmise.local.toml.exampleの更新までを行う。値が要るときは、セットアップの「秘密値を投入する」のコマンドを示し、止まらずに先へ進む。
docker composeは.envを読まない。mise runを通して実行する。

このリポジトリの変更は、計画の確定、実装、レビュー、修正、再レビューのループで進める。

コミットメッセージは<type>: <日本語の説明>の形にする(例: feat: Issueを拾うpoll_issuesのスケジュールを追加)。typeの一覧はコーディング規約にある。
コードの変更に伴う文書とスキルの更新は、同じコミットに含める。
PRの本文は.github/PULL_REQUEST_TEMPLATE.mdの章立てに従う。Windmillへの反映(マージ後にself_updateが反映するか、次のmise run upで反映されるか)を必ず書く。

mise run doctor、mise run up、mise run bootstrapの後で、次を確かめる。PRの修正のE2Eは、本番のIssueやブランチではなく、捨てブランチと捨てPRで行う。

sandboxのリポジトリで、Issueのテンプレートを使ってIssueを作り、factoryラベルを付ける。
poll_issuesの周期である5分以内に、Discordに通知が届き、Consoleの要対応に表示されることを確かめる。
理由を付けて一度差し戻し、要件定義が作り直されて、もう一度通知が来ることを確かめる。
承認し、IssueにConsoleへのリンクを含むコメントが1件だけ投稿されることを確かめる。要件定義の本文や図は転記されない。ラベルは起動のためだけに使うので、承認してもIssueのラベルは変わらない。
Consoleのレポートの分析に、コストとトークン数が出ることを確かめる。
何かの変更をself cloneに反映させ、self_updateのスケジュールが最新のSHAを取り込むことを確かめる。

上の1から4の後で、sandboxで実装フローを確かめる。sandboxには、factory_configのrepo_allowlistにあるsandboxのリポジトリを使う。f/factory/factory_configはgitで管理しないので、Windmillの画面で編集する。

check_commands_by_repoに、sandboxの検査コマンドを設定する。
```
{"<owner>/<repo>": ["bun install --frozen-lockfile", "bun test"]}
```
implement_enabledをtrueにする。
Issueを起票し、要件定義を作らせ、Consoleで承認する。
実装フローが走ることを確かめる。Consoleの作業項目の表で状態がimplementingになり、ブランチの列にブランチが出る。
PRができると状態がpr_openになり、PRの列にPRが出て、Discordにpr_openedの通知が届くことを確かめる。
PR本文の章立て(受入条件、動作確認結果、確認して欲しい点、Closes #N)を確かめる。
poll_prsがPRを拾い、pr_reviewが自動で走ることを確かめる。実装フローのimplement_finishがfactory:reviewのラベルを付けているので、ラベルを付け直さなくてよい。
下の表の項目を確かめる。
PRを閉じ、ブランチを消し、implement_enabledをfalseに戻す。本番での有効化は、E2Eの結果を確かめてから別に行う。

検査コマンドについては、次の点に注意する。

検査の前にgit clean -fdXがnode_modules/などを消す。依存関係のあるリポジトリでは、先頭のコマンドでインストールする。package.jsonが無いリポジトリならbun testだけでよい。
検査コマンドは、Claudeが書いたコードを非特権のユーザーで、コンテナの分離なしに実行する。Issueを信頼できる人だけが起票するリポジトリにだけ設定する。

implement_enabledについては、次の点に注意する。

falseのままだと、承認した作業項目はapprovedで止まる。retry_work_itemでの再実行も、falseなら拒否する。
インスタンス全体の設定なので、trueの間はrepo_allowlistのほかのリポジトリとfactory_repoでも、承認すると実装フローが走る。pushとPRの作成、対象リポジトリのCIまで進むので、E2Eの間はsandbox以外を承認しない。

確かめること	期待する結果
検査コマンド	ラウンドごとに実行され、`implement_rounds`に記録される
コスト	`agent_runs`にコストが記録される
`--restricted`の書き込み制限	Claudeが`.git`、`.gitattributes`、`.gitleaksignore`、元の要件定義のディレクトリに書けない
Workflowsの権限	PATにWorkflowsの権限が無く、`.github/workflows/`を含む変更のpushが拒否され、人の対応待ちの理由に載る

--restrictedの制限を破って書けた場合は、--restrictedの欠陥として扱い、止めて報告する。書けたときの結果は、書いた先によって次のように違う。

.gitに書けたら、作業項目は人の対応待ち(needs_human)になる。
.gitattributesと.gitleaksignoreは保護パスなので、そのラウンドは検査を飛ばしてPRを作り、PR本文の保護パスの節に載るだけで止まらない。.gitleaksignoreはgitleaksも読まない。
要件定義は、Claudeには書き込めるコピーを渡す。確かめるのは、元の要件定義のディレクトリのファイルが変わっていないことである。

Workflowsの権限は足さない。実装フローは.github/の変更を止めずに記録するので、pushの拒否が実質のガードになる。