# 台帳でキャッシュフローの役割を宣言：メタデータ1行で推測を置き換える

すべてのキャッシュフロー計算書は、勘定科目ごとに一度だけ下される静かな判断に基づいています。その勘定科目は説明対象の現金の一部なのか、それとも営業・投資・財務活動のいずれかなのか。この判断が正しければ、計算書はあなたのお金が実際にどこへ行ったのかを教えてくれます。間違っていれば、計算書は自信満々に誤解を招きます。

これまで、Beancount.ioのキャッシュフロー報告書は、ヒューリスティック（勘定科目のルートタイプと、名前からどの資産が現金かを推測する方法）でこの判断を自動的に行っていました。ほとんどの台帳では、この推測はほとんどの場合正しく、残りの場合は黙って間違っていました。名前が間違った形の証券口座は、間違ったセクションに分類されていました。実用上はすべての意味で現金であるマネー・マーケット・ファンドも、名前がそれを示していないために投資活動に置かれていました。

本日より、この分類を明示できるようになりました。勘定科目の`open`ディレクティブに、標準的なbeancountメタデータを1行追加するだけです：

```beancount
2000-01-01 open Assets:US:Brokerage
  cash-flow-role: "investing"

2000-01-01 open Assets:US:Marcus:Savings
  cash-flow-role: "cash"
```

1つのキーと4つの値—`cash`、`operating`、`investing`、`financing`—これで設定はすべてです。設定ページも、JSONファイルも、報告書ごとのオプションダイアログもありません。次にキャッシュフロー報告書を読み込むと、証券口座のフローは投資活動の下に表示され、普通預金口座は計算書が説明する変動の対象である現金の山に加わり、他のすべての勘定科目はこれまでどおり機能し続けます。

![サンプル台帳のBeancount.ioキャッシュフロー報告書：月次の純キャッシュフローチャートと、詳細な営業活動・投資活動のテーブル。](/img/blog/declare-cash-flow-roles-in-your-ledger/cash-flow-report.webp)

## 各ロールの意味

キャッシュフロー計算書は、すべての勘定科目を2つの役割のいずれかに振り分けます。`cash-flow-role`はこの両方を1つの単語で答えられます：

- **`"cash"`** — この勘定科目は現金および現金同等物の山に属します。現金勘定科目は明細項目として表示されることはありません。計算書はその合計残高の*変動*を説明し、2つの現金勘定科目間の振替は相殺されます。普通預金から当座預金への送金がそうであるべきように。
- **`"operating"` / `"investing"` / `"financing"`** — この勘定科目は現金ではなく、その期間中の変動が該当する活動セクションの明細行として表示されます。

デフォルトでは、報告書は名前に`Cash`、`Checking`、`Savings`、または`Bank`を含む資産勘定科目を現金同等物として扱います。ロールを宣言すると、両方向でこのデフォルトを上書きします。`cash-flow-role: "cash"`は、名前ルールでは拾えない勘定科目—マネー・マーケット・ファンドやステーブルコインのウォレットなど—を現金の山に取り込みます。また、`Assets:US:Bank:CD`への`cash-flow-role: "investing"`は、1行で2つのことを行います：CDを現金から除外*し*、名前が現金ルールに一致していたとしても投資に分類します。

意図的に2つではなく1つのキーを使いました。「この勘定科目は現金か？」と「どの活動セクションに属するか？」は決して独立した質問ではありません—勘定科目は現金の山の一部であるか、ちょうど1つの活動セクションに属するかのどちらかです。2つのキーでは、現金勘定科目に活動ロールが付くような無意味な状態が許されてしまいます。1つのキーなら、不正な状態は表現不可能になり、仕様全体がツイート1つに収まります。

![キャッシュフロー報告書の「活動別」ビュー：営業・投資・財務キャッシュフローを月ごとに積み上げ表示。](/img/blog/declare-cash-flow-roles-in-your-ledger/by-activity.webp)

あなたが宣言した分類は、すべてのビューが使用する分類です。「活動別」チャートは各月の営業・投資・財務フローを積み上げます。勘定科目のロールを変更すると、そのフローはチャートの正しい層、計算書の正しいセクション、エクスポートの正しい行へ、すべて同時に移動します。

## 宣言は推測に勝る—そして報告書はその作業内容を示す

分類は厳密な順序で解決されます：まずあなたのメタデータ、次に組み込みのヒューリスティックです。そして報告書は自分が何をしたかを正直に示します。計算書の最後には「この報告書の現金及び現金同等物」パネルがあり、数値の作成時に現金として扱った勘定科目を正確に列挙し、それからそれらを調整します：期首の現金、期末の現金、そして活動セクションが説明する純変動額です。

![キャッシュフロー計算書の末尾：現金及び現金同等物の純変動額の調整表と、報告書作成時に現金として扱った勘定科目を列挙するパネル。](/img/blog/declare-cash-flow-roles-in-your-ledger/cash-equivalents.webp)

