Xlsx

出力の要件

🎯 PAI のコンテキスト全体を読み込む

このスキルを使ったタスクを開始する前に、PAI のコンテキスト全体を読み込んでください：

read ~/.claude/PAI/SKILL.md

これにより、以下を利用できます：

• 連絡先リスト全体（Angela、Bunny、Saša、Greg、チームメンバー）
• 技術スタックの優先順位（TypeScript>Python、bun>npm、uv>pip）
• セキュリティ規則とリポジトリの安全性に関するプロトコル
• 回答形式の要件（絵文字を使った構造化形式）
• エージェントのルーティングに使う音声 ID（ElevenLabs）
• 個人の好みと操作手順

🔀 このサブスキルを使う場面

このサブスキルは、ユーザーのリクエストに Excel スプレッドシート（.xlsx、.xlsm、.csv、.tsv）が関係する場合に有効になります。

明示的なトリガー

• ユーザーが「スプレッドシートを作成」「新しい Excel ファイル」「Excel ワークブック」と述べる
• ユーザーが「数式」「財務モデル」「財務モデリング」を依頼する
• ユーザーが「再計算」または「数式を再計算」と希望する
• ユーザーが「Excel のデータを分析」「Excel を読み取る」「Excel データ分析」と述べる
• ユーザーが .xlsx、.xlsm、.csv、または .tsv ファイルに言及する

文脈上のトリガー

• ユーザーが .xlsx/.xlsm ファイルのパスを提示する
• ユーザーが計算、予測、または財務データについて話す
• ユーザーが財務予測、収益モデル、または評価額に言及する
• ユーザーがスプレッドシートの数式やデータを扱いたいと希望する

ワークフローの振り分け

作成ワークフロー（openpyxl）：

• 「スプレッドシートを作成」「新しい Excel ファイル」「財務モデルを構築」
• ユーザーが数式と書式を含む新しい .xlsx ファイルの作成を希望する
• 数式のサポートと Excel 固有の機能には openpyxl を使う

編集ワークフロー（openpyxl）：

• 「スプレッドシートを編集」「Excel を変更」「セルを更新」
• ユーザーが数式を保持したまま既存の .xlsx ファイルを変更したい
• 既存の書式と数式を保持するには load_workbook() を使う

データ分析ワークフロー（pandas）：

• 「データを分析」「Excel を読み取る」「データの可視化」
• ユーザーが Excel ファイルのデータを分析または可視化したい
• 強力なデータ操作と分析には pandas を使う

財務モデリングワークフロー：

• 「財務モデル」「収益予測」「評価モデル」
• ユーザーが色分けされたプロフェッショナルな財務モデルを希望する
• 財務モデルの基準に従う（入力値は青、数式は黒、リンクは緑）

再計算ワークフロー：

• 「再計算」「数式の値を更新」「数式を計算」
• 数式を含むファイルを作成または編集した後
• 数式を使った後に必ず実行する手順として、recalc.py スクリプトを実行する

すべての Excel ファイル

数式エラーゼロ

• Excel モデルはすべて、数式エラーがゼロ（#REF!、#DIV/0!、#VALUE!、#N/A、#NAME?）の状態で納品する必要があります

既存のテンプレートを保持する（テンプレートを更新する場合）

• ファイルを変更する際は、既存の形式、スタイル、慣例を確認し、完全に合わせる
• 確立されたパターンがあるファイルに、標準の書式を押し付けない
• 既存のテンプレートの慣例は、常にこれらのガイドラインより優先される

財務モデル

色分けの基準

ユーザーや既存のテンプレートから別途指定がない限り、以下に従ってください。

業界標準の色の使い分け

• 青字（RGB: 0,0,255）：ハードコードされた入力値、およびシナリオに応じてユーザーが変更する数値
• 黒字（RGB: 0,0,0）：すべての数式と計算
• 緑字（RGB: 0,128,0）：同じワークブック内の他のワークシートから取得するリンク
• 赤字（RGB: 255,0,0）：他のファイルへの外部リンク
• 黄色の背景（RGB: 255,255,0）：注意が必要な重要な前提条件、または更新が必要なセル

数値の書式設定基準

必須の書式ルール

• 年：テキスト文字列として書式設定する（例：「2,024」ではなく「2024」）
• 通貨：$#,##0 形式を使い、ヘッダーに必ず単位を明記する（「Revenue ($mm)」など）
• ゼロ：パーセンテージを含むすべてのゼロを「-」で表示する数値書式を使う（例：「$#,##0;($#,##0);-」）
• パーセンテージ：既定では 0.0% 形式（小数点以下 1 桁）にする
• 倍率：評価倍率（EV/EBITDA、P/E）は 0.0x 形式にする
• 負の数：マイナス記号付きの -123 ではなく、(123) のように括弧で表す

数式の作成ルール

前提条件の配置

• すべての前提条件（成長率、利益率、倍率など）は、個別の前提条件セルに配置します
• 数式ではハードコード値の代わりにセル参照を使用します
• 例：=B5*(1+$B$6) を使用し、=B5*1.05 は使用しません

