AI駆動開発ライフサイクル

ここでは『2.3 クイックスタート』で実践したスペック駆動開発を深掘りして、継続開発のライフサイクルの中でどうドキュメントを管理していくか解説します。

基本的な考えかた

既存のソフトウェア開発のライフサイクルはすでに十分成熟しています。さまざまな専門家を組織的にチーム化し、工程管理やリスク管理の中で適切かつ効率的な対話や合意形成プロセスをマネジメントし、工程ごとに必要な定義書・設計書を整備することで、期待どおりの品質（Q）・コスト（C）・納期（D）を管理しています。これにより、まだ見ぬソフトウェアを作るというチャレンジな活動を、予測可能な範囲でコントロールすることができます。

Claude Codeをはじめとしたコーディングエージェントは、ここまで皆さんが試して理解したとおり、ドキュメント作成やリポジトリ構造の把握、設計の相談などの支援をしたり、定義したルールに基づきコードを生成する自律型開発まで、幅広く利用することが可能です。

人間が実現してきたソフトウェア開発のノウハウと、AIで実現できるAI支援や自律型開発の能力を統合し、人間が期待する機能性・非機能性の品質が担保されたソフトウェアを、圧倒的な低コストとリードタイムで実現することが期待されます。そのために必要な考え方が『AI駆動開発ライフサイクル』と、それらの工程で必要になる具体的な取り組みかたです。

初回開発とエンハンス開発の違い

多くの開発ニーズは1からソフトウェアを作って完了できるものに比べて、すでにある動くソフトウェアに悪影響を与えず機能性を追加したり性能を改善するようなエンハンス開発のほうが圧倒的に多いはずです。スペック駆動開発の基礎をおさらいしながら、実際にエンハンス開発で役にたつ方法を理解しましょう。

オンボーディング(AI・人間)の重視

オンボーディングには2種類の考え方があります。今まで人間しか利用していなかったリポジトリをAIが理解しやすいようにAI-ready度合いを高め、AIにとっても利用しやすい環境整備をする活動と、人間がプロジェクトへオンボーディングする際に素早く抜け漏れなくリポジトリを理解するためのAI支援の活動です。

運用工程・本番環境で利用する

ソフトウェアの真の価値が発揮されるのは、そのソフトウェアを開発したときではなく、それが本番環境で実行されているときです。開発の活動だけでなく、運用工程・本番環境においても効率的に活用していきましょう。

スペック駆動開発の基本おさらい

スペック駆動開発の基本 では簡単なプロジェクトメモリ（CLAUDE.md）を定義することで、空のプロジェクトにおいて、プロダクト企画書、要求仕様書、機能設計書、技術仕様書、アプリ構造定義書、タスクリストを逐次作成し、内容を合意しながら次の工程に進めていきました。この内容でソフトウェアの規模として小さいもの、たとえばテトリスの2Dブラウザゲームなどであれば不具合がほとんどない完全に動作するプログラムができます。ただし、われわれが日々利用している多くのソフトウェアと同等の機能性・非機能性を、このワークフロー1回で完全に実現することは難しいと思われます。

また、それぞれのドキュメント作成のためにAIから質問をされたとき、まだ決められないことやわからないことが多くて、前に進めづらいと感じたこともあるでしょう。実際にMVPをリリースしてからユーザの声を聞きながら機能追加や改善を加えていきたいと考えた人もいるかもしれません。

そこで、重要なのが冒頭のClaude Code利用上の原則で伝えたとおり、小さい範囲でイテレーティブに開発を進めながら、変更やそれによる影響をコントロール可能な小さい範囲に留めながら開発を進めることです。あいまいな要件が多いまま作ったり、全機能ができてからテストをするようなことは避けましょう。

また多くのシステムやプロジェクトにおいて、今後どこかのタイミングでAIによる開発が入ってくる場合、いかに今までの資産に対してスムーズにAIをオンボーディングするか、そしてすばやく安全にエンハンス開発を開始するかがもっとも多く直面する課題になるでしょう。

プロジェクトオンボーディング

AIのオンボーディング

既存のシステムやプロジェクトにAIをオンボーディングする場合、いきなり自律型開発をClaude Codeに依頼するのではなく、まずはリポジトリをAI-readyにするための構造やドキュメント整備をする必要があります。

