Dev Support Skill

このスキルは、短時間で中断される可能性のある複数の作業セッションにわたって開発プロジェクトを管理するのを支援します。ドキュメント駆動開発と、タスク間の切り替えによる生産性の低下を最小限に抑えるためのコンテキスト保持を重視しています。

核となる原則

• 二層構造のドキュメント: プロジェクトレベル (docs/) + 機能レベル (docs/dev/[feature-name]/)
• 最優先ファイル: CONTEXT.md は中断と再開において最も重要なファイルです
• 技術スタック不問: あらゆるプログラミング言語やフレームワークで動作します
• 柔軟なセッション: 常にユーザーにセッション時間を尋ねてください（デフォルト: 30分）
• マニュアル優先: ユーザーが明示的にヘルパースクリプトを要求しない限り、標準的なコマンドを使用してください
• アーキテクチャの整合性: 新機能がプロジェクトのアーキテクチャと整合していることを確認してください
• AIによるダブルチェック: ユーザー確認の前に、環境で利用可能な別のAIツール（GitHub Copilot CLI, Gemini CLI, Claude Code 等）によるレビューを行ってください

セッション開始ワークフロー

1. セッション時間の確認: 「今回のセッション時間はどのくらいですか？（デフォルト: 30分）」
2. プロジェクトのドキュメント構造を確認:
   • docs/README.md (ドキュメントインデックス) を探す
   • ARCHITECTURE.md (プロジェクトレベルのアーキテクチャ) を確認
   • docs/dev/README.md (進行中の機能リスト) を検証
3. docs/dev/**/ 内の CONTEXT.md ファイルを探して読み込む
4. 前回のセッションを要約:
   • 日時と所要時間
   • 取り組んでいたタスク
   • 完了した項目と未完了の項目
   • CONTEXT.md からの次のアクション
5. ROADMAP.md が存在する場合、全体の進捗を表示
6. ユーザーに確認: 「前回の続きから再開しますか？」
7. 既存プロジェクトへの対応: 構造化されたドキュメントが存在しない場合、プロジェクト全体のドキュメントセットアップを提案してください

新機能開発

1. プロジェクトアーキテクチャとの整合性確認:
   • ARCHITECTURE.md または docs/architecture/overview.md を読み込む
   • 機能が既存のシステム設計に適合しているか検証
   • 影響を受けるコンポーネントを特定
2. ユーザーへの通知: docs/dev/[feature-name]/ ディレクトリの作成を推奨してください
3. 作成の提案:
   • SPEC.md: 要件、ユーザーストーリー、受入れ条件
   • DESIGN.md: アーキテクチャ、技術的決定、API設計
   • TEST_PLAN.md: テストケース、検証方法
   • ROADMAP.md: 実装フェーズ、マイルストーン、進捗管理
   • CONTEXT.md: 作業コンテキスト（再開に最も重要）
4. AIレビューの実行 (必須):
   • 作成したドキュメントやコードに対して、環境で利用可能なAI CLIツールでレビューを実行してください。
   • 例:
     • gh copilot suggest ...
     • gemini review ...
     • claude ...
   • 指摘事項があれば修正案に反映してください
5. ユーザー承認:
   • AIレビューを通過したものをユーザーに提示し、承認を得てください
   • 承認後、手動でドキュメントを作成:
   • mkdir -p docs/dev/[feature-name]
   • 各ファイルを適切なテンプレートで作成
6. 機能の登録:
   • docs/dev/README.md にステータス、優先度、依存関係を追加
   • プロジェクトの ROADMAP.md があれば更新
7. 技術スタックの追跡:
   • 質問: 「このプロジェクトで使用している技術スタックは何ですか？」
   • .meta.json に記録: {"feature": "name", "stack": "stack", "createdAt": "date"}
   • または、既存の DESIGN.md から読み取る
8. アーキテクチャ決定の記録:
   • 重要な技術的決定が行われた場合、docs/architecture/decisions/ に ADR を作成することを提案

セッション中の動作

