context-driven-development

コンテキスト駆動開発

コードと並行して、管理対象の成果物としてコンテキストを実装・維持するためのガイドです。構造化されたプロジェクトドキュメントを通じて、一貫した AI とのやり取りとチーム内の認識合わせを実現します。

このスキルを使用する場面

• 構造化されたコンテキストを用いて新しいプロジェクトを設定するとき
• コンテキスト成果物間の関係を理解するとき
• AI 支援による開発セッション全体の一貫性を維持するとき
• 既存のプロジェクトにチームメンバーを迎えるとき
• コンテキストドキュメントを更新するタイミングを判断するとき
• グリーンフィールドとブラウンフィールドのプロジェクトのコンテキストを管理するとき

基本理念

コンテキスト駆動開発では、プロジェクトのコンテキストをコードと並行して管理する第一級の成果物として扱います。その場限りのプロンプトや散在するドキュメントに頼るのではなく、すべての AI とのやり取りの基盤となる、永続的で構造化された土台を確立します。

主な原則：

1. コンテキストはコードに先行する：実装の前に、何をどのように構築するかを定義します
2. 生きたドキュメント：コンテキスト成果物はプロジェクトとともに進化します
3. 信頼できる唯一の情報源：情報の種類ごとに、正規の保管場所を1つ設けます
4. AI との認識合わせ：一貫したコンテキストによって、一貫した AI の動作が実現します

ワークフロー

コンテキスト → 仕様と計画 → 実装のワークフローに従います：

1. コンテキストフェーズ：プロジェクトのコンテキスト成果物が存在し、最新であることを確認または確立します
2. 仕様策定フェーズ：作業単位ごとに要件と受け入れ基準を定義します
3. 計画フェーズ：仕様を段階的で実行可能なタスクに分解します
4. 実装フェーズ：確立されたワークフローパターンに従ってタスクを実行します

成果物間の関係

product.md - WHAT（何を）と WHY（なぜ）を定義します

目的：製品のビジョン、目標、対象ユーザー、ビジネスの背景を記録します。

内容：

• 製品名と一行の説明
• 課題と解決策の概要
• 対象ユーザーのペルソナ
• 主な機能と能力
• 成功指標と KPI
• 製品ロードマップ（概要）

次の場合に更新します：

• 製品のビジョンや目標が変わったとき
• 新しい主要機能を計画するとき
• 対象ユーザーが変わったとき
• ビジネス上の優先事項が変化したとき

product-guidelines.md - HOW（どのように）伝えるかを定義します

目的：ブランドボイス、メッセージング基準、コミュニケーションパターンを定めます。

内容：

• ブランドボイスとトーンのガイドライン
• 用語と用語集
• エラーメッセージの規則
• ユーザー向け文面の基準
• ドキュメントのスタイル

次の場合に更新します：

• ブランドガイドラインが変わったとき
• 新しい用語が導入されたとき
• コミュニケーションパターンの改善が必要なとき

tech-stack.md - WITH WHAT（何を使って）実現するかを定義します

目的：技術の選択、依存関係、アーキテクチャ上の決定を記録します。

内容：

• 主な言語とフレームワーク
• バージョンを含む主要な依存関係
• インフラストラクチャとデプロイ先
• 開発ツールと環境
• テストフレームワーク
• コード品質ツール

次の場合に更新します：

• 新しい依存関係を追加するとき
• メジャーバージョンをアップグレードするとき
• インフラストラクチャを変更するとき
• 新しいツールやパターンを採用するとき

workflow.md - HOW（どのように）作業するかを定義します

目的：開発プラクティス、品質ゲート、チームのワークフローを定めます。

内容：

• 開発手法（TDD など）
• Git ワークフローとコミット規則
• コードレビューの要件
• テスト要件とカバレッジ目標
• 品質保証のゲート
• デプロイ手順

次の場合に更新します：

• チームのプラクティスが変化したとき
• 品質基準が変わったとき
• 新しいワークフローパターンを採用したとき

tracks.md - WHAT'S HAPPENING（現在の作業状況）を記録します

目的：ステータスとメタデータを含む、すべての作業単位の台帳です。

内容：

• 現在のステータスを含む進行中のトラック
• 完了日を含む完了済みのトラック
• トラックのメタデータ（種類、優先度、担当者）
• 個々のトラックディレクトリへのリンク

次の場合に更新します：

• 新しいトラックを作成したとき
• トラックのステータスが変わったとき
• トラックを完了またはアーカイブしたとき

コンテキストの維持に関する原則

成果物の同期を維持する

ある成果物への変更が、関連ドキュメントにも反映されるようにします。

