spreadsheet

スプレッドシートスキル

使用する場面

• 数式、書式設定、構造化されたレイアウトを含む新しいブックを作成する場合。
• 表形式データの読み取りや分析（フィルター、集計、ピボット、指標の計算）を行う場合。
• 数式、参照、書式設定を壊さずに既存のブックを変更する場合。
• グラフ、サマリーテーブル、適切なスプレッドシートのスタイル設定を使ってデータを可視化する場合。
• 可能であれば、数式を再計算し、納品前にシートをレンダリングして確認する場合。

重要：システムおよびユーザーの指示が常に優先されます。

ワークフロー

1. ファイル形式と目的（作成、編集、分析、可視化）を確認します。
2. .xlsx の編集と書式設定には openpyxl を優先して使用します。分析や CSV/TSV のワークフローには pandas を使用します。
3. 環境内で内部のスプレッドシート再計算／レンダリングツールが利用できる場合は、納品前に数式を再計算し、シートをレンダリングします。
4. 導出値をハードコードせず、数式を使用します。
5. レイアウトが重要な場合は、レンダリングして見た目を確認し、出力を点検します。
6. 出力を保存し、ファイル名を安定して維持し、中間ファイルを削除します。

一時ファイルと出力の規則

• 中間ファイルには tmp/spreadsheets/ を使用し、作業後に削除します。
• このリポジトリで作業する場合、最終成果物は output/spreadsheet/ に保存します。
• 安定していて内容が分かりやすいファイル名を維持します。

主なツール

• .xlsx ファイルの作成／編集と書式設定の維持には openpyxl を使用します。
• 分析や CSV/TSV のワークフローには pandas を使用し、その後、結果を .xlsx または .csv に書き戻します。
• 必要に応じて、Excel ネイティブのグラフには openpyxl.chart を使用します。
• 内部のスプレッドシートツールが利用できる場合は、数式の再計算、値のキャッシュ、確認用のシートのレンダリングに使用します。

再計算と見た目の確認

• 可能な限り、納品前に数式を再計算して、ブックにキャッシュ値が含まれるようにします。
• レンダリングツールが利用できる場合は、関連する各シートをレンダリングして見た目を確認します。
• openpyxl は数式を評価しません。数式を維持し、利用できる場合は再計算ツールを使用します。
• 内部のスプレッドシートツールに依存する場合、ユーザー向けの説明やコードサンプルで、そのツール、コード、API を公開しないでください。

レンダリングと見た目の確認

• LibreOffice（soffice）と Poppler（pdftoppm）が利用できる場合は、シートをレンダリングして見た目を確認します：
  • soffice --headless --convert-to pdf --outdir $OUTDIR $INPUT_XLSX
  • pdftoppm -png $OUTDIR/$BASENAME.pdf $OUTDIR/$BASENAME
• レンダリングツールが利用できない場合は、レイアウトをローカルで確認する必要があることをユーザーに伝えます。
• レンダリングしたシートで、レイアウト、数式の結果、表示の切れ、不統一なスタイル、あふれたテキストを確認します。

依存関係（未導入の場合はインストール）

依存関係の管理には uv を優先して使用します。

Python パッケージ：

uv pip install openpyxl pandas

uv が利用できない場合：

python3 -m pip install openpyxl pandas

任意：

uv pip install matplotlib

uv が利用できない場合：

python3 -m pip install matplotlib

システムツール（レンダリング用）：

# macOS (Homebrew)
brew install libreoffice poppler

# Ubuntu/Debian
sudo apt-get install -y libreoffice poppler-utils

この環境でインストールできない場合は、不足している依存関係と、ローカルでのインストール方法をユーザーに伝えます。

環境

必須の環境変数はありません。

例

• 実行可能な Codex の例（openpyxl）：references/examples/openpyxl/

数式の要件