• 時間の監視: 定期的に残り時間をユーザーに通知
• 5分前の警告: 「残り5分です。CONTEXT.md の更新を準備してください」
• 更新の提案:
  • アーキテクチャが変更された場合の DESIGN.md
  • テストケースを追加した場合の TEST_PLAN.md
  • 技術的決定を行った場合の CONTEXT.md
• タスクの分割: タスクがセッション時間を超える場合は、分割を推奨

セッション終了 (重要)

これは必須ステップです。決してスキップしないでください：

0. 成果物のAIレビュー:

   • セッション内で作成・変更した主要なファイルについて、AIレビューを実行してください
   • 利用可能なCLIツールを活用し、客観的な評価を得てください

1. 実際の時間を記録: 「今回のセッションは [X] 分でした」

2. CONTEXT.md を以下で更新:

   • 前回のセッション日時
   • セッション作業時間（開始時刻 – 終了時刻）
   • セッション時間（実際の作業時間）
   • 現在の作業の詳細
   • 進捗状況: 完了/進行中/未着手
   • 次のセッションのアクション（優先順位順）
   • 技術メモ、発見、問題点
   • 変更されたファイルのリスト
   • 環境復元手順（必要な場合）

3. ROADMAP.md の進捗率を更新

4. 必要に応じてプロジェクトレベルのドキュメントを更新:

   • docs/dev/README.md: 機能ステータスの更新
   • ARCHITECTURE.md: アーキテクチャが変更された場合
   • 重要な決定があった場合、docs/architecture/decisions/ に ADR を作成

5. Git コミットを推奨（WIP コミットも可）

CONTEXT.md テンプレート

## 前回のセッション
## 前回のセッション
- 日時: [YYYY-MM-DD]
- 作業時間: [HH:MM] - [HH:MM] ([X] min)
- 所要時間: [実際の作業時間]
- タスク: [取り組んだ内容]

## 進捗
- 完了: [完了した作業]
- 進行中: [現在の作業]
- ブロック中: [問題点]

## 次のセッション (優先順位順)
1. [アクション 1] - 優先度: 高
2. [アクション 2] - 優先度: 中

## 技術メモ
- [主要な決定事項や発見]

## 変更されたファイル
- [修正されたファイルのリスト]

## 環境の復元
### セットアップコマンド
[依存関係、環境変数など]

### 実行環境
- Node.js: [バージョン]
- その他のツール: [バージョン]

### ハードウェア状態 (IoT/電子工作)
- GPIO ピン: [接続状態]

技術スタック管理

技術スタックを決定する優先順位：

1. 機能ディレクトリの .meta.json があれば読み取る
2. DESIGN.md の内容から推測する
3. ユーザーに聞く: 「このプロジェクトで使用している技術スタックは何ですか？」
4. 将来のセッションのために .meta.json に記録する

ドキュメント作成サポート

ユーザーが情報を構造化されたドキュメントに整理するのを手伝ってください：

• 要件を SPEC.md 形式に変換
• 設計に関する議論を DESIGN.md にまとめる
• テストケースを TEST_PLAN.md の表形式に整理
• 作業計画を ROADMAP.md のフェーズに構造化

既存プロジェクトへの統合

構造化されたドキュメントがないプロジェクトで作業する場合：

1. 現在の状態を評価:
   • 既存のドキュメント（README, docs/, wiki など）を確認
   • プロジェクトの成熟度を特定（新規/成長中/成熟）
2. プロジェクト規模に基づいたドキュメント構造を提案:
   • 小規模/新規: 最小限の構造 (README + docs/dev/)
   • 成長中: ARCHITECTURE.md + docs/dev/README.md を追加
   • 成熟: architecture/, guides/, api/ を含む完全な構造
3. ユーザーが完全な構造を拒否した場合:
   • 適切な場所に最小限の CONTEXT.md を作成
   • セッションコンテキストをどこに保存するかユーザーに尋ねる
   • ユーザーの好みを尊重しつつ、ベストプラクティスを推奨