リポジトリ全体を理解してドキュメントを作成する

スペック駆動開発の基本 で作成したプロジェクトメモリ（CLAUDE.md）を既存のリポジトリに配置し、Claude Codeにドキュメント作成を指示してみましょう。

※既存リポジトリは破壊されても元に戻せるようにバックアップやバージョン管理システムで管理されている状態でおこなってください。

> リポジトリ全体を把握して、必要なドキュメントを作成し、最新化してください。

⏺ リポジトリの状況を確認して、ドキュメントを作成します。まず全体構造を把握させてください。

〜中略〜

⏺ 現在のリポジトリ状況を確認しました。タスク管理アプリケーションの開発プロジェクトです
  が、まだ実装コードがなく、以下のドキュメントのみが存在します：

  - product.md - プロダクト企画書（完成）
  - requirements.md - 要求仕様書（完成）
  - CLAUDE.md - 開発標準ルール（完成）
  - README.md - 簡単なタイトルのみ

  CLAUDE.mdの開発プロセスに従って、次のステップを進めます：

⏺ Update Todos
  ⎿  ☐ design.md（機能設計書）の作成           
     ☐ tech.md（技術仕様書）の作成
     ☐ structure.md（アプリ構造定義書）の作成
     ☐ 初期タスクリストの作成
     ☐ 開発環境のセットアップ（package.json等）

〜中略〜

これにより、リポジトリ内の構造や利用技術、アーキテクチャなどが、リポジトリ直下のそれぞれのmdファイルに出力されました。

人間のオンボーディング

上記のようにClaude Codeを利用すればリポジトリ内がどんな構造になっているか、どんな技術を利用しているか素早く把握することが可能です。

> バックエンドの処理のエントリポイントがどこか教えてください

> フロントエンドにXXX機能を追加する場合、どこにどんな処理を追加すれば良いか教えてください

> バックエンドの非効率なSQLを特定したい。CRUDを機能設計書に追加して、./extra配下に格納したスロークエリと合わせて改善計画を考えてください

従来、チームの同僚に教わっていたような内容がClaude Codeにより素早く把握できます。

エンハンス開発

プロジェクトドキュメントとステアリングファイルのライフサイクルの違い

現在利用しているプロジェクトメモリ（CLAUDE.md）では、永続的ドキュメントであるプロジェクトドキュメントと、1回1回の作業で利用するステアリングファイルの区別をしていませんでした。これだとエンハンス開発の際に必要な作業指示レベルのドキュメントが作成されません。それぞれを別々で管理し、作業単位でステアリングファイルを作ってタスクを実行し、最後に永続的ドキュメントを常に最新化するようにしましょう。

以下は永続的ドキュメントとステアリングファイルを分割し、エンハンス開発に対応した開発ルールを記載したプロジェクトメモリ(CLAUDE.md)の例です。

# 開発標準ルール

## 概要
本ドキュメントは、開発を進める際に必ず参照し、遵守すべき標準ルールを定義します。

## ドキュメント管理

### 永続的ドキュメント

プロジェクト全体を通して管理・更新される基本ドキュメント：

#### 1. プロダクト企画書 (`product.md`)
- プロダクトビジョンや目的
- ターゲットユーザと課題・ニーズ
- 主要な機能や目標
- 成功の定義

#### 2. 要求仕様書 (`requirements.md`)
- ユーザストーリー
- 受け入れ条件

#### 3. 機能設計書 (`design.md`)
- 機能ごとのアーキテクチャ
- 構成図

#### 4. 技術仕様書 (`tech.md`)
- テクノロジースタックやフレームワーク
- 開発ツールや手法
- 技術的な制約事項や要求事項
- 利用するサードパーティ製品

#### 5. アプリ構造定義書 (`structure.md`)
- フォルダやファイルの構成
- 命名規則
- コーディング規約

### ステアリングファイル

追加開発・修正開発時に作成する作業用ドキュメント：

#### 作成ルール
- **格納場所**: `.steering/[日付YYYYMMDD]-[開発タイトル]/` ディレクトリ
- **必須ファイル**:
  1. **要求仕様書** (`requirements.md`) - 今回の作業で要求されている仕様、作業依頼内容
  2. **機能設計書** (`design.md`) - 実装方針、設計詳細
  3. **タスクリスト** (`tasklist.md`) - 実装タスクの一覧と進捗管理

