新人向け「読むだけじゃ作れない」問題を解決するオンボーディングSkillとフロー

はじめに

いえらぶＧＲＯＵＰの開発部で執行役員を務めています、和田です。わだけんです。最近はありがたいことに「新人のAI禁止の方ですか！」とか言われたりしていただいたりすることもたまにあります。

Cursorブームの到来以降、Claude Codeを使って要件定義書や設計ドキュメントを作成し、それを開発担当者に渡して実装してもらうフローをひたすら整備してきました。チケットの背景から変更対象ファイル、テーブル設計、フェーズ分割まで、かなりの粒度で書けるようになったと思っています。

ですがやはり、新卒未経験のメンバーに渡すと、なかなか手が動かない。

ドキュメントは読んでくれている。理解してるとも言います。しかしいざ実装、となるとやはり「何から手をつければいいのかわからない」と。

まあ考えてみれば当然の話で、要件定義書って「何を作るか」は書いてあるけど「どの順番で、何をアウトプットしながら進めるか」は書いてない。中級者以上にとっては行間で補える部分を、未経験者には行間がそもそも見えていない。

ドキュメントの品質を上げるアプローチは1年やった。次のフェーズとして「ドキュメントを使って手を動かさせるためのドキュメント」が必要なんだと思って調整しました。

で、それをClaude Codeのスキル（カスタムスラッシュコマンド）として作ったので、仕組みと実際の成果物を共有したいと思います。

やりたかったこと

一言で言うと「要件定義書をもとに、ハンズオン形式で段階を踏んでインプットとアウトプットを繰り返しながら案件を遂行するための指示書」を自動生成したかった。

ポイントは3つあって：

1. 毎日1つの提出物がある（読んで終わりにならない）
2. Q&Aに模範解答がついている（メンターが毎回解説しなくていい）
3. セルフチェックリストがある（「できたつもり」を防ぐ）

手作業でこれを書くと1案件あたり半日〜1日かかる。案件ごとにコード構造もフェーズ分割も違うので、テンプレのコピペでは済まない。

Claude Codeのスキルにすれば、MRの差分や要件定義書の内容を読み込んだ上で、案件に特化した指示書を生成できるんじゃないかと。

スキルプロンプト（SKILL.md 原文）

Claude Codeのスキルは .claude/skills/{スキル名}/SKILL.md に配置することで、スラッシュコマンドとして呼び出せるようになります。以下が実際のプロンプト原文です。

SKILL.md 全文（クリックで展開）

---
name: onboarding-guide-creator
description: 指定案件（チケット番号）の実装オンボーディング指示書を自動生成するスキル。
  GitLab MR・要件定義書・コードベースから情報を収集し、初心者エンジニア向けの
  Step-by-Step指示書をMarkdownで生成する。各Stepには提出物テンプレート、
  Q&A（模範解答付き）、セルフチェックリスト、完了基準を含む。
---

# オンボーディング指示書作成スキル

## ワークフロー

### Phase 1: 情報収集

ユーザーから以下を確認する（不足分はAskUserQuestionで質問）:

1. **チケット番号**（必須）
2. **期間**（必須: 1週間 / 2週間 / 3週間）
3. **MR URL**（あれば）
4. **要件定義書URL**（あれば）
5. **前提条件**（あれば）

情報収集の手順:
- gitlab-investigator MCPで get_mr() → MR概要取得
- gitlab-investigator MCPで get_mr_diff() → 変更ファイル一覧・差分取得
- ドキュメントMRがあれば同様に差分取得
- コードベースの変更対象ファイルを Read で確認（コントローラー、モデル、テスト）
- 既存の類似パターンを Grep で調査

### Phase 2: 構造設計

期間に応じてStepを設計する。

**1週間（5日）**: 7〜10 Step、提出物10個前後
**2週間（10日）**: 10〜12 Step、提出物12個前後
**3週間（15日）**: 13〜15 Step、提出物15個前後

基本の流れ: 理解 → (調査 → 設計 →) 実装 → テスト → MR → 動作確認 → デプロイ

### Phase 3: ドキュメント生成

テンプレート構造に従い指示書を生成する。

### Phase 4: コミット・プッシュ

1. ドキュメントリポジトリで feature_{チケット番号} ブランチに切り替え
2. コミット・プッシュ

## Step設計の原則

### 理解系Step
- **3〜5問のQ&A**をテーブル形式で必ず含める
- **模範解答**も同じテーブル形式で提供する
- 質問は**比較**を含める（「AではなくBを使う理由」）
- 質問は**コードの具体的な部分**を指す（ファイル名・メソッド名・行番号）