4. 移行パス: プロジェクトの成長に合わせて徐々にドキュメントを進化させることを提案

ヘルパースクリプト (アドバンスド)

scripts/manage-dev.ts が存在し、かつユーザーが明示的に要求した場合:

• ディレクトリ/ファイルの自動作成を支援
• 進捗サマリーを提供
• テンプレートを生成

デフォルトの動作: ユーザーから指示がない限り、常に標準的なコマンド (mkdir, 直接のファイル作成) を使用してください。

ベストプラクティス

• 柔軟なセッション: ユーザーと所要時間について相談してください (15/30/45/60/90 分のオプション)
• ドキュメント作成時間の確保: 常にセッション終了の 5-10 分前には作業を切り上げてください
• CONTEXT.md は必須: これは未来の自分へのメッセージです
• タスクの適切な分割: セッション時間内に完了するようにしてください
• 頻繁なコミット: 小さなコミット、WIP も OK です
• 決定事項の文書化: 常に技術的決定の根拠を記録してください
• ドキュメント優先: 可能な限りコードの前にドキュメントを書いてください
• 実際の時間を記録: CONTEXT.md に実際の作業時間を記録してください
• 二層構造の思考: プロジェクト全体と機能レベルの両方への影響を考慮してください
• アーキテクチャの整合性: 新機能が既存のアーキテクチャに適合するか検証してください
• 大きな決定には ADR を: 重要な選択には Architecture Decision Records を作成してください

特定のツールではなく、ワークフローとドキュメント構造に焦点を当ててください。

プロジェクトドキュメント構造

推奨される完全な構造

project-root/
├── README.md                    # プロジェクト概要 (必須)
├── ARCHITECTURE.md             # システム全体のアーキテクチャ
├── CONTRIBUTING.md             # 貢献ガイドライン
├── CHANGELOG.md                # リリース履歴
│
├── docs/
│   ├── README.md              # ドキュメントインデックス
│   ├── getting-started/       # オンボーディングガイド
│   │   ├── installation.md
│   │   ├── quickstart.md
│   │   └── configuration.md
│   │
│   ├── architecture/          # システム設計
│   │   ├── overview.md       # システム概要
│   │   ├── components.md     # コンポーネント構成
│   │   ├── data-flow.md      # データフロー図
│   │   └── decisions/        # ADR (Architecture Decision Records)
│   │       ├── 001-database-choice.md
│   │       ├── 002-api-design.md
│   │       └── template.md
│   │
│   ├── api/                   # API 仕様
│   │   ├── rest-api.md
│   │   └── graphql-schema.md
│   │
│   ├── guides/                # 開発者ガイド
│   │   ├── coding-standards.md
│   │   ├── testing.md
│   │   └── deployment.md
│   │
│   └── dev/                   # アクティブな機能開発
│       ├── README.md          # アクティブな機能インデックス
│       └── [feature-name]/    # 機能ごとのドキュメント
│           ├── SPEC.md
│           ├── DESIGN.md
│           ├── TEST_PLAN.md
│           ├── ROADMAP.md
│           └── CONTEXT.md

最小限の構造 (小規模プロジェクト)

project-root/
├── README.md                    # プロジェクト概要
├── ARCHITECTURE.md             # 基本的なアーキテクチャメモ
└── docs/
    └── dev/
        ├── README.md          # アクティブな機能
        └── [feature-name]/
            ├── SPEC.md
            ├── DESIGN.md
            └── CONTEXT.md

ドキュメント成熟度レベル

レベル 1 – Startup (3ヶ月未満、1-2人の開発者):

• README.md
• docs/dev/[feature]/CONTEXT.md

レベル 2 – Growing (3-12ヶ月、2-5人の開発者):

• • ARCHITECTURE.md
• • docs/dev/README.md
• • docs/getting-started/

レベル 3 – Mature (1年以上、5人以上の開発者):

• • docs/architecture/decisions/ (ADRs)
• • docs/guides/
• • docs/api/
• • CONTRIBUTING.md