## 開発プロセス

### 初回開発時の手順

1. **日付の確認**
   - **重要**: 必ず `date +"%Y%m%d"` コマンドで今日の日付を確認する
   - ディレクトリ名やファイル名に使用する日付は必ず実行時の日付を使用

2. **永続的ドキュメントの作成**
   - 上記の永続的ドキュメント（1〜5）を作成
   - 各ドキュメントの内容を定義

3. **ステアリングディレクトリの作成**
   - `.steering/[日付YYYYMMDD]-initial-setup/` ディレクトリを作成

4. **ステアリングファイルの作成**
   - 要求仕様書 (`requirements.md`): 初回開発の要求事項を記載
   - 機能設計書 (`design.md`): システム全体の設計を記載
   - タスクリスト (`tasklist.md`): 実装タスクを洗い出して記載

5. **タスク実行**
   - ステアリングファイルのタスクリストに基づいて実装を進める
   - **必須**: 実装したコードに対して開発者テストを作成

6. **テスト実行と品質確認**
   - 作成したテストをすべて実行し、パスすることを確認
   - リント・型チェックを実行

### 追加開発・修正開発時の手順

1. **日付の確認**
   - **重要**: 必ず `date +"%Y%m%d"` コマンドで今日の日付を確認する
   - ディレクトリ名やファイル名に使用する日付は必ず実行時の日付を使用

2. **ステアリングディレクトリの作成**
   - `.steering/[日付YYYYMMDD]-[開発タイトル]/` ディレクトリを作成
   - 例: `.steering/20250918-user-authentication/`

3. **ステアリングファイルの作成**
   - 要求仕様書 (`requirements.md`): 今回の作業内容と要求事項を記載
   - 機能設計書 (`design.md`): 実装方針と設計詳細を記載
   - タスクリスト (`tasklist.md`): 実装タスクを洗い出して記載

4. **タスク実行**
   - ステアリングファイルのタスクリストに基づいて実装
   - **必須**: 実装したコードに対して開発者テストを作成

5. **テスト実行と品質確認**
   - 作成したテストをすべて実行し、パスすることを確認
   - リント・型チェックを実行

6. **永続的ドキュメントへの反映**
   - 開発完了後、変更内容を永続的ドキュメントに反映
   - **重要**: 1ファイルごとに編集後、必ず確認・承認を得てから次のファイル編集を行う

## テスト標準

### 開発者テストの実施

#### テスト作成の原則
- **必須**: すべての新規作成・修正コードに対してテストを作成
- **カバレッジ**: 作成・修正した機能の主要なパスとエッジケースをカバー
- **命名規則**: テストファイルは `[対象ファイル名].test.[拡張子]` または `[対象ファイル名].spec.[拡張子]`

#### テストの種類
1. **単体テスト**: 個々の関数・メソッドの動作確認
2. **統合テスト**: 複数のコンポーネント間の連携確認
3. **E2Eテスト**: ユーザ視点でのシナリオテスト（必要に応じて）

#### テスト実施タイミング
1. **コード実装後**: 即座にテストを作成・実行
2. **コミット前**: すべてのテストがパスすることを確認
3. **プルリクエスト前**: テストカバレッジを確認

## コマンド

### リント・型チェック・テスト
開発完了時は以下のコマンドを実行してコードの品質を確認すること：
- `npm run lint` - コードスタイルのチェック
- `npm run typecheck` - TypeScriptの型チェック
- `npm test` - テストの実行（プロジェクトに設定されている場合）

## 注意事項
- ドキュメントの更新は段階的に行い、各段階で承認を得る
- タスクリストは実施内容と日時が明確にわかる命名とする
- コード変更後は必ずリント・型チェックを実施する

開発ルールの大規模化に伴うメモリの効率化

ここまで開発ルールは、リポジトリ直下に配置した1つのプロジェクトメモリ（CLAUDE.md）にすべて記述してきました。今後、軽量なプロジェクトから、大規模なコードベースとなるシステムを開発する際に、プロジェクトメモリに記述される開発ルールは大規模化することが想定されます。

