開発者のためのツェッテルカステン：実践的で効果的な方法

開発者が通常直面するのは情報の不足ではありません。問題となるのは、情報があまりにも多すぎることです。

API ドキュメント、プルリクエスト、本番環境でのインシデント、設計に関する議論、会議の議事録、アーキテクチャ図、コードのコメント、Slackのやり取り、研究論文、実験結果、ブックマーク、そして五つもの異なるツールに散らばった完成していないアイデア……。ここで難しいのは、情報を保存することではありません。難しいのは、それらを再利用可能な思考へと変えることです。

そこで役立ってくるのが、ツェッテルカステン（Zettelkasten）です。

ツェッテルカステンはしばしば「ノート-taking（記録）システム」として説明されますが、それはその価値を過小評価しています。適切に使用されれば、それは時間の経過とともにアイデアを発展させるための個人知識管理システムとなります。開発者にとって、それはコード、アーキテクチャ、デバッグ、学習、そして執筆を繋ぐ実用的な橋渡しとなるのです。

ここで強調したいのは、大多数の開発者がツェッテルカステンを浪漫的な生産性趣味として使うべきではないということです。美しいノートの博物館を作るべきではありません。問題を解決し、システムを説明し、より良いエンジニアリングの判断を下すのを助ける、実際に動作するシステムを構築してください。

ツェッテルカステンとは何か？

「ツェッテルカステン」は「 slip box（カード箱）」を意味します。この手法は、社会学者のニクラス・ルーマンに由来しており、彼はリンクされたノートの大規模コレクションを使ってアイデアを発展させ、膨大な著作を残しました。

重要な教訓は、彼が紙のカードを使用していたことではありません。重要なのは、彼のノートが孤立したファイルではなかったということです。各ノートには明確なアイデアがあり、システムにおける位置づけと、他のノートへのリンクを持っていました。時間が経つにつれて、接続が蓄積されることで、システムはより価値のあるものになっていきました。

開発者にとって、現代版のツェッテルカステンはシンプルです。

1. ノート1つにつき、1つの有用なアイデアを書く。
2. 関連するノートとリンクする。
3. そのリンクを使って、説明、意思決定、パターン、記事などを成長させる。

それだけです。あとは実装の詳細に過ぎません。

なぜ開発者は知識過多に苦しむのか

ソフトウェア開発は、詳細でありながら一時的な性質の知識を生み出します。

キャッシュ無効化のバグがなぜ発生したのかを理解します。フレームワークにおける奇妙なエッジケースを発見します。2つのキューイング戦略を比較します。本番環境の障害をデバッグします。レガシーサービスがなぜ奇妙に振る舞うのかを理解します。分散トレーシングに関する優れた記事を阅读量します。

そして2ヶ月後、かつてその答えを知っていたことをぼんやりと覚えているだけです。

開発者が一般的に使う知識管理の手法は、この問題を悪化させます。

• ブックマークは理解ではなく、情報源を保存する。
• フォルダは早期の分類を強制する。
• ウィキは所有者がいなくなると陳腐化する。
• TODOリストはタスクとアイデアを混同する。
• コードのコメントはローカルな詳細を説明し、広範な概念は扱わない。
• チャットメッセージは履歴の中に消えていく。

ツェッテルカステンは、知識を倉庫ではなくネットワークとして扱うため、この問題に有効です。もしこの考え方が、セカンドブレイン（第二の脳）の構築に関する読書で耳慣れたものであれば、偶然ではありません。両方の手法は、キャプチャ（記録）と再利用の間の同じ隙間を埋めようとしていますが、ツェッテルカステンの原子ノートと明示的なリンクという規律は、開発者に技術的なアイデアに対するより細粒化した把握手段を提供します。

ツェッテルカステンの基本原理

原子ノート（Atomic Notes）

原子ノートとは、1つのアイデアのみを含むノートです。

1つのトピックではありません。1つの記事の要約ではありません。「PostgreSQL」などという巨大なページ1つではありません。1つのアイデアです。

例えば、以下は広すぎます：

