note-write

個人のメモ帳ディレクトリ (以下 001_Notes) にノートを書く・直す。

原則

ノートの価値は、半年後の本人が「あれどこに書いたっけ」で辿り着けることと、辿り着いたときに読んで意味が取れることだけである。

ただしノートはそのままチームや他部署に共有されることもあり、読み手によって必要な情報量が違う。 このスキルはそのために 5 つを代行する。

0. 誰が読むかを確かめる (これで粒度・目次・文体が決まる)
1. どこに置くか (既存ノートを直すか、既存フォルダに収めるか、ディレクトリを切るか)
2. どういうファイル名にするか
3. どういう構造で書くか
4. 文体を本人のものに揃えるか

0 と 4 は飛ばせない。 読み手を決めずに書くと、自分用には冗長、他人用には説明不足のノートになる。 AI 生成の癖が残った文章は、読み返したときに情報密度が低くて役に立たない。

手順

Step 0: 読み手を聞く (必ず最初に、1 問だけ)

ノートを作る・直す前に、必ず最初に誰が読むかをユーザーに聞く。 Step 1 のコマンド実行より前に聞く。

AskUserQuestion で 1 問だけ聞く。 ほかの質問 (置き場所やタイトルなど) と同じ呼び出しにまとめない。 一問一答で、回答を受け取ってから次に進む。

• question: 「このドキュメントは誰が読みますか？」
• header: 読み手
• multiSelect: false
• options (この順で固定する):
  1. 自分のみ — 自分が後で読み返すためのメモ
  2. チームメンバー — 同じチームのメンバーに共有する
  3. 部署・他チームのメンバー — チーム外も含む、部署内の人に共有する
• 4 つ目の「その他 (自由記述)」は AskUserQuestion が自動で付ける自由記述欄で受ける。選択肢として自分で足すと重複するので足さない

依頼文から読み手が読み取れるとき (「自分が読むだけ」「チームに共有する」など) も省略せずに聞く。 その場合は question の末尾に「依頼文からは〇〇と読めます」と添え、確認として答えやすくする。

AskUserQuestion が使えない環境 (Codex など) では、テキストで同じ 4 択 (1. 自分のみ / 2. チームメンバー / 3. 部署・他チームのメンバー / 4. その他 (自由記述)) を番号付きで示し、回答を待ってから進む。

既存ノートを更新する場合も聞く。 ノートのリードに - 読み手: の行があれば、question に「現在は〇〇向けに書かれています」と添える。

回答を受けたら、下の表で粒度・目次・文体を決める。 以降の Step 6 〜 9 はこの表に従う。

「その他」で最も近い行が決められないときだけ、もう 1 問だけ聞く (「前提として、システム名や社内ツールはどこまで知っている人ですか？」)。 ここでも一問一答にする。

決めた読み手は、ノートのリードの箇条書きに - 読み手: <回答> として残す。 あとで更新するときや共有範囲を広げるときの手がかりになる。

Step 1: メモ帳の現状を取る

書く前に必ず 1 コマンドで材料を揃える。 トピックのキーワード (システム名、チケットキー、テーマ語、英数 slug) を引数に渡すと、同じ話のノートが既にあるかまで一度に出る。

bash ${CLAUDE_SKILL_DIR}/scripts/notes-context.sh <keyword> [<keyword> ...]

(Codex ではスキルディレクトリからの相対パスで bash scripts/notes-context.sh と実行する)

メモ帳の場所は自動解決する ($NOTES_ROOT → cwd から上に探索 → 既定の候補パス)。 ディレクトリ名が 001_Notes でなければ NOTES_DIRNAME で指定する。 見つからないと言われたら、その時だけユーザーにパスを聞く。

Step 2: 出力からディレクトリの受け持ちを読み取る

ノートは日々増えるので、どのディレクトリが何を受け持っているかの固定表は作らない。 持てばすぐ実態とずれて嘘をつく。 毎回この出力から読み取る。

• recent: の行が一番の手がかり。そのディレクトリに最近何が置かれたかで受け持ちが分かる。同時にファイル名の流儀 (日時 prefix があるか、連番か、日本語タイトル直書きか) も分かる。新しく作るファイル名はそれに合わせる
• subdirs: があるディレクトリは分類軸が既に決まっている。軸がシステム名か作業名かテーマ名かをサブの名前から判断し、同じ軸で切る。軸を混ぜると探せなくなる
• md= が 1〜2 で updated= が古いディレクトリは単発で終わった話。名前が一致していても、そこに新しい話を足すと埋もれる。中身を見てから決める
• 名前と recent: から受け持ちが読めないときは、recent: にある 1 ファイルの H1 とリードだけ読めば足りる。ディレクトリ全体を読む必要はない

