domain-context

段階的ドメイン結晶化（PDC）スキル

このスキルでできること

このスキルを使うと、AI アシスタントはあらゆる業務アプリケーションに対応する常に更新されるドメインナレッジベースを構築し、利用できます。人間と AI が協働するプロトコルを通じて、セッションを重ねながら少しずつ蓄積していきます。

AI は、初期状態ではそのドメインについて「知っている」わけではありません。しかし、このスキルを使えば、次のことができます。

• 各セッションの開始時に、構造化された .tasks/domain.md ファイルを読み込む
• 業務で定義された社内用語やエンティティ名を、正確に使用する
• 作業中にドメイン理解の不足をその場で示す
• 人間が確認できるよう、ドメインファイルへの構造化された追加内容を提案する
• ナレッジベースを損なわない。更新はすべて提案として行い、自動では適用しない
• 段階的開示によってドメイン知識の増加を管理し、現在のセッションに関係する内容だけを読み込む

---

基本プロトコル

セッション開始時

1. プロジェクトのルートに .tasks/domain.md があるか確認します。
2. 見つかった場合 → ファイル構成を確認します。
   • 単一ファイル（約 200 行未満）：作業を始める前に、全体を読み込みます。
   • インデックス＋詳細ファイル（分割構成）：ルートにある .tasks/domain.md のインデックス（Tier 1 — コアコンテキスト）を読み込みます。次に、現在のタスクに関係する Tier 2 の詳細ファイルを判断し、該当するものだけを読み込みます。「段階的開示」を参照してください。
3. 見つからない場合 → .tasks/domain.md にあるテンプレートを使って初期化することを提案します。
4. ユーザーに次のように確認します。「[Project Name] のドメインコンテキストを読み込みました。[N] 個のエンティティと [N] 個のフローを把握しています。」分割モードの場合は、さらに次のように伝えます。「コアコンテキストを読み込みました。作業内容に応じて、必要な詳細ファイルを読み込みます。」

作業中

• エンティティ名、用語、略語は、.tasks/domain.md で定義されたとおりに正確に使用します。
• 未定義の用語やエンティティに遭遇した場合、その場で [UNKNOWN: <term>] と記します。
• エンティティ間の関係が不明確な場合、[RELATIONSHIP UNCLEAR: <entity-a> → <entity-b>] と記します。
• 文書化されていないものの、業務ルールが存在すると考えられる場合は、[RULE INFERRED: <description>] と記します。
• ドメインの事実を作り出さず、文書化された内容、またはセッション中にユーザーが確認した内容のみを使用します。
• 特定のエンティティまたはフローに取り組む際、対応する Tier 2 の詳細ファイルがあり、まだ読み込まれていない場合は読み込みます。

セッション終了時

最終回答の末尾に、必ず ## 📋 Proposed Domain Updates セクションを生成します。

次の形式にします。

## 📋 Proposed Domain Updates

> Review these and copy any confirmed items into your .tasks/domain.md

### New Entities Discovered
- **[EntityName]**: [Definition as understood from this session]
  - Attributes: [list]
  - Related to: [other entities]

### Terminology Clarified
- `[term]` → [plain definition]

### Relationships Identified
- [Entity A] → [verb] → [Entity B]: [description]

### Business Rules Observed
- [Rule description]

### Open Questions
- [ ] [Question about something ambiguous or unresolved]

### Suggested .tasks/domain.md Sections to Add/Update
- [ ] [specific section or entry to update]

人間が内容を確認して必要に応じて編集し、.tasks/domain.md を手動で更新します。これにより、人間がドメインの権威者としての役割を保てます。

---

段階的開示

ドメイン知識ファイルは時間とともに増えていきます。80 行で使いやすかった単一の .tasks/domain.md も、400 行になると扱いづらくなります。段階的開示を使えば、ナレッジベース全体を参照できる状態を保ちながら、現在のセッションに関係する情報に AI の注意を集中させられます。

ドメイン知識の 3 つの階層

