xlsx-processing-openai

スプレッドシートスキル（作成、編集、分析、可視化）

使用する場面

• 数式、書式設定、構造化されたレイアウトを備えた新しいワークブックを作成する。
• 表形式データを読み取り、分析する（フィルタリング、集計、ピボット、指標の計算）。
• 数式や参照を壊さずに既存のワークブックを変更する。
• チャートや表、適切な書式設定でデータを可視化する。

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

ワークフロー

1. ファイルの種類と目的（作成、編集、分析、可視化）を確認する。
2. .xlsx の編集には openpyxl を、分析および CSV/TSV のワークフローには pandas を使用する。
3. レイアウトが重要な場合は、視覚的な確認のためにレンダリングする（「レンダリングと視覚的なチェック」を参照）。
4. 数式と参照を検証する。openpyxl は数式を評価しないことに注意する。
5. 出力を保存し、中間ファイルを削除する。

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

• 中間ファイルには tmp/spreadsheets/ を使用し、完了後に削除する。
• このリポジトリで作業する場合、最終成果物は output/spreadsheet/ 配下に書き出す。
• ファイル名は安定していて、内容が分かるものにする。

主要なツール

• .xlsx ファイルの作成・編集と書式の維持には openpyxl を使用する。
• 分析および CSV/TSV のワークフローには pandas を使用し、結果を .xlsx または .csv に書き戻す。
• チャートが必要な場合は、ネイティブの Excel チャートを作成できる openpyxl.chart を優先する。

レンダリングと視覚的なチェック

• 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

任意（チャートが多い場合や PDF によるレビューのワークフロー）:

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/

数式の要件

• 結果を直接書き込むのではなく、派生値には数式を使用する。
• 数式はシンプルで読みやすく保ち、複雑なロジックには補助セルを使用する。
• 必要でない限り、INDIRECT や OFFSET などの揮発性関数は避ける。
• マジックナンバーよりセル参照を優先する（例: =1.04 ではなく =H6*(1+$B$3)）。
• 検証とチェックにより、エラー（#REF!、#DIV/0!、#VALUE!、#N/A、#NAME?）を防止する。
• openpyxl は数式を評価しないため、数式はそのまま残し、結果は Excel/Sheets で計算されることを明記する。

出典の要件

• スプレッドシート内では、出典をプレーンテキストの URL で示す。
• 財務モデルの場合は、入力値の出典をセルコメントに記載する。
• Web から取得した表形式データには、URL を記載した出典列を含める。

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

• 可能な場合は、変更前に提供されたスプレッドシートをレンダリングして確認する。
• 既存の書式とスタイルを正確に維持する。
• 以前は空白だったセルに新たに入力する場合は、周囲のスタイルに合わせる。

書式設定の要件（新規または未書式のスプレッドシート）

• 適切な数値および日付の書式を使用する（日付は日付として、通貨には記号を付け、パーセンテージは適切な精度で表示する）。
• 見やすいレイアウトにする。見出しはデータと明確に区別し、間隔を揃え、列幅は読みやすくする。
• すべてのセルに罫線を付けないようにし、余白と必要な罫線を使ってセクションを区切る。
• テキストが隣接するセルにはみ出さないようにする。

配色の規則（スタイルの指定がない場合）

• 青: ユーザー入力
• 黒: 数式・派生値
• 緑: リンク・インポートされた値
• グレー: 静的な定数
• オレンジ: レビュー・注意
• 薄い赤: エラー・フラグ
• 紫: 制御・ロジック
• ティール: 可視化の基点（主要 KPI やチャートの主要データ）

金融固有の要件

• ゼロは「-」と表示する。
• 負の数は赤字で括弧付きにする。
• ヘッダーには常に単位を明記する（例：「売上高（百万ドル）」）。
• すべての生データの入力値には、セルコメントで出典を明記する。

投資銀行向けのレイアウト

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

• 合計は直上の範囲をそのまま合計する。
• グリッド線は非表示にし、関連する列の合計行の上に水平罫線を引く。
• セクションヘッダーは、濃い塗りつぶしと白い文字の結合セルにする。
• 数値データの列ラベルは右揃え、行ラベルは左揃えにする。
• サブ指標は、親の項目の下に字下げして表示する。