• product.md に新機能を追加 → 新しい依存関係が必要な場合は tech-stack.md を更新
• トラックの完了 → 新しい機能を反映するため product.md を更新
• ワークフローの変更 → 影響を受けるすべてのトラック計画を更新

依存関係を追加する際に tech-stack.md を更新する

新しい依存関係を追加する前に、次のことを行います。

1. 既存の依存関係で要件を満たせるか確認する
2. 新しい依存関係を追加する理由を記録する
3. バージョンの制約を追加する
4. 必要な設定を記載する

機能の完了時に product.md を更新する

機能トラックの完了後、次のことを行います。

1. product.md で機能を「planned」から「implemented」に移す
2. 影響を受ける成功指標を更新する
3. 当初の計画から変更された範囲を記録する

実装前にコンテキストを確認する

トラックを開始する前に、次のことを行います。

1. すべてのコンテキスト成果物を読む
2. 古くなった情報があれば指摘する
3. 作業を進める前に更新案を提示する
4. ステークホルダーとコンテキストの正確性を確認する

グリーンフィールドとブラウンフィールドの取り扱い

グリーンフィールドプロジェクト（新規）

新規プロジェクトの場合：

1. 対話しながらすべての成果物を作成する
2. プロダクトのビジョン、技術面の希望、ワークフローについて質問に答える
3. 選択した言語の初期スタイルガイドを生成する
4. 空のトラックレジストリを作成する

特徴：

• コンテキスト構造を全面的に制御できる
• コードが存在する前に標準を定義できる
• 早い段階でパターンを確立できる

ブラウンフィールドプロジェクト（既存）

既存のコードベースの場合：

1. 既存のコード、設定、ドキュメントを分析する
2. 発見したパターンに基づいて成果物を事前に作成する
3. 生成されたコンテキストを確認し、改善する
4. 既存のパターンを望ましいパターンとすり合わせる

特徴：

• 既存のコードから暗黙的なコンテキストを抽出する
• 既存のパターンを望ましいパターンとすり合わせる
• 技術的負債とモダナイゼーション計画を記録する
• 標準を確立しながら、機能しているパターンを維持する

メリット

チームの連携

• 新しいチームメンバーが、明示されたコンテキストによってより早く業務に慣れる
• チーム全体で用語と規約を統一できる
• プロダクトの目標と技術的な判断について共通理解を得られる

AI の一貫性

• AI アシスタントがセッションをまたいで整合性のある出力を生成する
• やり取りのたびにコンテキストを説明し直す手間を削減できる
• 文書化された標準に基づく予測可能な動作が得られる

組織の知見の蓄積

• 決定事項とその理由が保存される
• チームが変わってもコンテキストが維持される
• 過去のコンテキストが将来の判断に役立つ

品質保証

• 標準が明示され、検証可能になる
• コンテキストからの逸脱を検出できる
• 品質ゲートが文書化され、適用可能になる

ディレクトリ構造

.claude/context/
├── product.md            # Product vision and goals
├── product-guidelines.md # Communication standards
├── tech-stack.md         # Technology preferences
├── workflow.md           # Development practices
├── tracks.md             # Work unit registry
└── tracks/
    └── <track-id>/
        ├── spec.md
        ├── plan.md
        ├── metadata.json
        └── index.md

コンテキストのライフサイクル

1. 作成：初期設定
2. 検証：各トラックの前に確認する
3. 進化：プロジェクトの成長に合わせて更新する
4. 同期：成果物の整合性を保つ
5. アーカイブ：過去の決定を記録する

コンテキスト検証チェックリスト

トラックの実装を開始する前に、コンテキストを検証します。

プロダクトのコンテキスト

• product.md に現在のプロダクトビジョンが反映されている
• 対象ユーザーが正確に記述されている
• 機能一覧が最新である
• 成功指標が定義されている

技術的なコンテキスト

• tech-stack.md に現在のすべての依存関係が記載されている
• バージョン番号が正確である
• インフラストラクチャの対象が正しい
• 開発ツールが文書化されている

ワークフローのコンテキスト

• workflow.md に現在のプラクティスが記載されている
• 品質ゲートが定義されている
• カバレッジ目標が指定されている
• コミット規約が文書化されている

トラックのコンテキスト

• tracks.md にすべての進行中の作業が示されている
• 古くなったトラックや放棄されたトラックがない
• トラック間の依存関係が記録されている

よくあるアンチパターン

次のようなコンテキスト管理の誤りを避けてください。

古くなったコンテキスト

問題：コンテキストドキュメントが古くなり、誤解を招くようになります。
解決策：各トラックの完了プロセスの一環として、コンテキストを更新します。

コンテキストの拡散

