diff --git a/.cursor/rules/00-global.mdc b/.cursor/rules/00-global.mdc index d2e4390..28da582 100644 --- a/.cursor/rules/00-global.mdc +++ b/.cursor/rules/00-global.mdc @@ -11,6 +11,8 @@ alwaysApply: true - 本リポジトリの AI 運用は「正本を1箇所に集約し、生成先へ配布する」方式を採用する。 - ルール更新時は `docs/ai/canonical/` を編集し、生成ファイルは直接編集しない。 - タスク開始時は必ずタスク設計を作成し、承認後に実装する。 +- プロダクト方針は `docs/product/vision.md` / `docs/product/goals.md` / `docs/product/milestones.md` / `docs/product/progress.md` を正本として管理する。 +- 新規タスク設計書には、`関連ゴールID` と `関連マイルストーンID` を必ず記載する。 - 既存の実装・ドキュメントとの整合を保ち、変更理由を記録する。 - ユーザーとのコミュニケーションは日本語で行う。 - CI は必須とし、品質ゲートの不一致を許容しない。 diff --git a/.cursor/rules/10-task-routing.mdc b/.cursor/rules/10-task-routing.mdc index e2e1772..3c8d72c 100644 --- a/.cursor/rules/10-task-routing.mdc +++ b/.cursor/rules/10-task-routing.mdc @@ -12,7 +12,7 @@ alwaysApply: true | --- | --- | --- | | 実装前設計 | 実装・修正・移行など、ファイル変更前にスコープ整理と承認が必要 | [task-design-gate](docs/ai/playbooks/task-design-gate.md) | | Python の CI / 品質ゲート導入 | `uv` 前提で lint/type/test/CI を一貫運用したい | [python-uv-ci-setup](docs/ai/playbooks/python-uv-ci-setup.md) | -| 新規プロジェクト初期構築 | Python プロジェクトを Hexagonal + 運用標準で立ち上げる | [python-project-bootstrap](docs/ai/playbooks/python-project-bootstrap.md) | +| 新規プロジェクト初期構築 | Python プロジェクトを Hexagonal + 運用標準で立ち上げ、`docs/product/*.md` を初期擦り合わせする | [python-project-bootstrap](docs/ai/playbooks/python-project-bootstrap.md) | | API 仕様同期 | API 実装と仕様ドキュメントの差分を同期する | [api-spec-sync](docs/ai/playbooks/api-spec-sync.md) | | 設計判断の記録・更新 | アーキテクチャ方針や運用ルールの採否を ADR として記録・更新する | [adr-management](docs/ai/playbooks/adr-management.md) | | コミット実行 | 変更内容を確認して規約に沿ったコミットを行う | [git-commit](docs/ai/playbooks/git-commit.md) | diff --git a/AGENTS.md b/AGENTS.md index de82e5a..0c79ad5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,8 @@ - 本リポジトリの AI 運用は「正本を1箇所に集約し、生成先へ配布する」方式を採用する。 - ルール更新時は `docs/ai/canonical/` を編集し、生成ファイルは直接編集しない。 - タスク開始時は必ずタスク設計を作成し、承認後に実装する。 +- プロダクト方針は `docs/product/vision.md` / `docs/product/goals.md` / `docs/product/milestones.md` / `docs/product/progress.md` を正本として管理する。 +- 新規タスク設計書には、`関連ゴールID` と `関連マイルストーンID` を必ず記載する。 - 既存の実装・ドキュメントとの整合を保ち、変更理由を記録する。 - ユーザーとのコミュニケーションは日本語で行う。 - CI は必須とし、品質ゲートの不一致を許容しない。 @@ -27,7 +29,7 @@ | --- | --- | --- | | 実装前設計 | 実装・修正・移行など、ファイル変更前にスコープ整理と承認が必要 | [task-design-gate](docs/ai/playbooks/task-design-gate.md) | | Python の CI / 品質ゲート導入 | `uv` 前提で lint/type/test/CI を一貫運用したい | [python-uv-ci-setup](docs/ai/playbooks/python-uv-ci-setup.md) | -| 新規プロジェクト初期構築 | Python プロジェクトを Hexagonal + 運用標準で立ち上げる | [python-project-bootstrap](docs/ai/playbooks/python-project-bootstrap.md) | +| 新規プロジェクト初期構築 | Python プロジェクトを Hexagonal + 運用標準で立ち上げ、`docs/product/*.md` を初期擦り合わせする | [python-project-bootstrap](docs/ai/playbooks/python-project-bootstrap.md) | | API 仕様同期 | API 実装と仕様ドキュメントの差分を同期する | [api-spec-sync](docs/ai/playbooks/api-spec-sync.md) | | 設計判断の記録・更新 | アーキテクチャ方針や運用ルールの採否を ADR として記録・更新する | [adr-management](docs/ai/playbooks/adr-management.md) | | コミット実行 | 変更内容を確認して規約に沿ったコミットを行う | [git-commit](docs/ai/playbooks/git-commit.md) | diff --git a/README.md b/README.md index 3e0298a..f71d517 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ Codex と Cursor を併用する Python プロジェクト向けのテンプレ ├── docs/ai/canonical/playbooks/*.md # Playbook手順の正本（手動編集） ├── docs/ai/playbooks/*.md # 自動生成（実行時の参照先） ├── docs/ai/playbook-assets/** # 参照資料（手動編集） +├── docs/product/*.md # プロダクト方針・目標・進捗の正本（手動編集） ├── scripts/playbooks/** # 補助スクリプト（手動編集） ├── scripts/sync_ai_context.py # 生成/検証 ├── scripts/bootstrap_after_canonical.py # 同期後ブートストラップ @@ -40,6 +41,19 @@ Codex と Cursor を併用する Python プロジェクト向けのテンプレ - `docs/ai/playbooks/*.md`、`AGENTS.md`、`.cursor/rules/*.mdc` は自動生成物として直接編集しない。 - Playbook の参照資料は `docs/ai/playbook-assets/`、補助スクリプトは `scripts/playbooks/` を正本とする。 +## プロダクト方針と進捗管理 + +- プロダクト方針の正本は `docs/product/` に置く。 +- 各タスク設計は `関連ゴールID` / `関連マイルストーンID` を明記し、日々の実装を中長期目標へ接続する。 +- テンプレート利用開始時は、`python-project-bootstrap` の初期対話で `docs/product/*.md` をユーザーと擦り合わせて埋める。 + +`docs/product/` の役割: + +- `docs/product/vision.md`: 最終的に目指す状態、対象ユーザー、再設定ルール +- `docs/product/goals.md`: ユーザー到達状態ゴール（Goal ID）と到達判定 +- `docs/product/milestones.md`: 到達ステップ（Milestone ID） +- `docs/product/progress.md`: やるべきこと一覧、完了済み、未完了、現在地 + ## README と AGENTS の書き分け | 書く場所 | 主な読者 | 記載する内容 | 記載しない内容 | diff --git a/docs/ai/canonical/global-policies.md b/docs/ai/canonical/global-policies.md index 6630ae7..ce1bf5e 100644 --- a/docs/ai/canonical/global-policies.md +++ b/docs/ai/canonical/global-policies.md @@ -3,6 +3,8 @@ - 本リポジトリの AI 運用は「正本を1箇所に集約し、生成先へ配布する」方式を採用する。 - ルール更新時は `docs/ai/canonical/` を編集し、生成ファイルは直接編集しない。 - タスク開始時は必ずタスク設計を作成し、承認後に実装する。 +- プロダクト方針は `docs/product/vision.md` / `docs/product/goals.md` / `docs/product/milestones.md` / `docs/product/progress.md` を正本として管理する。 +- 新規タスク設計書には、`関連ゴールID` と `関連マイルストーンID` を必ず記載する。 - 既存の実装・ドキュメントとの整合を保ち、変更理由を記録する。 - ユーザーとのコミュニケーションは日本語で行う。 - CI は必須とし、品質ゲートの不一致を許容しない。 diff --git a/docs/ai/canonical/playbooks/python-project-bootstrap.md b/docs/ai/canonical/playbooks/python-project-bootstrap.md index f4ba5d1..5e76b1b 100644 --- a/docs/ai/canonical/playbooks/python-project-bootstrap.md +++ b/docs/ai/canonical/playbooks/python-project-bootstrap.md @@ -1,6 +1,6 @@ --- name: python-project-bootstrap -description: 新しい Python プロジェクトの初期セットアップを標準化するPlaybook。AGENTS.md を対話で確定し、Hexagonal Architecture 前提のディレクトリ、SOLID/DRY ガイド、API/タスク設計ドキュメント、`.env.development`/`.env.production` と dotenvx 暗号化運用を整備するときに使う。CI は必須工程とし、品質ゲート設定は必ず `python-uv-ci-setup` を呼び出して完了させる依頼で適用する。 +description: 新しい Python プロジェクトの初期セットアップを標準化するPlaybook。AGENTS.md と docs/product を対話で確定し、Hexagonal Architecture 前提のディレクトリ、SOLID/DRY ガイド、API/タスク設計ドキュメント、`.env.development`/`.env.production` と dotenvx 暗号化運用を整備するときに使う。CI は必須工程とし、品質ゲート設定は必ず `python-uv-ci-setup` を呼び出して完了させる依頼で適用する。 --- # Pythonプロジェクト初期構築 @@ -10,6 +10,7 @@ description: 新しい Python プロジェクトの初期セットアップを ## 実行ルール - AGENTS.md の不明点がある状態で雛形を確定しない。必ず対話で埋める。 +- `docs/product/vision.md` / `docs/product/goals.md` / `docs/product/milestones.md` / `docs/product/progress.md` を空欄のまま放置しない。初期化時に必ずユーザーと擦り合わせる。 - 質問は 1〜3 問ずつ行い、回答を反映して次の質問へ進む。 - CI 設定は必須。必ず `python-uv-ci-setup` を使って完了させる。 - 既存ファイルがある場合は破壊的上書きを避け、差分統合を優先する。 @@ -32,31 +33,43 @@ description: 新しい Python プロジェクトの初期セットアップを - 未確定項目は既定値を勝手に固定せず、ユーザー確認を優先する。 - 既定値を使う場合は「既定値を採用した」と明示してから確定する。 -3. 初期構成を生成する。 +3. プロダクト方針（docs/product）を対話で初期確定する。 +- `docs/ai/playbook-assets/python-project-bootstrap/references/product-docs-alignment.md` を使い、1〜3問ずつ擦り合わせる。 +- 最低限、次を埋める。 + - `docs/product/vision.md`: 対象ユーザー、解く課題、成功状態 + - `docs/product/goals.md`: ユーザー到達状態ゴールと到達判定 + - `docs/product/milestones.md`: 到達ステップ + - `docs/product/progress.md`: やるべきこと一覧ベースの現在地 +- 不確定項目が残る場合は、`仮置き` と明記して次の確認タイミングを残す。 + +4. 初期構成を生成する。 - `scripts/playbooks/python-project-bootstrap/bootstrap_python_project.py` を実行して、ディレクトリと初期ドキュメントを生成する。 - 例: - `python3 scripts/playbooks/python-project-bootstrap/bootstrap_python_project.py --target --project-name --package-name --description ""` - 必要に応じて `--task-design-dir docs/task-designs`（既定）や `--force` を使う。 - 生成後に手順正本を `/docs/ai/canonical/playbooks/` に配置してコミットし、以後の実行基盤を repo ローカルへ固定する。 -4. 生成内容をレビューする。 +5. 生成内容をレビューする。 - `docs/ai/playbook-assets/python-project-bootstrap/references/project-structure.md` を基準に、`adapters/application/domain/ports` の責務分離を確認する。 - `docs/rules/solid/README.md` と `docs/rules/code_architecture/README.md` の導線が AGENTS.md から参照できることを確認する。 - `docs/ai/playbook-assets/python-project-bootstrap/references/env-and-dotenvx.md` を基準に `.env.*` の運用記載が整合しているか確認する。 +- `docs/product/*.md` が生成され、対話で確定した内容が反映されていることを確認する。 -5. CI を必須で設定する。 +6. CI を必須で設定する。 - 生成直後に必ず `python-uv-ci-setup` を呼び出して、`uv` ベースの品質ゲートと GitHub Actions を整備する。 - 本Playbook内で CI 設定を再実装しない（DRY を維持）。 -6. 検証する。 +7. 検証する。 - 生成ファイル一覧を確認する。 - `AGENTS.md` の必須セクションが埋まっていることを確認する。 +- `docs/product/vision.md` / `docs/product/goals.md` / `docs/product/milestones.md` / `docs/product/progress.md` が初期記入されていることを確認する。 - `.env.development` / `.env.production` の整合を確認する。 - CI 設定完了後に `uv run pre-commit install` が実行可能な状態であることを確認する。 -7. 結果を報告する。 +8. 結果を報告する。 - 作成・更新したファイル - 対話で確定した項目 +- `docs/product` で合意した内容（Vision/Goal/Milestone/Progress） - CI 設定の実行結果 - 残課題（手動で埋めるべき値や鍵など） - Playbook 配置先（repo 配下 / 個人グローバル）と採用理由 @@ -65,5 +78,6 @@ description: 新しい Python プロジェクトの初期セットアップを - AGENTS.md ヒアリング項目: `docs/ai/playbook-assets/python-project-bootstrap/references/agents-md-checklist.md` - AGENTS と Playbooks の責務境界: `docs/ai/playbook-assets/python-project-bootstrap/references/agents-playbooks-boundary.md` +- docs/product 擦り合わせ質問: `docs/ai/playbook-assets/python-project-bootstrap/references/product-docs-alignment.md` - Hexagonal 構成と責務: `docs/ai/playbook-assets/python-project-bootstrap/references/project-structure.md` - `.env.*` と dotenvx 暗号化運用: `docs/ai/playbook-assets/python-project-bootstrap/references/env-and-dotenvx.md` diff --git a/docs/ai/canonical/playbooks/task-design-gate.md b/docs/ai/canonical/playbooks/task-design-gate.md index 96811c7..a1489f0 100644 --- a/docs/ai/canonical/playbooks/task-design-gate.md +++ b/docs/ai/canonical/playbooks/task-design-gate.md @@ -25,6 +25,7 @@ description: 実装前にタスク設計書を作成し、スコープ・前提 ## 出力ルール - `docs/ai/playbook-assets/task-design-gate/references/_task-design-template.md` の見出し順を厳守して Markdown で出力する。 +- タスク設計書のメタデータには、`関連ゴールID` と `関連マイルストーンID` を必ず記載する。 - 各セクションはリポジトリ固有の具体内容で記載し、一般論を避ける。 - ファイルは必ず明示的なパスで列挙する。 - 少なくとも 1 つ以上のリスクと検証手順を含める。 diff --git a/docs/ai/canonical/task-routing.md b/docs/ai/canonical/task-routing.md index bdf7a47..8ff89c8 100644 --- a/docs/ai/canonical/task-routing.md +++ b/docs/ai/canonical/task-routing.md @@ -4,7 +4,7 @@ | --- | --- | --- | | 実装前設計 | 実装・修正・移行など、ファイル変更前にスコープ整理と承認が必要 | [task-design-gate](docs/ai/playbooks/task-design-gate.md) | | Python の CI / 品質ゲート導入 | `uv` 前提で lint/type/test/CI を一貫運用したい | [python-uv-ci-setup](docs/ai/playbooks/python-uv-ci-setup.md) | -| 新規プロジェクト初期構築 | Python プロジェクトを Hexagonal + 運用標準で立ち上げる | [python-project-bootstrap](docs/ai/playbooks/python-project-bootstrap.md) | +| 新規プロジェクト初期構築 | Python プロジェクトを Hexagonal + 運用標準で立ち上げ、`docs/product/*.md` を初期擦り合わせする | [python-project-bootstrap](docs/ai/playbooks/python-project-bootstrap.md) | | API 仕様同期 | API 実装と仕様ドキュメントの差分を同期する | [api-spec-sync](docs/ai/playbooks/api-spec-sync.md) | | 設計判断の記録・更新 | アーキテクチャ方針や運用ルールの採否を ADR として記録・更新する | [adr-management](docs/ai/playbooks/adr-management.md) | | コミット実行 | 変更内容を確認して規約に沿ったコミットを行う | [git-commit](docs/ai/playbooks/git-commit.md) | diff --git a/docs/ai/playbook-assets/python-project-bootstrap/references/agents-md-checklist.md b/docs/ai/playbook-assets/python-project-bootstrap/references/agents-md-checklist.md index 554cc98..69b8634 100644 --- a/docs/ai/playbook-assets/python-project-bootstrap/references/agents-md-checklist.md +++ b/docs/ai/playbook-assets/python-project-bootstrap/references/agents-md-checklist.md @@ -42,6 +42,11 @@ AGENTS.md はエージェントの行動境界を固定する「常時参照さ - 空リポジトリ時のみグローバル bootstrap を初回1回だけ許容するか（既定: 許容する） - 初回生成後に `/docs/ai/canonical/playbooks/` を正本化するか（既定: 正本化する） +7. プロダクト方針（docs/product） +- `docs/product/vision.md` で対象ユーザー・課題・成功状態を初期確定するか（既定: 初期確定する） +- `docs/product/goals.md` を「ユーザー到達状態ゴール」で定義するか（既定: 定義する） +- `docs/product/progress.md` を `%` ではなく「やるべきこと一覧」で管理するか（既定: 管理する） + ## 任意項目（必要時のみ） - フロントエンド併設の有無 @@ -75,6 +80,12 @@ AGENTS.md はエージェントの行動境界を固定する「常時参照さ - 空リポジトリ時のみ、グローバル `python-project-bootstrap` を初回1回だけ使う運用でよいですか。 - 生成後は `/docs/ai/canonical/playbooks/` を正本に固定してよいですか。 +### ラウンド5（プロダクト方針） + +- 開発開始前に `docs/product/vision.md` の対象ユーザー・課題・成功状態を確定してよいですか。 +- `docs/product/goals.md` は期限ではなく「ユーザー到達状態」で定義してよいですか。 +- `docs/product/progress.md` は `%` ではなく「やるべきこと一覧（完了済み/未完了/現在地）」で運用してよいですか。 + ## AGENTS.md 反映チェック - 「参照すべきドキュメント」が相対パスで明示されている。 @@ -85,3 +96,4 @@ AGENTS.md はエージェントの行動境界を固定する「常時参照さ - 長いコマンド列は AGENTS.md ではなく Playbook に配置されている。 - 共有必須 Playbook の配置方針（repo 配下優先）が記載されている。 - 「初回のみグローバル、以後ローカル正本」の例外ルールが記載されている。 +- `docs/product/*.md` の初期確定方針が記載されている。 diff --git a/docs/ai/playbook-assets/python-project-bootstrap/references/product-docs-alignment.md b/docs/ai/playbook-assets/python-project-bootstrap/references/product-docs-alignment.md new file mode 100644 index 0000000..bf455bc --- /dev/null +++ b/docs/ai/playbook-assets/python-project-bootstrap/references/product-docs-alignment.md @@ -0,0 +1,46 @@ +# docs/product 擦り合わせテンプレート + +## 目的 + +テンプレート利用開始時に `docs/product/*.md` を空欄のままにせず、 +「何を目指すか」「何を完了条件にするか」「現在地をどう示すか」をユーザーと合意して初期記入する。 + +## 進め方 + +- 質問は 1〜3 問ずつ行う。 +- 回答を要約して合意を取ってから次へ進む。 +- 未確定項目は `仮置き` と明記し、次の確認タイミングを記録する。 + +## ラウンド1（Vision） + +- このプロダクトで最初に価値を届けたい対象ユーザーは誰ですか。 +- そのユーザーのどの課題を最優先で解決しますか。 +- どの状態になれば「Vision が一段達成できた」と判断しますか。 + +反映先: +- `docs/product/vision.md` + +## ラウンド2（Goals / Milestones） + +- ユーザーが到達したい状態を 3〜5 個挙げると何ですか。 +- 各状態について「これが満たされたら達成」と言える判定条件は何ですか。 +- 到達順序（ステップ）をどう並べますか。 + +反映先: +- `docs/product/goals.md` +- `docs/product/milestones.md` + +## ラウンド3（Progress） + +- 各 Goal で「やるべきこと一覧」を 2〜5 項目に分解すると何ですか。 +- いま完了済み / 未完了はどれですか。 +- いまの現在地を一文で表すとどうなりますか。 + +反映先: +- `docs/product/progress.md` + +## 出力チェック + +- `%` 表示に頼らず、やるべきこと一覧ベースで進捗が表現されている。 +- Goal ID / Milestone ID が付与され、タスク設計書と紐づけ可能。 +- README と Playbook の説明が `docs/product/*.md` と矛盾しない。 diff --git a/docs/ai/playbook-assets/task-design-gate/references/_task-design-template.md b/docs/ai/playbook-assets/task-design-gate/references/_task-design-template.md index 5c8b496..3900a29 100644 --- a/docs/ai/playbook-assets/task-design-gate/references/_task-design-template.md +++ b/docs/ai/playbook-assets/task-design-gate/references/_task-design-template.md @@ -29,6 +29,8 @@ - 対象コンポーネント: - 関連: <リンクや関連設計書> - チケット/リンク: +- 関連ゴールID: +- 関連マイルストーンID: ## 0. TL;DR - <目的と結論を3〜5行で要約> diff --git a/docs/ai/playbooks/python-project-bootstrap.md b/docs/ai/playbooks/python-project-bootstrap.md index 565ddca..a8c76d3 100644 --- a/docs/ai/playbooks/python-project-bootstrap.md +++ b/docs/ai/playbooks/python-project-bootstrap.md @@ -1,6 +1,6 @@ --- name: python-project-bootstrap -description: 新しい Python プロジェクトの初期セットアップを標準化するPlaybook。AGENTS.md を対話で確定し、Hexagonal Architecture 前提のディレクトリ、SOLID/DRY ガイド、API/タスク設計ドキュメント、`.env.development`/`.env.production` と dotenvx 暗号化運用を整備するときに使う。CI は必須工程とし、品質ゲート設定は必ず `python-uv-ci-setup` を呼び出して完了させる依頼で適用する。 +description: 新しい Python プロジェクトの初期セットアップを標準化するPlaybook。AGENTS.md と docs/product を対話で確定し、Hexagonal Architecture 前提のディレクトリ、SOLID/DRY ガイド、API/タスク設計ドキュメント、`.env.development`/`.env.production` と dotenvx 暗号化運用を整備するときに使う。CI は必須工程とし、品質ゲート設定は必ず `python-uv-ci-setup` を呼び出して完了させる依頼で適用する。 --- @@ -13,6 +13,7 @@ description: 新しい Python プロジェクトの初期セットアップを ## 実行ルール - AGENTS.md の不明点がある状態で雛形を確定しない。必ず対話で埋める。 +- `docs/product/vision.md` / `docs/product/goals.md` / `docs/product/milestones.md` / `docs/product/progress.md` を空欄のまま放置しない。初期化時に必ずユーザーと擦り合わせる。 - 質問は 1〜3 問ずつ行い、回答を反映して次の質問へ進む。 - CI 設定は必須。必ず `python-uv-ci-setup` を使って完了させる。 - 既存ファイルがある場合は破壊的上書きを避け、差分統合を優先する。 @@ -35,31 +36,43 @@ description: 新しい Python プロジェクトの初期セットアップを - 未確定項目は既定値を勝手に固定せず、ユーザー確認を優先する。 - 既定値を使う場合は「既定値を採用した」と明示してから確定する。 -3. 初期構成を生成する。 +3. プロダクト方針（docs/product）を対話で初期確定する。 +- `docs/ai/playbook-assets/python-project-bootstrap/references/product-docs-alignment.md` を使い、1〜3問ずつ擦り合わせる。 +- 最低限、次を埋める。 + - `docs/product/vision.md`: 対象ユーザー、解く課題、成功状態 + - `docs/product/goals.md`: ユーザー到達状態ゴールと到達判定 + - `docs/product/milestones.md`: 到達ステップ + - `docs/product/progress.md`: やるべきこと一覧ベースの現在地 +- 不確定項目が残る場合は、`仮置き` と明記して次の確認タイミングを残す。 + +4. 初期構成を生成する。 - `scripts/playbooks/python-project-bootstrap/bootstrap_python_project.py` を実行して、ディレクトリと初期ドキュメントを生成する。 - 例: - `python3 scripts/playbooks/python-project-bootstrap/bootstrap_python_project.py --target --project-name --package-name --description ""` - 必要に応じて `--task-design-dir docs/task-designs`（既定）や `--force` を使う。 - 生成後に手順正本を `/docs/ai/canonical/playbooks/` に配置してコミットし、以後の実行基盤を repo ローカルへ固定する。 -4. 生成内容をレビューする。 +5. 生成内容をレビューする。 - `docs/ai/playbook-assets/python-project-bootstrap/references/project-structure.md` を基準に、`adapters/application/domain/ports` の責務分離を確認する。 - `docs/rules/solid/README.md` と `docs/rules/code_architecture/README.md` の導線が AGENTS.md から参照できることを確認する。 - `docs/ai/playbook-assets/python-project-bootstrap/references/env-and-dotenvx.md` を基準に `.env.*` の運用記載が整合しているか確認する。 +- `docs/product/*.md` が生成され、対話で確定した内容が反映されていることを確認する。 -5. CI を必須で設定する。 +6. CI を必須で設定する。 - 生成直後に必ず `python-uv-ci-setup` を呼び出して、`uv` ベースの品質ゲートと GitHub Actions を整備する。 - 本Playbook内で CI 設定を再実装しない（DRY を維持）。 -6. 検証する。 +7. 検証する。 - 生成ファイル一覧を確認する。 - `AGENTS.md` の必須セクションが埋まっていることを確認する。 +- `docs/product/vision.md` / `docs/product/goals.md` / `docs/product/milestones.md` / `docs/product/progress.md` が初期記入されていることを確認する。 - `.env.development` / `.env.production` の整合を確認する。 - CI 設定完了後に `uv run pre-commit install` が実行可能な状態であることを確認する。 -7. 結果を報告する。 +8. 結果を報告する。 - 作成・更新したファイル - 対話で確定した項目 +- `docs/product` で合意した内容（Vision/Goal/Milestone/Progress） - CI 設定の実行結果 - 残課題（手動で埋めるべき値や鍵など） - Playbook 配置先（repo 配下 / 個人グローバル）と採用理由 @@ -68,5 +81,6 @@ description: 新しい Python プロジェクトの初期セットアップを - AGENTS.md ヒアリング項目: `docs/ai/playbook-assets/python-project-bootstrap/references/agents-md-checklist.md` - AGENTS と Playbooks の責務境界: `docs/ai/playbook-assets/python-project-bootstrap/references/agents-playbooks-boundary.md` +- docs/product 擦り合わせ質問: `docs/ai/playbook-assets/python-project-bootstrap/references/product-docs-alignment.md` - Hexagonal 構成と責務: `docs/ai/playbook-assets/python-project-bootstrap/references/project-structure.md` - `.env.*` と dotenvx 暗号化運用: `docs/ai/playbook-assets/python-project-bootstrap/references/env-and-dotenvx.md` diff --git a/docs/ai/playbooks/task-design-gate.md b/docs/ai/playbooks/task-design-gate.md index 6e6d3b2..7763db0 100644 --- a/docs/ai/playbooks/task-design-gate.md +++ b/docs/ai/playbooks/task-design-gate.md @@ -28,6 +28,7 @@ description: 実装前にタスク設計書を作成し、スコープ・前提 ## 出力ルール - `docs/ai/playbook-assets/task-design-gate/references/_task-design-template.md` の見出し順を厳守して Markdown で出力する。 +- タスク設計書のメタデータには、`関連ゴールID` と `関連マイルストーンID` を必ず記載する。 - 各セクションはリポジトリ固有の具体内容で記載し、一般論を避ける。 - ファイルは必ず明示的なパスで列挙する。 - 少なくとも 1 つ以上のリスクと検証手順を含める。 diff --git a/docs/product/goals.md b/docs/product/goals.md new file mode 100644 index 0000000..0ff0af0 --- /dev/null +++ b/docs/product/goals.md @@ -0,0 +1,17 @@ +# ユーザー到達状態ゴール + +最終更新: + +## ゴール一覧 + +| Goal ID | ユーザーが到達したい状態 | 到達判定（Definition of Done） | 状態 | +| --- | --- | --- | --- | +| G-01 | <到達状態1> | <判定条件1> | Planned | +| G-02 | <到達状態2> | <判定条件2> | Planned | +| G-03 | <到達状態3> | <判定条件3> | Planned | + +## 運用ルール + +- ゴールは 3〜5 個に絞る。 +- 各ゴールは必ず「ユーザーが到達したい状態」で書く。 +- 各ゴールに `到達判定（Definition of Done）` を 1 つ以上持たせる。 diff --git a/docs/product/milestones.md b/docs/product/milestones.md new file mode 100644 index 0000000..ef3f472 --- /dev/null +++ b/docs/product/milestones.md @@ -0,0 +1,17 @@ +# 到達ステップ + +最終更新: + +## ステップ一覧 + +| Milestone ID | 対応 Goal ID | 到達ステップ | 完了条件 | 状態 | +| --- | --- | --- | --- | --- | +| M-01 | G-01 | <ステップ1> | <完了条件1> | Planned | +| M-02 | G-02 | <ステップ2> | <完了条件2> | Planned | +| M-03 | G-03 | <ステップ3> | <完了条件3> | Planned | + +## 運用ルール + +- マイルストーンは時期ではなく「到達ステップ」として管理する。 +- 各マイルストーンは必ず Goal ID に紐づける。 +- 完了したマイルストーンは削除せず、状態を `Done` に更新して履歴を残す。 diff --git a/docs/product/progress.md b/docs/product/progress.md new file mode 100644 index 0000000..70e3106 --- /dev/null +++ b/docs/product/progress.md @@ -0,0 +1,25 @@ +# 進捗スコアボード + +最終更新: + +## 更新ルール + +- 更新頻度: 状態変化があったタイミングで更新する。 +- 更新者: 該当 Goal に紐づくタスク設計を更新した担当者。 +- 記載単位: Goal ID 単位。 +- 進捗表示: `%` は使わず、「やるべきこと一覧」「完了済み」「未完了」「現在地」で記録する。 + +## Goal別進捗 + +### G-01: <ゴール名> + +**やるべきこと一覧** + +| Item ID | やるべきこと | 状態 | 根拠 | +| --- | --- | --- | --- | +| G01-I01 | <やるべきこと1> | Planned | <関連ファイル/リンク> | +| G01-I02 | <やるべきこと2> | Planned | <関連ファイル/リンク> | + +- 完了済み: +- 未完了: +- 現在地: <現状を1文で記述> diff --git a/docs/product/vision.md b/docs/product/vision.md new file mode 100644 index 0000000..57e674b --- /dev/null +++ b/docs/product/vision.md @@ -0,0 +1,36 @@ +# プロダクトビジョン + +最終更新: + +## 1. Vision Statement + +<このプロダクトが最終的に実現したい状態を1〜2文で記述する。> + +## 2. 対象ユーザー + +- <最優先ユーザー1> +- <最優先ユーザー2> + +## 3. 解決する課題 + +- <課題1> +- <課題2> + +## 4. 提供価値 + +- <価値1> +- <価値2> + +## 5. 成功状態 + +- <どの状態になれば「価値提供できた」と判断するか> + +## 6. Vision の再設定ルール + +- <どの条件で Vision を見直すか> + +## 7. 関連ドキュメント + +- ユーザー到達状態ゴール: `docs/product/goals.md` +- 到達ステップ: `docs/product/milestones.md` +- 現在地スコアボード: `docs/product/progress.md` diff --git a/docs/task-designs/20260208194941_dotenvx-operation-guideline-enhancement.md b/docs/task-designs/20260208194941_dotenvx-operation-guideline-enhancement.md deleted file mode 100644 index bd27218..0000000 --- a/docs/task-designs/20260208194941_dotenvx-operation-guideline-enhancement.md +++ /dev/null @@ -1,136 +0,0 @@ -# タスク設計書: dotenvx 運用ガイドの解像度向上 - -最終更新: 2026-02-08 -- ステータス: 完了(done) -- 作成者: Codex -- レビュー: shogohasegawa -- 対象コンポーネント: docs / scripts -- 関連: docs/ai/playbook-assets/python-project-bootstrap/references/env-and-dotenvx.md -- チケット/リンク: 該当なし - -## 0. TL;DR -- 現在の dotenvx 記載は方針レベルに留まり、実際の運用フロー（暗号化、実行、追加、平文混在）が十分に示せていない。 -- あなたが提示した運用イメージを基準に、Playbook asset を手順レベルへ拡張する。 -- AGENTS 側は詳細手順を持たない方針を維持しつつ、参照導線を明確化する。 -- dotenvx 運用を標準とするため、プロジェクト初期化時の `.env.example` 自動生成を廃止する。 - -## 1. 背景 / 課題 -- 現行は「dotenvx で encrypted: 管理」「.env.keys はコミットしない」が中心で、日常運用コマンドが不足している。 -- 特に以下の実務判断の説明不足がある。 - - 環境ごとの暗号化手順（`.env.development` / `.env.production`） - - `dotenvx run -f` での実行方法 - - 新規秘密値の追加時に `dotenvx set` を使う流れ - - 平文（非機密）と暗号文の混在可否 -- `.env.keys` の取り扱いは「コミット禁止」だけでは不十分で、共有チャネルの注意点が明文化されていない。 -- `python-project-bootstrap` は `.env.example` を自動生成しており、dotenvx 前提運用と役割が重複している。 - -## 2. ゴール / 非ゴール -### 2.1 ゴール -- `env-and-dotenvx.md` を、初期化から日常運用まで辿れる手順書に更新する。 -- 「何をコミットして良いか / だめか」を明示する。 -- 平文と暗号文の混在運用（`encrypted:` プレフィックスで識別）を明記する。 -- bootstrap 生成物から `.env.example` を外し、Playbook 記述と整合させる。 - -### 2.2 非ゴール -- dotenvx 自体の検証コード追加や CI 実装変更。 -- 既存プロジェクトの `.env.*` 内容変更。 -- 秘密情報管理基盤（Vault/1Password等）の導入判断。 - -## 3. スコープ / 影響範囲 -- 変更対象: dotenvx 運用ドキュメントと bootstrap 生成スクリプト。 -- 影響範囲: 今後このテンプレートを使うチームの環境変数運用手順と初期生成物。 -- 互換性: `.env.example` が自動生成されなくなる（方針に沿った仕様変更）。 -- 依存関係: `scripts/sync_ai_context.py`（canonical 更新時のみ）。 - -## 4. 要件 -### 4.1 機能要件 -- dotenvx インストール確認、暗号化、実行、追加の各コマンド例を記載する。 -- `.env.development` / `.env.production` / `.env.keys` の責務を明確化する。 -- 「暗号化対象（秘密情報）」と「平文許容対象（非機密）」の判断基準を明記する。 -- `.env.keys` の共有は安全な私的チャネルのみ可とし、Issue/PR/チャット本文へ貼らないことを明記する。 -- プロジェクト初期化時に `.env.example` を生成しない方針へ変更する。 - -### 4.2 非機能要件 / 制約 -- AGENTS.md には詳細手順を重複記載しない（責務分離維持）。 -- 例示値は必ずダミーを使用し、秘密値を含めない。 -- 既存の canonical → generated の同期フローを維持する。 - -## 5. 仕様 / 設計 -### 5.1 全体方針 -- 詳細手順は `docs/ai/playbook-assets/python-project-bootstrap/references/env-and-dotenvx.md` に集約する。 -- `python-project-bootstrap` の canonical/生成物/スクリプトから `.env.example` 前提を除去する。 - -### 5.2 変更点一覧 -| 対象 | 変更内容 | 影響 | 備考 | -| --- | --- | --- | --- | -| `docs/ai/playbook-assets/python-project-bootstrap/references/env-and-dotenvx.md` | 手順を実運用レベルに拡張（暗号化/実行/追加/混在運用/共有注意） | dotenvx 運用の解像度向上 | 主変更 | -| `docs/ai/canonical/playbooks/python-project-bootstrap.md` | 検証項目から `.env.example` 前提を削除 | Playbook と運用方針の整合 | 正本更新 | -| `scripts/playbooks/python-project-bootstrap/bootstrap_python_project.py` | `.env.example` 自動生成を削除 | 新規構築時の生成物が方針準拠 | スクリプト更新 | -| `docs/ai/playbooks/python-project-bootstrap.md` | canonical 反映で自動更新 | 参照用 Playbook の同期 | 直接編集しない | - -### 5.3 詳細 -#### API -- 該当なし。 - -#### UI -- 該当なし。 - -#### データモデル / 永続化 -- 該当なし。 - -#### 設定 / 環境変数 -- `.env.development` / `.env.production`: 暗号化済み秘密値 + 必要に応じて非機密平文を保持。 -- `.env.keys`: 秘密鍵を保持し、Git 管理外。 -- `.env.example`: 本運用では原則非採用（必要な場合のみ手動で仕様書として作成）。 - -### 5.4 代替案と不採用理由 -- 代替案A: AGENTS.md に詳細手順を直接追加する。 - - 不採用理由: README/AGENTS/Playbook の責務分離に反する。 -- 代替案B: `.env.example` を残し続ける。 - - 不採用理由: dotenvx 前提運用では重複管理になり、更新漏れを招く。 - -## 6. 移行 / ロールアウト -- ドキュメント更新後、`python3 scripts/sync_ai_context.py` で生成物を同期する。 -- ロールバック条件: 既存方針と矛盾する記載や過度な運用負荷が判明した場合。 -- ロールバック手順: 変更差分を戻し、同期チェックが通る状態へ戻す。 - -## 7. テスト計画 -- 単体: 記載コマンド・ファイル名が一貫していることを静的レビューで確認。 -- 結合: `python3 scripts/sync_ai_context.py --check` を実行。 -- 手動: `env-and-dotenvx.md` だけ読んで初期化〜追加運用まで手順が追えることを確認。 -- LLM/外部依存: 該当なし。 -- 合格条件: 主要運用シナリオ（暗号化、実行、追加、混在、共有注意）が明確に記載され、`.env.example` 非生成が反映されている。 - -## 8. 受け入れ基準 -- dotenvx の基本フローがコピペ可能なコマンドで示されている。 -- `.env.keys` をコミットしないだけでなく、共有時の注意が明記されている。 -- 暗号文と平文の混在運用のルールが明記されている。 -- bootstrap 実装と Playbook 記載から `.env.example` の自動生成前提が除去されている。 - -## 9. リスク / 対策 -- リスク: 「.env.keys をチーム共有可」を誤って広いチャネルで運用して漏えいする。 -- 対策: 共有可否ではなく「共有チャネル制約（安全な私的チャネルのみ）」を明記する。 - -## 10. オープン事項 / 要確認 -- 該当なし。 - -## 11. 実装タスクリスト -- [x] `env-and-dotenvx.md` を手順レベルへ更新する。 -- [x] `python-project-bootstrap` 正本から `.env.example` 前提を除去する。 -- [x] bootstrap から `.env.example` 自動生成を削除する。 -- [x] `sync_ai_context.py` 実行/チェックを実施する。 - -## 12. ドキュメント更新 -- [ ] `README.md`（必要に応じて） -- [ ] `AGENTS.md`（必要に応じて） -- [x] `docs/`（該当ファイルあれば） - -## 13. 承認ログ -- 承認者: shogohasegawa -- 承認日時: 2026-02-08 19:52 -- 承認コメント: OK.承認 - -## 実装開始条件 -- [x] ステータスが `承認済み(approved)` である -- [x] 10. オープン事項が空である -- [x] 受け入れ基準とテスト計画に合意済み diff --git a/scripts/playbooks/python-project-bootstrap/bootstrap_python_project.py b/scripts/playbooks/python-project-bootstrap/bootstrap_python_project.py index 5c3e0f4..bfbe3ce 100755 --- a/scripts/playbooks/python-project-bootstrap/bootstrap_python_project.py +++ b/scripts/playbooks/python-project-bootstrap/bootstrap_python_project.py @@ -150,6 +150,11 @@ def build_agents_md( - タスク設計テンプレート: `{task_template}` - APIテンプレート: `docs/api/_endpoint_template.md` - API一覧: `docs/api/index.md` +- プロダクト方針: + - `docs/product/vision.md` + - `docs/product/goals.md` + - `docs/product/milestones.md` + - `docs/product/progress.md` ## Task Design Gate (Mandatory) @@ -160,6 +165,7 @@ def build_agents_md( - 設計書に未解消のオープン事項がある間は実装を開始しない。 - 実装ファイルの編集は、設計書に対するユーザーの明示承認後にのみ許可する。 - 実装中にスコープ変更が発生した場合、実装を停止して設計書を更新し、再承認を取得する。 +- 新規プロダクト開発の開始前に、`docs/product/*.md` をユーザーと擦り合わせて初期確定する。 ## Playbook運用ルール @@ -346,6 +352,121 @@ def build_hexagonal_architecture_doc(package_name: str) -> str: """ +def build_product_vision_template() -> str: + """プロダクトビジョンの初期テンプレートを返す。""" + return """# プロダクトビジョン + +最終更新: + +## 1. Vision Statement + +<このプロダクトが最終的に実現したい状態を1〜2文で記述する。> + +## 2. 対象ユーザー + +- <最優先ユーザー1> +- <最優先ユーザー2> + +## 3. 解決する課題 + +- <課題1> +- <課題2> + +## 4. 提供価値 + +- <価値1> +- <価値2> + +## 5. 成功状態 + +- <どの状態になれば「価値提供できた」と判断するか> + +## 6. Vision の再設定ルール + +- <どの条件で Vision を見直すか> + +## 7. 関連ドキュメント + +- ユーザー到達状態ゴール: `docs/product/goals.md` +- 到達ステップ: `docs/product/milestones.md` +- 現在地スコアボード: `docs/product/progress.md` +""" + + +def build_product_goals_template() -> str: + """ユーザー到達状態ゴールの初期テンプレートを返す。""" + return """# ユーザー到達状態ゴール + +最終更新: + +## ゴール一覧 + +| Goal ID | ユーザーが到達したい状態 | 到達判定（Definition of Done） | 状態 | +| --- | --- | --- | --- | +| G-01 | <到達状態1> | <判定条件1> | Planned | +| G-02 | <到達状態2> | <判定条件2> | Planned | +| G-03 | <到達状態3> | <判定条件3> | Planned | + +## 運用ルール + +- ゴールは 3〜5 個に絞る。 +- 各ゴールは必ず「ユーザーが到達したい状態」で書く。 +- 各ゴールに `到達判定（Definition of Done）` を 1 つ以上持たせる。 +""" + + +def build_product_milestones_template() -> str: + """到達ステップの初期テンプレートを返す。""" + return """# 到達ステップ + +最終更新: + +## ステップ一覧 + +| Milestone ID | 対応 Goal ID | 到達ステップ | 完了条件 | 状態 | +| --- | --- | --- | --- | --- | +| M-01 | G-01 | <ステップ1> | <完了条件1> | Planned | +| M-02 | G-02 | <ステップ2> | <完了条件2> | Planned | +| M-03 | G-03 | <ステップ3> | <完了条件3> | Planned | + +## 運用ルール + +- マイルストーンは時期ではなく「到達ステップ」として管理する。 +- 各マイルストーンは必ず Goal ID に紐づける。 +- 完了したマイルストーンは削除せず、状態を `Done` に更新して履歴を残す。 +""" + + +def build_product_progress_template() -> str: + """進捗スコアボードの初期テンプレートを返す。""" + return """# 進捗スコアボード + +最終更新: + +## 更新ルール + +- 更新頻度: 状態変化があったタイミングで更新する。 +- 更新者: 該当 Goal に紐づくタスク設計を更新した担当者。 +- 記載単位: Goal ID 単位。 +- 進捗表示: `%` は使わず、「やるべきこと一覧」「完了済み」「未完了」「現在地」で記録する。 + +## Goal別進捗 + +### G-01: <ゴール名> + +**やるべきこと一覧** + +| Item ID | やるべきこと | 状態 | 根拠 | +| --- | --- | --- | --- | +| G01-I01 | <やるべきこと1> | Planned | <関連ファイル/リンク> | +| G01-I02 | <やるべきこと2> | Planned | <関連ファイル/リンク> | + +- 完了済み: +- 未完了: +- 現在地: <現状を1文で記述> +""" + + def build_task_readme(task_design_dir: str) -> str: """タスク設計ディレクトリ README を返す。""" return f"""# タスク設計書の保存先 @@ -394,6 +515,8 @@ def build_task_template() -> str: - 対象コンポーネント: - 関連: <リンクや関連設計書> - チケット/リンク: +- 関連ゴールID: +- 関連マイルストーンID: ## 0. TL;DR - <目的と結論を3〜5行で要約> @@ -736,6 +859,7 @@ def main() -> None: target / "docs" / "rules" / "code_architecture", target / "docs" / "architecture", target / "docs" / "api", + target / "docs" / "product", target / Path(task_design_dir), ] ensure_directories(directories, report) @@ -754,6 +878,10 @@ def main() -> None: target / Path(task_design_dir) / "_task-design-template.md": build_task_template(), target / "docs" / "api" / "index.md": build_api_index(), target / "docs" / "api" / "_endpoint_template.md": build_api_endpoint_template(), + target / "docs" / "product" / "vision.md": build_product_vision_template(), + target / "docs" / "product" / "goals.md": build_product_goals_template(), + target / "docs" / "product" / "milestones.md": build_product_milestones_template(), + target / "docs" / "product" / "progress.md": build_product_progress_template(), target / ".env.development": build_env_file("development"), target / ".env.production": build_env_file("production"), }