Step 3: 更新か新規作成かを決める

キーワード一致に同じ対象・同じテーマのノートが出ていたら、新しくファイルを作らずそこを更新する。 同じ話が別ファイルに分かれると、あとで探すときにどちらが正なのか分からなくなる。

更新する場合:

• 必ず現状を読んでから差分で直す。既存ノートを丸ごと書き直して上書きしてはいけない
• 追記位置は内容で決める。時系列の記録なら末尾。結論が変わったなら ## 結論 を書き換え、いつ何が分かって変えたかを残す。古い結論を黙って消すと、判断の経緯が追えなくなる
• 触った箇所は Step 7 の文体と Step 8 の構造レビューを通す。触っていない既存部分は変えない

新規作成の場合は Step 4 へ。

Step 4: 配置先を決める

原則は 必要な分だけディレクトリを切る。 1 ファイルで完結するノートのためにディレクトリを新設しない。 切るのは、そのトピックで 2 ファイル以上になるか、今後継続して増えることが読めるときだけ。

上から順に当てはめる。

1. トピックにチケットキー ([A-Z]+-\d+) がある → 同名ディレクトリがあればそこ。無ければ 001_Notes/<キー>/ を新設する。チケット単位のノートは必ず複数になるので、1 ファイル目でも切ってよい
2. subdirs: を持つ親ディレクトリのサブカテゴリに当たる → その親配下に、Step 2 で読み取った軸で 1 つ切る (システム名の軸なら新しいシステム名、作業名の軸なら新しい作業名)
3. 既存ディレクトリのテーマに収まる → そのディレクトリに直接ファイルを置く
4. 単発の小ネタ・手順の断片で、他とつながらない → tips/ に 1 ファイル。ディレクトリは切らない
5. どこにも当たらず、複数ファイルになる調査・インシデント → 001_Notes/YYYYMMDD-<slug>/ を新設し、00-index.md を必ず置く
6. どこにも当たらず 1 ファイルで済む → 今後増えるテーマなら新しいテーマ名のディレクトリを 1 つ切る。増えないなら tips/ を検討する。001_Notes/ 直下への直置きは避ける

迷ったら「半年後の自分が最初にどこを開くか」で決める。 テーマ名で探す人なので、日付より内容が読める名前を優先する。

Step 5: ファイル名を決める

置く先が決まったら、そのディレクトリの recent: に出ているファイル名に合わせる。 それが最優先。 既存が無い、または流儀が読めないときのデフォルトが下表。

• 英数 slug は kebab-case。日本語タイトルはスペースを含んでよい
• 日時 prefix を付けるのは、同じ対象で何度も起きる事象を時系列で並べたいときだけ。一度しか書かないノートに日付を付けると探しにくくなる

Step 6: 本文を書く

frontmatter は付けない。 メモ帳の既存ノートが frontmatter を使っている場合だけ、それに合わせる。

目次 (H2 の並び) は Step 0 の表で決めた読み手の行に従う。 下の骨格は「自分のみ」の場合で、ほかの読み手では表の目次に置き換える。

骨格 (自分のみ):

# <タイトル>

<1〜3 行のリード。何のメモで、なぜ書いたか>

- 読み手: 自分のみ
- チケット: <URL>
- 関連: [[other-note]]

## 結論

<何を調べて何が分かったか。ここだけ読んで用が済む密度で>

## <以下、根拠と詳細>

読み手が自分以外のときに足すもの:

• チームメンバー: ## 背景 に、なぜ調べたか・何が起きていたかを 2 〜 3 行で書く。## 再現手順 には、コマンドと実行場所 (### user@host など) を省略せずに書く。読み手に頼みたいことがあれば、結論とは別に箇条書きで書く
• 部署・他チームのメンバー: 冒頭の ## 概要 に、影響範囲と読み手にしてほしいことを 3 行以内で書く。## 背景と前提 に用語の表を置き、システム名・チーム内ツール・略称を説明する。本文中でも、初出の固有名には一言説明を添える。最後に ## 今後の予定と問い合わせ先 を置く
• その他: 土台にした行の「足すもの」に従い、記述内容に合わせて調整する

書くときに守ること:

• H1 は 1 つだけ。ファイル名とタイトルは揃える (完全一致でなくてよい)
• 1 文 1 行で書く。地の文は「。」の直後で改行し、文を横に繋げない。段落の区切りは空行。表のセル・箇条書きの項目内・コードブロック・callout の [!NOTE] 行はこの限りではない
• 結論を先に出す。調査・検証系は ## 結論 を冒頭近くに置く。冒頭に「これから調べます」と書くのは、読み返すときに何の役にも立たない
• 結論は 1 セクションあたり 5 行程度に収める。詳細は後述の別セクションに送る (下記)
• 事実と推測を分ける。確定は「〜である」、推測は「〜のはず」「〜と考えられる」。未確定のことは未確定と書く。埋めるために断定しない
• 根拠は数字で。「負荷が高い」ではなく average(usr,sys,iow) = (35.94%, 2.67%, 4.72%)
• コードブロックの直前に実行文脈のコメントを置く (### user@host)。あとで再実行するときにどこで叩くかが分からないと使えない
• 状態の整理は表。台数、計画、ノート一覧など
• 注意喚起は > [!IMPORTANT] / > [!WARNING]
• 長い補足は末尾の別セクションに送る。<details> で畳まない。エディタによっては <details> の中身をコピーしようとすると固まる
• リンク: 同じディレクトリ内は既存ノートと同じ [[ファイル名]] 形式 (拡張子なし)。別ディレクトリは相対パスリンクでスペースを %20 にする

複数ファイル構成にする場合、00-index.md には現在の到達点 (結論のダイジェスト) とノート一覧の表 (ファイル / 内容 / 状態) を置く。 索引だけのファイルにはしない。 索引を開いた時点で状況が分かるようにする。

結論は 5 行で書く

情報量が多いノートは読まれない。 「調べたことを全部書いたノート」は、書いた本人も読み返さないので価値がゼロになる。 そのため 結論は 1 セクションあたり 5 行程度に収める。 行数は目安であって厳密でなくてよいが、10 行を超えたら削る。 この上限は読み手が誰でも同じである。 読み手が自分以外のときに増やすのは結論ではなく、背景・前提・再現手順の節である。

• 1 行目に答えを置く。「ある。ただし通知していない。」「できる。検証済み。」のように、まず断定してから理由に入る
• 2 行目以降は根拠と、その答えが持つ含意。読み手が次に何を判断できるかまで書く
• 調査項目が複数ある場合は、項目ごとに H2 を切って各 5 行。項目を跨いだ長文の解説にしない
• 削る対象: クエリの全文、実行結果の生データ、参照実装の一覧、対応表。これらは結論の後ろの別セクションに置く (<details> は使わない)
• 削らない対象: 未確定な点、再現できなかった事実、判断を仰ぎたい論点。あとで自分を助けるのはここなので、短くしても落とさない

判断に迷ったら「半年後の自分がこのセクションだけ読んで、次の一手を決められるか」で測る。 決められないなら足りず、読み飛ばしたくなるなら多すぎる。

一読で通る文にする

書いている最中に守るのはこの 4 つでよい。 残りは Step 8 で読み返して直す。

• 同じものを 2 つの名前で呼ばない。最初に出した語で最後まで通す。言い換えると、読者は新しい概念が出たと解釈して止まる
• 1 語に 2 つの意味を持たせない。「処理」「実行」「対応」「管理」「確認」のような守備範囲の広い語は、意味ごとに別の語を割り当てる
• 文頭に足場を置く。長い目的語や「や」「と」でつないだ列挙で文を始めない。短い枠 (「1 回の調査には」) か主題を先に置き、長い列挙は述語の後ろへ送る
• 新しい語を表・コードブロック・見出しで初出させない。地の文で 1 度出してから使う

判断基準の全体は references/structure-ja.md。

Step 7: 文体を通す (必須。2 段とも通す)

書いた本文、または更新で触った箇所に対して、この順で 2 段を通す。 それぞれ、対応するスキルが入っていればそれを呼ぶ (Claude Code では Skill ツール、Codex では $<スキル名>)。 入っていなければ、下に書いた観点を自分で当てる。

7-1. 本人の文体に寄せる

本人の口調・表記ルールを持つスキル (例: my-voice) があれば呼ぶ。 無ければ、下で決める媒体の文末 (だ・である / です・ます) に揃え、メモ帳の既存ノートの表記 (括弧、数値範囲、英数字前後のスペース) に合わせる。

媒体は Step 0 の表の「文体」列で決める。

• 自分のみ・チームメンバー → 技術メモ (だ・である調)
• 部署・他チームのメンバー → 社内発信 (です・ます調)
• その他 → 土台にした行の媒体

ただしノートの中に他人に出す文章のブロックがある場合は、そのブロックだけ該当媒体で変換する。

• 「Slack 下書き」「Slack 投稿案」のセクション → Slack 媒体
• 「メール返信案」「依頼文の下書き」のセクション → Slack 媒体に準じつつ、依頼の作法 (依頼内容・期限・背景を先に置く) に寄せる

7-2. AI 生成の癖を取る

AI 臭を取るスキル (例: ja-writing-humanizer) があれば呼ぶ。 無ければ、定型導入、意義の過剰強調、見出し付き箇条書きの機械的反復、em ダッシュを自分で探して潰す。

この順序である理由: 7-1 で文体の骨格 (文末、表記ルール、結論先出し) を作ってから AI 臭を取ると、直した箇所に AI 臭が戻らない。 逆順だと 7-1 の変換で定型表現が再導入される。

2 段目で壊してはいけないもの

7-2 は「表記を一般的な形に揃える」方向に働くので、7-1 で決めた表記ルールを戻してしまうことがある。 7-1 で揃えた表記 (英数字前後のスペース、数値範囲の記号、括弧の全角・半角、コマンド名・ホスト名・専門用語のバッククォート) は 7-1 側が正なので保持する。

文体変換の対象外

以下は 1 文字も変えない。 整える対象は地の文だけ。

• コードブロックの中身、コマンド、ログ、設定ファイルの引用
• 数値、日時、ホスト名、システム名、URL、チケットキー、人名
• 表の中の実測値

変換後に、変換前の数値・固有名詞・コマンドがすべて残っているか照合する。 文体を直すつもりで事実が変わると、メモとして致命的に使えなくなる。

Step 8: 構造レビュー (書き込む前に 1 回読み返す)

Step 7 の 2 段は文体と表記を整えるが、文と段落の構造は直さない。 平易化の過程で語がずれたり文末が衝突したりするので、書き込む前に構造だけを見て 1 回読み返す。

references/structure-ja.md を読み、ノートの長さに応じて当てる範囲を決める。

• 読み手が自分のみで、H2 が 2 つ以下 — §1.1 同一物の改名 / §1.2 多義語 / §2.1 文頭の足場 / §3.1 主語の鎖 の 4 つだけ。引っかかりの大半はこれで説明できる
• 読み手が自分以外、長いノート、00-index.md、他人に出すブロック (メール返信案 / Slack 下書き) を含むノート — 全項目。他人が読むノートは、書き手の頭の中にある前提で補って読んでもらえない

読み手が部署・他チームのメンバーのときは、加えて「システム名・チーム内ツール・略称が、初出で説明されているか」を全文で確認する。

短いノートで 4 つを超えて当てない。 全項目を機械的に当てるのは時間の無駄になる。

Step 7 で触った箇所については、範囲にかかわらず次の 3 つを確認する。 文体を直したときに実際に起きる副作用である。

• 平易化のために言い換えた語が、他の節の同じ語とずれていないか (その語を全文検索する)
• 文末を変えた文が、直前の文と同じ形で終わっていないか
• 1 か所を直した結果、問題が隣の文に移っていないか

引っかかりを見つけたら、症状 (太字、後付けの注釈、接続語の追加) を外すのではなく原因を直す。 症状だけ外しても読みにくさは残る。

Step 9: 書き込んで検証し、報告する

1. 新規ならファイルを作成し、更新なら差分で直す。ディレクトリの新設が必要なら先に mkdir -p
2. 書き込んだファイルを読み直して実際の中身を確認する。書き込んだつもりで空、という事故を防ぐ
3. 結果を報告する

完了時に返すもの

書き出しました。

- パス: 001_Notes/<dir>/<file>.md
- 読み手: <Step 0 の回答> (目次: <採用した目次>)
- 配置: 既存の <dir> が <受け持ち> のため / <dir>/ を新設 (既存に該当なし、<理由>)
- 変更: 新規作成 / <どのセクションを>更新
- 文体: <7-1 で使ったスキル or 自前> → <7-2 で使ったスキル or 自前> 適用済み
- 構造: 4 項目 / 全項目を確認、<直した項目> を修正 (なければ「指摘なし」)

配置先は自動で決めて事後報告する。 ディレクトリを新設したときと既存ノートを更新したときは、なぜそう判断したかを 1 行添える。 あとで本人が「そこじゃない」と判断できる材料になる。

参照

• scripts/notes-context.sh — メモ帳の現状ダンプと既存ノート検索。Step 1 で、書く前に必ず実行する
• references/structure-ja.md — 一読で意味が取れるかの点検項目。Step 6 で書きながら、Step 8 で読み返すときに読む