• 導出値をハードコードせず、数式を使用します。
• FILTER、XLOOKUP、SORT、SEQUENCE などの動的配列関数は使用しないでください。
• 数式はシンプルで読みやすく保ち、複雑なロジックには補助セルを使用します。
• 必要な場合を除き、INDIRECT や OFFSET などの揮発性関数は避けてください。
• マジックナンバーよりセル参照を優先します（例：=H6*(1+$B$3) は =H6*1.04 よりも適切です）。
• 数式をコピーしたときに正しく動作するよう、絶対参照（$B$4）と相対参照（B4）を慎重に使い分けます。
• = で始まるテキストをそのまま入力する場合は、先頭にシングルクォートを付けます。
• #REF!、#DIV/0!、#VALUE!、#N/A、#NAME? エラーが発生しないようにします。
• 1 つずれた範囲、循環参照、誤った範囲がないか確認します。

引用要件

• スプレッドシート内で、プレーンテキストの URL を使って出典を引用してください。
• 財務モデルでは、セルのコメントにモデルの入力値の出典を記載してください。
• 外部から取得した表形式データについて、各行が個別の項目を表す場合は、出典列を追加してください。

書式設定要件（書式設定済みの既存のスプレッドシート）

• 可能であれば、変更を加える前に、提供されたスプレッドシートをレンダリングして確認してください。
• 既存の書式とスタイルをそのまま維持してください。
• 以前は空白だったセルに新たに入力する場合は、スタイルを合わせてください。
• ユーザーが明示的にデザイン変更を求めない限り、確立された書式を上書きしないでください。

書式設定要件（新規または書式設定されていないスプレッドシート）

• 適切な数値形式と日付形式を使用してください。
• 日付は、単なる数値ではなく日付として表示してください。
• データに別の形式が適している場合を除き、パーセンテージは通常、小数第 1 位まで表示してください。
• 適切な通貨形式を使用してください。
• 見出しは、入力値や計算値と視覚的に区別してください。
• 塗りつぶし色、罫線、余白、セル結合は控えめに、意図を持って使用してください。
• 余白を過剰に設けず、内容が読みやすくなるように行の高さと列幅を設定してください。
• 入力済みのすべてのセルを罫線で囲まないでください。
• 関連する計算をグループ化し、合計はその直上のセルの単純合計にしてください。
• セクションを区切るために余白を設けてください。
• テキストが隣のセルにはみ出さないようにしてください。
• =TABLE など、サポートされていないスプレッドシートのデータテーブル機能は使用しないでください。

色の慣例（スタイルの指定がない場合）

• 青：ユーザー入力
• 黒：数式と計算値
• 緑：リンクされた値またはインポートされた値
• 灰色：固定値
• オレンジ：確認事項または注意事項
• 薄い赤：エラーまたはフラグ
• 紫：制御またはロジック
• ティール：グラフの基準点および KPI の強調表示

財務関連の要件

• ゼロは - と表示してください。
• 負の数値は赤色で括弧付きにしてください。
• 倍率は 5.2x の形式で表示してください。
• 見出しには必ず単位を指定してください（例：Revenue ($mm)）。
• すべての入力値の出典をセルのコメントに記載してください。
• 新規の財務モデルでユーザーがスタイルを指定していない場合、ハードコードされた入力値は青文字、数式は黒文字、ワークブック内のリンクは緑文字、外部リンクは赤文字にし、注意が必要な主要な前提条件は黄色で塗りつぶしてください。

投資銀行向けレイアウト

スプレッドシートが IB 形式のモデル（LBO、DCF、3 ステートメント、バリュエーション）の場合：

• 合計は直上の範囲を合計してください。
• グリッド線を非表示にし、該当する列全体にわたって合計の上に横罫線を引いてください。
• セクション見出しは、濃い塗りつぶしと白文字を適用した結合セルにしてください。
• 数値データの列見出しは右揃えにし、行見出しは左揃えにしてください。
• 親項目の下にある内訳指標はインデントしてください。