| name | update-notes |
| description | 開発中の問題解決と知見の記録。エラーや予期しない動作に遭遇したら既存のnotesを確認し、新しい発見はnotesに記録する。未解決の問題はissuesに記録する。「このエラーの解決策は？」「なぜ動かない？」などのリクエスト時に使用。 |
開発ノート管理
開発中の問題解決と知見の蓄積を行う。
対象ディレクトリ
.claude/notes/ - 解決済みの知見.claude/issues/ - 未解決の問題
トリガー
以下の状況で発動:
- エラーや予期しない動作に遭遇した
- ライブラリの不具合を発見した
- ワークアラウンドが必要になった
- 開発中に有益な発見をした
フロー
問題に遭遇した場合
Step 1: 既存のnotesを確認
ls .claude/notes/
関連するノートがあれば読んで解決策を探す。
Step 2: 解決策が見つかった場合
そのノートの内容に従って問題を解決する。
Step 3: 解決策が見つからない場合
- 自分で調査して解決を試みる
- 解決できたら notes に記録
- 解決できなかったら issues に記録
記録先の判断
| 状況 | 記録先 |
|---|
| 解決済みの知見・ベストプラクティス | notes/ |
| 未解決の問題・バグ | issues/ |
notes テンプレート
ファイル名:
内容がわかる名前にする。
例:
tanstack-router-prerender-middleware.mddrizzle-d1-local-setup.mdcloudflare-workers-env-binding.md
本文:
# タイトル
## 問題
何が起きていたか。
## 原因
なぜ起きていたか。
## 解決策
どう解決したか。
issues テンプレート
ファイル名:
問題を端的に表す名前にする。
本文:
# 問題のタイトル
## 問題
何が起きているか。
## 再現手順（必要に応じて）
1. ...
2. ...
## ワークアラウンド（あれば）
暫定的な回避策。
## 調査メモ（あれば）
調べたこと、試したこと。
背景
なぜ notes と issues を分けるか
- notes: 解決済み → 他の開発者がすぐ参照できる
- issues: 未解決 → 誰かが引き継いで調査できる
なぜ即座に記録するか
問題を解決したらすぐに記録する。後回しにすると忘れる。
問題発生 → 調査 → 解決 → 即座に記録
解決したら issues から notes へ
issues に記録した問題が解決したら:
- 解決策を notes に記録
- issues のファイルを削除
CLAUDE.md との使い分け
| 場所 | 用途 |
|---|
| CLAUDE.md の Issues セクション | 重要な問題をシンプルに箇条書き |
| .claude/issues/ | 詳細な調査結果・再現手順・試したこと |
CLAUDE.md は概要、.claude/issues/ は詳細という関係。
CLAUDE.md への案内追加
notes または issues を新規作成した場合、CLAUDE.md にこれらのディレクトリに関する案内がなければ追加する。
確認方法
grep -E "\.claude/(notes|issues)" CLAUDE.md
案内がない場合
CLAUDE.md の適切な場所 (Notes セクションの後など) に以下を追加:
## Development Notes
- `.claude/notes/` - 解決済みの知見・ベストプラクティス
- `.claude/issues/` - 未解決の問題・調査中の課題
