比例縮尺財務諸表リファレンスをCodexで3回レビューして仕上げた

4つのサブエージェントを並行で走らせてコンポーネント構造を洗い出し、Codex（GPT-5.4）にレビューを3回ぶつけて、リファレンスドキュメントを磨き上げた。指摘のたびにドキュメントを書き直して再投入する往復を繰り返し、「中核コンポーネントは概ね再実装可能」という判定を引き出すところまで持っていった。

背景: なぜリファレンスドキュメントが必要か

mdx-playgroundには比例縮尺のBS/PLアニメーション、PLウォーターフォール、CFウォーターフォールなどのVueコンポーネント群がある。これを別プロジェクトに移植するとき、「コードだけ渡しても、設計意図や計算ロジックの勘所が伝わらない」という問題があった。

コンポーネントは合計で数千行。全部読むのは現実的ではないので、再実装に必要な情報だけを抽出したリファレンスを作ることにした。

4サブエージェントによる並行調査

コンポーネント群の全体像を把握するために、4つのサブエージェントで同時に調査を走らせた。

この並行調査の結果を1つのマークダウンにまとめて memo/2026-04-11/proportional-financial-statements-reference.md に保存した。

Codexレビュー 3回の反復

1回目: 5つの重大な指摘

初回レビューで、Codexは5件の問題を突いてきた。

指摘1: CFウォーターフォールのデータ変換が未記載

CashFlowData型からCFWaterfallData型への変換ロジックが抜けていた。beginningCash/endingCashの算出方法、otherInvestingCFの計算式（investingCF - capex - acquisitions - investmentInSecurities）を追記した。

指摘2: SVG座標計算のゼロライン処理

正負混在時のゼロライン位置の決定ロジックが「核心」なのにドキュメントに含まれていなかった。maxPositive / (maxPositive + maxNegative) でゼロライン比率を出す計算式と、マイナス値が微小な場合のフォールバック処理を追加。

指摘3: BS正規化（transform）関数のルール欠落

コンポーネントは入力データをそのまま表示するのではなく、内部のtransform関数で正規化してから表示する。流動資産の分割ルール（「現預金・短期投資」を2項目に分割）、有利子負債の集約と配置順序（短期を最下部、長期を最上部に隣接配置）など、再実装時に必須のルールが丸ごと抜けていた。

指摘4: composableの返却型が不明確

useFinancialData composableが何を返すのか、型シグネチャが書かれていなかった。

指摘5: PLウォーターフォールの日本企業向け拡張ポイント

現行の実装は米国企業向けで経常利益・特別損益のバーがない。日本企業向けに拡張する際のコード挿入ポイントと色定義を明記した。

5件すべてをドキュメントに反映し、再投入。

2回目: 「概ね再実装可能」の判定

Codexは前回の5件中3件が解決済みと判定。残り2件と新規1件の指摘があった。

• 残課題A: CFデータ変換のコード例が疑似コードのままで、実際の計算式が曖昧 → 具体的な算術式に書き直した
• 残課題B: BS正規化のラベルマッチングで日本企業ラベルの例が不足 → '1年内返済予定の長期借入金'、'社債' 等の具体例を追加
• 新規指摘: composableの getCashFromBS がどのBS項目からキャッシュを探すか不明 → 探索ロジックを記載

この回で「中核コンポーネントは概ね再実装可能」という判定が出た。

3回目: スコープ明確化と日本企業対応の詰め

最後のレビューでは、細部の明確化が2件。

• 右カラム9種チャートのスコープ: FinancialChartsPanelが9種のミニチャート（ROE推移、負債比率など）を含むが、どれが必須でどれがオプショナルかが不明だった。スコープを明記し、「右カラムは移植対象外、参考情報として記載」と位置づけた
• getCashFromBSの日本企業向け探索順: 米国企業では Cash and Cash Equivalents → Cash, Cash Equivalents and Short-term Investments の順で探すが、日本企業では '現金及び預金' → '現金及び現金同等物' の順で探索すべき。探索順序を明記した

修正後、Codexから追加の重大指摘はなく、リファレンスとして十分な品質に到達した。

最終的なリファレンスの構成

完成したドキュメントは以下の構成になった。

1. アーキテクチャ概要 - データフロー図、コンポーネント階層
2. 型定義 - そのままコピーできるTypeScript型（BSData, PLDetailedData, CashFlowData等）
3. 比例縮尺BS/PL - flexベースのスケーリング、BS正規化ルール、マイナス値処理、色パレット
4. PLウォーターフォール - 「結果表示 vs フロー」パターン、SVG座標計算、日本企業向け拡張コード
5. CFウォーターフォール - CashFlowData→CFWaterfallData変換、getCashFromBS探索順
6. composable - useFinancialData の返却型とインターフェース

保存先: memo/2026-04-11/proportional-financial-statements-reference.md

教科書的コンテンツの企画

リファレンス作成と並行して、個人開発の教科書的コンテンツの企画を memo/2026-04-11/cf_product_planning.md に書き出した。詳細は省略するが、今日のリファレンス作成プロセス自体が「コンポーネントの知識を構造化して外部に渡す」という行為であり、企画の方向性を考える材料になった。

学びメモ

Codexレビューの回し方

3回のレビューで体感したのは、Codexは「書いてあることの矛盾や欠落」を見つけるのが得意だが、「何を書くべきか」の判断はこちらが握る必要があるということ。1回目の指摘でBS正規化ルールの欠落を突かれたとき、自分では「型定義があれば再実装できる」と思い込んでいたのが崩れた。transform関数の存在を知らなければ、移植先で入力データがそのまま表示されて首をかしげることになる。

「瑣末な点へのクソリプはするな、致命的な点だけ指摘しろ」という指示を毎回入れたのも効いた。3回目にはノイズがほぼなくなり、スコープ明確化と探索順序という実務的な指摘だけが返ってきた。

サブエージェント並行調査のコスト感

4エージェントで並行調査すると、1エージェントで順番に読むより体感2-3倍速い。ただし結果のマージ（4つの調査結果を1つのドキュメントに統合する作業）にそれなりの時間がかかる。調査対象が明確に分割できるケース（今回のように型/BS/PL/CFと独立している場合）では有効だが、依存関係が絡み合うコードでは逆に重複調査が増える。

リファレンスドキュメントの粒度

「コードを丸ごとコピーできるリファレンス」と「設計意図を伝えるリファレンス」は別物。今回は後者を目指したが、Codexの1回目レビューで「疑似コードではなく実際の計算式を」と突かれた箇所もあった。結果として、核心の計算ロジック（SVG座標変換、BS正規化ルール）は具体的なコードで、それ以外は設計意図の説明で、というハイブリッドに落ち着いた。