報告書はまた、あなたが宣言した分類と推測した分類を区別し、その区別はCSVおよびMarkdownエクスポートにも引き継がれます：完全に宣言されたロールのみから構築された計算書には、もはや「分類は推測です」という開示行は付きません。その時点で分類は推測ではなく、台帳の一部だからです。

タイプミスは、プレーンテキストツールが扱うべき方法で処理されます。`cash-flow-role: "invsting"`は黙って受け入れもされず、黙って無視もされません：勘定科目はデフォルトのヒューリスティックにフォールバックし、ステータスパネルがそれをフラグ付けします—「不明なcash-flow-role値、デフォルトを使用」—つまり、間違いはログに埋もれるのではなく、あなたが見る場所に表示されます。

## 何も変更しなければ、何も変わらない

注釈のない勘定科目は、これまでと同じ公開されたデフォルトを使用します：収益と費用は営業活動に、非現金の資産は投資活動に、負債と純資産は財務活動にマッピングされ、名前が一致する現金同等物が現金の山を形成します。既存の台帳は、このリリースの前後で同一に表示されます。ほとんどのユーザーは、デフォルトが間違っている少数の勘定科目に注釈を付け、残りについては考えないでしょう。

移植性も損なわれません。`open`ディレクティブのメタデータはコアなbeancount構文であり、すべてのv2/v3ツールで解析され、この特定のキーを探さないものは無視します。`bean-check`は通り、Favaは気にせず、あなたの台帳はBeancount.ioの外でも完全に使用可能です。

## あなたの現金に関するすべてのビューが互いに一致する

1つの共有リゾルバーが各勘定科目の最終的なロールを生成し、すべての利用者はそれから読み取ります：

- **キャッシュフロー報告書**は、解決されたロールから活動セクションとその結論（現金及び現金同等物の純変動額）を構築します。
- **CSV、Markdown、印刷エクスポート**は同じ数値を運び、推測された分類の開示はヒューリスティックが実際に使用された場合のみ表示されます。
- **概要のサンキー図**は同じ宣言を読み取るため、現金としてマークした勘定科目はフローノードとして表示されなくなり、非収益勘定科目には宣言した活動ロールが尊重されます。
- **勘定科目ステータスパネル**は、宣言された勘定科目を「未分類の資産」としてリスト表示しなくなります。

![概要のサンキー図：収入から現金を経て費用カテゴリ、投資、貯蓄への資金の流れを描く—キャッシュフロー報告書と同じ勘定科目分類に基づいています。](/img/blog/declare-cash-flow-roles-in-your-ledger/overview-sankey.webp)

計算書と図があなたの現金について意見を異にする方法はありません。意見を異にするための答えが1つしかないからです。

## なぜ設定ページではなく台帳なのか

これがこのリリースで最も強く感じている部分です。設定UIを検討し、3つの理由で却下しました：

1. **台帳が真実の情報源です。** 他のどこかに置かれた分類は、それが説明する帳簿と矛盾する可能性があります。`open`ディレクティブにある分類は勘定科目とともに移動します—名前変更、リポジトリの移行、ファイルを読むすべてのクライアントを通じて。
2. **プレーンテキストは差分、検索、レビューが可能です。** 台帳をgitで管理しているなら—Beancount.ioを使っていればそうでしょう—分類ルールは`grep`、`diff`、`blame`ができ、レビュアーがプルリクエストで確認できるものになります。設定ページはそのどれでもありません。
3. **オフラインでもどこでも動作します。** どのエディタでもロールを宣言できます。台帳を読む将来のクライアントは、クライアントごとの設定を同期することなく、分類を無料で取得できます。

同じ理由で、分類は意図的に日付効果を持ちません。メタデータは勘定科目の性質を記述しており、それはめったに変わりません。変わるときは`open`ディレクティブを編集し、git履歴が何がいつ変わったかを記録します。その履歴*こそ*監査証跡です。

## あなたの台帳で試す

この機能は現在すべての台帳に展開されています。ロールの宣言にはテキストエディタだけが必要です：

1. 勘定科目の`open`ディレクティブがあるファイルを開きます。
2. `cash-flow-role: "cash"`（または`"operating"`、`"investing"`、`"financing"`）をその下にインデントしたメタデータ行として追加します。
3. キャッシュフロー報告書を再読み込みします。あなたの宣言は即座にヒューリスティックに勝ります。

デフォルトの推測が間違っている勘定科目から始めましょう—本当は現金ではないCD、本当は現金であるマネー・マーケット・ファンド、投資活動の下にきれいに置きたい証券口座。残りはそのままにしてください。完全な仕様—受け入れられる値、優先順位、デフォルト分類、不正な値の処理方法—は[キャッシュフローロールリファレンス](/docs/cash-flow-roles)にあります。

あなたの帳簿は、どの勘定科目が投資で、どれが日常の支出かをすでに知っていました。今やキャッシュフロー計算書もそれを知っています。
