research-note

リサーチノートのワークフロー

ユーザーからリサーチノートとして記録するための大まかな質問を受け取ったら、以下の手順を正確に実行してください。

ステップ 0：料理の手順に関する例外を確認する

料理やローストの方法に関するノートは、リサーチノートではありません。

代わりに、[[recipe-cleanup]] 形式を使用してください。YAML フロントマターに tags: recipe を記載し、材料はウィキリンク付きのチェック済みチェックボックスにし、「Prep」セクションを設け、手順は小文字で始まり、末尾にピリオドを付けず、各文を個別の段落にした通常の段落で記載します。

外部ソースがない場合は、creator、pic、source フィールドを省略してください。

この場合、以降の手順は適用されません。

ステップ 1：質問を整理する

どの LLM にもコピーして貼り付けられるよう、明確かつ正確で、自己完結した質問に書き換えてください。

ルール：

• 前の会話や、別のモデルが把握できない文脈への言及を取り除きます。必要な背景情報は文中に含めます
• 曖昧さをなくします。最も可能性の高い解釈を選ぶか、構成を変更します
• 文法、スペル、句読点を修正します
• 平易で直接的な表現を使い、冗長な語句を削ります
• 質問の各文は個別の段落にし、空行で区切ります
• 範囲を定めます。有用な回答ができないほど広い質問は絞り込み、単独で成立しないほど狭い質問は範囲を広げます
• 質問に複数の要素が含まれる場合は、明確に分けます
• この手順では質問に回答しません

質問の背景にある動機を保ち、抽象的な質問に変えてしまわないでください。

名前の挙がっている具体例、特定のツール、提案されたワークフロー、明示された制約を保持してください。

目標は、明確さと、時間が経ってからも使えることです。ノートを後日有用にする具体的な詳細を犠牲にして、短くすることではありません。

これらの書き換えルールは、/Users/mtm/.claude/commands/question-cleanup.md にある question-cleanup コマンドにも重複して記載されています。このファイルは chezmoi のテンプレート command-question-cleanup から生成されます。このスキルは、その commands ディレクトリがないマシンにもインストールされるため、独自のコピーを保持しています。変更する場合は、両方を一緒に変更してください。

ステップ 2：異なる質問の数を数える

入力に、個別に回答できる質問が複数含まれている場合は、質問を分けてください。質問ごとにファイルを1つ作成します。

質問が異なる側面を扱い、互いを参照せずに回答できる場合、それらは別々の質問です。

ステップ 3：元ファイルの名前を変更してファイル名を決める

新しいファイルを作成して元ファイルを削除するのではなく、元ファイルの名前を説明的なファイル名に変更してください。

名前を変更することで、元ファイルを改良中の同一の成果物として扱い、追跡対象ファイルの git 履歴を保持できます。

git で追跡されているファイルには git mv "Untitled NNNN.md" "descriptive name.md" を、追跡されていないファイルには mv を使用します。その後、名前を変更したファイルにノートの内容を書き込みます。

ファイル名のルール：

• すべて小文字
• 単語はハイフンやアンダースコアではなく、スペースで区切る
• 具体的な質問の内容がわかる名前にする
• 拡張子は .md

例：lamination fold what builds strength.md

ステップ 2 で複数のノートが作成された場合、元ファイルの名前を変更して作成できるのはそのうち1つだけです。残りは新しいファイルとして作成し、ステップ 9 を参照してください。

ステップ 4：ファイルを書く

構成：

1. tags: [voice-memo-research] を含む YAML フロントマター
2. コンテキストブロック（元ファイルに Obsidian のウィキリンクが含まれている場合）— 質問文の前に [[wikilinks]] をそのまま保持します
3. 整理した質問 — ラベルや見出しを付けず、質問文のみを記載します
4. URL が指定されている場合は ## Source セクション
5. ノートに複数のトピックセクションが含まれる場合は ## Short answer セクション
6. トピックごとに ## セクションを1つ設け、それぞれに回答と検索リンクを記載します
7. ## Original request セクション

書式ルール：

• 各文は個別の段落にし、空行で区切ります
• ファイル内では斜体、太字、強調を一切使用しません
• すべてのリストに箇条書きを使用します
• ファイルの末尾に改行を入れます

フロントマターの形式：

---
tags:
  - voice-memo-research
---

ステップ 5：Source セクションを書く

ユーザーがそのトピックを知った URL を記録します。読んでいた記事、ニュースレター、ページなどを指定し、プロジェクト自体のホームページやソースリポジトリは指定しません。

目的は、元の文脈に戻って読み直せるようにすることです。

依頼に URL が含まれていない場合に限り、このセクションを省略します。

ステップ 6：トピックごとにセクションを書く

それぞれの異なる観点やサブトピックに、専用の ## セクションを設け、その観点を表す名前を付けます。

セクション名の例：## 利益相反、## コストの比較、## 代替案、## オンライン上の反応。

その観点に関する回答をセクションに書き、各文をそれぞれ段落にします。

回答には、最善の理解を記します。検索リンクは、ユーザーが内容を確認し、さらに調べるためのものです。

その観点の検索リンクは、各セクションの末尾に置きます。

すべてのリンクをノートの末尾にある単一の ## 検索リンク ブロックにまとめてはいけません。

セクションごとにリンクを置くと、後からセクションを発展させる際に、ここへリンクする新しい文書を作らずに済みます。

