capture-learning

学びの記録

最近の会話のコンテキストを分析して学びを記録します。プロジェクトのナレッジファイル、または複数のプロジェクトで再利用できるスキル／コマンド／サブエージェントに記録します。

基本的なワークフロー

ステップ 1：最近のコンテキストを分析する

現在の会話を確認して、次の点を特定します。

1. 発生した問題 - 何がうまくいかなかったか、何がわかりにくかったか
2. 根本原因 - なぜそれが起きたのか
3. 解決策 - どのように解決したか
4. 予防策 - 今後、どのように回避するか

漠然とした要約ではなく、具体的で実行可能な知見を抽出します。

良い学びの例：

When running `npm install` on Node 20+, the `--legacy-peer-deps` flag
is required due to React 18 peer dependency conflicts.

悪い学びの例：

Had some issues with npm install, fixed it eventually.

ステップ 2：学びの適用範囲を判断する

記録先を決める前に、この学びはプロジェクト固有か、一般的かを確認します。

適用範囲	特徴	記録先
プロジェクト固有	このコードベースのアーキテクチャ、規約、依存関係、ローカル環境設定に関する内容	プロジェクトのナレッジファイル（.claude/CLAUDE.md、.claude/docs/）
一般的	言語のパターン、フレームワークのベストプラクティス、ツールの使い方、API の特性など、すべてのプロジェクトに適用できる内容	スキル、コマンド、またはサブエージェント

判断のための質問：

1. 同じ言語／フレームワークを使う別のプロジェクトでも役立ちますか？
2. これは一般的な手法ですか、それともこのリポジトリ固有の実装ですか？
3. この分野をすでにカバーしているスキルはありますか？

例：

学び	適用範囲	記録先
「このリポジトリでは、エラー処理に ApiError クラスを使用する」	プロジェクト固有	.claude/CLAUDE.md
「SwiftUI の matchedGeometryEffect はコンテンツではなく、背景の図形にのみ適用する」	一般的	swiftui-excellence スキル
「このプロジェクトでは npm install --legacy-peer-deps を実行する」	プロジェクト固有	.claude/CLAUDE.md
「React Server Components では useState を使用できない」	一般的	react-component-dev スキルなど
「CI パイプラインでは NODE_ENV=test が必要」	プロジェクト固有	.claude/docs/setup.md
「Playwright の page.waitForSelector は、適切なエラー処理がないとタイムアウトしてもエラーを表示しない」	一般的	playwright-qa-tester エージェントまたは新しいスキル

一般的な内容の場合： 適切なスキル／コマンド／サブエージェントのファイルを開き、既存の構成に沿って更新します。その後、保存する前にユーザーに確認します。

プロジェクト固有の内容の場合： ステップ 3 に進みます。

ステップ 3：ナレッジファイルを確認する（プロジェクト固有の学び）

プロジェクトの .claude/ ディレクトリにある既存のナレッジファイルを確認します。

# Primary targets (most common)
.claude/CLAUDE.md          # Main project instructions
./CLAUDE.md                # Root-level alternative

# Secondary targets
.claude/docs/*.md          # Reference documentation
.claude/docs/**/*.md       # Nested docs

