開発ノート管理

開発中の問題解決と知見の蓄積を行う。

対象ディレクトリ

• •.claude/notes/ - 解決済みの知見
• •.claude/issues/ - 未解決の問題

トリガー

以下の状況で発動:

• •エラーや予期しない動作に遭遇した
• •ライブラリの不具合を発見した
• •ワークアラウンドが必要になった
• •開発中に有益な発見をした

フロー

問題に遭遇した場合

Step 1: 既存のnotesを確認

ls .claude/notes/

関連するノートがあれば読んで解決策を探す。

Step 2: 解決策が見つかった場合

そのノートの内容に従って問題を解決する。

Step 3: 解決策が見つからない場合

• •自分で調査して解決を試みる
• •解決できたら notes に記録
• •解決できなかったら issues に記録

記録先の判断

notes テンプレート

ファイル名:

内容がわかる名前にする。

例:

• •tanstack-router-prerender-middleware.md
• •drizzle-d1-local-setup.md
• •cloudflare-workers-env-binding.md

本文:

# タイトル

## 問題

何が起きていたか。

## 原因

なぜ起きていたか。

## 解決策

どう解決したか。

issues テンプレート

ファイル名:

問題を端的に表す名前にする。

本文:

# 問題のタイトル

## 問題

何が起きているか。

## 再現手順（必要に応じて）

1. ...
2. ...

## ワークアラウンド（あれば）

暫定的な回避策。

## 調査メモ（あれば）

調べたこと、試したこと。

背景

なぜ notes と issues を分けるか

• •notes: 解決済み → 他の開発者がすぐ参照できる
• •issues: 未解決 → 誰かが引き継いで調査できる

なぜ即座に記録するか

問題を解決したらすぐに記録する。後回しにすると忘れる。

問題発生 → 調査 → 解決 → 即座に記録

解決したら issues から notes へ

issues に記録した問題が解決したら:

1. •解決策を notes に記録
2. •issues のファイルを削除

CLAUDE.md との使い分け

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/` - 未解決の問題・調査中の課題