PostgreSQLのメモ
Kubernetes
Caching（キャッシュ）
システム設計

以下は原子ノートに近いです：

部分インデックスは、クエリが小さなサブセットを対象とする場合、書き込みオーバーヘッドを削減する
Kubernetesのレディネスプローブは、コンテナの起動ではなく、トラフィックルーティングを保護する
ライトスルー・キャッシングは一貫性を向上させるが、書き込みレイテンシを増加させる
冪等性キー（Idempotency keys）は、リトライを安全な操作に変える

原子ノートが強力なのは、リンクしやすいためです。巨大なページは漠然としたトピックとしてしかリンクできません。焦点の絞られたノートは、特定の概念、意思決定、バグ、またはシステムに正確に接続できます。

良い開発者のノートは、通常、以下のいずれかの質問に答えるべきです。

• アイデアは何ですか？
• それが重要になるのはいつですか？
• どのようなトレードオフを露呈していますか？
• 実際のコードでどこでこれを見たことがありますか？
• どのような他の概念と関連していますか？

リンキング

リンクこそがシステムの心臓部です。

目的は、美しいグラフを作成することではありません。アイデアを再利用可能にすることです。

冪等性キーについてのノートを書くときは、リトライ、分散システム、決済処理、メッセージキュー、API設計、インシデント防止に関するノートとリンクします。データベースマイグレーションについてのノートを書くときは、デプロイの安全性、ロールバック戦略、後方互換性、フィーチャーフラグとリンクします。

リンクは通常、以下の意味を持つべきです。

• 「これは別の角度から同じ概念を説明している」
• 「これはそのアイデアの実践的な例である」
• 「これはトレードオフまたは反論である」
• 「この概念はあの概念に依存している」
• 「このノートはより大きな議論の一部である」

怠惰なリンクを避けてください。すべてのノートを他のすべてのノートとリンクするとノイズが生じます。最も良いリンクは意図的なものです。

創発（Emergence）

創発は、ツェッテルカステンの神秘的に聞こえる部分ですが、実際には実用的です。

完璧な構造を最初から設計する必要はありません。有用なノートを追加し、正直に接続し、クラスタ（集まり）が時間とともに出現するのを待ちます。

数ヶ月経つと、多くのノートが以下のトピックの周りで接続されていることに気づくかもしれません。

• APIの信頼性
• 可観測性（Observability）
• 開発者体験
• イベント駆動アーキテクチャ
• データベースのパフォーマンス
• 技術的負債
• ドキュメント
• セキュリティレビュー

これらのクラスタは、将来の記事、内部ドキュメント、設計原則、カンファレンスでの発表、オンボーディング資料、あるいはより良いエンジニアリングの判断へとつながります。

これが、ツェッテルカステンをフォルダ階層と区別する理由です。フォルダは、あなたがそれを完全に理解する前に、知識をどこに属させるべきか決めてしまいます。リンクは、知識が複数の文脈に属することを可能にします。

開発者へのツェッテルカステンの適用

クラシックなツェッテルカステンのアドバイスは、学術的な執筆からよく来ます。個人知識管理の文献はその伝統をよくカバーしています。しかし、開発者は少し異なるバージョンを必要とします。

開発者のツェッテルカステンは、以下の3つを接続するべきです。

1. 概念
2. コード
3. システム

概念

概念ノートは、再利用可能なアイデアを説明します。

例：

バックプレッシャーは、高速なプロデューサーが低速なコンシューマーを圧倒するのを防ぐ
楽観的ロックは、リーダーをブロックすることなく競合する書き込みを検出する
サーキットブレーカーは、依存関係を繰り返し失敗する呼び出しから保護する

これらのノートは、あなた自身の言葉で書くべきです。ドキュメントをコピーしただけでは不十分です。価値は、概念を明確に説明することを自分自身に強制することから生まれます。

有用な概念ノートには以下のものが含まれる可能性があります。

• 短い説明
• 具体的な例
• トレードオフ
• 関連するパターンへのリンク
• 実際に使用したシステムへのリンク

コード

コードノートは、実践的な実装知識を記録します。

