xlsx-processing-anthropic

出力の要件

すべての Excel ファイル

専門的なフォント

• ユーザーから別途指示がない限り、すべての成果物で Arial や Times New Roman など、一貫性のある専門的なフォントを使用してください

数式エラーゼロ

• すべての Excel モデルは、数式エラー（#REF!、#DIV/0!、#VALUE!、#N/A、#NAME?）がゼロの状態で納品しなければなりません（MUST）

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

• ファイルを変更する際は、既存の形式、スタイル、規則を十分に確認し、正確に合わせてください
• 既存の書式パターンがあるファイルに、標準化された書式を押し付けないでください
• 既存のテンプレートの規則は、常にこれらのガイドラインより優先されます

財務モデル

色分けの標準

ユーザーまたは既存のテンプレートで別途指定がない限り、以下に従ってください

業界標準の色の規則

• 青色の文字（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) と表記してください

数式の作成ルール

前提条件の配置

• 成長率、利益率、倍率などのすべての前提条件は、別の前提条件セルに配置してください
• 数式内では値を直接書き込まず、セル参照を使用してください
• 例: =B51.05 ではなく =B5(1+$B$6) を使用します

数式エラーの防止

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

直接入力値に関する文書化の要件

• コメントとして記載するか、表の末尾の場合は隣接するセルに記載してください。形式: "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 が必要です: scripts/recalc.py スクリプトを使用して数式の値を再計算するため、LibreOffice がインストールされていることを前提としてかまいません。このスクリプトは初回実行時に LibreOffice を自動的に設定します。Unix ソケットが制限されているサンドボックス環境でも対応しています（scripts/office/soffice.py が処理します）。

データの読み取りと分析

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. 数式の再計算（数式を使用する場合は必須）: scripts/recalc.py スクリプトを使用する

   python scripts/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 ファイルには、数式は文字列として含まれていますが、計算済みの値は含まれていません。提供されている scripts/recalc.py スクリプトを使用して数式を再計算してください:

python scripts/recalc.py <excel_file> [timeout_seconds]

例:

python scripts/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 値を確認する
• 右端の列: 会計年度のデータは 50 列目以降にあることが多い
• 複数の一致: 最初の一致だけでなく、すべての出現箇所を検索する
• ゼロ除算: 数式で / を使用する前に分母を確認する（#DIV/0!）
• 誤った参照: すべてのセル参照が意図したセルを指していることを確認する（#REF!）
• シート間参照: シートをリンクする際は正しい形式（Sheet1!A1）を使用する

数式のテスト戦略

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

scripts/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 を使用する
• 数式は保持されますが評価はされません。値を更新するには scripts/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 ファイル自体について:

• 複雑な数式や重要な前提条件を含むセルにはコメントを追加する
• ハードコードされた値のデータソースを記載する
• 主要な計算やモデルのセクションには注記を含める