write-tbp

テクニカルブログ記事を書く

このスキルは、tldraw の実装の詳細についてのテクニカルブログ記事を書く方法を扱います。

プロセス

1. ワークスペースを作成する

このスキルディレクトリ内に、このトピック用の assets フォルダーを作成します:

assets/<topic>/
├── research.md   # Gathered context and notes
└── draft.md      # The blog post draft

トピックには短いケバブケースの名前を使用します（例: scribbles、arrow-routing、dash-patterns）。

2. トピックを調査する

Explore サブエージェントを使って、関連するすべての情報を収集します:

Task (subagent_type: Explore, thoroughness: very thorough)

Find all code, documentation, and context related to [TOPIC] in the tldraw codebase.

Look for:
- Implementation files in packages/editor and packages/tldraw
- Type definitions in packages/tlschema
- Related examples in apps/examples
- Any existing documentation in apps/docs/content
- Tests that reveal behavior
- Comments explaining why things work the way they do

For each relevant file, note:
- What it does
- Key functions/classes
- Interesting implementation details
- Any "why" comments or non-obvious decisions

Output a comprehensive summary of how [TOPIC] works. This document will be read by another agent. No need to over-optimize for human readability.

調査結果を assets/<topic>/research.md に保存します。

3. 興味深い切り口を見つける

書く前に、調査結果からこれらの問いに答えます:

• これはどんな問題を解決するのか？ 「何をするのか」ではなく「それがなければ何がうまくいかないのか」。
• 何が意外で直感に反するのか？ うまくいかない明白なアプローチ、あるいは隠れた複雑さ。
• 重要な洞察は何か？ 解決策を機能させる「ひらめき」。
• 最初に何を試したのか？ コードやコメントに見える道のりや反復。

興味深い切り口が見つからない場合、そのトピックはテクニカルブログ記事に適していないかもしれません。

4. 下書きを書く

blog-guide の構成に従って assets/<topic>/draft.md を作成します:

1. 問題を述べる — システムが何をするのか、それがなければ何がうまくいかないのか
2. 洞察を示す — それを機能させる鍵となるアイデア
3. 実装を順に説明する — コードと解説、複雑さを積み上げながら
4. まとめる — どこにあるか、トレードオフ、ファイルへのリンク

目標は 800〜1500 語です。

簡素に下書きする

下書きは人間の編集者にとっての素材であり、完成した記事ではありません。簡素に保ち、内容そのものに語らせます。編集者はパーソナリティ、逸話、迫力を好きな場所に加えます。それは、簡素で正確な下書きに加える方が、書きすぎた下書きから削り取るよりもはるかに簡単です。

具体的には:

• システムが何をするのか、記事が何を扱うのかを述べることから始めます。情景、逸話、仮想のユーザー（「あなたの電車がトンネルに入ると…」）で始めないでください。それらは AI の埋め草のように読まれ、編集者は削除します。
• 物語は仕組みから組み立てます。各部分がどの問題を解決するのかを、各部分が互いに依存する順序で示します。緊張感は文章からではなく、設計から生まれます（スキャンは削除を認識できない、プルーナーはかつて穴を残していた、など）。
• 道のりやバグは淡々と述べます。「プルーナーの初期バージョンはウォーターマークを進めなかったため、古いクライアントは削除のない差分を受け取っていました」で十分です。「私たちはこれを苦労して学びました」といった類の語りは省きます。
• オチの一文、交差対句、締めの決めゼリフはなし。何かを言うためではなく、よく聞こえるために存在する文は削除します。
• ダッシュ（em dash）は段落ごとに最大 1 つ、通常はゼロ。
• 意見はまとめに留め、短く具体的に保ちます（「十分に長く離れていたクライアントには、メタデータを有界にする代わりに、完全な再ダウンロードを受け入れます」）。
• 人間の要素が属する箇所（書き出し、来歴、トレードオフ）では、色をでっち上げるのではなく、段落を簡素なままにしておきます。それらの箇所は引き継ぎで言及します。

5. 自己評価する

blog-guide のチェックリストに照らして下書きを確認します:

• 書き出し — 解決策の前に問題を、演出された逸話なしで簡素に述べているか？
• 洞察 — 明確な鍵となるアイデアがあり、構成がそこに向かって積み上がっているか？
• 具体性 — tldraw の実際の実装に基づいているか？
• コード — 例は単に構文を示すだけでなく、理解を深めているか？
• トーン — 簡素で直接的か？ 感傷もオチも、編集者が AI の残骸だと気づくようなものもないか？
• リンク — リポジトリ内の実際のコードを指しているか？
• 長さ — トピックに対して適切な深さか？

不足があれば下書きを修正します。

6. 出力

最終的な下書きをレビューのためにユーザーに提示し、人間の編集者が色を加えたいと考える可能性が最も高い箇所（通常は書き出し、来歴やバグの話、トレードオフ）を指摘します。下書きはユーザーが満足するまで assets/<topic>/draft.md に残り、満足した時点で適切な場所に移動できます。

参考資料

• スタイルガイド: 文体、トーン、構成については ../shared/blog-guide.md を参照してください。
• ライティングガイド: 一般的なライティング規約については ../../VOICE.md を参照してください。