Issue から PR まで任せている Claude Code のスキルを棚卸ししてみた

1. はじめに

こんにちは。リテールアプリ共創部の中村です。

普段は、Issue から PR 作成までを一気通貫で進めてくれるスキル（Skills）を自作し、それを使って開発業務をしています。日々スキルを改善していく中で、自分でも把握しきれていない部分が出てきました。そこで、このタイミングでスキルの中身を整理・棚卸しして、理解を深めようと思います。

本記事は、次の順に進めます。

1. スキルの構成：ディレクトリ構造と、誰がどの工程を受け持つか
2. 実装とレビューのループ：どこで回し、いつ止めるか
3. 置き場所の基準：決まりの性質ごとに、どこに置くか
4. 置き場所ごとに気をつけたこと：それぞれで工夫したこと
5. スキルの効果：PR の評判が良くなった理由
6. 棚卸しして見えたこと：終わる条件を持つループが、実装とレビューの間にしか無いこと

2. スキルの構成

2-1. ディレクトリ構造

スキルに関係するファイルは、~/.claude/ の下に次のように置いています。

~/.claude/
├── CLAUDE.md                     # 取り消しにくい操作の聞き方
├── settings.json                 # hook の登録（PreToolUse・Bash）
├── skills/
│   ├── drive-dev-flow/           # 今回の一気通貫スキル
│   │   ├── SKILL.md              # 工程の流れ・ゲート・ループの条件
│   │   ├── roles.md              # 作る側の担当の定義
│   │   └── history.md            # 決まりを足した経緯
│   └── _shared/                  # ほかのスキルと共有するチェックリスト
│       ├── coding-principles.md  # コードの書き方の原則（paths 付き）
│       ├── gate-principles.md    # ゲート運用の共通ルール
│       ├── design-review-checklist.md
│       ├── test-coverage-checklist.md
│       └── ...                   # React・TypeScript・DDD・命名・変更の局所性など
├── agents/                       # レビュー役4つ
│   ├── ddf-design-reviewer.md
│   ├── ddf-testlist-reviewer.md
│   ├── ddf-impl-reviewer.md
│   └── ddf-checklist-reviewer.md
├── hooks/
│   └── ddf-gate-guard.py         # ゲート3・4を止める hook
└── rules/
    └── coding-principles.md      # skills/_shared/coding-principles.md へのリンク

このほか、ワークツリー（Issue ごとに作る作業用のディレクトリ）の git 管理領域に、hook が見る小さなファイルを置きます。これらはリポジトリの中身に入らず、ワークツリーを消すと一緒に消えます。

<ワークツリーの git 管理領域>/     # git rev-parse --absolute-git-dir の場所
├── ddf-active                    # hook が動く目印（ワークツリーを作るときに置く）
├── ddf-approve-commit            # 承認の記録（30分で切れる）
├── ddf-approve-push
└── ddf-approve-pr

2-2. 全体像

メイン（指揮者）が全体を進め、作る作業をチームメイトに、レビューなどをサブエージェントに任せる作りです。工程は「Issue → 設計 → テストリスト → 実装 → PR」の5つで、途中にゲート1〜4（ユーザーの承認）を置いています。

図1：一気通貫スキルの全体像

標準の構成では、メインのほかに、チームメイト3体とサブエージェント5体が動きます。工程の進み具合は、状態メモ（工程ごとの結果を書く Markdown ファイル）で引き継ぎます。

3. 実装とレビューのループ

実装のあとは、レビューの指摘が基準に収まるまで「直す → 検証する」を繰り返します。作る役（Maker）と確かめる役（Checker）を分け、終わる条件と止まる条件を先に決めています。

図2：実装とレビューのループ

• 役を分ける：直すのは実装担当です。検証するのは、別の文脈で動くレビュー役2体（実装レビューとチェックリストレビュー）です
• 終わる条件：どのレビューも重大度の高 0・中 0、低5件以下になったら抜けます。そのあと、ゲート3でユーザーにコミット・push の承認をもらいます
• 止まる条件：5往復しても終わらないとき、同じ箇所への指摘が3回続いたときは、ループを抜けてユーザーに判断を仰ぎます。直し方そのものを見直すサインと考えています
• 経過を残す：指摘を反映したか見送ったかと、その理由を状態メモに残します。2回目以降は、修正で増えた差分だけを再レビューします

Addy Osmani 氏の記事「Loop Engineering」では、ループの中でいちばん役に立つ構造として、書く役と確かめる役を分けることが挙げられています。確かめられる完了の条件を満たすまで回し続ける仕組みも紹介されており、このスキルの役の分け方と終わる条件は、それと同じ形になっていました。

参考：Loop Engineering｜AddyOsmani.com

4. 置き場所の基準

公式ドキュメントには、CLAUDE.md や自動メモリについて次のように書かれています。

Claude はこれらをコンテキストとして扱い、強制的な設定ではありません。アクションをブロックするには、Claude の判断に関わらず PreToolUse hook を使用してください。

スキルの文章も同じで、読んだうえで Claude が判断します。そこで、決まりの性質ごとに、次の基準で置き場所を分けています。

参考：Claude があなたのプロジェクトを記憶する方法｜Claude Code Docs・カスタムサブエージェントの作成｜Claude Code Docs・Hooks リファレンス｜Claude Code Docs・Claude をスキルで拡張する｜Claude Code Docs

5. 置き場所ごとに気をつけたこと

置き場所を分けるだけでは、うまく動きませんでした。それぞれで気をつけたことをまとめます。

5-1. SKILL.md と roles.md：流れだけを書く

