概要
Claude Code の「スキル」という仕組みを試してみた。
今回は「振り返りレポートを docs/ に生成するスキル」を作って運用してみたところ、思った以上に体験が良かったので紹介する。
スキルとは
基本的には、/retrospective のようなスラッシュコマンドを自分で定義でき、呼び出すと Claude がプロジェクトを探索して指定の処理を実行してくれるもの。
今回は「振り返り」と言うだけでスキルを使うようにした。コマンドに切り替える必要もなくて便利。
作ったスキルの概要
まず最初にClaudeに「振り返り」を依頼した。
出てきた結果が良かったので「これをスキル化して」と依頼した。
生成されたスキルファイルは下記。
---
name: retrospective
description: プロジェクトの現状を探索し、設計・実装の振り返りレポートを docs/ に生成する。
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash
---
# 振り返りレポート生成
## 手順
1. コードベース探索
- ディレクトリ構成・各 app/package の役割を把握する
- git ログで直近の変更を確認する (git log --oneline -20)
...
2. レポート生成
ファイル名: docs/retrospective-YYYY-MM-DD.md
以下のセクションを含める：
- 概要 / 作ったもの / 技術選定の判断 / 実装して良かったこと / 苦労したこと・課題 / 今後やること
スキルファイルを置くだけで Claude が自動認識するため、/retrospective と入力するか「振り返り」と言うだけで起動できる。Claude がリポジトリを探索し、以下のような内容を docs/retrospective-YYYY-MM-DD-<topic>.md に書き出してくれる。
- 何を作ったか（変更ファイル一覧・アーキテクチャ図）
- 技術選定の判断理由
- 実装してよかったこと
- 苦労したこと・課題
- 今後やること
- 設計上の学び
よかったこと
push・プルリク作成前にレビューできる
プルリクの説明欄に書く内容は、コードを書いたあとに改めて「何をしたか」をまとめる作業だ。振り返りをファイルに保存しておくと、push する前にそのファイルを開くだけでセルフレビューができる。
「この変更、本当に出してよいか？」を確認する最後のチェックポイントとして機能する。プルリクの本文にそのまま貼り付けることもできる。
なぜその実装をしたかが後から確認できる
コミット履歴には「何を変えたか」は残るが、「なぜそうしたか」は残りにくい。振り返りファイルには技術選定の判断理由が明示的に書かれているので、数週間後に「なんでここ Promise.all にしたんだっけ？」と思ったときに即答できる。
## 3. 技術選定の判断
### `extractFactsFromText` と `extractPersonaHintsFromReply` を並列実行
2つの LLM 呼び出しは互いに独立しているため並列化。
会話1ターンあたりのレイテンシを削減。
このような記録が docs/ に蓄積されていくため、なぜこの実装なのかという意思決定ログとして使えそう。
Claude が一気にコードを書いたときに体験が良い
Claude Code を使うと、1つの機能を一気にまとめて実装してもらえる。バックエンド・フロントエンド・型定義・スタイルを横断して変更が走るため、「とりあえず動くか確認する」フェーズで何が変わったかを追うのが大変になりがち。
こういうときに振り返りスキルを使うと、
差分を1ファイルずつ読まなくても、何がどう変わったかを俯瞰できる。
まとめ
| やりたいこと | 振り返りスキルで得られるもの |
|---|---|
| push前のセルフレビュー | 変更の全体像・判断理由を一覧で確認 |
| なぜその実装か後から確認 |
docs/ に設計判断の記録が蓄積される |
| Claude が大量に書いたコードの把握 | 最後に1ファイル確認するだけでよい |
Claude Code のスキル機能は数行の定義で動くので、プロジェクトに合わせたカスタマイズが気軽にできる。振り返りのような「締め作業」をスキルにしておくと、実装のたびに自然とドキュメントが積み上がっていく。
もうしばらく続けてみようと思う。
車輪の再発明かもしれないので、もっといい手法などご存じの方いれば、コメントいただきたい。