階層	内容	読み込むタイミング	典型的なサイズ
Tier 1 — コア	プロジェクト概要、用語集、エンティティ名（1 行の説明のみ）、業務ルールの表、ユーザーロールの表	セッション開始時に常に	80–120 行
Tier 2 — 作業コンテキスト	エンティティの詳しい説明（ライフサイクル、メモ、エッジケース）、フローの全手順、関係性マップ、統合ポイント	セッションで対象のエンティティやフローを扱うときに必要に応じて	ファイルあたり 30–80 行
Tier 3 — アーカイブ	変更履歴、解決済みの未解決事項、データ移行に関するメモ、ベンダー固有の詳細	明示的な要求があったとき、またはプロジェクト履歴を確認するとき	可変

各階層に含める内容

Tier 1 — コア（ルートの .tasks/domain.md、常に読み込み）：

• ## Project Overview — どのようなプロジェクトか、誰が使用するか、ビジネス上の目標（5行）
• ## Domain Boundaries — 対象範囲、補助的な範囲、明示的に除外する範囲。過剰な構築を防ぎます。
• ## Terminology Glossary — 略語の一覧表
• ## Entity Registry — 名前と1行の説明のみ（属性の完全な一覧、ライフサイクルの詳細、注記は含めません）。エンティティの目次として考えてください。
• ## State Models — ステータスやライフサイクル段階を持つエンティティについて、名前付きの列挙値と有効な状態遷移を記載します。AI はこれらを唯一の有効な値として扱う必要があります。
• ## Business Rules — 厳守すべきルールの表（BR-001、BR-002 など）。これらは AI が常に把握しておくべき確かな情報です。
• ## User Roles — ロールの一覧表
• ## Stakeholder Map — 名前、システムとの関係、主な懸念事項、関与させるタイミングを記載します。導入と合意形成に不可欠です。
• ## Open Questions — 現在未解決の項目
• ## Detail Files — Tier 2 ファイルの概要を1行ずつ記載した索引（以下のファイル構成を参照）

Tier 2 — 作業コンテキスト（別ファイル、タスクごとに読み込み）：

• エンティティの完全な仕様 — 属性、ライフサイクル、関係、注記、エッジケース（主要なエンティティごとに1ファイル）
• フローの完全な説明 — 手順ごとのプロセス解説（フローごとに1ファイル）
• 関係マップ — エンティティ間の関係をすべて記載した表
• 統合ポイント — 外部システムの詳細

Tier 3 — アーカイブ（別ファイル、要求に応じて読み込み）：

• 変更履歴 — 学んだ内容のセッションごとの履歴
• 解決済みの質問 — クローズした未解決の質問の履歴
• データ移行に関する注記 — ベンダーカタログの詳細、インポート手順
• ベンダー固有の詳細 — 価格表の構成、ポータルへのアクセスに関する注記

分割するタイミング：約200行のルール

初期段階のプロジェクトでは、単一の .tasks/domain.md が適しています。分割の判断基準はシンプルです。

.tasks/domain.md が約200行を超えたら、分割を提案します。

ユーザーには次のように伝えます。「ドメインファイルの内容がかなり増えてきました。[N] 行、[N] 件のエンティティ、[N] 件のフローがあります。索引ファイルと詳細ファイルに分割しますか？この方法なら、必要な情報を失うことなく、セッションで関連する内容に集中できます。」

ユーザーが同意した場合は、階層化されたファイル構成に再編成します（以下を参照）。単一ファイルのままにしたい場合は、その希望を尊重してください。これは必須条件ではなく、好みの問題です。

セッション開始時の AI による階層の活用方法

1. Read root .tasks/domain.md (Tier 1 — always)
      ↓
2. Understand the current task
      ↓
3. Determine which entities/flows are relevant
      ↓
4. Load only those Tier 2 files
      ↓
5. Work — loading additional Tier 2 files if the task expands
      ↓
6. Propose updates — specifying which file each update belongs to

例：ユーザーが「PM 更新フローを更新したい」と言った場合、AI は次のようにします。

1. ルートの .tasks/domain.md を読み込む（コアコンテキスト — すべてのエンティティ名とビジネスルールを把握）
2. docs/domain/flows/pm-renewal.md を読み込む（関連するフロー）
3. docs/domain/entities/pm-renewal.md を読み込む（関連するエンティティ）
4. docs/domain/flows/lead-distribution.md や docs/domain/entities/customer.md は読み込みません。このタスクには関連しないためです。