本当に単一の観点だけを扱うノートには、セクションが 1 つあれば十分です。

その単一セクションがすでに回答なので、そのような構成のノートには、それより上に何も必要ありません。

ステップ 6a：複数のセクションがあるノートは短い回答から始める

トピックのセクションを書き終えてから、その数を数えます。

複数ある場合は、質問の直下に ## 短い回答 セクションを追加します。

6 つのセクションがあるノートでは、読者は回答を知るために 6 つすべてに目を通すことになります。それではノートの目的に反します。

最初に、質問に含まれる前提と矛盾する点がある場合はそれも含めて、結論を 1 文で示します。

続いて、トピックの各セクションにつき箇条書きを 1 つ用意し、そのセクションの結論を記して、根拠のある場所を示すためにセクション名も挙げます。

最後に、実用上の要点と、以降の内容をどこまで信頼できるかに影響する注意点を記します。

スクロールせずに読める長さに収めます。

短い回答には検索リンクを付けません。短い回答内の主張はすべて、検索リンクがすでにある下位のセクションに属するためです。

ノートへの導入であって、調査結果を記載する場所ではないため、下位のセクションで裏付けられていない事実を記載しません。

ステップ 7：検索リンクを整形する

各セクションに、Google 検索リンクを 4～6 件、箇条書きで追加します。

各リンクは、そのセクションのトピックに異なる観点からアプローチするものにします。

すべての項目を、クリック可能な Markdown リンクにします。URL をそのまま記載してはいけません。

各箇条書きは - [内容が分かるリンクテキスト](https://www.google.com/search?q=search+terms+separated+by+plus+signs) の形式にします。

リンクテキストには、どのような検索結果が表示されるかを記し、URL 自体は使用しません。

URL 内の検索語句は、プラス記号で区切ります。

これは、Obsidian が自動でリンクできるよう URL を単独の行に記載するという、Vault の一般的な慣例に対する意図的な例外です。

例：

## Swallowing and coughing

- [clinical term for coughing triggered by swallowing](https://www.google.com/search?q=coughing+while+eating+medical+term+oropharyngeal+dysphagia)
- [how penetration and aspiration differ](https://www.google.com/search?q=laryngeal+penetration+vs+aspiration+difference)

ファイルを完成させる前に、各セクションのリンクをすべて読み返し、各項目が角括弧と丸括弧を使った形式になっていることを確認します。

ステップ 8：Original request セクションを書く

ノートの末尾に ## Original request セクションを追加し、ソースファイルの元の内容をそのまま記載します。

ソースファイルのテキストは、ウィキリンクのように見えるもの、コピーされたテキスト、アプリが自動生成したメッセージであっても、削除しないでください。

ユーザーは、きれいな質問のように見えなくても、その内容をコンテキストや素材として意図的に収集した可能性があります。

逐語的に記載するのは言葉であり、改行ではありません。そのため、ユーザーが使った「1 文につき 1 段落」の形式に整えてください。

• 文法の修正、言い換え、削除をせず、すべての単語を正確にそのまま保ちます
• 文の区切りごとに新しい段落を始め、空行で区切ります
• ウィキリンク、URL、貼り付けられたブロックなど、文章ではない行はそのまま残します

このセクションを設けることで、ユーザーは整理された質問と実際に尋ねた内容を比較できます。表現に手を加えると、その比較ができなくなります。

音声入力のソースは、改行のない長いブロックとして届きます。その改行までコピーすると、読みにくい文章の塊になってしまいます。

変更前：

One question I have is: why would I need RAG if I have Claude Code? When I ask it questions it seems to do the same thing. Let's make a new document for this.

変更後：

One question I have is: why would I need RAG if I have Claude Code?

When I ask it questions it seems to do the same thing.

Let's make a new document for this.

ステップ 9：分割した場合に限り、ソースファイルを削除する

ステップ 3 でソースをノートに名前変更しているため、調査ノートが 1 つだけの場合は削除する必要はありません。

ステップ 2 で入力を複数のノートに分割した場合、ソースをすべてのノートに名前変更することはできません。そのため、すべての出力ファイルをコミットした後でソースを削除してください。

削除する前にユーザーに確認を求めないでください。

削除後、次の作業に進む前にすぐコミットしてください。

ステップ 10：コミットする

ファイルを作成または更新したら、すぐに git にコミットしてください。

変更を個別に元に戻せるよう、ファイルごとにコミットしてください。

短く、命令形のコミットメッセージを記載してください。

コミットする前にユーザーに確認を求めないでください。

ステップ 11：追加の質問に対応する

調査中にユーザーから質問があった場合は、その質問を質問文の ## 見出しとしてアクティブなノートに追加し、その下に回答を記載してください。

すぐに対応し、ノートを更新するかどうかを尋ねないでください。

段落だけを追加するのではなく、見出しを使うことで、後からコンテキストが増えたときに質問を発展させやすくなります。

ステップ 10 に従い、追加のたびにコミットしてください。

ユーザーから質問や小さな質問の不足を指摘された場合も同様です。確認を求めずに該当するファイルへ追加し、コミットしてください。

追加によって、トピックセクションが 1 つから 2 つに増えることがあります。追加後に数を確認し、ステップ 6a を適用してください。

ノートにすでに ## Short answer がある場合は、ノートの内容が増えたのに説明が更新されない状態にならないよう、新しいセクションの項目を箇条書きで追加してください。