ryryo architecture-refactor-loop
コードベースを一気に書き換えず、現状把握、フェーズ計画、goal file、委譲判定、実装、検証、Codex 側レビュー、変更結果の記録、再監査の単位で進める。main Codex が設計判断・採否・統合・レビュー・完了判定を持ち、分離できる局所作業だけを必要に応じて worker に委譲する。
絶対ルール
- main Codex がアーキテクチャ方針、委譲判定、統合、レビュー、完了判定を担当する。
- Cursor CLI worker は必須ではない。ただし各 goal の実装前に、Cursor CLI worker に委譲するかどうかを必ず明示的に判定し、使わない場合も理由を記録する。
- 実装前委譲判定記録を書かずにコード編集へ入らない。ログや
PROGRESS_FILEにCursor CLI worker 判定が出ていない実装は手順違反として扱う。 - Cursor CLI worker にレビュー、採否判断、完了判断、version control／remote操作を任せない。
- レビューは Codex 側で行う。可能なら Codex subagent に read-only fresh review を依頼し、難しければ main Codex が code-review stance で差分レビューする。
- 既存挙動、公開 API、保存形式、データ形式、schema、URL、イベント順、error semantics、外部副作用を意図なく変えない。
- 外部 state、production data、secret、remote migration、課金や権限に関わる操作は明示許可なしに行わない。
- 既存のユーザー変更を戻さない。関係がある場合は差分を読んで作業し、関係がなければ触らない。
- 「好みの整理」だけでは goal にしない。各 goal は具体的な architecture pain、受け入れ条件、検証方法を持つ。
/tmpの進捗ファイルと goal file は一時的な作業管理用であり、ユーザーが永続化を求めない限り成果物へ含めない。
Read-only audit mode
利用者または呼出元スキルがread-only audit modeを指定した場合、この節を通常の作業ディレクトリ、goal file、委譲判定、実装ループ、再監査より優先する。
- repositoryと指定scopeをfreshに読み、編集、進捗file作成、テスト／build実行、Cursor CLI、version control、外部作用を行わない。
- 許容された既存差分を
git status --shortで確認し、baselineと現在差分の両方を監査する。 - 実行入口、データフロー、state owner、副作用／resource、public contract、module境界、依存方向、test seamをmapにする。
- 責務境界、依存方向、state ownership、副作用、contract保護、test seam、runtime riskを一件目で止めずに一巡する。
- 行数、命名、好み、到達不能な推測だけをfindingへ昇格させない。
- audit agentは採否、goal化、実装、完了判定をせず、一回のfresh reportを返して停止する。
出力には次を含める。
- 実際に確認したscopeとpath
- architecture map
- 全観点のfinding sweep
- findingごとのseverity、path／line、到達する因果経路、破られるcontractまたはarchitecture pain、最小修正境界、既存oracle
- 既に差分で直っている問題、却下／deferした候補と理由
追加のP0／P1／P2がなければNO_FINDINGSとする。read-only audit modeはここで終了する。
作業ディレクトリ
project name は repository basename を小文字英数字とハイフンに正規化して決める。
PROJECT_NAME="<repo-basename-normalized>"
REF_DIR="/tmp/refactor-$PROJECT_NAME"
PROGRESS_FILE="/tmp/refactor-$PROJECT_NAME.md"
GOALS_DIR="$REF_DIR/goals"
mkdir -p "$GOALS_DIR"
PROGRESS_FILE にはフェーズ、goal、委譲判定、検証、レビュー、変更path、残課題を追記する。GOALS_DIR には G01_<slug>.md のような goal file を作る。
/tmp が使えない環境では、理由を記録したうえで .codex/tmp/{YYMMDD}_architecture-refactor-{projectname}/ を使う。
Phase 0: 現状把握
まず repository を読む。必要な範囲に絞りつつ、architecture 判断に必要な入口は必ず確認する。
git status --short
読む対象の目安:
AGENTS.md、README、package / build / test 設定。- entrypoint、routing、CLI command、server handler、主要 module。
- domain / application / infrastructure / UI / adapter の境界。
- state、cache、DB、filesystem、network、time、random などの副作用境界。
- public API、schema、payload、event、error handling。
- 既存 test、fixture、mock、integration check。
- 依存方向、循環依存、巨大 module、重複 logic、暗黙 global state。
現状把握の結果を PROGRESS_FILE に短く書く。
## 現状把握
- 対象:
- 主要 entrypoint:
- 検証コマンド:
- architecture pain:
- 守る contract:
- 既存のユーザー変更:
Discovery Gate
満足条件やフェーズ計画を作る前に、初回洞察が浅すぎないかを必ず確認する。最初に見つけた 1 つの問題だけを goal 化して終わってはいけない。
Discovery Gate では、少なくとも以下を PROGRESS_FILE に書く。
## Architecture Map
- 実行入口:
- 主要データフロー:
- 主要 state owner:
- 副作用境界:
- public contract:
- 層 / module 境界:
- 依存方向:
- 検証境界:
## Architecture Finding Sweep
| 観点 | 確認した場所 | finding | severity | 対応 |
| --------------- | ------------ | ------- | ---------------- | --------------- |
| 責務境界 | | | P0/P1/P2/P3/なし | goal/defer/なし |
| 依存方向 | | | P0/P1/P2/P3/なし | goal/defer/なし |
| state ownership | | | P0/P1/P2/P3/なし | goal/defer/なし |
| 副作用境界 | | | P0/P1/P2/P3/なし | goal/defer/なし |
| contract 保護 | | | P0/P1/P2/P3/なし | goal/defer/なし |
| test seam | | | P0/P1/P2/P3/なし | goal/defer/なし |
| 実行時リスク | | | P0/P1/P2/P3/なし | goal/defer/なし |
severity の目安:
- P0: 既存挙動、データ、安全性、ビルド、リリースを壊す恐れが高い。
- P1: architecture 上の主要な詰まりで、今後の変更を明確に危険または高コストにしている。
- P2: 分離・依存・検証性の悪さがあり、今回の scope で直す価値がある。
- P3: 好みや小規模整理に近く、他 goal のついででよい。
浅い計画として差し戻す条件:
- 実行入口、データフロー、state owner、副作用境界、public contract のいずれかを説明できていない。
- finding が 1 件だけで、他の観点を「なし」と判断した根拠がない。
- phase が 1 つだけで、検証基盤、境界整理、依存整理、状態・副作用、contract 保護、最終監査のどれを扱うかが見えていない。
- goal が実装手順だけで、どの architecture pain を解消するか書けていない。
- 「満足条件」が特定ファイルの修正完了だけになっている。
Discovery Gate を通すには、全観点で finding または「なし」の根拠を書き、P1 / P2 を goal 化するか、defer 理由を明示する。P3 だけが残る状態を最初の満足条件の候補にしてよい。
満足条件
「満足できるまで」を無限ループにしない。Phase 0 の後に、今回の完了条件を明示する。
満足条件は Discovery Gate の結果から作る。特定の 1 問題を直すだけの条件にしない。対象範囲に対して、どの architecture 観点を調べ、どの P1 / P2 を解消し、何を defer するかが分かる形にする。
満足条件の例:
- 対象範囲の P0 / P1 / P2 architecture finding が解消済み、または明示的に defer 済み。
- module boundary、依存方向、state ownership、副作用境界、test seam の主要な不整合が説明できる状態になっている。
- 変更した public contract がない、または明示承認された contract 変更だけである。
- 重要な goal ごとに実動作確認または代替検証が済んでいる。
- Codex 側レビューで blocking finding がない。
- 各integration batchの変更pathと検証結果が記録済みで、未確認の対象差分が残っていない。
満足条件は PROGRESS_FILE に書く。途中で変更する場合は、理由と変更日を追記する。
フェーズ計画
現状把握後に、3 から 7 個程度の phase に分ける。phase は成果物や境界で切る。
フェーズ計画は Discovery Gate の finding sweep から作る。1 つの目立つ問題だけを phase にしない。少なくとも「安全網または検証」「境界または依存方向」「最終監査」を含め、不要な phase は理由を付けて省く。
よく使う phase:
- Foundation: 検証基盤、characterization test、型境界、最小 safety net。
- Boundary: module / layer / package / route / adapter 境界の整理。
- Dependency: 依存方向、循環参照、barrel、shared utility の整理。
- State and Side Effects: state ownership、cache、I/O、timer、random、network 境界。
- Contract Preservation: public API、schema、payload、error semantics の保護。
- Cleanup: dead code、重複削減、命名、不要 compatibility の整理。
- Final Audit: 再監査、残課題 defer、最終検証。
phase ごとに goal 候補を作る。大きい goal は分割し、小さすぎる goal は同じ検証で安全に見られる単位へまとめる。
Goal File Contract
各 goal file は GOALS_DIR/Gxx_<slug>.md に作る。goal file はその goal の実行契約であり、実装前に必ず書く。
# Gxx: <goal title>
## 目的
<この goal で改善する architecture pain>
## 現状
- 対象:
- 問題:
- 守る既存挙動:
## 望む構造
- 責務境界:
- 依存方向:
- state / side effect ownership:
- test seam:
## 委譲判定
- owner: main-codex | codex-subagent-readonly | cursor-cli-worker | no-delegation
- 理由:
- Cursor CLI worker 判定: use | not-use | unavailable
- Cursor CLI worker 判定理由:
- Codex subagent 判定: use | not-use | unavailable
- Codex subagent 判定理由:
- read scope:
- write scope:
- 禁止範囲:
- worker を使う場合の検収方法:
## 実装方針
- steps:
- migration / compatibility:
- rollback risk:
## 受け入れ条件
- [ ] 既存挙動を変えない
- [ ] architecture pain が解消または明示的に defer されている
- [ ] 必要な test / typecheck / build / smoke が通る
- [ ] Codex 側レビューで blocking finding がない
## 検証
- command:
- 手動 smoke:
- 実行できない場合の代替確認:
## レビュー
- reviewer: main-codex | codex-subagent-readonly
- review focus:
## 変更結果
- changed paths:
- verification result:
ユーザーが /goal 実行を明示した環境では、goal file をそのまま /goal の入力単位として扱う。そうでない環境では、main Codex が goal file を読み、その契約に沿って直接実行する。
委譲判定ゲート
委譲判定は、goal 作成時と実行直前の 2 回行う。実行直前に状況が変わっていたら goal file と PROGRESS_FILE を更新する。実装直前の判定は独立したステップとして行い、判定記録を書いてからでなければコードを編集しない。
実装前委譲判定記録は、各 goal で必ずこの形で PROGRESS_FILE と goal file に残す。
## 実装前委譲判定記録
- Goal:
- Cursor CLI worker 判定: use | not-use | unavailable
- Cursor CLI worker 判定理由:
- cursor-agent-sprint-cli path check: exists | missing | not-needed
- Codex subagent 判定: use | not-use | unavailable
- Codex subagent 判定理由:
- main Codex が直接持つ判断:
- owner: main-codex | codex-subagent-readonly | cursor-cli-worker | no-delegation
- 実装前停止確認: 記録済み
Cursor CLI worker 判定 は、最終 owner が main Codex でも省略しない。使わない場合は、contract 判断を含む、write scope が広い、検証が曖昧、既存のユーザー変更に触れる、preflight 不可、などの具体的理由を書く。
main Codex が直接担当する:
- architecture 方針、責務境界、依存方向、public contract を決める。
- 複数 module / layer にまたがる変更を統合する。
- 既存挙動や暗黙 contract の解釈が必要。
- migration、schema、API、auth、storage、routing、external state に関わる。
- 失敗時の rollback 判断が難しい。
- 既存のユーザー変更に触れる。
- 検証方法が曖昧。
Codex subagent に委譲してよい:
- read-only の architecture audit。
- 設計案比較。
- diff review。
- test strategy / risk analysis。
- fresh review。
Cursor CLI worker に委譲してよい:
- write scope が明確で狭い。
- 他 task とファイル競合しない。
- contract 判断を含まない。
- acceptance と verification を具体的に書ける。
- main Codex が後で diff review できる。
Cursor CLI worker 判定の手順:
- goal の write scope が単一または少数ファイルに閉じるか確認する。
- architecture 方針、public contract、依存方向の判断が worker 側に漏れないか確認する。
- acceptance と verification を worker prompt に具体的に書けるか確認する。
- 他 goal / 他 worker と write scope が競合しないか確認する。
- 使う候補になった場合だけ、
WORKSPACE/.codex/skills/dev/cursor-agent-sprint-cliの存在確認と preflight を行う。 - 使わない場合も
Cursor CLI worker 判定: not-useと理由を記録する。
Cursor CLI worker を使う場合は、WORKSPACE/.codex/skills/dev/cursor-agent-sprint-cli をパス参照し、そのスキルの preflight、prompt、monitor、diff 検収手順に従う。存在しない、preflight が通らない、または write scope を分離できない場合は使わない。
委譲しない:
- 分離できない。
- 判断が曖昧。
- 検証方法がない。
- worker に渡すほど小さくない、または危険。
実装ループ
各 goal は以下の順に進める。
- goal file を読む。
- 委譲判定ゲートを通す。
実装前委譲判定記録をPROGRESS_FILEと goal file に書く。Cursor CLI worker 判定が記録されていることを確認する。- 実装前に必要な safety check または characterization test を作る。
- main Codex または選定 worker が実装する。
- main Codex が diff と write scope を確認する。
- 必須検証を実行する。
- Codex 側レビューを行う。
- blocking finding があれば修正し、検証とレビューを繰り返す。
PROGRESS_FILEを更新する。- 変更pathと検証結果を
PROGRESS_FILEへ記録する。
検証の優先順:
- focused test / characterization test
- typecheck
- lint
- integration test
- build
- smoke / browser / CLI 実行
検証できない場合は、理由、代替確認、残リスクを PROGRESS_FILE と final report に書く。
Codex 側レビュー
レビューは必ず Codex 側で行う。Cursor CLI worker の報告は参考情報であり、レビュー結果ではない。
レビュー観点:
- 既存挙動、public contract、error semantics を変えていないか。
- 依存方向が改善しているか。新しい循環依存や層越え依存を作っていないか。
- 責務境界が明確か。巨大 helper や曖昧な shared module に逃げていないか。
- state ownership と副作用境界が明確か。
- テスト容易性が上がっているか。単に mock が増えただけになっていないか。
- 変更範囲が goal の write scope に収まっているか。
- 既存のユーザー変更を戻していないか。
- 削除した code が本当に不要か。
- performance、concurrency、resource lifecycle に新しい risk がないか。
Codex subagent が使える場合は、重要 goal または phase 完了時に read-only fresh review を依頼してよい。依頼する場合も、採否判断は main Codex が行う。
進捗記録
PROGRESS_FILE は短く、実行判断に必要な情報だけを書く。
# Refactor Progress: <project>
## 満足条件
- ...
## Phase Plan
| Phase | Goal | Owner | Status | Changed paths | Verification |
| ----- | ---- | ----- | ------ | ------ | ------------ |
## Current Findings
- P0:
- P1:
- P2:
- Deferred:
## Activity Log
### <date> Gxx <title>
- 委譲判定:
- Cursor CLI worker 判定:
- Cursor CLI worker 判定理由:
- Codex subagent 判定:
- owner:
- 変更:
- 検証:
- Codex review:
- changed paths:
- 残リスク:
PROGRESS_FILE は最終 report の材料にする。長い調査ログや思考過程を溜め込まない。
再監査と完了判定
phase 完了ごとに architecture audit を行う。audit は main Codex または Codex subagent の read-only review として行い、Cursor CLI worker には完了判定を任せない。
再監査で新しい P0 / P1 / P2 finding が出た場合:
- 今回の満足条件に含めるべきなら goal を追加する。
- 今回の scope 外なら理由を付けて deferred にする。
- 判断できないならユーザーに確認する。
完了時は最終検証を実行し、作業ツリーを確認する。
git status --short
最終報告
最終報告には以下を含める。
- 対象範囲。
- 満足条件に対する結果。
- phase / goal 一覧。
- main Codex が直接担当した設計判断。
- worker に委譲した task と、その検収結果。
- Codex 側レビュー結果。
- 実行した検証と結果。
- 変更path一覧。
- deferred item と残リスク。
長い progress file の全文は貼らず、判断に必要な要約だけを書く。