### 実装系Step
- **セルフチェックリスト**（チェックボックス形式）を必ず含める
- チェック項目はYes/Noで客観判定可能なもの
- 必須チェック: 言語バージョン互換、既存処理未変更、ドキュメント付与

### 確認系Step
- **動作確認レポートテンプレート**をテーブル形式で提供
- 確認項目: 正常系 + 異常系 + 影響なし確認

### デプロイ系Step
- **デプロイチェックシート**（手順・実施者・確認者・完了時刻）を提供
- 立ち会い必須の旨を明記

## 出力品質チェック

生成後、以下を自己確認:
- [ ] 全Stepに提出物が設定されている
- [ ] 全Stepに完了基準が設定されている
- [ ] 理解系StepにQ&A + 模範解答がある
- [ ] 実装系Stepにセルフチェックリストがある
- [ ] スケジュール（日付+STEP対応）が冒頭にある
- [ ] サマリーがある
- [ ] メンター向け申し送り事項がある
- [ ] 変更履歴がある

ポイントとしては、スキルプロンプトには「何を質問すべきか」「何を提出物にすべきか」の設計原則しか書いていないということです。具体的なQ&Aの中身や、チェック項目の中身は、MR差分やコードベースを読み込んだ上でClaude Codeが案件ごとに生成します。

つまりスキルは「オンボーディング指示書の作り方のルール」を定義しているだけで、中身は毎回変わる。これが手書きテンプレとの決定的な違いかなと思っています。

成果物サンプル

実際に生成されるオンボーディング指示書のイメージを共有します。「問い合わせ自動応答メール機能」を2週間で開発する想定の架空事例です。案件固有の情報が入る箇所は実物ではMR差分やコードから自動的に埋まりますが、ここでは雰囲気を掴んでもらうために汎用的な内容にしています。

問い合わせ自動応答メール機能 2週間開発オンボーディング指示書（サンプル）

# 【XXXX】問い合わせ自動応答メール機能 2週間開発オンボーディング指示書

## 概要

| 項目 | 内容 |
|------|------|
| 対象チケット | XXXX - 問い合わせ受信時に自動応答メールを送信する |
| 対象者 | 本案件にアサインされた初心者エンジニア |
| 期間 | 2週間（10営業日） |
| ゴール | テンプレート管理 + 自動送信処理の本番デプロイ完了 |
| 前提 | なし（新規機能） |

### 進め方のルール

- 毎日1つの提出物を作成し、メンターに共有する
- メンターのOKが出てから次のステップに進む
- 不明点はその日のうちに質問する
- メール送信テストは**必ずメンター立ち会い**で実施する

### 関連ドキュメント

| ドキュメント | パス |
|-------------|------|
| 要件定義書 | requirements/XXXX/要件定義書.md |
| テーブル定義 | requirements/XXXX/ddl_auto_reply_template.sql |
| MR（Phase 1） | GitLab MR URL |

---

## Week 1: 理解 → Phase 1（テンプレート管理）実装

### Step 1: 背景理解

**やること:** 要件定義書を読み、なぜこの機能が必要かを理解する

**提出物: 課題整理メモ（Slackで提出）**

以下の4問に各2〜3行で回答する。

| No | 質問 |
|----|------|
| Q1 | 現状、問い合わせを受けた後の初回応答はどのように行われているか |
| Q2 | 自動応答が必要とされている理由を、顧客体験の観点から1文で |
| Q3 | テンプレートを管理画面から編集可能にする理由（ハードコーディングとの比較） |
| Q4 | 自動応答メールに含めてはいけない情報は何か、その理由とともに |

**模範解答:**

| No | 回答 |
|----|------|
| A1 | 担当者が手動で返信している。営業時間外は翌営業日まで放置される |
| A2 | 初回応答までの時間が長いと離脱率が上がるため、即時の受付確認が必要 |
| A3 | テンプレートの文面変更のたびにデプロイが必要になる。運用担当が自分で変更できる方が保守コストが低い |
| A4 | 個人情報（担当者の個人連絡先等）。自動送信は送信先の検証が甘くなるため、漏洩時の影響が大きい |

**完了基準:** メンターが認識ズレなしと確認

---

### Step 2: 既存コード理解

**やること:** 既存の問い合わせ受信処理とメール送信共通処理を読む