分割モードでの更新提案

ドメインが複数のファイルに分割されている場合、「提案するドメインの更新」セクションで、それぞれの更新をどのファイルに記載するか指定します。

## 📋 Proposed Domain Updates

### Update: `.tasks/domain.md` (Tier 1 — core)
- Add to Business Rules: BR-013 — [rule description]

### Update: `docs/domain/entities/pm-renewal.md` (Tier 2)
- Add attribute: `priceAdjustmentPercent` — annual price increase applied on renewal

### New File: `docs/domain/flows/engineering-review.md` (Tier 2)
- [Full flow description to create]

### Update: `docs/domain/archive/changelog.md` (Tier 3)
- [Session summary entry]

バージョン管理

.tasks/domain.md のフロントマターにはバージョンヘッダーが含まれています。これは人が読める形式のバージョンであり、ドメイン知識がどのような状態にあるかを AI とチームに伝えます。

バージョン形式： MAJOR.MINOR

• MAJOR は、基本的な範囲が変わったときに増やします（新しいビジネスプロセス、大規模なエンティティの再構成、ドメイン境界の変更）。
• MINOR は、承認された更新ごとに増やします（新しいエンティティ、新しいルール、フローの調整、ステークホルダーの追加）。

増分する担当者： 承認された更新ごとに、システムが MINOR を自動的に増やします。MAJOR は、チームがドメインを根本的に拡張したと判断したときに、手動で増やします。

バージョンヘッダーは .tasks/domain.md のフロントマターにあります：

> **Version:** 1.5
> **Last updated:** 2026-04-06 (Session 30)
> **Changes:** +Commission Report entity, +BR-013–015, updated Quote-to-Close flow

承認された更新ごとに、AI は次の作業を行う必要があります：

1. バージョン番号を増やす（MINOR +1）
2. 「Last updated」の日付とセッション参照を更新する
3. 「Changes」の行を簡潔な概要で更新する
4. Changelog セクションに項目を追加する

システムで git を使用している場合、コミットメッセージは Changes の行と同じ内容にする必要があります。バージョンヘッダーと git の履歴は、それぞれ異なる対象者向けです。ヘッダーは AI とビジネスユーザー向け、git はエンジニアリング向けです。

---

.tasks/domain.md のファイル構成

完全なテンプレートについては .tasks/domain.md を参照してください。

単一ファイルモード（約 200 行未満）

ファイルでは、次のトップレベルセクションをすべて 1 つのファイルに記述します：

セクション	Tier	目的
## Project Overview	1	アプリの機能、利用者、主な目標
## Domain Boundaries	1	対象範囲、補助的な範囲、対象外の範囲
## Terminology Glossary	1	社内用語と平易な定義の対応付け
## Entity Registry	1（名称）／2（詳細）	属性と説明を含むビジネスオブジェクト
## State Models	1	エンティティの有効なステータス、タイプ、状態遷移
## Relationship Map	2	エンティティ間のつながり
## Flow Catalog	2	情報の流れをステップごとに記載した、名前付きのビジネスプロセス
## Business Rules	1	制約、検証、エッジケース
## Integration Points	2	外部システム、API、データソース
## User Roles	1	システムの利用者と、その利用者が実行できる操作
## Stakeholder Map	1	名前付きの関係者、システムとの関係、懸念事項、関与する時期
## Open Questions	1	未解決の曖昧な点。定期的に確認して解消します
## Changelog	3	学んだ内容とその時期

単一ファイルモードでは、すべての Tier を 1 つのファイルにまとめます。これは問題ありません。Tier のラベルは、将来的な分割の指針となる注釈にすぎません。

分割ファイルモード（約 200 行超）

your-project/
├── .tasks/domain.md                   ← Tier 1: Core index (always loaded)
├── docs/
│   └── domain/
│       ├── entities/                  ← Tier 2: One file per major entity
│       │   ├── quote.md
│       │   ├── customer.md
│       │   ├── product.md
│       │   └── ...
│       ├── flows/                     ← Tier 2: One file per business process
│       │   ├── quote-to-close.md
│       │   ├── pm-renewal.md
│       │   └── ...
│       ├── relationships.md           ← Tier 2: Full relationship map
│       ├── integrations.md            ← Tier 2: External system details
│       └── archive/                   ← Tier 3: Historical records
│           ├── changelog.md
│           └── resolved-questions.md
└── ... (rest of your project)

