開発
Document Driven Development
BluePeriodの開発手法。Issue→Plan→実装→Reportのサイクルと、AIとの協働における国語重視の哲学
Document Driven Development
1. DDDとは
BluePeriodにおけるDDD（Document Driven Development）は、すべての実装をドキュメントで駆動する開発手法です。コードを書く前に「なぜ」「何を」「どうするか」を文章で定義し、その文章を実装に翻訳するサイクルを回します。
Issue（課題の定義）
→ Plan（解決策の設計）
→ 実装（コードの記述）
→ Report（結果の記録）2. なぜDDDなのか
AIの時代、「国語」が最強のプログラミング言語になった
大規模言語モデル（LLM）の台頭により、自然言語で意図を正確に伝える能力が、コーディング能力と同等かそれ以上に重要になりました。プロンプトエンジニアリングの本質は「自分の思考を言語化する力」であり、これはDDDの「ドキュメントで設計する」という方針と完全に一致します。
AIへのコンテキストマネジメント
AIは文脈（コンテキスト）の中で最善を尽くす存在です。DDDのドキュメント群は、AIに対する構造化されたコンテキストとして機能します。Issueは「問題の境界」を、Planは「解決の道筋」を、Reportは「結果の検証」をAIに伝え、一貫した高品質な出力を導きます。
デザイナーにとってのDDD
BluePeriodの開発者はデザイナー寄りの背景を持っています。「国語で理解できるコード・実装」であることは、デザイン思考と実装の間の翻訳コストを最小化します。ドキュメントはデザイナーとエンジニアの境界をなくす橋渡しであり、同時にAIにとっても最も処理しやすい入力形式です。
3. サイクル
Issue — 課題の定義
何が問題なのか、何を達成したいのかを記述します。
---
title: タイトル
date: YYYY-MM-DD_HHMM
tags: [tag1, tag2]
status: open | close
priority: high | medium | low
---
# タイトル
## 1. 背景
（なぜこのタスクが必要なのか）
## 2. 目的
（何を達成するのか）
## 3. 要件
（具体的な条件）
## 4. スコープ外
（やらないこと）Plan — 解決策の設計
どう解決するのかを記述します。Issueを受けて、実装の設計を行います。
---
title: タイトル
date: YYYY-MM-DD_HHMM
tags: [tag1, tag2]
status: open | close
priority: high | medium | low
completion_percentage: 0
last_updated: "YYYY-MM-DD"
---
# タイトル
## 1. 概要
## 2. 設計方針
## 3. 実装フェーズ
- [ ] Phase 1: ...
- [ ] Phase 2: ...
## 4. 成功基準
## 5. リスクと留意点Report — 結果の記録
何をしたのか、結果はどうだったのかを記述します。Planの各フェーズの実行結果を記録します。
---
title: タイトル
date: YYYY-MM-DD_HHMM
tags: [tag1, tag2]
status: close
priority: high | medium | low
---
# タイトル
## 概要
（Planに基づく実装結果の要約）
## 実行内容
（各フェーズの実行結果）
## 成功基準の達成状況
- [x] 基準1
- [ ] 基準2
## 残存課題
（あれば）4. AIセッションプロンプト
以下のプロンプトは、Claude Code等のAIツールとの開発セッションで使用するテンプレートです。プロジェクトの文脈をAIに伝え、一貫した協働を実現します。
開発用（標準）
コード変更を伴うタスクに使用します。開発規約の遵守と品質チェックを含みます。
▼BluePeriod開発依頼
▼ 基本：プロジェクト理解
まず
- document_index.md / document_architecture.md
から今回のタスクを実践するうえで把握しておいたほうが良いドキュメントを自己判断し、詳細に把握しておいてください。
- 全文を読むとタスクごとの要件としては必ずしも必要ないテキストでコンテキストを圧迫してしまうため、あなたがSubAgentなどを使える環境にある場合は、サブエージェントに探索させて最適化されたドキュメントを受け取ってください。
**【警告】すべてのコード変更タスク（機能実装、バグ修正、リファクタリング等）を開始する前に、必ず以下のドキュメントを読み込み、その内容を完全に遵守してください。**
1. **06_development_guidelines.md**: コーディング規約、命名規則、コンポーネント設計、状態管理などの基本方針。
2. **09_design_system.md**: デザイン哲学、カラースキーム（セマンティックトークン）、レスポンシブ戦略、UIパターン。**UIの変更を伴う場合は、読み込みが必須です。**
これらを無視して実装されたコードは、プロジェクトの一貫性を損なうため、受け入れられません。タスクに着手する思考プロセスの第一歩として、必ずこれらのガイドラインの確認を組み込んでください。
▼ 作業方針 / 禁止事項 / 開発規則
- 作業が終わったなら、**playwrightによるUIテストはしなくてよい**です。
- コードレビューは大事ですが、**Verifyは軽くでいいので**タスク完遂することを最重要視してください。
- 稼働ツールによっては、エージェントReACTループのバグで延々とgit statusやらgit diffして最終的にフリーズするなどの致命的なバグを引き起こすことがあります。これは厳禁です。無限の微細なチェックループに陥る前に気づき、かならず人間に相談すること。
- また基本的に、リポジトリへの致命的な破損を防ぐために**gitコマンドはどうしても使わなければ作業できない場合以外、使用を禁止します。**
- **next-app/public/sw.js や next-app/public/sitemap.xml の自動で更新される際のDiffのアーティファクトは、バグでない限り無視して構いません**
- もしタスクが実装依頼の場合に限り、タスク完了後は必ず`package.json`の"scripts"に提議してあるコマンドから適切なものを選び、タスクに応じて最適な形で現存するバグがないかチェックし、必要に応じてバグフィックスを試行してください。
- ただし、実装が難航/または追加で実装をし始めた場合は、毎回Lintはしないなど柔軟に対処してください。
- Planningの際にPlanやTaskドキュメントを作成するなどの必要がある場合は、日本語でお願いします。
- rm rfのような破滅的な結果を生む可能性のあるコマンドは厳禁します。絶対に使用しないでください。
- コーディングについてはあなたのほうが知識がある場合もあるため、こちらからあなたをガイドしたり指示することは必ずしもできるわけではありません。言われなければやらない、という風だと困るため、開発においてはある程度のイニシアチブをとりつつ、こちらの承認を取るようにしてください。
- **回答や思考は日本語でお願いします。**
- ファイルを探索したり、分析などをする場合は、優先的に備え付けのTool(IDEやCLIから提供されている標準ツール)を使用してください。Grepやrgなども使ってよいですが、標準ツールでできるのに不必要に用いないでください。
- ブラウザ自動使用ツールは、指示を受けない限り使用禁止とします。
- もしPlanドキュメントにおいて、適切なPhase分けをされていたとしたら、一気通貫にやるのではなくPlanに従ってPhaseごとにやっていきましょう。
- Planが提示されている場合は、基本的にはそれに準拠して実装しますが、実際に手を動かして見つかる発見もあると思います。実装担当として、あなたの裁量を発揮することができます。Plan作成者のコードスニペットなどを絶対的に信頼したりはせず、美しく機能するコードとなるように作業してください。
- Bashコマンドを打つなどする際、長大な呪文のようなコマンドを打たれると、私が読解するための認知不可がかかるので、シンプルにするように努めてください。
# ====== ** 今回のタスク ** =========
開発用（軽量）
小規模な修正や調査に使用します。ガイドライン読み込みを最小限に抑えます。
▼BluePeriod開発依頼
▼ 基本：プロジェクト理解
- document_index.md / document_architecture.md
から今回のタスクを実践するうえで把握しておいたほうが良いドキュメントを自己判断し、詳細に把握しておいてください。
- 全文を読むとタスクごとの要件としては必ずしも必要ないテキストでコンテキストを圧迫してしまうため、あなたがSubAgentなどを使える環境にある場合は、サブエージェントに探索させて最適化されたドキュメントを受け取ってください。
1. **06_development_guidelines.md**: コーディング規約、命名規則、コンポーネント設計、状態管理などの基本方針。
- rm rfのような破滅的な結果を生む可能性のあるコマンドは厳禁します。絶対に使用しないでください。
# ====== ** 今回のタスク ** =========
ADRセッション用
アーキテクチャ決定記録（Architecture Decision Record）の作成に使用します。開発用プロンプトに加え、設計判断に焦点を当てます。
▼BluePeriod ADRセッション
まず
- document_index.md / document_architecture.md
から今回のタスクを実践するうえで把握しておいたほうが良いドキュメントを自己判断し、詳細に把握しておいてください。
- 全文を読むとタスクごとの要件としては必ずしも必要ないテキストでコンテキストを圧迫してしまうため、あなたがSubAgentなどを使える環境にある場合は、サブエージェントに探索させて最適化されたドキュメントを受け取ってください。
**【警告】すべてのコード変更タスク（機能実装、バグ修正、リファクタリング等）を開始する前に、必ず以下のドキュメントを読み込み、その内容を完全に遵守してください。**
1. **06_development_guidelines.md**: コーディング規約、命名規則、コンポーネント設計、状態管理などの基本方針。
2. **09_design_system.md**: デザイン哲学、カラースキーム（セマンティックトークン）、レスポンシブ戦略、UIパターン。**UIの変更を伴う場合は、読み込みが必須です。**
これらを無視して実装されたコードは、プロジェクトの一貫性を損なうため、受け入れられません。タスクに着手する思考プロセスの第一歩として、必ずこれらのガイドラインの確認を組み込んでください。
▼作業方針
- Planningの際にPlanやTaskドキュメントを作成するなどの必要がある場合は、日本語でお願いします。
- rm rfのような破滅的な結果を生む可能性のあるコマンドは厳禁します。絶対に使用しないでください。
- コーディングについてはあなたのほうが知識がある場合もあるため、こちらからあなたをガイドしたり指示することは必ずしもできるわけではありません。言われなければやらない、という風だと困るため、開発においてはある程度のイニシアチブをとりつつ、こちらの承認を取るようにしてください。
- **回答や思考は日本語でお願いします。**
- ファイルを探索したり、分析などをする場合は、優先的に備え付けのTool(IDEやCLIから提供されている標準ツール)を使用してください。Grepやrgなども使ってよいですが、標準ツールでできるのに不必要に用いないでください。
- Planが提示されている場合は、基本的にはそれに準拠して実装しますが、実際に手を動かして見つかる発見もあると思います。実装担当として、あなたの裁量を発揮することができます。Plan作成者のコードスニペットなどを絶対的に信頼したりはせず、美しく機能するコードとなるように作業してください。
- Bashコマンドを打つなどする際、長大な呪文のようなコマンドを打たれると、私が読解するための認知不可がかかるので、シンプルにするように努めてください。
# ====== ** 今回のタスク ** =========
PR Review用
メンテナーがAIを用いてPRをレビューする際に使用します。pr-review-guide に基づく観点でレビューを行います。
▼BluePeriod PR Review
PRのレビューをお願いします。
▼ レビュー観点
以下の観点でレビューしてください。詳細は system/pr-review-guide.md を参照。
1. **スコープの整合性** — PRのSummaryに書かれていない実装が含まれていないか
2. **規約への準拠** — 06_development_guidelines / 09_design_system に沿っているか
3. **アーキテクチャの整合性** — 01_architecture のBFF/BYOKパターンに沿っているか
4. **セキュリティ** — eval(), 外部リクエスト, 機密情報, 難読化コードがないか
5. **品質** — TypeScriptの型, エラーハンドリング, ローディングUI
▼ レビュー手順
1. `gh pr diff {番号}` で差分を取得
2. PRのSummaryと実際の変更内容を照合
3. 上記5観点で確認
4. 判定とフィードバックを返信:
- **Approve**: CI通過 + 観点を満たす
- **Request Changes**: セキュリティ問題、規約違反、スコープ外の変更がある
- **Comment**: 軽微な改善提案（マージをブロックしない）
- 指摘事項がある場合は、具体的な改善案をセットで提示してください。
- 初回コントリビューターのPRには歓迎のトーンを心がけてください。
# ====== ** 対象PR ** =========
5. 外部コントリビューターとDDD
DDDはメンテナーの内部開発フローです。外部コントリビューターには、必須ではありませんが基本的には推奨します。小規模なPR（バグ修正やタイポ）では、標準的なFork→Branch→PRのフローでも許容されます。大規模な変更では、doc/log/に設計ドキュメントを含めることを推奨します。
詳細は development_contributing の「貢献フロー」セクション、およびリポジトリルートの CONTRIBUTING.md を参照してください。
関連ドキュメント
- document_architecture — ドキュメント体系の構造定義（WikiLinks、命名規則、URL構造）
- document_maintenance — ドキュメント整備のワークフロー（影響分析、更新判断基準）
- document_index — 全ドキュメントの担当スコープ索引
- development_contributing — コントリビューションガイド（規約、フロー、レビュー体制）
- pr-review-guide — PRレビューの観点とセキュリティチェックリスト