それらはランダムなスニペットの投棄ではありません。スニペットは、意思決定またはパターンを説明する場合にのみ有用です。

例えば：

## データベース制約による冪等なリクエスト処理

最も安全な実装は、通常、冪等性キーに対する一意制約です。
アプリケーションは、重複したリクエストが2番目の副作用を生成するのではなく、同じ保存された結果に解決されるため、安全にリトライできます。

関連:
- [[リトライには冪等な操作が必要]]
- [[データベース制約は並行制御である]]
- [[決済APIはネットワーク障害を不確実な結果として扱うべき]]

良いコードノートは、コードがなぜ機能するか、いつ使用するべきか、そして何が間違える可能性があるかを説明します。

システム

システムノートは、抽象的なアイデアをあなたの実際のアーキテクチャに接続します。

例えば：

請求サービスは、決済プロバイダーへの呼び出しがHTTPクライアントがタイムアウトしても成功する可能性があるため、冪等性キーを使用しています。

このノートは以下とリンクできます。

冪等性キーはリトライを安全な操作に変える
タイムアウトは失敗を証明しない
決済APIは不確実な結果をモデル化するべき
アウトボックスパターンはデータベース書き込みと外部の副作用を分離する

ここが、ツェッテルカステンがシニアエンジニアリング作業にとって価値を持つ場所です。それは、システムがなぜそのように形作られているのかという記憶を構築するのに役立ちます。

実用的なワークフロー

ステップ1：一時的なノートをキャプチャする

一時的なノート（Fleeting Notes）は、粗いキャプチャです。磨く必要はありません。

例：

デプロイ中にレディネスプローブが失敗した理由を調べる。
リトライが重複請求バグを悪化させたかもしれない。
インシデントレビューからの良い引用：タイムアウトは失敗ではない。
調査: Postgresのアクティブな行のみを対象とする部分インデックス。

最も速いものを使ってください。Obsidianのデイリーノート、Logseqのジャーナル、テキストファイル、モバイルノート、またはスクラッチバッファなど。

ルールはシンプルです。素早くキャプチャし、後で処理する。

ステップ2：ノートを恒久的なノートに処理する

処理こそが、価値が現れる場所です。

粗いノートを明確で再利用可能なノートに変換します。あなた自身の言葉で書き直します。各ノートにアイデアを述べるタイトルを付けます。

悪いタイトル：

リトライ

より良いタイトル：

リトライは操作が冪等である場合にのみ安全である

悪いノート：

リトライのために冪等性が必要。

より良いノート：

リトライは、一時的なネットワークの問題を重複する副作用に変える可能性があります。
リトライは、操作が複数回実行されても同じビジネス結果を生成する場合にのみ安全です。APIの場合、これには通常、冪等性キー、一意制約、または保存されたリクエスト結果が必要です。

ステップ3：文脈が新鮮なうちにリンクを追加する

ノートを記述した後、以下を自問してください。

• これは何を説明していますか？
• これは何に依存していますか？
• コードでどこでこれを見たことがありますか？
• 反対の意見は何ですか？
• どのシステムがこれから恩恵を受けますか？

未来のあなたを考えるのに役立つリンクだけを追加してください。

ステップ4：インデックスノートまたはコンテンツマップを作成する

クラスタが成長したら、インデックスノートを作成します。

例えば：

# APIの信頼性

## 核心的なアイデア

- [[リトライは操作が冪等である場合にのみ安全である]]
- [[タイムアウトは失敗を証明しない]]
- [[サーキットブレーカーは失敗する依存関係への圧力を軽減する]]
- [[レート制限は共有リソースを保護する]]

## 実装パターン

- [[冪等性キーはリトライを安全な操作に変える]]
- [[アウトボックスパターンは永続化と配信を分離する]]
- [[デッドレターキューは検査のために失敗したメッセージを保存する]]

## システムの例

- [[請求サービスのペイメントリトライ設計]]
- [[Webhook配信の障害処理]]

これにより、すべてをフォルダに強制することなくナビゲーションが可能になります。

ステップ5：ノートを出力に使用する