**読むファイル:**
- 問い合わせ受信コントローラーの受付アクション
- メール送信共通サービスクラス
- 既存のメール送信テンプレート（1ファイル）

**提出物: 処理フロー図 + 設計意図Q&A（Markdownで提出）**

フロー図に含める要素:
フォーム送信 → バリデーション → DB保存 → 担当者通知メール → 完了画面表示

| No | 質問 |
|----|------|
| Q1 | 自動応答メールの送信処理を、コントローラーに直接書かずにサービスクラスに分離する理由は？ |
| Q2 | メール送信をDB保存と同一トランザクションに含めるべきか？含めない場合のリスクは？ |
| Q3 | 既存のメール送信処理ではエラー時にどう処理しているか？自動応答でも同じ方針でよいか？ |

**模範解答:**

| No | 回答 |
|----|------|
| A1 | コントローラーに書くと単体テストが困難になる。また、バッチからも自動応答を再送する可能性があり、サービスに分離しておけば再利用できる |
| A2 | 含めるべきではない。メール送信失敗でDB保存までロールバックすると、問い合わせデータ自体が失われる。メール送信失敗はログ記録 + リトライで対応する |
| A3 | 既存処理はcatch内でログ出力のみ行い、メイン処理を止めない設計。自動応答も同様に、送信失敗が問い合わせ受付自体を阻害しない設計にする |

**完了基準:** フロー図がコードと一致し、3問とも「なぜその設計か」を比較で説明できている

---

### Step 3: テーブル設計理解 + 既存パターン調査

**やること:** DDLを読み、既存の類似テーブル（通知設定テーブル等）と比較する

**提出物: テーブル比較表 + 調査メモ**

| 比較観点 | 既存の通知設定テーブル | 今回の自動応答テンプレートテーブル |
|---------|--------------------|-----------------------------|
| 主キー構成 | | |
| テナント分離の方法 | | |
| 有効/無効の制御方法 | | |
| 変更履歴の持ち方 | | |

追加Q&A:

| No | 質問 |
|----|------|
| Q1 | テンプレートテーブルに account_id カラムが必要な理由は？なかったら何が起きるか |
| Q2 | テンプレートの「有効/無効」をカラムで管理する方式と、レコード削除で管理する方式の違いは |

**完了基準:** マルチテナント分離の必要性を自分の言葉で説明できる

---

### Step 4: Phase 1 実装（テンプレート管理CRUD）

**やること:** 管理画面からテンプレートを登録・編集・削除できるようにする

**提出物: feature_XXXX ブランチへのコミット**

セルフチェックリスト（MRに貼ること）:

- [ ] 全てのDB操作で account_id による絞り込みが入っている
- [ ] INSERT/UPDATE時にバリデーション（件名・本文の必須チェック、文字数上限）が入っている
- [ ] DELETE は物理削除ではなく論理削除（is_deleted フラグ）になっている
- [ ] SQLにユーザー入力値を直接結合していない（プリペアドステートメント使用）
- [ ] 既存のコントローラー・モデルに変更を加えていない

**完了基準:** セルフチェック全項目OK

---

### Step 5: Phase 1 MR作成 + 動作確認

**提出物①: GitLab Merge Request**

MR説明文の必須記載事項:
- 変更概要（1〜2行）
- 変更ファイル一覧
- 影響範囲（新規機能のため既存影響なし）
- 動作確認結果

**提出物②: 動作確認レポート**

| No | 確認項目 | 期待結果 | 実際の結果 | OK/NG |
|----|---------|---------|-----------|-------|
| 1 | テンプレート新規作成 | 正常に登録される | | |
| 2 | テンプレート編集 | 変更が保存される | | |
| 3 | テンプレート削除 | 論理削除される（DBにレコードは残る） | | |
| 4 | 他テナントのテンプレート | 表示されない | | |
| 5 | 件名空欄で保存 | バリデーションエラーになる | | |
| 6 | 本文にHTMLタグ入力 | エスケープされて保存される | | |

**完了基準:** 全項目OK、MRがレビュー可能状態

---

## Week 2: Phase 2（自動送信処理）実装 → デプロイ

### Step 6: Phase 2 設計

**やること:** 自動応答メールの送信処理の設計方針をまとめる

**提出物: 送信処理設計メモ（Markdownで提出）**

以下の項目を各2〜3行で記載する:

| 設計項目 | 記載内容 |
|---------|---------|
| 送信トリガー | どのタイミングで送信するか（同期 or 非同期） |
| 送信元アドレス | 何を使うか、返信可能にするか |
| テンプレート変数 | 本文に埋め込む変数の一覧（顧客名、問い合わせ番号等） |
| エラー時の挙動 | 送信失敗時にどう処理するか |
| テスト方針 | メール送信をモック化する方法 |

**完了基準:** メンターが設計方針を承認

---

### Step 7: Phase 2 実装（送信サービス）

**やること:** 自動応答メール送信サービスクラスを実装する

**提出物: feature_XXXX_phase2 ブランチへのコミット**

セルフチェックリスト（MRに貼ること）:

- [ ] 送信処理が try-catch で囲まれており、失敗しても問い合わせ受付処理を止めない
- [ ] テンプレートが未設定または無効の場合、送信をスキップしてログ出力する
- [ ] メール本文のテンプレート変数置換で、未定義変数が残らない処理がある
- [ ] 送信先メールアドレスのフォーマット検証がある
- [ ] テスト用のメール送信モックが作成されている

**完了基準:** セルフチェック全項目OK

---

### Step 8: Phase 2 MR作成 + テスト環境動作確認

**提出物①: GitLab Merge Request（Phase 2）**

**提出物②: 動作確認レポート**

| No | 確認項目 | 期待結果 | 実際の結果 | OK/NG |
|----|---------|---------|-----------|-------|
| 1 | テンプレート有効時に問い合わせ送信 | 自動応答メールが届く | | |
| 2 | メール本文の変数置換 | 顧客名・問い合わせ番号が正しく埋まる | | |
| 3 | テンプレート無効時に問い合わせ送信 | 自動応答メールが届かない（正常動作） | | |
| 4 | 不正なメールアドレスで問い合わせ送信 | 自動応答は送信失敗、問い合わせ自体は正常登録 | | |
| 5 | 既存の担当者通知メール | 従来通り届く（影響なし） | | |

**注意:** メール送信テストは**メンター立ち会い**で実施すること

**完了基準:** 全項目OK

---

### Step 9: レビュー対応 + 本番デプロイ

**提出物: 本番デプロイチェックシート**

| No | 手順 | 実施者 | 確認者 | 完了時刻 |
|----|------|--------|--------|---------|
| 1 | テーブル作成確認（本番DB） | | | |
| 2 | Phase 1 ソースデプロイ | | | |
| 3 | 管理画面からテンプレート作成確認 | | | |
| 4 | Phase 2 ソースデプロイ | | | |
| 5 | テスト問い合わせ送信 → 自動応答メール受信確認 | | | |
| 6 | 既存の担当者通知メールが従来通り届くことを確認 | | | |

**完了基準:** 全手順完了、メンター確認済み

---

### Step 10: 本番動作確認 + 完了報告

**提出物①: 本番動作確認レポート**

| No | 確認項目 | 期待結果 | 実際の結果 | OK/NG |
|----|---------|---------|-----------|-------|
| 1 | 本番環境でテンプレート作成 | 正常に作成される | | |
| 2 | 本番環境で問い合わせ → 自動応答 | メールが届く | | |
| 3 | エラーログ | 異常なし | | |

**提出物②: 完了報告サマリー**

| Phase | 内容 | デプロイ日 | 動作確認結果 |
|-------|------|----------|------------|
| Phase 1 | テンプレート管理CRUD | MM/DD | OK |
| Phase 2 | 自動応答メール送信 | MM/DD | OK |

**完了基準:** 本番環境で正常動作確認済み

---

## 2週間サマリー

Week 1: 理解 → Phase 1（テンプレート管理）
  Step 1   課題整理メモ（Q&A 4問）
  Step 2   処理フロー図 + 設計意図Q&A
  Step 3   テーブル比較表 + 調査メモ
  Step 4   Phase 1 コミット
  Step 5   Phase 1 MR + 動作確認レポート

Week 2: Phase 2（自動送信）→ デプロイ
  Step 6   送信処理設計メモ
  Step 7   Phase 2 コミット
  Step 8   Phase 2 MR + 動作確認レポート
  Step 9   本番デプロイチェックシート
  Step 10  本番動作確認 + 完了報告

**提出物合計: 12個**（1日1〜2個提出 → メンターが翌朝確認のサイクル）

---

## メンター向け申し送り事項