数式エラーの防止

• すべてのセル参照が正しいことを確認します
• 範囲指定でのオフバイワンエラーを確認します
• すべての予測期間で数式が一貫していることを確認します
• エッジケース（ゼロ値、負の数）でテストします
• 意図しない循環参照がないことを確認します

ハードコード値の文書化要件

• コメントを付けるか、表の横のセルに記載します（表の末尾の場合）。形式：「Source: [System/Document], [Date], [Specific Reference], [URL if applicable]」
• 例：
  • 「Source: Company 10-K, FY2024, Page 45, Revenue Note, [SEC EDGAR URL]」
  • 「Source: Company 10-Q, Q2 2025, Exhibit 99.1, [SEC EDGAR URL]」
  • 「Source: Bloomberg Terminal, 8/15/2025, AAPL US Equity」
  • 「Source: FactSet, 8/20/2025, Consensus Estimates Screen」

XLSX の作成、編集、分析

概要

ユーザーから .xlsx ファイルの内容の作成、編集、分析を依頼されることがあります。タスクに応じて、さまざまなツールとワークフローを利用できます。

重要な要件

数式の再計算には LibreOffice が必要です：recalc.py スクリプトを使用した数式値の再計算には、LibreOffice がインストールされているものとします。このスクリプトは初回実行時に LibreOffice を自動的に設定します

データの読み取りと分析

pandas によるデータ分析

データ分析、可視化、基本的な操作には、強力なデータ操作機能を備えた pandas を使用します。

import pandas as pd

# Read Excel
df = pd.read_excel('file.xlsx')  # Default: first sheet
all_sheets = pd.read_excel('file.xlsx', sheet_name=None)  # All sheets as dict

# Analyze
df.head()      # Preview data
df.info()      # Column info
df.describe()  # Statistics

# Write Excel
df.to_excel('output.xlsx', index=False)

Excel ファイルのワークフロー

重要：ハードコード値ではなく数式を使用する

値を Python で計算してハードコードするのではなく、必ず Excel の数式を使用してください。 これにより、スプレッドシートの動的な状態が保たれ、更新可能になります。

❌ 誤り - 計算値のハードコード

# Bad: Calculating in Python and hardcoding result
total = df['Sales'].sum()
sheet['B10'] = total  # Hardcodes 5000

# Bad: Computing growth rate in Python
growth = (df.iloc[-1]['Revenue'] - df.iloc[0]['Revenue']) / df.iloc[0]['Revenue']
sheet['C5'] = growth  # Hardcodes 0.15

# Bad: Python calculation for average
avg = sum(values) / len(values)
sheet['D20'] = avg  # Hardcodes 42.5

✅ 正しい - Excel の数式を使用

# Good: Let Excel calculate the sum
sheet['B10'] = '=SUM(B2:B9)'

# Good: Growth rate as Excel formula
sheet['C5'] = '=(C4-C2)/C2'

# Good: Average using Excel function
sheet['D20'] = '=AVERAGE(D2:D19)'

これは、合計、パーセンテージ、比率、差異など、すべての計算に適用されます。ソースデータが変更されたときに、スプレッドシートを再計算できる必要があります。

一般的なワークフロー

1. ツールを選択：データには pandas、数式や書式設定には openpyxl
2. 作成／読み込み：新しいブックを作成するか、既存のファイルを読み込みます
3. 変更：データ、数式、書式を追加／編集します
4. 保存：ファイルに書き込みます
5. 数式を再計算（数式を使用する場合は必須）：recalc.py スクリプトを使用します

   python recalc.py output.xlsx
   

6. エラーを確認して修正：
   • スクリプトはエラーの詳細を含む JSON を返します
   • status が errors_found の場合は、error_summary を確認して、具体的なエラーの種類と場所を特定します
   • 特定されたエラーを修正し、再度再計算します
   • よくある修正対象のエラー：
     • #REF!：無効なセル参照
     • #DIV/0!：ゼロ除算
     • #VALUE!：数式のデータ型が正しくありません
     • #NAME?：数式名が認識されません

新しい Excel ファイルの作成

# Using openpyxl for formulas and formatting
from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment

wb = Workbook()
sheet = wb.active

# Add data
sheet['A1'] = 'Hello'
sheet['B1'] = 'World'
sheet.append(['Row', 'of', 'data'])

# Add formula
sheet['B2'] = '=SUM(A1:A10)'

# Formatting
sheet['A1'].font = Font(bold=True, color='FF0000')
sheet['A1'].fill = PatternFill('solid', start_color='FFFF00')
sheet['A1'].alignment = Alignment(horizontal='center')

# Column width
sheet.column_dimensions['A'].width = 20

wb.save('output.xlsx')

既存の Excel ファイルの編集

# Using openpyxl to preserve formulas and formatting
from openpyxl import load_workbook

# Load existing file
wb = load_workbook('existing.xlsx')
sheet = wb.active  # or wb['SheetName'] for specific sheet