ツェッテルカステンは何かを生み出すべきです。

開発者にとって、出力とは以下のものになり得ます。

• アーキテクチャ意思決定記録（ADR）
• 設計ドキュメント
• ブログ記事
• デバッグガイド
• オンボーディングドキュメント
• プルリクエストの説明
• 内部での発表
• リファクタリング計画
• インシデントレビューの洞察

あなたのノートがあなたの仕事に影響を与えないなら、そのシステムは装飾的すぎます。

開発者に推奨されるノートタイプ

一時的なノート（Fleeting Notes）

素早いキャプチャ用の一時的なノートです。

以下に使用してください。

• コーディング中のアイデア
• デバッグの観察
• 会議の断片
• 質問
• 後で処理するためのブックマーク

速やかに削除するか変換してください。沼になるのを許可しないでください。

文献ノート（Literature Notes）

外部の情報源に関するノートです。

開発者にとって、情報源とは以下のものになり得ます。

• ドキュメント
• ブログ記事
• RFC
• ソースコード
• カンファレンスの発表
• GitHubのイシュー
• ポストモーテム（事故報告書）
• 本の章

ソースノートをあなたの恒久的なノートと分けて保管してください。ソースノートは「この情報源はこれを言った」と言います。恒久的なノートは「私はこのアイデアをこのように理解している」と言います。

恒久的なノート（Permanent Notes）

これこそがツェッテルカステンの核です。

恒久的なノートは以下のようになるべきです。

• 原子的である
• あなた自身の言葉で書かれている
• 関連するノートとリンクされている
• 元の情報源を必要とせずに有用である
• 後で再訪するのに十分安定している

プロジェクトノート

プロジェクトノートは許可されていますが、それらを恒久的なノートと混同しないでください。

プロジェクトノートは以下のようになるかもしれません。

請求ワーカーをキュー v2 にマイグレート

それは以下の恒久的なノートとリンクできます。

バックプレッシャーはキューのコンシューマーの崩壊を防ぐ
アウトボックスパターンは永続化と配信を分離する
フィーチャーフラグはデプロイのリスクを削減する

プロジェクトは終了します。しかし、概念は残ります。

ツールの例

Obsidian

Obsidianは、ローカルのMarkdownファイルを使用し、内部リンクをサポートするため、開発者のツェッテルカステンに適しています。

シンプルなObsidianの構造：

notes/
  fleeting/
  sources/
  permanent/
  maps/
  projects/

ノートの例：

# タイムアウトは失敗を証明しない

タイムアウトとは、クライアントが待機を止めたことを意味します。それはサーバーが失敗したことを証明するものではありません。
操作は成功している、失敗している、またはまだ実行中かもしれません。

これは決済API、ジョブキュー、およびあらゆる外部の副作用において重要です。

関連:
- [[リトライは操作が冪等である場合にのみ安全である]]
- [[冪等性キーはリトライを安全な操作に変える]]
- [[外部の副作用は調整を必要とする]]

ファイルの所有権、プレーンテキスト、エディタのようなワークフローを好むなら、Obsidianは良い選択肢です。

Logseq

Logseqは、アウトライン、デイリージャーナル、ブロックレベルの参照を好む場合に有用です。

そのブロックモデルは、思考の小さな単位をキャプチャするのに適しています。ジャーナルで粗いノートを記述し、その後、有用なブロックを恒久的なノートに昇格させることができます。

Logseqスタイルのワークフローの例：

- 決済リクエスト中のタイムアウトは決済の失敗を証明しない。
  - これは不確実な結果に関する恒久的なノートになるべきである。
  - 関連: [[冪等性]], [[リトライ]], [[決済API]]

思考がアウトラインから始まり、ブロック参照を好むなら、Logseqは良い選択肢です。ワークフロースタイル、同期オプション、プラグインエコシステム全体にわたる両ツールの並べて比較については、Obsidian vs Logseqでトレードオフが明確に描かれています。

プレーンMarkdownとGit

特別なアプリは必要ありません。

MarkdownファイルのGitリポジトリで十分です。