• レビューの観点は、スキルに文章で書かない：観点は _shared の項目 ID 付きチェックリストに出し、スキルからは「どれを読むか」だけを指定しています。文章で書くと、全項目を見たかどうかを確かめられないためです
• 工程の間は、会話ではなく状態メモと成果物で引き継ぐ：設計書・テストリスト・差分を次の担当に渡す形にして、メインの会話が長くならないようにしています
• 作る側の担当は、チームメイトのままにする：設計・テストリスト・実装は、ユーザーと相談しながら進めます。会話を続けられるチームメイトが合っているので、agents にはしていません

5-2. agents：レビュー役に余計なことをさせない

• 編集の機能を持たせない：レビュー役が自分でコードを直すと、作る役と確かめる役が混ざります。Edit を外し、指摘をファイルに書き出すだけにしています
• 作る側と別のモデルで動かす：同じモデルだと、見落とす箇所が重なりやすいと考えたためです
• 使う場面を説明（description）で絞る：「drive-dev-flow のメインが起動する。それ以外の場面では使わない。」と書き、ほかの作業で呼ばれないようにしています
• 共通のルールは写さない：4つの定義に同じルールを書くと、直すときにずれます。定義からは roles.md の共通ルールを読みに行かせています

※指摘を書き出すための Write と、差分を見るための Bash は持たせているので、ファイルの書き換えそのものは防げていません。

5-3. hook：止める範囲と判断の材料を絞る

• 開発フローのワークツリーでだけ動かす：目印のファイルがある場所でだけ止めるので、普段の作業のコミットは邪魔しません
• 判断の材料は、決まった形の記録ファイルにする：状態メモの承認の書き方は「✅」「通過」「省略」などばらばらで、読んで判断すると誤判定しそうでした。そのため、承認の記録だけを別の小さなファイルに分けています
• 承認の記録が使える時間を30分に限る：1回の OK を、時間がたったあとの別の操作に使い回さないためです
• 担当からの実行は、記録があっても止める：コミット・push・PR の作成はメインの仕事です。入力の agent_id で担当からの実行を見分けています

※仮のリポジトリで26通りの入力を試し、期待どおり動くことを確かめました。実環境での確認はこれからです。

5-4. rules と _shared：同じ内容を二重に持たない

• ファイルは1つにする：コードの書き方の原則は _shared にあり、~/.claude/rules/ からはシンボリックリンクで指しています。スキルから読んでも rules として読み込まれても、同じ内容です
• 読み込む場面を TS・JS に絞る：paths を TS・JS のファイルにしています。rules は開発フロー以外の作業でも読み込まれるので、関係の無いファイルでは読み込まれないようにしました

※チームメイトとして動く実装担当にもこのルールが読み込まれるかは、公式ドキュメントに書かれていないので、実際に動かして確かめます。

5-5. CLAUDE.md：短く、行為を名指しする

• どの作業でも守ることだけを短く書く：取り消しにくい操作の節には、「コミット・push・PR の作成・GitHub への書き込みの前は、内容を見せ、行為を名指しして承認をもらう」という決まりだけを置いています
• あいまいな OK を承認にしない：「続けてよいですか」への OK や相づちは、承認として扱わないと書いています
• hook に止められたときの動きも書く：記録を書いて通そうとせず、ユーザーに伝えてから聞き直すようにしています

6. スキルの効果

チェックリストとループを取り入れてから、PR をレビューしてくださる方からの評判が良くなりました。

うまくいっている理由は、次の3つの組み合わせだと考えています。

1. さまざまな観点で見ている
   バグを探す実装レビューに加えて、受け入れシナリオとの照合や、テスト網羅性・React・TypeScript・DDD・命名・変更の局所性などのチェックリストで差分を見ています。項目ごとに結果の表を残すので、「見たつもり」で終わりません。
2. 作る役と確かめる役を分けている
   レビュー役は、実装した担当とは別の文脈・別のモデルで動き、コードを直す役目を持ちません。書いた本人の思い込みが、そのまま通りにくくなります。
3. 基準を満たすまでループしている
   1回のレビューで終わらせず、3章の終わる条件まで繰り返します。指摘への対応とその理由も状態メモに残るので、PR を出す時点で説明がそろっています。

人がレビューする前に、観点の広さとやり直しの回数をスキルの側で担保しておくと、質の高い PR になりやすいと感じています。

7. 棚卸しして見えたこと

終わる条件・止まる条件を持って回っているのは、実装とレビューの間だけです。

レビューの指摘が設計書に無い判断を必要とするものなら、メインが設計担当に戻す決まりはあります。ただ、設計まで戻ったときに、設計レビューをどう回し直し、いつ止めるかは決めていません。内容によっては設計まで戻る必要があるので、その場合のループも考えておく必要があると感じました。

8. まとめ

一気通貫のスキルは、決まりを書き足すうちに、何がどこでどう効いているのかが見えにくくなります。

棚卸ししてみると、強制したいものは hook、役が決まっているものは agents、触るファイルで決まるものは rules、どこでも守るものは CLAUDE.md、流れはスキル、と置き場所ごとに説明できる形になっていました。また、チェックリストとループの組み合わせが PR の質につながっている一方で、終わる条件を持つループが設計まで届いていないことも見えてきました。

スキルが大きくなってきて、中身の見直しを考えている方の参考になれば幸いです。

9. 参考資料

本記事の内容は、以下の情報で確認しました（2026年11月9日時点）。

Claude Code Docs

• Claude があなたのプロジェクトを記憶する方法｜Claude Code Docs
• カスタムサブエージェントの作成｜Claude Code Docs
• Hooks リファレンス｜Claude Code Docs
• Claude をスキルで拡張する｜Claude Code Docs

ループの考え方

• Loop Engineering｜AddyOsmani.com