問題：情報が複数の場所に散在しています。 解決策：定義済みのアーティファクト構造を使い、新しいドキュメントの種類を作らないようにします。

暗黙のコンテキスト

問題：アーティファクトに記録されていない知識に依存しています。 解決策：何度も参照する情報がある場合は、適切なアーティファクトに追加します。

コンテキストの抱え込み

問題：チームの意見を取り入れず、一人でコンテキストを管理しています。 解決策：プルリクエストでコンテキストアーティファクトをレビューし、共同で更新します。

過剰な詳細化

問題：コンテキストが詳細になりすぎて、維持できなくなっています。 解決策：AI の動作やチームの認識に影響する判断に焦点を当て、アーティファクトの内容を絞ります。

開発ツールとの統合

IDE との統合

コンテキストファイルが目立つように IDE を設定します。

• すぐ参照できるように product.md をピン留めします
• tech-stack.md をプロジェクトのメモに追加します
• スタイルガイドの一般的なパターンのスニペットを作成します

Git フック

次のような処理を行う pre-commit フックを検討します。

• tech-stack.md を更新せずに依存関係が変更された場合に警告します
• 機能ブランチをマージする際に product.md の更新を促します
• コンテキストアーティファクトの構文を検証します

CI/CD との統合

パイプラインにコンテキストの検証を含めます。

• tech-stack.md が実際の依存関係と一致することを確認します
• コンテキストドキュメント内のリンクが有効であることを確認します
• tracks.md のステータスが git ブランチの状態と一致することを確認します

セッションの継続性

コンテキストを保持して、複数セッションにわたる開発を支援します。

新しいセッションの開始

1. product.md を読んで状況を把握します
2. tracks.md で進行中の作業を確認します
3. 該当するトラックの plan.md を確認し、現在のタスクを把握します
4. コンテキストアーティファクトが最新であることを確認します

セッションの終了

1. 現在の進捗を plan.md に更新します
2. 発生したブロッカーや下した判断を記録します
3. 状況が明確にわかる形で作業途中の変更をコミットします
4. ステータスが変わった場合は tracks.md を更新します

中断への対処

タスクの途中で中断された場合：

1. 停止した時点のメモを添えて、タスクを [~] にします
2. 作業途中の変更を機能ブランチにコミットします
3. コミットされていない判断があれば、plan.md に記録します

ベストプラクティス

1. まずコンテキストを読む：作業を始める前に、必ず関連するアーティファクトを読みます
2. 小さく更新する：大規模な書き換えではなく、コンテキストを段階的に変更します
3. 判断を関連付ける：実装方法を選ぶ際に、コンテキストを参照します
4. コンテキストをバージョン管理する：コードの変更とともにコンテキストの変更もコミットします
5. コンテキストをレビューする：コードレビューにコンテキストアーティファクトのレビューを含めます
6. 定期的に検証する：大規模な作業の前に、コンテキスト検証チェックリストを実行します
7. 変更を共有する：コンテキストアーティファクトに大きな変更があった場合は、チームに知らせます
8. 履歴を保持する：git を使って、コンテキストの変遷を継続的に追跡します
9. 古くなっていないか確認する：コンテキストに違和感があれば、原因を調べて更新します
10. 実行に役立つ内容にする：すべてのコンテキスト項目が、判断や動作に役立つようにします

絶対に守るべき原則

1. 必ず、実装トラックを始める前に、関連するコンテキストアーティファクト（product.md、tech-stack.md、workflow.md）をすべて読みます。古い、または未検証のコンテキストに基づいてコーディングを始めてはいけません。
2. 決して、定義済みのディレクトリ構造にある既存のカテゴリで対応できる場合に、新しいアーティファクトの種類やドキュメントの場所を作ってはいけません。コンテキストの拡散を防ぎます。
3. 必ず、コードの変更とコンテキストアーティファクトの更新を同じコミットでまとめて行います。コンテキストの更新を別の PR に分けると、乖離や古い参照が発生します。
4. 決して、コンテキストファイルが 20KB を超えるまま放置してはいけません。ローテーションまたはアーカイブを行います。際限のない肥大化はコンテキストを使いにくくし、AI とのやり取りを遅くします。
5. 必ず、実装の前に古いコンテキストや矛盾するコンテキストを指摘します。古くなった tech-stack.md や誤った product.md は、AI とのやり取りを重ねるたびに深刻化する技術的負債です。

メモリプロトコル（必須）

開始前：

cat .claude/context/memory/learnings.md

完了後：

• 新しいパターン → .claude/context/memory/learnings.md
• 問題の発見 → .claude/context/memory/issues.md
• 判断の決定 → .claude/context/memory/decisions.md

中断されることを前提にします：メモリに記録されていなければ、起きていないのと同じです。