xlsx-report-builder

# xlsx-report-builder Excel 帳票を作るスキル。**基本の使い方は、依頼のフレーズから流れ（フロー）を選んで進める**こと。個々のサブコマンドを直接呼ぶ使い方は、オプション（[サブコマンド一覧](#サブコマンド一覧個別に呼ぶ場合)）。 - テンプレート（体裁の決まった .xlsx）がある → 既存の書式を保ったまま、データを流し込む（罫線・フォント・セル色・列幅・図・グラフはそのまま） - テンプレートが無い → JSON スペックから新規に生成する パスはこの SKILL.md からの相対パス。コマンド実行前にこのディレクトリに `cd` すること。 ## 起動手順 スキル開始時に必ず実行する: ```bash cd .github/skills/xlsx-report-builder uv sync ``` ## 使い方: フレーズ → フロー 依頼のフレーズから、次のどれかのフローを選ぶ。判断がつかないときは、まず「テンプレートはありますか。ある場合、どこで作られたものですか」と聞く。 | # | 依頼のフレーズ（例） | フロー（→ は順に進む。【確認】はユーザーに確認する） | 使うサブコマンド | |---|----------------------|------------------------------------------------------|------------------| | 1 | 「このExcelにデータを入れて」「テンプレートに流し込んで」「この書式のままxlsxを作って」「他のプロジェクトの成果物を元に作って」「去年の報告書を雛形にして」 | 出所を聞く【流用なら可否を確認】→ テンプレートの事実を読む → 範囲ごとに 残す/流し込む/繰り返す/無視する/文書の値 を決める【確認】→ 定義を確定して検査 → データを用意 → 再構成 → 読み返して検証 | `inspect`・`analyze`・`check`・`render` | | 2 | 「今月分も同じ帳票で作って」「同じ形式でもう一度」（定義が確定済み） | データを用意 → 再構成（専用スクリプトがあればそれを実行）→ 検証 | `render`（または専用スクリプト） | | 3 | 「列を足して」「テンプレートが更新された」「入れる欄を変えたい」 | 既存の定義（専用スクリプトなら埋め込みの定義）を取り出す → 定義を直す【確認】→ 検査 → 書き出し直す／再構成。表の構造が変わったなら #1 に戻る | `export --from-script`・`check`・`render` | | 4 | 「毎回使えるスクリプトにして」「LLM なしで回せるように」「単体で動くようにして」 | 定義を確定して検査 → 専用の単体スクリプトを書き出す → 動作を確かめる | `check`・`export` | | 5 | 「Excelを作って」「集計表を作って」「売上レポートをExcelで」（テンプレート無し） | データと体裁を確認 → JSON スペックを組む → 生成 → 検証 | `example`・`build` | | 6 | 「このExcelの構造を教えて」「どこが入力欄か調べて」「サンプルの値が残っていないか見て」 | テンプレートの事実を読む → 結果を要約して返す（生成はしない） | `inspect`（`analyze`） | - #1 の「流用」（他プロジェクトの成果物）は、同じフローに流用の可否の確認を足す。値・メタデータを持ち越さない決めごと（`strict`・`keep`・`properties.scrub`）は、流用でなくても既定で入る。詳細は [T2](#t2-範囲ごとに役割を決める) の「前の文書の値・メタデータを持ち越さない」 - #1・#3 の LLM の関与は、判断（範囲の役割・定義）とデータの用意まで。`check`・`render`・`export` と、書き出した専用スクリプトは、決まった処理だけで動く - #2・#4 は、定義が確定していることが前提。無ければ #1 から ## フローの詳細: 新規生成（#5） ### Step 1: データと出力イメージを確認する 1. 元データの所在（ユーザー提示・CSV・DB クエリ結果・コード生成等）を確認する 2. 帳票の体裁を確認する: シート構成・列・数値書式（通貨/パーセント/日付）・合計の要否・グラフの要否 3. 不明点（通貨単位・小数桁・期間の粒度など）があれば確認する。**勝手に数値を捏造しない** ### Step 2: JSON スペックを組み立てる スペックの構造は [references/spec.md](references/spec.md) を参照。雛形は次で取得できる: ```bash uv run python scripts/xlsx_builder.py example ``` ポイント: - `columns[].key` と `rows[]` のキーを一致させる - 金額は `number_format: "¥#,##0"`、率は `"0.0%"`、日付は `"yyyy-mm-dd"`（ISO 文字列は自動で日付型に変換） - 合計が必要なら `total_row.sums` に対象列を指定（`SUM` 数式が入る） - 見出し固定は `freeze: "A2"`、絞り込みは `auto_filter: true` 組み立てたスペックは作業ファイル（例 `spec.json`）に保存する。 ### Step 3: 生成する ```bash uv run python scripts/xlsx_builder.py build --spec spec.json # または stdin から cat spec.json | uv run python scripts/xlsx_builder.py build ``` `filename` に指定したパスへ `.xlsx` が出力される。 ### Step 4: 検証して引き渡す 1. 生成された行数・合計・書式が意図通りか確認する（必要なら openpyxl で読み返す） 2. 出力ファイルのパスをユーザーに伝える ## フローの詳細: テンプレートへの流し込み（#1〜#4） テンプレートはサンプル値が入っていることが多く、表の行数も可変になる。他のプロジェクトの成果物を流用する場合は、実データやメタデータも入っている。そこで、**事実を読む → 役割を決める（確認あり）→ 定義を確定して検査する → データで再構成する**、の順で行う。不変部分（書式・列幅・図・グラフ・他シート）は元のままコピーされる。詳細は [references/template.md](references/template.md)。 ### 段の一覧 ``` T0 出所と流用の可否を確認 ──→ T1 inspect（事実を読む）──→ T2 役割を決める ──→ ユーザー確認 │ T6 検証 ←── T5 export（繰り返すなら）←── T4 render ←── T3 check（定義の検査）←──┘ ``` | 段 | 何をするか | 誰が | コマンド | |----|-----------|------|----------| | T0 | テンプレートの出所を聞く。他プロジェクトの成果物なら、流用してよいか（社外秘・個人情報・権利）を確認する | LLM → ユーザー | — | | T1 | テンプレートの事実（値・数式・書式の種類・結合・仮値の疑い・**来歴**）を読む | コマンド → LLM | `inspect` / `analyze` | | T2 | 範囲ごとに 残す・流し込む・繰り返す・無視する・文書の値 を決め、一覧をユーザーに確認してもらう | LLM + ユーザー | — | | T3 | 定義を確定し、整合と「テンプレートの値の残り」を検査する | コマンド | `check` | | T4 | データを用意して再構成する | コマンド（LLM なし） | `render` | | T5 | 同じ帳票を繰り返し作るなら、専用の単体スクリプトにする（LLM なしで毎回動く） | コマンド | `export` | | T6 | 出力を読み返して確かめる | LLM / コマンド | — | LLM が関わるのは T0〜T3 だけ。T4 以降は、定義とデータが同じなら、LLM なしで同じ結果が出る。 ### T0: 出所と流用の可否を確認する テンプレートの出所をユーザーに聞く。**他のプロジェクトの成果物（実データが入ったもの）を流用する場合**は、次を確認してから進める。 - 流用してよいか（社外秘・個人情報・権利）。許可が不明なら進めない - 元の値を、どれだけ残してよいか（ラベルや見出しだけか、固定の文面も残すか） - 出力を渡す相手。元のプロジェクトを知らない相手なら、持ち越しを特に厳しく検査する（T2 の「前の文書の値・メタデータを持ち越さない」） ### T1: テンプレートの事実を読む ```bash uv run python scripts/xlsx_builder.py inspect path/to/template.xlsx # 判断用の事実（--json も可） uv run python scripts/xlsx_builder.py analyze path/to/template.xlsx -o def.yaml # 定義の下書き（自動検出） ``` `inspect` は、次を出す。 - 行ごとの値・数式・書式の種類（同じ見た目は同じ番号）・結合・条件付き書式・入力規則 - **仮の値の疑い**（`サンプル`・`〇〇`・`yyyy` など）と**注記の疑い**（`※`）、同じ書式が続く範囲 - **来歴・持ち越しの注意**: 文書のプロパティ（作成者・会社名・タイトル）、プレビュー画像、コメント（作成者つき）、外部リンク、マクロ、非表示のシート・行・列、変更履歴 同じ書式が長く続く行は、テキストでは先頭と末尾だけを出す（仮の値・注記の疑いがある行は省略しない。`--all` ですべて、`--json` は常にすべて）。 `analyze` は、そこから表を機械的に拾った下書き。**下書きは確定ではない**。判断は、`inspect` の事実を読んだこちら（LLM）が行う。 ### T2: 範囲ごとに、役割を決める テンプレートの各範囲に、次の 5 つのどれかを割り当てる。機械的な検出に任せず、**値の意味・書式・並び**から決める。 | 役割 | 意味 | 定義での書き方 | 向く範囲 | |------|------|----------------|----------| | 残す（keep） | テンプレートのまま出す | `keep` に明示する（`analyze` が見出し・ラベルを入れる） | 毎回同じタイトル・ラベル・見出し・固定の注記・ロゴ。**値は入れない** | | 流し込む（fill） | データの値で置き換える（データが `null` なら空欄） | `cells`（固定セル）、`columns.<列>.key` | 宛名・日付・明細の値、文書番号・版・作成者・環境情報など**ラベルに対する値**、空欄の記入枠 | | 繰り返す（repeat） | サンプル行を、データの件数だけ複製する | `tables`（`pattern`・`block_rows`）、数式は `formula: true` | 明細の行、1 件が複数行のカード | | 文書の値（doc） | データ（表の行・記入欄）ではないが、文書ごとに変わる値。文の一部だけでも差し替える | `cells` の `{text: "{文書.年度}年度 第{文書.四半期}四半期 売上報告書"}`、ラベルの右の欄は `文書.作成日`、`header_footer`、`properties` | 表紙のタイトル、宛名の「○○ 御中」、明細の見出しの「（2025年9月）」、対象期間、フッターの表題、作成日・作成者・版・文書番号 | | 無視する（ignore） | 出力に残さない | `clear`（値だけ空にして書式は残す）、`drop_rows`（行ごと取り除く） | 記入例・仮の値・ダミー行・使わない注意書き | 判断の目安: - **タイトル・宛名・期間は、文字の中の可変の部分を見る**。「2025年度 第2四半期 売上報告書」の年度・四半期、「株式会社○○ 御中」の宛名、「売上明細（2025年9月）」の年月は、次の文書では変わる。文全体を残す（keep）のでも、文全体をデータにするのでもなく、変わる部分だけを文書の値にする。`analyze` は年度・四半期・年月・日付・期間・版・宛名を見つけて下書きに入れ、`!` で挙げる。毎回同じ文字（「社外秘」・会社のロゴ文字）や、変わらない年（「創業 1990年」）は keep に戻す - **文書の値は、データの `文書:` にまとめる**。表紙と明細の作成日、タイトルとフッターの年度のように、いくつかの場所に出る同じ値は、1 つのキー（`文書.作成日`）にする。ラベルの右の作成日・作成者・版・文書番号・宛先なども `文書.` の下に入る - **ラベルに対する値は、残さない**。文書番号・版・作成日・作成者・環境情報（OS・DB・バージョン）・変更履歴は、前の案件の実データ。テンプレートとして使う以上、データから流し込むか空にする。「固定の欄だから keep」にしない - **データに書くのは、文書ごとに変わる値だけ**。次はデータに書かない。`analyze` は機械的に分かるものを下書きに入れ、`needs_confirm` に挙げる。意味で決まるもの（会社名・発行元のように毎回同じ値、人が手で書く欄）は、下書きを読んで直す - 毎回同じ値（どの行も `式`・`円` の列、発行元の会社名）→ 残す（列は `keep: true`、固定セルは `keep`） - 人が書き込む欄（押印・署名・承認・確認者・手書きの欄）→ データに入れない。前の値があれば `clear`（列は `clear: true`） - 体裁の余白（見出しも値も無い列・空行）→ 定義にもデータにも入れない。空かどうかは、**既定値を除いてから**判定する。既定値は、連番・`×` や `-` の印・どの行も同じ値・数式。見出しが無く `×` だけの列は余白（印は書式として残す）。連番と `×` だけの行は、記入例ではなく空の行 - **表の見た目に頼る値は、データで意味の分かる形にする**。○× の列（択一・複数選択）、1 列の ○、年・月・日に分かれた日付、コードは、データでは `判定: 合格`・`対象OS: [Windows, Linux]`・`要再試: true`・`実施日: 2026-10-08`・`優先度: 高` と書き、変換は定義（`when` / `map` / `part`）に任せる。`analyze` が見つけたものは `needs_confirm` に挙がる。詳細は [references/template.md](references/template.md) の「表の見た目に頼る値」 - **空欄の記入枠も、キーを残す**。今は空でも、次の文書では入れる欄。`analyze` は、ラベルの右隣のセルを、空欄でも `cells` に入れる。消さない - 同じ書式が並び、値が連番や例に見える行 → **繰り返す**。縞模様なら `pattern` に周期の行を並べる。1 件が 2 行以上（明細 + 備考など）なら `block_rows` を使う - 仮の値の疑い（`サンプル株式会社`・`2020-01-01`）のうち、データで置き換える欄 → **流し込む**。置き換えない欄 → **無視する**（`clear`） - 記入例の行や、利用者向けの書き方の注意（`※ 記入例`）→ **無視する**。印刷物として残すべき注記（`※ 振込手数料はご負担ください`）→ **残す** - 合計・小計・税などの行 → **残す**。`SUM` の範囲は、表の行数に合わせて自動で伸びる - 集計の表（支店別・商品別など）→ 明細から数式で出すか、集計した値をデータで流し込むかを**利用者に確かめる**。数式なら列は `formula: true`。行を横に足す `=SUM(B2:E2)` の列は、合計の行ではなく表の列 - `analyze` の下書きに `!` で挙がる「前の文書の作成者・会社名を含む」文字（`東邦物流様 … 設計書` のタイトルなど）は、`keep` のまま残さない。流し込むか、利用者に確かめる - 定数の列（`円` など）→ `keep: true`。サンプルの値を持ち越したくない列 → `clear: true` - 迷う範囲は、決めずに**ユーザーに聞く**。聞くときは、範囲・候補の役割・理由を 1 行ずつ示す #### 前の文書の値・メタデータを持ち越さない テンプレートは、たいてい前の案件の成果物から作る。元の実データを出力に持ち越さないため、`analyze` の下書きは、はじめから次の形になっている。外すのは、ユーザーが望んだときだけ。 1. **`strict: true` と、見出し・ラベルだけの `keep`**。ラベルの右隣のセル（空欄の記入枠を含む）と、ラベルの無い数値・日付は `cells` に入る。下書きを読み、値のあるセルを 1 つずつ確かめる。仮の値の疑いの印が付かない実データ（実在の顧客名・金額・日付・バージョン）も、ラベルや見出しでなければ「流し込む」か「無視する」にする。決め忘れた値が残るセルがあると、`check` と `render` が、シートごとに範囲（`A1, A3:A5`）にまとめて挙げて止まる。挙がったものをそのまま全部 `keep` に貼らない 2. **`properties.scrub: true`**。作成者・最終更新者・会社名・タイトルなどを空にし、プレビュー画像・カスタムプロパティ・コメント（メモ）を取り除く。共有文字列に残った元の値と、グラフに残った古い値のキャッシュも取り除く。残したい項目、与えたい値（`title: "請求書"`）は、同じ `properties` に書く 3. **外部リンク・非表示のシート/行・変更履歴（リビジョン）**は、`inspect` が挙げるが、自動では消さない。ユーザーに見せて扱いを決める（不要なら、先にテンプレートの側で消してもらう） 4. マクロ（VBA）つきなら、出力の拡張子は `.xlsm` 決めたら、判断の一覧（範囲 | 役割 | 理由）を**ユーザーに見せて確認してもらう**。確認前に定義を確定しない。確定した定義には、判断の記録として `decisions`（範囲・役割・理由の一覧）を残してよい（render は読まない）。 ### T3: 定義を検査する ```bash uv run python scripts/xlsx_builder.py check --def def.yaml # テンプレートは定義の template（定義ファイルからの相対パス）から読む。--template で上書き ``` テンプレートと定義の整合（シート名・行・pattern・列）を確かめ、雛形データで試しに再構成する。`strict: true` なら、決め忘れた値の残りもここで見つかる。来歴の警告も出る。問題があれば、定義を直して、もう一度検査する。 ### T4: データを用意して再構成する データは、表ごとのキーにオブジェクトの配列を持つ JSON か YAML にする（[assets/template.data.example.json](assets/template.data.example.json)）。数値を捏造しない。 ```bash uv run python scripts/xlsx_builder.py render --def def.yaml --data data.yaml -o out.xlsx ``` データが大きくなるなら、ファイルを分けてよい。`--data` に複数のファイルかフォルダを渡すと、1 つにまとめて流し込む。表の行はファイルの順（フォルダなら名前順）につなぐ。同じ欄に違う値があるとき、表の同じ行が 2 つのファイルにあるとき、ほかのまとまりのデータも持つファイル（前のデータ一式を写したもの）から表の行が来たときは、ファイルの名前を挙げて止まる。書き出した専用スクリプトも同じ。データを分けて担当に渡すときは、前のデータ一式を写さず、自分のまとまりのファイルだけを直すよう伝える。分け方は、行数ではなく**タブのまとまり**ごと。定義の `sheets[].group` が同じタブを 1 ファイルにし、無ければタブごとに分ける。`analyze` は、名前が同じ言葉で始まるタブ（`受注_一覧`・`受注_明細`）に `group` を入れる。意味で決まるまとまり（表紙と改訂履歴など）は、下書きを読んで `group` を直す。`extract --split DIR` は、取り出したデータをこのまとまりごとのファイルに分けて書く。 ```bash uv run python scripts/xlsx_builder.py render --def def.yaml --data head.yaml items-1.yaml items-2.yaml -o out.xlsx uv run render_invoice.py --data data/ -o out.xlsx # フォルダの中のデータファイルを名前順に ``` 記入済みの文書（前の案件の成果物・以前に `render` した文書）からデータを起こすなら、`extract` で取り出してから直す。`○`・年月日の列は `判定: 合格`・`実施日: 2026-10-08` の形に戻る。既定値だけの空の行は書かない。どの行も空の欄も、記入枠としてキーを残す。 ```bash uv run python scripts/xlsx_builder.py extract filled.xlsx --def def.yaml -o data.yaml ``` テンプレートは定義の `template`（定義ファイルのある場所からの相対パス。`analyze` がそう書く）から読む。別のパスなら `--template` で上書きする。列の key がデータのどの行にも無いと、その列は空欄になる。データに使われていないキーがある（綴りの違いの疑い）か、どの key も当たらないときは警告が出る。テンプレートに列を足した後に前のデータを使い回すと、足した列は黙って空欄になるので、`--example-data` や `skeleton` で足りないキーを確かめる。数値の欄に数値として読めない文字（数量「たくさん」）を入れると、警告が出る（合計などが `#VALUE!` になる）。定義ファイルとデータは、JSON でも YAML（`.yaml` / `.yml`）でもよい。`analyze -o def.yaml` のように、出力の拡張子で形式を選べる。 ### T5: この文書専用の単体スクリプトにする（任意） 同じ帳票を繰り返し作るなら、確定した定義を埋め込んだ、スキル不要の 1 ファイルを書き出せる。テンプレートの .xlsx は、既定では別ファイルのまま置く（スクリプトからの相対パスで読む）。書き出し時に `check` と同じ検査をする。 ```bash uv run python scripts/xlsx_builder.py export --def def.yaml -o render_invoice.py uv run render_invoice.py --data data.yaml -o out.xlsx # PEP 723 で依存（lxml・openpyxl・pyyaml）を自動で入れる ``` - 書き出した `.py` は、スキルのディレクトリが無くても動く。テンプレートを同じ場所に置いておく - 配布を 1 ファイルにしたいときだけ `--embed` を付ける（テンプレートを base64 で埋め込む） - `--example-data` でデータの雛形、`--extract-def` で埋め込みの定義を取り出せる。`--help` にデータの形が出る #### 書き出したスクリプトの改修 スクリプトを手で書き換えない。定義を直して、書き出し直す。 ```bash python render_invoice.py --extract-def def.yaml # 1. 埋め込みの定義を取り出す # def.yaml を直す（列の追加・キーの変更・pattern の見直しなど） uv run python scripts/xlsx_builder.py export --from-script render_invoice.py --def def.yaml -o render_invoice.py # 2. 書き出し直す ``` - 定義を直さずに `--from-script` だけを付けると、定義とテンプレートを引き継いで、最新のエンジンで書き出し直す（エンジンの更新） - テンプレートが変わったときは `--template new.xlsx` を付ける。構造が変わったなら、T1 からやり直して定義を確定する（列を足した・並べ替えたテンプレートは、見出しが定義と合わないので、書き出しの検査が列を挙げて止まる） ### T6: 検証する 1. 出力を openpyxl で読み返し、行数・値・数式（`=SUM(E8:E12)` など）が意図どおりか確認する 2. 書式（罫線・色・フォント）がテンプレートと同じか、サンプルの値が残っていないかを確認する 3. 流用した場合は、出力の文書のプロパティ・共有文字列・コメントに、元のプロジェクトの情報が残っていないかを確認する 4. 数式の結果は、Excel で開いたときに再計算される。値を確かめたいときは LibreOffice で CSV に変換する テストの実行: `uv run python -m unittest discover -s tests -v` ## サブコマンド一覧（個別に呼ぶ場合） フローを使わず、個々のサブコマンドを直接呼ぶこともできる。すべて `uv run python scripts/xlsx_builder.py <サブコマンド>`。 | サブコマンド | 役割 | 主な引数 | |--------------|------|----------| | `inspect <template.xlsx>` | テンプレートの事実（値・数式・書式の種類・結合・仮値の疑い・来歴）を出す | `--json` | | `analyze <template.xlsx>` | 表の自動検出による、定義の下書きを書く（確定ではない） | `-o def.yaml`（拡張子で JSON / YAML を選ぶ） | | `check --def <def>` | 定義の整合と、テンプレートの値の残り（`strict`）を検査する | `--template` | | `render --def <def> --data <data> -o <out.xlsx>` | テンプレート + 定義 + データから再構成する | `--template`、`--data -`（標準入力）、`--data a.yaml b.yaml` / `--data DIR`（分けたデータをまとめる） | | `extract <filled.xlsx> --def <def>` | 記入済みの文書から、定義に沿ってデータを取り出す（`render` の逆） | `-o data.yaml`（省略時は標準出力に JSON）、`--template`、`--split DIR`（タブのまとまりごとのファイルに分ける） | | `export --def <def> -o <render.py>` | 定義を埋め込んだ、単体で動く専用スクリプトを書き出す | `--embed`、`--template`、`--from-script <旧.py>`（改修・エンジン更新） | | `build --spec <spec.json>` | テンプレート無しで、JSON スペックから新規生成する | stdin も可 | | `example` | `build` のサンプルスペックを出す | — | 専用スクリプト（`export` の出力）の引数: `--data`（複数のファイル・フォルダも可）、`-o`、`--template`、`--example-data`、`--extract-def`、`--extract-template`。 ## できること / できないこと | 対象 | 可否 | |------|------| | 複数シート・見出し装飾・数値書式 | ✅ | | 合計行（SUM）・フリーズペイン・オートフィルタ | ✅ | | 条件付き書式（カラースケール / データバー / しきい値） | ✅ | | グラフ（棒 / 折れ線 / 円、単・複数系列） | ✅ | | ピボットテーブル・マクロ(VBA)・複雑な相互参照数式 | ❌ 非対応（必要なら別途相談） | | 既存 .xlsx テンプレートへの流し込み（書式・不変部分を保持） | ✅ `analyze` / `render` | | 既存 .xlsx の任意の編集 | ❌ 流し込み以外は対象外 | ## ガードレール | 制限 | 内容 | |------|------| | データの事実性 | スペックに無い数値を生成しない。集計は呼び出し側で確定させる | | 機密 | 元データのシークレット・個人情報の取り扱いに注意し、不要な列を含めない | | スコープ | 帳票生成に集中する。データ取得・分析そのものは別スキル/別タスク |