プロジェクトメモリ（CLAUDE.md）はインタラクティブモードでClaude Codeに指示をする際に必ず読み込まれるファイルですが、必要なタイミングでのみ読み込まれるようにしたり、Claude Codeが必要性を感じたときに別ドキュメントから読み込むようにすることが可能です。

メモリの階層化

CLAUDE.mdの再帰的読み込みを参考に、フロントエンドとバックエンドが共存したり、複数のマイクロサービスが同一リポジトリ内で管理されている場合には、作業するサブディレクトリ単位にCLAUDE.mdを分割することが可能です。

仕様書化

アーキテクチャ選定の指針や、インフラ設計上の制約、特定業界向けの開発標準などのドキュメントは個別の仕様書として管理し、必要なフェーズやタスクでのみ参照させるほうが効率的です。

.references/
├ architecting-rules.md
└ ref-automotive-spice.md

ユビキタス言語やパタン言語(用語集)の定義

特定業界において当たり前な概念や用語、設計に役立つ知識などはドメイン駆動設計で有名なユビキタス言語を作成したり、特定の設計・開発手法を定義しておくことで、Claude Codeの作業品質を向上することができます。

たとえば以下は居酒屋業界のシフト管理業務に関するユビキタス言語定義の簡単な例です。

他にも『テスト駆動開発（DDD）の当社における定義』や、『ドメイン駆動開発』『当社におけるXXX開発メソッドの定義』などを定義しておくことで、自社のルールやコンテキストを理解しているエンジニアとしてClaude Codeを活動させることが可能です。

.references/
└ izakaya-ubiquitous-language.md

# 居酒屋業界ユビキタス言語定義

## 概要
本ドキュメントは、居酒屋業界におけるシフト管理業務に関するユビキタス言語を定義します。

## ドメインエンティティ

### 人的リソース

#### 店舗スタッフ
- **店長**: 店舗運営の責任者。シフト表の最終決定権を持つ
- **副店長**: 店長不在時の代理責任者
- **社員**: 正社員として雇用されている従業員
- **アルバイト**: 時給制で雇用されているパートタイム従業員
- **研修生**: 入社3ヶ月未満の新人スタッフ

#### スタッフ属性
- **ベテランスタッフ**: 勤続1年以上のスタッフ
- **キッチンスタッフ**: 調理担当のスタッフ
- **ホールスタッフ**: 接客・配膳担当のスタッフ
- **キャッシャー**: レジ業務を担当できるスタッフ
- **クローザー**: 閉店作業を任せられるスタッフ
- **オープナー**: 開店準備を任せられるスタッフ

### 時間管理

#### シフト区分
- **早番シフト**: 開店〜17:00の時間帯
- **遅番シフト**: 17:00〜閉店の時間帯
- **通しシフト**: 開店〜閉店まで（休憩含む）
- **ヘルプシフト**: ピーク時間帯のみ（18:00〜22:00）

#### 営業時間帯
- **ランチタイム**: 11:00〜14:00
- **アイドルタイム**: 14:00〜17:00（準備・休憩時間）
- **ディナータイム**: 17:00〜22:00
- **深夜営業**: 22:00〜翌2:00

#### 曜日属性
- **平日**: 月曜日〜木曜日
- **週末**: 金曜日〜日曜日
- **祝前日**: 祝日の前日
- **祝日**: 国民の祝日
- **繁忙日**: 金・土・祝前日
- **閑散日**: 月・火・水

### シフト管理プロセス

#### シフト希望提出
- **シフト希望**: スタッフが勤務可能な日時の申請
- **第一希望**: 最も勤務したい日時
- **第二希望**: 第一希望が不可の場合の代替日時
- **NG日**: 勤務不可能な日
- **希望提出期限**: シフト希望を提出する締切日
  - **前半提出期限**: 毎月15日（翌月1日〜15日分）
  - **後半提出期限**: 毎月末日（翌月16日〜末日分）

#### シフト作成
- **シフト表**: 確定した勤務スケジュール表
- **仮シフト**: 調整中の未確定シフト
- **確定シフト**: 承認済みの最終シフト
- **シフト公開日**: 確定シフトを公開する日
  - **前半公開日**: 毎月20日（翌月1日〜15日分）
  - **後半公開日**: 翌月5日（翌月16日〜末日分）