# Tertiary (check but don't modify without explicit request)
.claude/plans/*.md         # Planning docs (usually ephemeral)

更新の優先順位：

1. CLAUDE.md（プロジェクトのルートまたは .claude/）- 一般的な学び、セットアップの問題
2. .claude/docs/troubleshooting.md - 存在する場合は、デバッグに関する知見
3. .claude/docs/setup.md - 存在する場合は、環境／ビルドに関する問題
4. ユーザーから依頼された場合に限り、新しいファイルを作成

ステップ 4：学びを分類する

学びを記録するセクションを決定します。

学びの種類	記録先のセクション	例
ビルド／依存関係の問題	## Build & Setup または ## Troubleshooting	npm のフラグ、バージョン要件
環境設定	## Environment または ## Prerequisites	環境変数、ツールのバージョン
コードのパターン	## Patterns または ## Conventions	命名、アーキテクチャ上の判断
既知の問題	## Known Issues または ## Gotchas	特有の挙動、回避策
デバッグに関する知見	## Debugging	特定の問題を診断する方法

記録先のセクションが存在しない場合は、適切な位置に作成することを提案します。

ステップ 5：更新内容を作成する

ドキュメント用に学びを整えます。

問題に基づく学びの構成：

### [Short descriptive title]

**Problem:** [What went wrong]
**Cause:** [Why it happened]
**Solution:** [How to fix/prevent]

パターン／規約に基づく学びの構成：

### [Pattern name]

[Brief description of when/why to use this pattern]

```code
[Example if applicable]

**Structure for quick tips:**
```markdown
- [Concise actionable tip]

各項目は次のようにまとめます。

• 見つけやすく - 見出し、箇条書き、コードブロックを使います
• 実行可能に - 具体的な手順やコマンドを示します
• 文脈がわかるように - 「何を」だけでなく、「なぜ」も説明します

ステップ 6：変更内容を提示して確認する

ファイルを変更する前に、次の内容をユーザーに提示します。

1. 対象ファイル - 更新するファイル
2. 場所 - 対象のセクション（既存または新規）
3. 追加予定の内容 - 追加する正確なテキスト
4. 差分プレビュー - 挿入箇所の前後のコンテキストを表示

確認プロンプトの例：

I'll add this to `.claude/CLAUDE.md` under "## Troubleshooting":

### Node 20 Peer Dependency Fix

**Problem:** `npm install` fails with peer dependency conflicts
**Cause:** React 18 has strict peer deps incompatible with some packages
**Solution:** Run `npm install --legacy-peer-deps`

Should I apply this update?

書き込みを行う前に、ユーザーから明示的な承認を得てください。

ステップ 7：更新を適用する

確認を得た後：

1. 対象ファイルを読み取る
2. 適切な挿入箇所を見つける
3. 適切な書式で新しい内容を追加する
4. 更新したファイルを書き込む
5. 更新が適用されたことを確認する

新しいセクションを作成する場合は、論理的な位置に配置します。

• セットアップ／ビルドのセクションは上部付近
• トラブルシューティングのセクションは下部付近
• パターン／規約は中ほど

ファイル検出の詳細

スキャン戦略

# Check for .claude directory
ls -la .claude/ 2>/dev/null

# Find all markdown files in .claude
find .claude -name "*.md" -type f 2>/dev/null

# Check root for CLAUDE.md
ls CLAUDE.md 2>/dev/null

ファイルの目的の認識

次の情報からファイルの目的を推測します。

1. ファイル名 - troubleshooting.md、setup.md、patterns.md
2. 場所 - 参照資料は .claude/docs/、計画資料は .claude/plans/
3. 内容 - 既存のセクション見出しからファイルの対象範囲を判断する
4. CLAUDE.md の特別な扱い - 一般的な知見を記録する有効な対象ファイルとして常に扱う

適切なファイルが存在しない場合

.claude/CLAUDE.md が存在しない場合：

1. プロジェクトのルートに ./CLAUDE.md があるか確認する
2. どちらも存在しない場合は、次の選択肢をユーザーに尋ねます。
   • .claude/CLAUDE.md を作成する
   • 特定のドキュメントファイル（例：.claude/docs/troubleshooting.md）を作成する
   • 今回は記録をスキップする

知見の抽出パターン

ビルド／セットアップの問題

次のような会話パターンを探します。

• エラーメッセージの後に解決策が示されている
• 「これで修正できた」または「解決策は……だった」
• バージョン固有の回避策
• 依存関係または設定の不足

抽出する内容：エラー、根本原因、修正コマンド／手順。

コードパターン

次の内容を探します。

• 「このコードベースでは……を使用している」という発見
• アーキテクチャ上の決定に関する説明
• 特定された命名規則
• フレームワーク固有のパターン

抽出する内容：パターンの説明とその理由。

デバッグに関する知見

次の内容を探します。

• 複数段階のデバッグ手順
• 一見して分かりにくい根本原因
• 診断コマンドや手法
• 「実際の問題は……だった」

抽出する内容：症状、調査手順、根本原因。

例

例 1：ビルドの問題

コンテキスト： TypeScript のバージョン不一致によるビルド失敗の修正に取り組んだセッション。

記録した知見：

### TypeScript Version Requirement

**Problem:** Build fails with "Cannot find module 'typescript'"
**Cause:** Project requires TypeScript 5.3+ but system has 5.0
**Solution:**
```bash
npm install typescript@^5.3.0 --save-dev

### Example 2: Environment Setup

**Context:** Session discovered required environment variables.

**Captured learning:**
```markdown
### Required Environment Variables

The following must be set in `.env.local`:
- `DATABASE_URL` - PostgreSQL connection string
- `NEXTAUTH_SECRET` - Generate with `openssl rand -base64 32`
- `NEXTAUTH_URL` - Set to `http://localhost:3000` for development

例 3：コードパターン

コンテキスト： プロジェクトのエラー処理規約が明らかになったセッション。

記録した知見：

### Error Handling Pattern

All API routes use the `ApiError` class for consistent error responses:
```typescript
throw new ApiError(404, "Resource not found");

エラーハンドラーミドルウェアは、これらを JSON レスポンスに変換します。

## Edge Cases

### Multiple Learnings

If the session contains multiple distinct learnings:
1. List them for the user
2. Ask which to capture (or all)
3. Process each separately with confirmation

### Conflicting Information

If new learning contradicts existing documentation:
1. Show both versions
2. Ask user which is correct
3. Update or replace as directed

### Sensitive Information

Never capture:
- API keys, tokens, or secrets
- Passwords or credentials
- Personal information
- Internal URLs that shouldn't be documented

If a learning involves secrets, document the *pattern* without the actual values.

## Quick Reference

**Trigger phrases:** "capture this", "remember this", "update docs", "document this", "add to CLAUDE.md", "save this knowledge"

**First question:** Is this project-specific or general?

**Project-specific targets:** `.claude/CLAUDE.md` (primary), `.claude/docs/*.md` (secondary)

**General targets:** Skills (`~/.claude/skills/`), commands (`~/.claude/commands/`), subagents (plugin agents)

**Always confirm:** Show exact changes before writing

**Format:** Problem → Cause → Solution (for issues), Description → Example (for patterns)

## Additional Resources

### Reference Files

- **[references/section-templates.md](references/section-templates.md)** - Complete templates for common documentation sections (Troubleshooting, Build & Setup, Environment, Patterns, Known Issues, Debugging). Consult when creating new sections or structuring complex learnings.