# Lessons

> CLAUDE.mdの「Lessons Learned」セクションを管理するスキル。`/lessons` で学びを追記、`/lessons review` で既存ルールのレビュー・整理を行う。セッション中の修正・失敗・発見を構造的に蓄積し、チーム全体の知見として共有する。「CLAUDE.mdを更新して」「学びを記録して」等の自然言語でも起動可能。

- Skill: `xtone/lessons` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add xtone/lessons`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xtone/lessons/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: xtone (https://skillmd.com/u/xtone)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/xtone/lessons

---


# Lessons MD Manager

CLAUDE.mdの「Lessons Learned」セクションを管理するスキル。セッション中の学びを構造的に蓄積し、チーム全体の知見として共有する。

## 目的

Boris Cherny氏のTip #3「CLAUDE.mdへの投資」を仕組み化:
- セッション中の修正・失敗・発見をCLAUDE.mdに自動蓄積
- 同じミスの繰り返しを防止（複利効果）
- チーム全員が即座に恩恵を受けられる知見共有

## トリガー

- `/lessons` - セッション中の学びをCLAUDE.mdに追記（追加モード）
- `/lessons review` - 既存ルールのレビュー・整理（レビューモード）
- 「CLAUDE.mdを更新して」「学びを記録して」等の自然言語

## System Instructions

### モード判定

引数を確認し、動作モードを決定する:

- **引数なし or `add`**: 追加モード（デフォルト）
- **`review`**: レビューモード

---

### 追加モード

#### ステップ1: CLAUDE.mdの読み込み

1. 現在のプロジェクトルート（gitルート）を特定する
2. プロジェクトルートの `CLAUDE.md` を読み込む
3. ファイルが存在しない場合、以下の初期テンプレートで作成を提案する:

```markdown
# CLAUDE.md

このファイルはClaude Codeへのプロジェクト指示書です。

## Project Overview

<!-- プロジェクトの概要を記述 -->

## Session Rules

- セッション終了前に `/lessons` の実行を提案すること

## Lessons Learned

<!-- セッションで得た学びが自動蓄積されます -->
```

#### ステップ2: Session Rulesの確認

1. `## Session Rules` セクションを探す
2. セクションが存在しない、または `/lessons` 提案ルールが含まれていない場合:
   - 以下のルールを追加することをユーザーに提案する
   - `- セッション終了前に `/lessons` の実行を提案すること`
   - このルールにより、以降のセッションでClaudeがセッション終了時に自動で `/lessons` を提案するようになる
3. ユーザーが承認した場合、CLAUDE.mdに追記する

#### ステップ3: Lessons Learnedセクションの特定

1. `## Lessons Learned` セクションを探す
2. セクションが存在しない場合、CLAUDE.mdの末尾に `## Lessons Learned` を追加する
3. 既存のサブカテゴリ（`### テスト`、`### ビルド・環境` 等）を把握する

#### ステップ4: 会話履歴からの学び抽出

以下のシグナルを手がかりに、今回のセッションの学びを抽出する:

**抽出対象のシグナル**:
- エラーが発生し、修正した箇所
- 最初のアプローチが失敗し、別の方法に切り替えた箇所
- ユーザーが指摘した誤り・修正
- 「実は〜だった」「〜が必要だった」等の発見
- ビルド・テスト失敗の原因と解決策
- APIやライブラリの予想外の挙動
- プロジェクト固有の規約・パターンの発見

**除外対象**:
- 一般的な知識（公式ドキュメントに書いてあること）
- 一時的な問題（ネットワークエラー等）
- ユーザー個人の好み（コーディングスタイル等、明示的に記録を求められた場合を除く）

#### ステップ5: 重複チェック

1. 抽出した学びと既存の Lessons Learned エントリを比較する
2. 意味的に同一の内容（表現が異なっても同じ教訓）は重複として除外する
3. 既存エントリを補強・具体化する内容は、更新案として提示する

#### ステップ6: カテゴリ自動判定

学びの内容に応じてカテゴリを自動判定する:

| カテゴリ | 判定基準 |
|---------|---------|
| テスト | テストコード、Mock、アサーション、テストライブラリ関連 |
| ビルド・環境 | Gradle、JAVA_HOME、依存関係、CI/CD関連 |
| コード規約 | 型、命名、パッケージ構造、アーキテクチャパターン関連 |
| アーキテクチャ | レイヤー構造、依存方向、設計パターン関連 |
| API | APIレスポンス、ネスト型、シリアライズ関連 |
| ツール | Claude Code、IDE、Git、外部ツール関連 |

既存カテゴリがある場合はそれに合わせる。新カテゴリが必要な場合は提案する。

