😇
Spec Kitで勤怠チェックアプリを作成
Spec Kit実践ガイド
開発の背景
- プロジェクト名: 勤怠チェックアプリ（CheckWorkTime）
-
使用技術:
- Python 3.8+
- Slack SDK (slack-sdk)
- Flask (Webアプリケーション)
- pandas (データ処理)
- openpyxl (Excel読み込み)
- python-dateutil (日付解析)
- 開発期間: 1セッション（約2-3時間）
-
達成した目標:
- Slackチャンネルから休み・遅刻情報を自動抽出
- 勤怠表（Excel/CSV）との自動照合
- コメント有無のチェック機能
- Mockデータによるテスト環境の構築
1. Spec Kitとは
基本概念
Spec Kitは、Cursor IDEの/speckitコマンド群を使用した、仕様駆動開発の実践手法です。自然言語で要件を定義し、AIアシスタントが自動的にコードを生成・実装します。
主要コマンド
-
/speckit.constitution: プロジェクトの基本方針とルールを定義 -
/speckit.specify: 詳細な機能要件を指定 -
/speckit.clarify: 要件の確認と明確化
メリット
- 迅速なプロトタイピング: 要件を書くだけでコードが生成される
- 一貫性のある実装: 仕様に基づいた統一されたコード構造
- ドキュメントとコードの同期: 仕様がそのままドキュメントになる
- 反復的な改善: 要件を追加・修正するだけで機能が拡張される
2. 環境構築
1.Spec kitのインストール
$ curl -LsSf https://astral.sh/uv/install.sh | sh
$ uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
2. プロジェクトの初期化
- pythonのバーチャル環境作成
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
- プロジェクトの初期化
specify init <プロジェクト名>
3. 依存関係のインストール
pip install slack-sdk python-dotenv pandas openpyxl python-dateutil flask flask-cors
4. .cursorディレクトリの作成（オプション）
mkdir -p .cursor/commands
3. 実践例
準備ステップ: プロジェクトのセットアップ
specify init check_work_time
ステップ1: 基本要件の定義（/speckit.constitution）
最初に、プロジェクトの全体像を定義します。
例:
/speckit.constitution Slack内チャンネルの会話から指定した人の休み情報を抽出して
その人勤怠表と一致するかどうかのアプリ
ステップ2: 詳細要件の追加（/speckit.specify）
基本要件が実装されたら、詳細を追加します。
例:
/speckit.specify
slackに以下のように休みと遅刻を報告している。
鈴木の勤怠連絡です。
11/10(月) 私用のため全休
11/21(金) 私用のため全休
毎月末に勤怠表をチェックする。
勤怠表は画像で添付した。
休みと遅刻はちゃんと勤怠表一致しているかと
休みと遅刻した日はコメント入れたかどうかをチェックするアプリ作りたい
ステップ3: 要件の明確化（/speckit.clarify）
実装前に、不明な点を確認します。
例:
/speckit.clarify
確認すべき項目:
- 日付の扱い（過去の月もチェックするか）
- 判定基準（遅刻の基準時刻など）
- データ形式（勤怠表の構造）
- エッジケースの処理
ステップ4: 実装とテスト
AIが生成したコードを確認し、必要に応じて修正します。
実装の流れ:
- プロジェクト構造の作成
- 各モジュールの実装
- テストデータの準備
- 動作確認
4. Tipsとベストプラクティス
要件定義のコツ
✅ 良い例
/speckit.constitution Slack内チャンネルの会話から指定した人の休み情報を抽出して
その人勤怠表と一致するかどうかのアプリ
ポイント:
- 簡潔に目的を述べる
- 主要な機能を1-2文で表現
- 技術的な詳細は後で追加
/speckit.specify
11/10(月) 私用のため全休
11/15(火) 体調不良のため1000出社
こういう形式で報告している。
9:00が標準出社時間、それ以降は遅刻。
勤怠表はタブ区切りで、以下の列がある：
日、出勤時刻、退勤時刻、休暇等種別、勤務内容・理由
良い点:
- 具体的なデータ形式を示している
- 判定基準を明確にしている
- データ構造を説明している
❌ 悪い例
/speckit.specify
休み情報をチェックするアプリを作って
問題点:
- 抽象的すぎる
- データ形式が不明
- 判定基準が不明
反復的な改善
- 小さく始める: 基本機能から実装
- 段階的に追加: 詳細要件を順次追加
- テストしながら: 各段階で動作確認
- ドキュメント化: 変更内容を記録
コード生成後の確認ポイント
- 構造の確認: プロジェクト構造が適切か
- 依存関係: 必要なライブラリが含まれているか
- エラーハンドリング: 適切な例外処理があるか
- テスト可能性: テストしやすい構造か
５. よくある課題と解決策
課題1: 生成されたコードが期待と異なる
原因:
- 要件が曖昧
- 技術的な制約の説明不足
解決策:
/speckit.clarify
- 具体的な実装方法を確認
- 技術的な制約を説明
- 期待する動作を明確に
課題2: データ形式の不一致
原因:
- 実際のデータ形式と想定が異なる
解決策:
/speckit.specify
実際のデータ形式を添付または説明
- 列の順序
- データ型
- 特殊な形式
実例:
実際の勤怠表はタブ区切りで、ヘッダーが6行ある。
7行目からデータが始まる。
列の順序は：日、曜、承認状況、勤務、出勤時刻、退勤時刻...
課題3: エッジケースの処理
原因:
- 特殊なケースが考慮されていない
解決策:
/speckit.specify
以下のケースに対応してほしい：
- 日付が数値の場合（01, 02...）
- コメントが空の場合
- 複数のメッセージに同じ日付がある場合
課題4: テスト環境の構築
原因:
- 外部APIが利用できない
解決策:
Mockデータを使用したテスト環境を構築してほしい
実装例:
- Mockクラスの作成
- テストデータの準備
- テストスクリプトの作成
6. 開発フローの全体像
┌─────────────────────────────────────┐
│ 1. 基本要件の定義 │
│ /speckit.constitution │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 2. 初期実装の生成 │
│ - プロジェクト構造 │
│ - 基本機能 │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 3. 動作確認 │
│ - 生成されたコードの確認 │
│ - 基本的な動作テスト │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 4. 詳細要件の追加 │
│ /speckit.specify │
│ - データ形式の詳細 │
│ - 判定基準 │
│ - エッジケース │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 5. 実装の改善 │
│ - 機能の追加 │
│ - バグ修正 │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 6. 要件の明確化 │
│ /speckit.clarify │
│ - 不明点の確認 │
│ - 仕様の最終確認 │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 7. テスト環境の構築 │
│ - Mockデータ │
│ - テストスクリプト │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 8. 完成 │
│ - ドキュメント整備 │
│ - 最終テスト │
└─────────────────────────────────────┘
7. 成功のポイント
1. 段階的なアプローチ
- 一度にすべてを実装しようとしない
- 基本機能から始めて、段階的に追加
2. 具体的な例を示す
- 抽象的な説明より、実際のデータ形式を示す
- スクリーンショットやサンプルデータを活用
3. 反復的な改善
- 一度で完璧を目指さない
- 動作確認しながら改善
4. ドキュメント化
- 各段階で変更内容を記録
- READMEやコメントを充実させる
5. テストの重要性
- Mockデータでテスト環境を構築
- 各機能を個別にテスト
8. まとめ
Spec Kitを使用することで、以下のような開発が可能になります：
- 迅速なプロトタイピング: 要件を書くだけでコードが生成
- 一貫性のある実装: 仕様に基づいた統一された構造
- 反復的な改善: 要件を追加するだけで機能が拡張
- ドキュメントとコードの同期: 仕様がそのままドキュメント
次のステップ
- 自分のプロジェクトでSpec Kitを試す
- 要件定義のスキルを向上させる
- 生成されたコードを理解し、カスタマイズする
- テスト環境を構築し、品質を確保する
参考資料
- Cursor IDE公式ドキュメント
- プロジェクトのREADME:
README.md - 開発ログ:
log.md - Mockテストガイド:
MOCK_TEST.md
作成日: 2024年
プロジェクト: CheckWorkTime（勤怠チェックアプリ）
開発手法: Spec Kit（Specification-Driven Development）
Discussion