RyoMurakami1983 プロジェクト開発憲法
.github/copilot-instructions.md を「生きたドキュメント」として作成・維持するワークフロー。製品の本質、アーキテクチャ原則、ドメイン設計ルール、UIポリシー、テスト方針、Git規約を記録し、実装中のすべての判断をブレのない基盤に根ざす。
背景: このスキルは rakugaki_writer プロジェクトで copilot-instructions.md を実際に作成した経験から生まれた。核心となる気づき：「明示的なアーキテクチャ基盤なしに実装が加速すると、ドメイン境界が溶けていく」。
こんなときに使う
以下の場面で使います：
- 新しいプロジェクトを立ち上げ、最初のアーキテクチャ決定を行うとき
- 既存プロジェクトのアーキテクチャが曖昧になり、一貫性が失われてきたとき
- 設計意図を理解する必要がある新メンバーが加わるとき
- ふりかえりで「実装の判断がブレていた」と気づいたとき
- AIコーディングエージェントがセッション開始前にグラウンディングコンテキストを必要とするとき
このスキルではないもの: git-initial-setup はGit操作のデフォルト（フック、ブランチ保護）を扱う。このスキルは設計思想のドキュメント化を扱う。
関連スキル
furikaeri-practice— ふりかえりで新しい知見が生まれたとき、憲法更新のトリガーになるgit-initial-setup— Git操作設定（ブランチ保護、フック）git-commit-practices— Step 6で参照するコミット規約github-issue-intake— アーキテクチャ決定をIssueとして記録
依存関係
- プロジェクトルートに
.github/ディレクトリ（なければ作成） - ツール不要 — ドキュメント化ワークフロー
コア原則
- ドメインファースト — 実装開始前にコアドメインを定義する (基礎と型)
- 生きたドキュメント — 追記・修正が基本。ゼロから書き直さない (継続は力)
- 暗黙知より形式知 — 結果だけでなく、決断とその理由を記録する (温故知新)
- AIが読める形式 — AIコーディングエージェントがグラウンディングコンテキストとして使える書き方で (余白の設計)
- 最小の儀式 — 1ファイル、プレーンMarkdown。ツールのオーバーヘッドを避ける (ニュートラル)
ワークフロー: 開発憲法を作る
Step 1: 製品本質を定義する
「このプロジェクトは誰のために何を解決するか」を1〜3文で書く。
3つの必須要素：
| 要素 | 問い | 例 |
|---|---|---|
| Who | ターゲットユーザー | 集中して書きたいソロライター |
| What problem | 解決する痛み | ツールバー操作で思考が途切れる |
| Core value | 削れない核の価値 | エディタが消える——文章だけが残る |
## 製品本質 / Product Essence
- **Who**: オフラインファーストで集中執筆したいソロライター
- **What problem**: モード切り替えとツールバー操作が創造的フローを断ち切る
- **Core value**: エディタが邪魔をしない——書くことだけに集中できる
これがすべての機能判断の北極星になる。この核心価値に矛盾する機能提案は、別のプロダクトの話だ。
新規プロジェクト開始時、またはステークホルダーがフィーチャー優先度で議論するとき。
Values: 基礎と型 / ニュートラル
Step 2: アーキテクチャ方針を記録する
採用したアーキテクチャパターン、レイヤー構造、依存方向のルールを記録する。
必須要素：
- レイヤー構造（例：DDD: domain / application / infrastructure / presentation）
- 依存方向のルール（例：「UIはドメインに依存する。逆は禁止」）
- 技術スタックと選定理由（なぜこのスタックか、何かだけでなく）
## アーキテクチャ方針 / Architecture Principles
### レイヤー構造
- `domain/` — Entity・ValueObject・UseCase・Repositoryインターフェース（ポート）
- `application/` — オーケストレーション、コマンド/クエリハンドラ
- `infrastructure/` — ファイルシステム、OS API、外部ストレージ（アダプタ）
- `presentation/` — UIコンポーネント、状態バインディング
### 依存方向
- 依存方向: presentation → application → domain ← infrastructure（逆は禁止）
- domainはUIフレームワーク・ファイルシステム・ネットワークを一切知らない
- infrastructureはdomainのインターフェース（ポート）を実装する。定義はしない
### 技術スタック
- **Tauri + Rust** — クロスプラットフォームネイティブランタイム。Electronオーバーヘッドなしのオフラインファースト
- **React + TypeScript** — 強い型安全性を持つコンポーネントモデル
- **Vite** — 高速な開発イテレーション、最小限の設定
新規プロジェクト設定時、またはチームメンバーが「このコードはどこに置く？」と聞いたとき。
Values: 基礎と型 / 温故知新
Step 3: コアドメイン先行チェックリスト
新機能を始める前に必ず確認する5項目のチェックリスト。最も多い判断ブレ——ドメインモデルが明確になる前にUIを作り始める——を防ぐ。
## コアドメイン先行チェックリスト / Domain-First Checklist
新機能追加前に確認:
- [ ] ドメインモデルの変更を特定した（Entity / ValueObject / UseCase）
- [ ] ドメイン層から実装を始める——UIから始めていない
- [ ] ポート（インターフェース）を先に定義した
- [ ] ドメイン層のテストを先に書く
- [ ] インフラ依存（ファイルシステム / DB / OS API）がdomainに漏れていない
なぜ重要か: UIから始めるのは自然だ——見えるし、具体的だから。しかしUIファーストの開発はドメインに偶発的複雑さを埋め込む。チェックリストは、各機能の前に意図的な立ち止まりの瞬間を作る。
すべての新機能・ストーリー・重要なバグ修正の前に。
Values: 基礎と型 / 余白の設計
Step 4: UIポリシーを明文化する
UI設計の決断を個人の好みではなくポリシーとして記録する。将来のコントリビューター（人間とAI両方）が何が意図的かを知る必要がある。
必須要素：
- インスピレーション / デザイン参照 — 目指す美的ターゲット
- 明示的な禁止事項 — 作ってはいけないもの（作るべきものと同じくらい重要）
- アクセシビリティのコミットメント — 最低限のアクセシビリティ方針
## UIポリシー / UI Policy
### デザイン方向
- Notionインスパイア: 最小ヘッダー、コンテキスト依存ツールバー、コンテンツキャンバスへの集中
- シングルサーフェスエディタ: 日常操作にモーダルダイアログを使わない
### 禁止事項
- ヘッダーツールバーにモードボタンを詰め込まない
- テキスト未選択時にフォーマットコントロールを表示しない
- ユーザーの明示的なオプトインなしに永続サイドバーを追加しない
### アクセシビリティ
- すべての主要操作にキーボードナビゲーション必須
- 十分なカラーコントラスト（WCAG AA最低限）
- アイコンのみのボタンにはすべてスクリーンリーダー用ラベル
UIコンポーネント実装時、またはUI関連PRのレビュー時。
Values: 基礎と型 / ニュートラル
Step 5: テスト方針を明文化する
最初のテストを書く前にテスト原則を確立する。一貫性のないテスト哲学は時間とともに複利で悪化する。
必須要素：
- 戦略 — TDD / BDD / After（デフォルトを1つ選ぶ）
- 優先順位 — どのレイヤーを最初にテストするか
- モック方針 — モックが許可 / 禁止の条件
- ファイル配置 — テストファイルの場所の規約
## テスト方針 / Test Strategy
### 戦略
domainとapplicationレイヤーはTDD。infrastructureアダプタは結合テスト。
### 優先順位
1. domainレイヤー（純粋なビジネスロジック——モック不要）
2. applicationレイヤー（ユースケースオーケストレーション——domainポートをモック）
3. infrastructureレイヤー（アダプタ契約——実依存でテスト）
4. UIレイヤー（インタラクションテスト——実装ではなくユーザーワークフローに集中）
### モック方針
- domainレイヤー: モック禁止。モックが必要なら依存はinfrastructureに属する。
- applicationレイヤー: domainポート（インターフェース）のみモック可。
- infrastructureレイヤー: アダプタテストには実実装を使う。
### ファイル配置
- ユニットテスト: ソースと同置（`*.test.ts`）
- 結合テスト: `tests/integration/`
- E2Eテスト: `tests/e2e/`
プロジェクト設定時、またはポリシーに違反するテストパターンを導入するPRのレビュー時。
Values: 基礎と型 / 継続は力
Step 6: Git・コーディング規約
コミット形式、ブランチ戦略、言語固有のスタイルルールを記録する。git-commit-practices と整合させること。
## Git・コーディング規約 / Git and Coding Conventions
### コミット形式（Conventional Commits）
- `feat:` — 新機能
- `fix:` — バグ修正
- `refactor:` — 振る舞いの変更なし
- `test:` — テストの追加・修正
- `docs:` — ドキュメントのみ
- `chore:` — ツール、依存関係
### ブランチ戦略
- `main` — 本番相当。保護済み（直接プッシュ禁止）
- `feat/<issue番号>-<短い説明>` — フィーチャーブランチ
- `fix/<issue番号>-<短い説明>` — バグ修正ブランチ
### コーディングスタイル
- TypeScript strictモード有効
- コメントによる明示的な正当化なしに `any` を使わない
- domainロジックは純粋関数。副作用はinfrastructure/presentationのみ
- Rust: `clippy` デフォルトに従う。本番パスで `unwrap()` を使わない
Values: 継続は力 / 基礎と型
Step 7: 更新タイミングの指針
開発憲法は生きたドキュメント。いつ更新するかを定義する。
更新トリガー:
| トリガー | アクション |
|---|---|
ふりかえりで新しい知見が生まれた（furikaeri-practice Step 5） |
該当セクションに1行追記 |
| アーキテクチャ決定を行った | Step 2に理由付きで記録 |
| 判断パターンを3回以上適用した | 明示的なルールとして昇格させる |
| 新メンバーが「なぜこうしたの？」と聞いた | 答えを憲法に追記する |
更新の規律:
- 追記・修正が基本 — ゼロから書き直さない
- 重要な変更は更新ログに日付を記録
- 毎PR更新しない — 決断が定着したと確認できたときに更新
スプリント終了時、furikaeri-practice セッション完了時、またはADR（アーキテクチャ決定レコード）記録時。
Values: 継続は力 / 温故知新 / 成長の複利
よくある失敗
実装後に憲法を書く 対策: Steps 1–3が完了するまで実装をブロックする。憲法はドメインモデルを守るためのもの——UIを守るためではない。
抽象的すぎてアクション不可能 対策: 各セクションに必ず具体的な禁止事項または具体的な例を含める。曖昧な原則（「シンプルに保つ」）は制約にならない。
作成後に一度も更新されない 対策:
furikaeri-practiceStep 5のSkill-izationチェックに憲法レビューをデフォルトで追加する。知見が表面化したら文書を更新する。テンプレートをカスタマイズせずにコピーする 対策: Step 1（製品本質）は必須。どのプロジェクトにも当てはまる汎用的な「北極星」は、どのプロジェクトにも当てはまらない。
READMEと混同する 対策: READMEはユーザーとコントリビューター向け。憲法はAIエージェントと設計決定追跡のためのもの。別ファイルに保つ。
アンチパターン
- 憲法を一度きりの作業として書いてアーカイブする
- 理由なしに制約ドキュメントとして使う（「Xはできない」だけで理由がない）
- すべてのコーディングスタイル好みを追加する（それはlint設定に属する）
- AIエージェントに憲法を生成させてStep 1のヒューマンレビューをスキップする
クイックリファレンス
開発憲法テンプレート
# 開発憲法 / Development Constitution
## 製品本質 / Product Essence
<!-- Who: -->
<!-- What problem: -->
<!-- Core value: -->
## アーキテクチャ方針 / Architecture Principles
<!-- レイヤー構造: -->
<!-- 依存方向のルール: -->
<!-- 技術スタック + 選定理由: -->
## コアドメイン先行チェックリスト / Domain-First Checklist
新機能追加前に確認:
- [ ] ドメインモデルの変更を特定した（Entity / ValueObject / UseCase）
- [ ] ドメイン層から実装を始める——UIから始めていない
- [ ] ポート（インターフェース）を先に定義した
- [ ] ドメイン層のテストを先に書く
- [ ] インフラ依存をdomainに入れない
## UIポリシー / UI Policy
<!-- デザイン方向 / インスピレーション: -->
<!-- 禁止事項: -->
<!-- アクセシビリティ: -->
## テスト方針 / Test Strategy
<!-- 戦略（TDD/BDD/After）: -->
<!-- 優先順位: -->
<!-- モック方針: -->
<!-- ファイル配置: -->
## Git・コーディング規約 / Git and Coding Conventions
<!-- コミット形式: -->
<!-- ブランチ戦略: -->
<!-- 言語固有スタイル: -->
## 更新ログ / Update Log
- YYYY-MM-DD: 開発憲法を初回作成
Stepサマリー
| Step | 成果物 | スキップの条件 |
|---|---|---|
| 1 製品本質 | 1〜3文の北極星 | なし——すべてのプロジェクトで必須 |
| 2 アーキテクチャ方針 | レイヤー図 + 依存ルール | アーキテクチャ意図のないプロトタイプ |
| 3 コアドメイン先行チェックリスト | 機能前5項目ゲート | ドメインモデルのないプロジェクト |
| 4 UIポリシー | デザイン方向 + 禁止事項 | 非UIプロジェクト |
| 5 テスト方針 | 戦略 + 優先順位 + モック方針 | スパイク / 捨てるプロトタイプ |
| 6 Git規約 | コミット形式 + ブランチ戦略 | ソロ・PRなしワークフロー |
| 7 更新タイミング | トリガー + 規律 | なし——常に維持する |
判断テーブル
| 状況 | アクション |
|---|---|
| 新規プロジェクト、初日 | 実装コードを書く前にSteps 1–6を完了する |
| 既存プロジェクト、アーキテクチャが漂流中 | Steps 1–3を完了。ポリシーが存在すればSteps 4–6はスキム |
| 新メンバー参加 | 憲法ファイルを共有。Step 1を一緒に歩む |
| ふりかえりで設計に関する知見が出た | Step 7経由で該当セクションを更新 |
| AIエージェントが新セッション開始 | .github/copilot-instructions.md をグラウンディングとして指示 |
参考文献
- Eric Evans, Domain-Driven Design — Steps 2–3のベース読書
- Michael Feathers, Working Effectively with Legacy Code — ドメイン分離の動機
- Conventional Commits — Step 6のコミット形式
furikaeri-practice— Step 7の更新サイクルのトリガーgit-commit-practices— Step 6と整合する詳細なコミットワークフロー