# Working with multiple sheets
for sheet_name in wb.sheetnames:
    sheet = wb[sheet_name]
    print(f"Sheet: {sheet_name}")

# Modify cells
sheet['A1'] = 'New Value'
sheet.insert_rows(2)  # Insert row at position 2
sheet.delete_cols(3)  # Delete column 3

# Add new sheet
new_sheet = wb.create_sheet('NewSheet')
new_sheet['A1'] = 'Data'

wb.save('modified.xlsx')

数式の再計算

openpyxl で作成または変更した Excel ファイルには、数式が文字列として含まれますが、計算済みの値は含まれません。数式を再計算するには、付属の recalc.py スクリプトを使用します。

python recalc.py <excel_file> [timeout_seconds]

例：

python recalc.py output.xlsx 30

このスクリプトは次の処理を行います：

• 初回実行時に LibreOffice マクロを自動的に設定します
• すべてのシートの数式を再計算します
• Excel のエラー（#REF!、#DIV/0! など）がないか、すべてのセルをスキャンします
• エラーの場所と件数の詳細を含む JSON を返します
• Linux と macOS の両方で動作します

数式の検証チェックリスト

数式が正しく動作することを確認するための簡易チェック：

必須の確認事項

• サンプルの参照を2～3個テスト：モデル全体を構築する前に、正しい値を取得できることを確認します
• 列の対応関係：Excel の列が正しく対応していることを確認します（例：列64は BK ではなく BL）
• 行のオフセット：Excel の行番号は1始まりであることに注意します（DataFrame の5行目 = Excel の6行目）

よくある落とし穴

• NaN の処理：pd.notna() で null 値を確認します
• 右端の列：FY データは列番号 50 以降にあることがよくあります
• 複数の一致箇所：最初の箇所だけでなく、すべての出現箇所を検索します
• ゼロ除算：数式で / を使う前に分母を確認します（#DIV/0!）
• 誤った参照：すべてのセル参照が意図したセルを指していることを確認します（#REF!）
• シート間の参照：シートをリンクする際は、正しい形式（Sheet1!A1）を使います

数式のテスト戦略

• 小さく始める：数式を広範囲に適用する前に、2～3 個のセルでテストします
• 依存関係を確認する：数式で参照されているすべてのセルが存在することを確認します
• エッジケースをテストする：ゼロ、負の値、非常に大きな値を含めます

recalc.py の出力の解釈

スクリプトは、エラーの詳細を含む JSON を返します：

{
  "status": "success",           // or "errors_found"
  "total_errors": 0,              // Total error count
  "total_formulas": 42,           // Number of formulas in file
  "error_summary": {              // Only present if errors found
    "#REF!": {
      "count": 2,
      "locations": ["Sheet1!B5", "Sheet1!C10"]
    }
  }
}

ベストプラクティス

ライブラリの選択

• pandas：データ分析、一括操作、シンプルなデータのエクスポートに最適です
• openpyxl：複雑な書式設定、数式、Excel 固有の機能に最適です

openpyxl の使用

• セルのインデックスは 1 始まりです（row=1、column=1 はセル A1 を指します）
• 計算済みの値を読み取るには data_only=True を使います：load_workbook('file.xlsx', data_only=True)
• 警告：data_only=True で開いて保存すると、数式は値に置き換えられ、完全に失われます
• 大きなファイルの場合：読み込みには read_only=True、書き込みには write_only=True を使います
• 数式は保持されますが、評価はされません。値を更新するには recalc.py を使います

pandas の使用

• 型推論の問題を避けるため、データ型を指定します：pd.read_excel('file.xlsx', dtype={'id': str})
• 大きなファイルの場合、特定の列を読み込みます：pd.read_excel('file.xlsx', usecols=['A', 'C', 'E'])
• 日付は適切に処理します：pd.read_excel('file.xlsx', parse_dates=['date_column'])

コードスタイルのガイドライン

重要：Excel 操作用の Python コードを生成する際は：

• 不要なコメントを入れず、最小限で簡潔な Python コードを記述します
• 冗長な変数名や不要な処理は避けます
• 不要な print 文は避けます

Excel ファイル自体について：

• 複雑な数式や重要な前提があるセルにはコメントを追加します
• ハードコードされた値のデータソースを記録します
• 重要な計算やモデルのセクションには注記を追加します

例

例 1：財務モデルを構築する

User: "Create a revenue projection model for the next 5 years"
→ Creates workbook with assumptions sheet + projections
→ Uses Excel formulas (=SUM, growth rates) not hardcoded values
→ Applies color coding (blue inputs, black formulas), runs recalc.py

例 2：Excel ファイルのデータを分析する

User: "What are the top 10 customers by revenue in this spreadsheet?"
→ Reads Excel with pandas
→ Groups, sorts, and filters data
→ Returns summary with statistics

例 3：既存のスプレッドシートを更新する

User: "Add a new column with profit margin calculations"
→ Loads workbook preserving existing formulas
→ Adds new column with margin formula referencing existing cells
→ Saves and recalculates to verify no errors