| 項目 | 内容 |
|------|------|
| つまずきやすいポイント | トランザクション境界の理解（メール送信をDBトランザクションに含めてしまう）、マルチテナント分離の漏れ |
| 最初に触らせない方がよいもの | 既存の問い合わせ受付処理の本体（影響範囲が広い） |
| 理解度チェックの質問例 | 「メール送信失敗時に問い合わせデータまでロールバックしたらどうなる？」 |
| 成功体験のタイミング | Step 8 で自分が作ったテンプレートの自動応答メールが実際に届いた時 |
| 立ち会い必須の作業 | メール送信テスト（Step 8）、本番デプロイ（Step 9） |

何が起きたか

この指示書を使って新卒未経験のメンバーに案件を任せてみたんですが、感覚的に2つの変化がありました。

1つ目は「何から手をつけるか」で止まらなくなった。

当然といえば当然で、毎日の提出物が決まっているので「今日はこの調査シートを埋める」「今日はこのチェックリストを全部チェックする」という粒度で動ける。要件定義書だけ渡されて「よろしく」と言われるのとは、手の動かしやすさが全然違う。

2つ目は「理解の浅さ」が提出物で可視化される。

Q&Aの回答を見れば、メンターが「ここの理解が浅いな」とすぐわかる。要件定義書だけだと「読みました」「わかりました」で進んでしまって、実装段階で認識ズレが発覚する、というパターンが多かったんですが、それが減りました。

まあ逆に言えば、今まで「ドキュメント渡して終わり」にしていた自分のやり方が雑だったということでもあるので、あんまり偉そうなことは言えないんですが（笑）。

スキルの構造的な工夫

いくつか設計上こだわったポイントがあります。

Q&Aは「比較」を必ず含める

「〇〇とは何か？」という知識確認型の質問は、調べればわかるので提出物としての意味が薄い。

サンプルのStep 2で言えば、「サービスクラスに分離する理由をコントローラーに直接書く方式と比較して答えよ」のように、設計判断の理由を比較で問う形式にしています。回答を見ればメンターが「この人がどの程度コードの意図を理解しているか」を判別できるからです。

セルフチェックリストはGrepで確認可能なものを優先

「既存処理に手を加えていないこと」のように主観的な項目もありますが、「SQLにユーザー入力値を直接結合していない」「account_idによる絞り込みが全DB操作に入っている」のように機械的に確認できる項目を優先して入れるようにしています。

チェック漏れが「やってないのに知らずにチェック入れた」ではなく「Grepの結果を貼ってあるから嘘つけない」になるのが大事かなと。

メンター向け申し送り事項

地味ですが、「つまずきやすいポイント」「成功体験のタイミング」をメンター向けに書いてあるのが結構効いています。メンターが毎回案件のコードを全部読まなくても、どこで声をかければいいかがわかる。

サンプルでは「Step 8 で自分が作ったテンプレートの自動応答メールが実際に届いた時」を成功体験のタイミングとして指定しています。自分が書いたコードが動いてメールが届く瞬間は、未経験者にとってはかなり大きな成功体験なんですよね。そのタイミングをメンターが見逃さずに声をかけられるかどうかで、その後のモチベーションが全然変わってくる。

動かし方

# Claude Codeで以下のスラッシュコマンドを実行
/onboarding-guide-creator

あとはチケット番号と期間を聞かれるので答えるだけです。GitLabのMR差分、要件定義書、コードベースを読み込んだ上で、案件に特化した指示書が生成されます。

技術スタックとしては:

• Claude Code のカスタムスキル（.claude/skills/ に配置）
• gitlab-investigator MCP（GitLab APIラッパー）
• ドキュメントリポジトリへの自動コミット・プッシュ

ここまでの振り返り

1年間やってきた流れを整理すると：

Phase 1: 要件定義書を作る仕組みを整備した（2025年前半）
Phase 2: 設計ドキュメントを充実させた（2025年後半）
Phase 3: ドキュメントを「使って手を動かさせる」仕組みを作った（2026年〜）  ← いまここ

結局のところ、ドキュメントの精度を上げること自体は正しかったと思っています。ただ、ドキュメントを渡すだけでは人が動けるようにはならなかった。「読む」と「やる」の間には溝があって、そこを埋めるのは「やることリスト」と「提出物」だった、というのが1年越しの学びです。

別にこれは新卒に限った話ではなくて、中途入社のメンバーや、普段触らないモジュールを初めて改修するメンバーにも同じ効果がありそうだなと思っていて、今後そちらにも広げていくつもりです。

おわり。

CM

こんな感じで、AIを使いながら開発プロセスの改善に取り組んでくれる方を、いえらぶは常に募集しています。

新卒採用サイト：