#### 人員配置
- **必要人数**: 各時間帯に必要な最小スタッフ数
- **適正人数**: 効率的な運営のための理想的なスタッフ数
- **最小構成**: 営業可能な最小限のスタッフ構成
  - キッチン: 最低1名
  - ホール: 最低1名
  - キャッシャー可能者: 最低1名

### シフト調整

#### 変更管理
- **シフト変更申請**: 確定後のシフト変更依頼
- **シフト交代**: スタッフ間での勤務日交換
- **代替要員**: 欠勤時の代わりのスタッフ
- **急募シフト**: 人員不足時の緊急募集

#### 勤怠状況
- **出勤**: 予定通りの出勤
- **欠勤**: 事前連絡ありの休み
- **無断欠勤**: 連絡なしの欠勤
- **遅刻**: 勤務開始時刻に遅れること
- **早退**: 勤務終了時刻前に退勤すること
- **残業**: 予定終了時刻を超えての勤務

### 労務管理

#### 勤務制約
- **週40時間制限**: 労基法による週間労働時間上限
- **月間勤務上限**: アルバイトの月間勤務時間制限
- **連続勤務制限**: 連続勤務日数の上限（通常6日）
- **インターバル規制**: 勤務間隔の最低時間（通常8時間）

#### 休暇管理
- **有給休暇**: 法定有給休暇
- **希望休**: スタッフが希望する休日
- **指定休**: 会社が指定する休日
- **特別休暇**: 冠婚葬祭等の特別な休暇

### 業務負荷

#### 繁忙度
- **ピークタイム**: 最も忙しい時間帯（19:00〜21:00）
- **繁忙期**: 年末年始、歓送迎会シーズン（3-4月、12月）
- **閑散期**: 2月、8月の平日
- **予約状況**: 事前予約の入り具合

#### スキル要件
- **ワンオペ可能**: 一人で店舗運営可能なスキルレベル
- **新人教育可能**: 新人指導ができるスキルレベル
- **メニュー習熟度**: 全メニューの調理・説明が可能
- **酒類知識**: 日本酒・焼酎等の専門知識保有

## シフト作成業務フロー

### 1. シフト希望収集フェーズ

#### 1.1 希望提出期間
- **前半期間**: 毎月1日〜15日（翌月1日〜15日分の希望収集）
- **後半期間**: 毎月16日〜末日（翌月16日〜末日分の希望収集）

#### 1.2 提出方法
- **紙面提出**: 所定のシフト希望表への記入
- **システム入力**: シフト管理システムへの直接入力
- **LINE/メール**: デジタルツールでの希望連絡

### 2. シフト作成フェーズ

#### 2.1 制約条件確認
- 労働法規の遵守確認
- 各スタッフの契約条件確認
- 必要スキル保有者の確認

#### 2.2 最適化調整
- 希望と必要人数のマッチング
- スキルバランスの調整
- コスト（人件費）の最適化

#### 2.3 確定処理
- 仮シフトの作成と内部確認
- スタッフへの事前確認（必要に応じて）
- 最終確定と承認

### 3. シフト公開・運用フェーズ

#### 3.1 公開
- 確定シフトの掲示・通知
- 各スタッフへの個別連絡（必要に応じて）

#### 3.2 調整対応
- シフト変更要望の受付と調整
- 急な欠員への対応
- 代替要員の確保

#### 3.3 実績管理
- 実際の勤務時間記録
- 勤怠状況の管理
- 次回シフト作成への反映

## 用語集（五十音順）

- **アイドルタイム**: 客数が少ない時間帯
- **オープン作業**: 開店準備作業
- **クローズ作業**: 閉店作業
- **シフトイン**: 勤務開始
- **シフトアウト**: 勤務終了
- **人時生産性**: 1人1時間あたりの売上高
- **スポット勤務**: 単発・臨時の勤務
- **ダブルワーク**: 複数の職場で働くこと
- **手待ち時間**: 客がいない待機時間
- **ヘルプ**: 他店舗からの応援スタッフ
- **マルチタスク**: 複数業務の同時遂行
- **労働分配率**: 売上に対する人件費の割合