分割モードのルート .tasks/domain.md には、次の内容を記載します：

• Tier 1 のセクション全体（Project Overview、Domain Boundaries、Glossary、エンティティ名の表、State Models、Business Rules、User Roles、Stakeholder Map、Open Questions）
• 各 Tier 2 ファイルへのリンクと 1 行の概要を記載した ## Detail Files インデックス：

## Detail Files

| File | Contents |
|------|----------|
| `docs/domain/entities/quote.md` | Quote entity — lifecycle, attributes, status workflow |
| `docs/domain/entities/customer.md` | Customer/Account entity — parent-child, territory assignment |
| `docs/domain/flows/quote-to-close.md` | Full quote lifecycle from opportunity to installation |
| `docs/domain/flows/pm-renewal.md` | PM contract renewal process |
| `docs/domain/relationships.md` | Complete entity relationship map |
| `docs/domain/integrations.md` | Salesforce, Watertight, Procore, vendor portals |
| `docs/domain/archive/changelog.md` | Session-by-session learning history |

---

初期化ワークフロー

.tasks/domain.md が存在しない場合、AI は次の作業を行います：

1. ユーザーに最初の質問を 5 つする（references/seed-questions.md を参照）
2. 回答を使ってテンプレートに内容を記入する
3. .tasks/domain.md のドラフトを作成する
4. 保存前にレビュー用として提示する

初期ファイルは 200 行を大きく下回ります。まず単一ファイルモードで始め、ファイルが大きくなってから分割します。

---

時間をかけたドメインの拡張

各セッションでは、次のサイクルに従います：

READ .tasks/domain.md (+ relevant Tier 2 files if split)
      ↓
DO WORK (flag unknowns inline)
      ↓
PROPOSE UPDATES (specify target file if split)
      ↓
HUMAN REVIEWS & APPROVES
      ↓
HUMAN UPDATES .tasks/domain.md (or detail files)
      ↓
(next session reads updated files)

成長ライフサイクル

Sessions 1–3:     Single .tasks/domain.md, ~60–80 lines      (Tier 1 only)
Sessions 4–10:    Single .tasks/domain.md, ~100–200 lines     (Tier 1 + 2 mixed)
Sessions 10+:     Split into index + detail files       (Tier 1 / 2 / 3 separated)
Mature project:   Full three-tier structure with archive

ファイルが約200行を超えたら、AI は分割を積極的に提案します。

「ドメインファイルは現在[N]行で、[N]個のエンティティと[N]個のフローを詳しく記述しています。コアインデックスファイルと個別の詳細ファイルに分割しますか？各セッションでは、作業内容に関連する部分だけを読み込めるため、情報が失われることはありません。」

ユーザーが同意した場合：

1. Tier 1 の内容を簡潔なルートの .tasks/domain.md（約80～120行）に抽出する
2. 各エンティティの完全な説明を docs/domain/entities/[name].md に移動する
3. 各フローの完全な説明を docs/domain/flows/[name].md に移動する
4. 関係マップと統合ポイントを、それぞれ別の Tier 2 ファイルに移動する
5. 変更履歴を docs/domain/archive/changelog.md に移動する
6. ルートの .tasks/domain.md に ## Detail Files インデックスを追加する
7. 保存する前に、新しい構成を提示してレビューを受ける

時間の経過とともに、.tasks/domain.md は次の用途の唯一の信頼できる情報源になります。

• 新しい開発者のオンボーディング
• 今後の AI セッション（あらゆるモデル、あらゆるツール）
• ドキュメントと仕様
• テストケースの根拠

---

参考ファイル

• .tasks/domain.md — 新しいドメインファイルを初期化するための空のテンプレート
• references/seed-questions.md — 新しいドメインの初期設定時に尋ねる質問
• references/entity-template.md — 個別のエンティティファイル用テンプレート（大規模プロジェクト向け）
• references/anti-patterns.md — ドメインコンテキストを構築する際に避けるべきよくある間違い