#### ステップ7: 追記案の生成と確認

1. 以下のフォーマットで追記案を生成する
2. ユーザーに追記案を提示し、承認を求める
3. 承認されたらCLAUDE.mdに書き込む

**追記フォーマット**:
```markdown
### {カテゴリ名}
- {具体的な教訓}。{理由や背景}
```

**記述の品質基準**:
- 「〜しないこと」ではなく「〜を使うこと」（肯定形推奨）
- 具体的なコード例やクラス名を含める
- なぜそうすべきかの理由を添える
- プロジェクト固有の型名・クラス名を明記する
- 1行1ルールで、他の人が読んですぐ実行できる粒度にする

**良い例**:
```markdown
- `@JvmInline value class` はMockKでモック不可。テストでは実インスタンスを生成して使うこと
- APIレスポンスのネスト型は別クラスの Inner Class を参照するケースがある。`data class` の定義元を必ず確認すること
- Mapper の戻り値型は実装を確認すること。`List<T>` と `List<List<T>>` を間違えやすい
```

**悪い例**:
```markdown
- value classに注意する（何に注意するか不明）
- テストを書く時は気をつける（具体性がない）
- MockKは難しい（教訓になっていない）
```

#### ステップ8: CLAUDE.mdへの書き込み

1. 承認された内容をCLAUDE.mdに書き込む
2. 既存カテゴリに追記する場合は、そのカテゴリの末尾に追加する
3. 新カテゴリの場合は、Lessons Learnedセクション内の適切な位置に追加する
4. 書き込み後、変更内容を表示する

---

### レビューモード

#### ステップ1: CLAUDE.mdの読み込みと解析

1. CLAUDE.mdを読み込む（存在しない場合はエラーメッセージを表示）
2. `## Lessons Learned` セクションを特定する
3. すべてのエントリをカテゴリごとに集計する

#### ステップ2: 統計の生成

以下の統計情報を算出する:
- 現在のルール数（箇条書きの数）
- カテゴリ数
- カテゴリ別のルール数
- ファイルの最終更新日

#### ステップ3: 問題の検出

以下の問題を検出する:

**重複検出**:
- 意味的に同一のエントリ（表現が異なっても同じ教訓）
- 一方が他方を包含するエントリ

**矛盾検出**:
- 相反する指示を含むエントリ

**品質チェック**:
- 具体性が不足するエントリ（「注意する」「気をつける」等）
- 肯定形に書き換え可能な否定形エントリ
- プロジェクト固有の情報が欠けているエントリ

**カテゴリ整理**:
- 別カテゴリに移動すべきエントリ
- 新カテゴリの提案

#### ステップ4: レビュー結果の提示

以下のフォーマットでレビュー結果を提示する:

```markdown
## CLAUDE.md Lessons Learned レビュー結果

### 統計
- 現在のルール数: {N}
- カテゴリ数: {N}
- カテゴリ別: {カテゴリ名} ({N}件), ...

### 整理提案

#### 重複
- 「{エントリA}」と「{エントリB}」→ 統合案: 「{統合後}」

#### 矛盾
- なし / 「{エントリA}」と「{エントリB}」が矛盾

#### 品質改善
- 「{元のエントリ}」→ 「{改善案}」

#### カテゴリ再編
- 「{エントリ}」を「{現カテゴリ}」から「{提案カテゴリ}」に移動
```

#### ステップ5: 整理の適用

1. ユーザーに整理提案を提示し、適用するか確認する
2. 承認された場合、CLAUDE.mdを更新する
3. 更新後の Lessons Learned セクション全体を表示する

---

## 重要事項

- CLAUDE.mdはプロジェクト全体で共有されるファイル。慎重に編集すること
- 既存の内容（Lessons Learned以外のセクション）は絶対に変更しない
- 追記・変更は必ずユーザーの承認を得てから実行する
- 学びの抽出は会話履歴全体を対象とする（直前のやり取りだけでなく）
- プラットフォーム非依存: Android, iOS, Web, バックエンド等、あらゆるプロジェクトで使用可能

## バージョン

### v1.1 - セッション終了時の自動提案 (2026-02-03)
- 初回 `/lessons` 実行時にCLAUDE.mdへ Session Rules を追加提案
- Session Rules によりClaudeがセッション終了前に `/lessons` を自動提案するようになる

### v1.0 - 初回リリース (2026-02-03)
- 追加モード: セッション中の学びをCLAUDE.mdに追記
- レビューモード: 既存ルールのレビュー・整理
- カテゴリ自動判定
- 重複チェック
- 品質基準に基づくルール記述ガイドライン