CFスキル体系を再編しExcel生成ルールを整備した
朝、スキルファイルの一覧を開いたとき、cf-lifecycle-journal.md の守備範囲が広すぎることに気づいた。借入金も貸付金も資本政策も1ファイルに詰め込まれていて、論点を追加するたびにファイルが膨れていく。今日はこのスキル体系を解体・再編するところから始めて、最終的にExcel生成ルールの明文化まで一気に走った。
スキルファイルの分離とリネーム
cf-lifecycle-journal.md には3つの領域が同居していた。借入金、貸付金、資本政策。このうち資本政策は勘定科目の性質も生成スクリプトもまったく別物で、同じファイルに押し込む理由がない。
まず資本政策（305_資本政策）を cf-lifecycle-equity-policy.md として独立させた。次に、元ファイルを borrowing-lending に特化したファイルにリネームした。1ファイル1責務になったことで、スキルを読むときに「今どの論点の話か」で迷わなくなった。
さらに全スキルファイルにスクリプトマッピングテーブルを追加した。論点番号、対応するPythonスクリプト、出力ファイル名の3列を並べたテーブルで、「この論点のExcelはどのスクリプトで生成するのか」が一覧で分かる。
review-cf-skills スラッシュコマンドの新設
スキルファイルが増えると、ファイル間の整合性が崩れやすくなる。あるスキルでは gen_cfws_multi_year.py と書いているのに、別のスキルでは旧名の gen_cfws.py を参照している、といった不一致が実際に起きていた。
これを防ぐために review-cf-skills スラッシュコマンドを新設した。全スキルファイルとスクリプトをスキャンして、以下を検証する。
- スクリプトマッピングテーブルのファイル名が実在するか
- スキル間で同一スクリプトの名前が一致しているか
- 出力ファイルの命名規則に違反がないか
Codexレビューで2件の致命的指摘
作り終えたレビューコマンドをCodexに投げたところ、2件の致命的な指摘が返ってきた。
1つ目は、スキルファイルのパスをハードコードしていた点。ディレクトリ構造が変わった瞬間にコマンド全体が壊れる。glob パターンで動的に探索する方式に書き直した。
2つ目は、レビュー結果の出力が成功時に何も表示しない設計だった点。「問題なし」なのか「実行されていない」のか区別できない。成功時にも件数サマリーを出すように修正した。
軽微な指摘は無視して、この2件だけ対応してからマージした。
シート命名規則の三転 --- TPL から TXN、そして「取引_」へ
今日いちばん時間を食ったのが、シート命名規則の変更だった。
第1案: TPL_（テンプレート）
最初は TPL_返済予定表 のようにテンプレートの略称を接頭辞にしていた。しかし実際にはテンプレートではなく、取引データそのものが入っている。名前と中身が噛み合っていない。
第2案: TXN_（トランザクション）
次に TXN_返済予定表 に変えた。英語略称で統一する方針。ところが他のシート名は日本語（「年次推移表」「CF精算表」など）なので、接頭辞だけ英語が浮く。タブを並べて見たときに視認性が落ちる。
最終案: 取引_（漢字2文字）
最終的に 取引_返済予定表 に落ち着いた。漢字2文字なら幅も短く、日本語のシート名に溶け込む。
11ファイルの一括置換を実行した。Pythonスクリプト内のシート名参照、スキルファイル内の記述、テストの期待値をすべて 取引_ に揃えた。ただし memo/ 配下の議事録や検討履歴はそのまま残した。過去の経緯が消えると「なぜこの名前にしたか」を追えなくなる。
Excel生成ルールの明文化
スクリプトが増えるにつれて、生成されるExcelのフォーマットがスクリプトごとにバラつき始めていた。あるスクリプトは小計行をデータ領域に含め、別のスクリプトは集計関数で別セルに出している。ルールが頭の中にしかない状態を脱するため、excel-generation.md に原則を書き出した。
データとビューを分ける
最も大事な原則。小計行や合計行をデータ領域に混ぜない。データ領域は個別取引だけを並べ、集計はSUMIFS関数で別の領域に置く。
理由は単純で、小計行がデータに紛れると、フィルタやピボットテーブルで二重計上が起きる。データ領域を「生の事実だけ」に保てば、どんな切り口で集計しても壊れない。
タイトル行の書式変更
従来は紺色背景に白文字というヘッダースタイルを使っていたが、印刷すると黒く潰れて読めない場面があった。ミディアムグレー背景 + 白太字14pt に変更した。画面でも印刷でも視認性が安定する。
この変更はIBフォーマットスキル側にも反映した。スキルとスクリプトで書式が食い違うと、「どちらが正なのか」で毎回迷うことになるので、変更は必ず両方に入れる。
ファイルロック時の対応ルール
openpyxl で .save() を呼んだとき、対象ファイルがExcelで開かれているとPermissionErrorで落ちる。これまではエラーが出るたびにExcelを閉じて再実行していたが、閉じ忘れてデータが消えるリスクがある。
ルールを決めた。ロック検出時は上書きせず、タイムスタンプ付きの新ファイルに保存する。 CF_borrowing_20260404_143052.xlsx のように日時を末尾に付ける。CLAUDE.mdにも追記して、全スクリプトで統一した。
年次推移表のフォーマット不整合修正
CFWS生成パイプラインの中で、年次推移表シートのフォーマットだけが浮いていた。スタンドアロン版の gen_annual_table.py では太字・青文字・インデントが適用されているのに、CFWS内の create_annual_sheet 関数ではプレーンテキストのまま出力されていた。
原因はシンプルで、create_annual_sheet をCFWS用に書き直したとき、フォーマット処理をコピーし忘れていた。スタンドアロン版から書式設定のコードを移植して、両者の見た目を揃えた。
今日の学び
スキルファイルもコードと同じで、1ファイルに責務を詰め込みすぎると読む人が迷子になる。分割した瞬間に「この論点はこのファイルを開けばいい」と指が迷わなくなった。
命名規則を3回変えたのは一見ロスに見えるが、TPLのままだったら「テンプレートなのにデータが入っている」という認知のズレをずっと抱えることになった。名前が実態を正確に指すまでリネームを繰り返すほうが、長い目で見ると手戻りが減る。
Codexレビューの「成功時にも結果を表示せよ」という指摘は、自分では気づけなかった。作った本人は「何も出なければ成功」と知っているが、初見の人間には沈黙と故障の区別がつかない。ツールのUIは「知らない人が使う」前提で設計する、という当たり前のことを改めて叩き込まれた。