knowledge/
  permanent/
  sources/
  maps/

通常のMarkdownリンクを使用します。

[リトライは操作が冪等である場合にのみ安全である](../permanent/retries-safe-only-with-idempotency.md)

このアプローチは地味ですが、耐久性があり、開発者フレンドリーです。これは賞賛です。

ノートの命名

主張となるタイトルを優先してください。

弱いタイトル：

Caching（キャッシュ）
Queues（キュー）
OAuth
PostgreSQL indexes（インデックス）

強いタイトル：

キャッシュ無効化は調整の問題である
キューはレイテンシを隠すが、作業を除去しない
OAuthアクセストークンは短命であるべき
部分インデックスはクエリがサブセットを対象とする場合に有用である

主張ベースのタイトルは、ノートを理解しやすくし、リンクしやすくします。

開発者のツェッテルカステンに何を入れるべきか

良い候補：

• アーキテクチャ原則
• デバッグの教訓
• 本番インシデントの洞察
• API設計のルール
• データベースパターン
• セキュリティの前提
• パフォーマンスのトレードオフ
• フレームワークのエッジケース
• リファクタリングのヒューリスティック
• テスト戦略
• デプロイの教訓
• コードレビューパターン

悪い候補：

• 生の会議のトランスクリプト
• 処理されていないブックマーク
• コピーされた巨大なドキュメントページ
• 説明のないランダムなスニペット
• タスクリスト
• シークレット
• クレデンシャル
• 公式の会社ドキュメントにのみ属するもの

個人のツェッテルカステンは仕事を参照できますが、プライベートなシステムの安全でないシャドウコピー（複製）になるべきではありません。

一般的なミス

ミス1：早期に構造を過度に整えすぎる

開発者は構造を愛します。それは時々問題になります。

最初の1週間に、フォルダ、タグ、テンプレート、命名規則、ダッシュボード、自動化の設計に費やさないでください。あなたのノートが必要とする構造をまだ知らないのです。

以下の少数のノートタイプから始めます。

fleeting（一時的）
sources（情報源）
permanent（恒久的）
maps（マップ）
projects（プロジェクト）

複雑さがその場所を勝ち取るのを待ちます。

ミス2：フォルダのように扱う

ツェッテルカステンは、より良いフォルダツリーではありません。

すべてのノートが正確に1つのフォルダに属し、意味のあるリンクを持たないなら、あなたはファイルキャビネットを構築しました。それはまだ有用かもしれませんが、それはツェッテルカステンではありません。

価値は接続から来ます。

APIリトライ -> 冪等性 -> データベース制約 -> 決済の安全性 -> インシデント防止

そのチェーンは「Backend（バックエンド）」というフォルダよりも有用です。

ミス3：保存するのではなく、考える

コピーすることは学習ではありません。

ドキュメントから保存された段落は後で役立つかもしれませんが、書き直された説明は今すぐ役立ちます。あなた自身の言葉でアイデアを再記述する行為こそが、理解が深まる場所です。

良いルール：

コピーせずにアイデアを説明できるようになるまで、恒久的なノートを生成しない。

ミス4：すべてをリンクする

リンクが多すぎても、少なすぎても同じくらい悪い。

存在するからといって、単語をリンクしないでください。関係が重要だから、アイデアをリンクしてください。

有用なリンクは、未来のあなたが以下に答えるのを助けるべきです。

なぜこれが接続されているのか？

ミス5：タグと構造を混同する

タグはステータスと広範なグループ化に有用です。

#todo
#source
#security
#draft

しかし、タグがシステム全体を支えるべきではありません。タグだけに依存すると、直接リンクのより豊かな意味を失います。

リンクは以下と言います。

このアイデアは特定の方式であのアイデアに関連している。

タグは通常以下と言います。

これは広範なバケツ（カテゴリ）に属する。

どちらも有用です。しかし、それらは同じではありません。

ミス6：出力を生成しない

出力を生成しないツェッテルカステンは、プライベートなアーカイブになります。

出力が公開執筆を意味する必要はありません。それは設計ドキュメント、インシデントレビュー、より良いプルリクエスト、またはチームメイトへの明確な説明になり得ます。

システムはあなたの思考を再利用しやすくするべきです。

ミニマルなテンプレート

小さなテンプレートを使用してください。15のフィールドを持つフォームを作成する誘惑に抵抗してください。

# 主張としてのタイトル

## アイデア

あなた自身の言葉でアイデアを説明する。

## なぜ重要なのか

実用的な影響を記述する。

## 例

コード、システム、またはデバッグの例を示す。

## トレードオフ

制限、リスク、または反論に言及する。

## リンク

- [[関連ノート]]
- [[別の関連ノート]]

多くのノートにとって、これですら十分すぎるかもしれません。タイトル、1段落、3つのリンクで十分です。

例：バグからツェッテルカステンのノートへ

タイムアウト後にユーザーが2回請求されるバグを修正したと想像してください。

弱いノートは以下になります。

決済バグ - リトライが重複請求を引き起こした。

より強力なノートのセットは以下になるかもしれません。

タイムアウトは失敗を証明しない
リトライは操作が冪等である場合にのみ安全である
冪等性キーはリトライを安全な操作に変える
決済APIは不確実な結果をモデル化するべき
データベース制約は並行制御である

これで、バグは再利用可能なエンジニアリング知識になりました。

後で、それらのノートは以下を支えることができます。

• ポストモーテム
• 決済リトライのための設計ドキュメント
• 冪等性に関するブログ記事
• 外部API統合のためのチェックリスト
• コードレビューのコメント
• より安全な実装

これがツェッテルカステンの実用的な価値です。

週間のメンテナンスルーチン

複雑なレビュープロセスは必要ありません。

1週間に1度、以下のことをします。

1. 粗いノートを処理する。
2. もう重要でないノートを削除する。
3. 有用なアイデアを恒久的なノートに変換する。
4. 欠けているリンクを追加する。
5. クラスタをマップノートに昇格させる。
6. 1つのノートを選び、それを出力に変える。

軽量に保ってください。システムは開発をサポートし、それと競争するべきではありません。

実用的なルール

以下のルールを使用して、システムを健全に保ってください。

• ノート1つにつき1つのアイデア。
• タイトルを主張として書く。
• フォルダよりもリンクを優先する。
• ソースノートをあなた自身のアイデアから分離する。
• ノートを実際のコードと実際のシステムに接続する。
• クラスタが存在する場合のみ、マップノートを生成する。
• 低価値のノートを削除する。
• ワークフローを理解する前に自動化しない。
• 何かを生み出すためにシステムを使用する。

ツェッテルカステンが報われない場合

ツェッテルカステンはすべての問題の答えではありません。

以下の場合は、大げさすぎるかもしれません。

• タスクマネージャーだけを必要としている。
• 技術的なアイデアをほとんど再訪しない。
• 書く、教える、設計する、またはドキュメントを作成しない。
• ノートの大部分が短期間のプロジェクト詳細である。
• 実際の作業をするのを避けるために使用している。

それは、あなたの仕事が累積する理解に依存する場合に最も有用です。

それには、シニアエンジニアリング、アーキテクチャ、技術リーダーシップ、複雑なシステムのデバッグ、執筆、コンサルティング、研究、そして長年にわたる深い学習が含まれます。

最終的な思考

開発者にとって、ツェッテルカステンはノートを収集することではありません。思考環境を構築することです。

この手法は、実用的な状態を維持しているときに最も良く機能します。原子ノート、意味のあるリンク、実際の例、そして定期的な出力。概念をコードに接続する。コードをシステムに接続する。システムを意思決定に接続する。

完璧なセカンドブレインを構築しようとしません。有用なものを構築してください。

良い開発者のツェッテルカステンは、より良い質問に答えるのをあなたに助けるべきです。

以前この問題を見たのはどこか？
このバグを説明する概念は何か？
私たちはどのようなトレードオフを行っているのか？
ここに適用されるパターンは何か？
もう一度これを再学習しないように、何をメモすべきか？

それで十分です。