domainkit

domainkit

プロジェクトのドメインモデルを記録する domainkit は、2つの常に更新される成果物を維持します。**CONTEXT.mdは、製品の概要と対象ユーザーを短く説明した後、プロジェクトで広く使われている用語の用語集を掲載します。docs/adr/**は、アーキテクチャ上の意思決定とその理由を記録します。中核となる流れは意図的に絞られており、タイミングを検出し、記録を提案し、同意を得てから書き込むことで、用語と難しい選択の背景にある理由を、誰かが覚えておかなくても明確に保ちます。

主に設計作業の副産物として動作します。意思決定について議論しているとき、計画を作成しているとき、またはコードを書いているときに、用語の意味が固まったり、意思決定が確定したりします。そのタイミングで domainkit が起動し、記録内容を提案して、同意を得てから書き込みます。この流れに加えて、明示的なモードが2つあります。1つはプロジェクトの CONTEXT.md を一度に作成し、もう1つは後からコードとの整合性を確認します。

起動するタイミング

次の3つのモードのいずれかに振り分けます。

• record。デフォルトです。曖昧だったり、複数の意味で使われていたり、同じ概念に2つの言葉が使われていたりするため、ドメイン用語を明確にする必要がある場合に使います。また、ADR の基準を満たす意思決定が確定した場合も使います。明示的な依頼があった場合も対象です。「この意思決定を記録して」「ADR を書いて」「用語集を更新して」「この用語を広く使われている言語に追加して」「/domainkit」などです。また、別のスキルでドメインモデルの最新状態を維持する必要がある場合は、そのスキルが独自に形式を扱うのではなく、ここに委ねます。
• init。ユーザーがドメインモデルの作成を依頼した場合に使います。「CONTEXT.md を設定して」「プロジェクトの概要を書いて」「domainkit init」などです。リポジトリを読み、オーナーに一度だけ質問し、CONTEXT.md 全体を提案します。
• audit。ユーザーがモデルの最新性を確認したい場合に使います。「CONTEXT.md は今も正確？」「用語集を監査して」「domainkit audit」などです。CONTEXT.md がコードに追いついていない場合、statuskit がここに振り分けます。

モデルが起動した場合は、常に record に振り分けます。 init と audit はユーザーから依頼があった場合にのみ実行します。どちらもリポジトリ全体を読み、大きな差分を提案するため、そのコストを負担するかどうかはユーザーが選びます。

domainkit が意図的に扱わないことは2つあります。

• 尋問役ではありません。 用語に異議を唱えること、エッジケースを考案すること、意思決定が妥当かどうかをストレステストすることは、尋問の段階で行います。domainkit が記録するのは、確定した理解です。用語や意思決定がまだ本当に未解決である場合は、推測を書き残すのではなく、インストールされていれば grillkit を使うか、ユーザーに直接決定してもらいます。init ではオーナーに質問しますが、コードからは判断できない事実について、推奨する回答を添えて尋ねるだけです。
• ステータストラッカーではありません。 status.md も「現在の状態」を記録するファイルもありません。プロジェクトの状態は、課題で計画を、git とセッション履歴で実際の変更を追跡し、必要に応じてハンドオフで状態を要約することで把握できます。domainkit が保存するのは、これらでは復元できない情報、つまり製品の目的、用語、そして取り消せない選択の背景にある理由だけです。

同意（すべてのモード）

書き込みには必ず同意が必要です。domainkit は明示的な承諾を得てから書き込みます。record では各項目を個別に提案します。init と audit では、提案する変更全体、ファイル全体または差分全体を提示し、1回の承諾で書き込みます。誤検知があっても、無視できる提案が1つ表示されるだけで、誤ったファイルが作成されることはありません。

モード

各モードの本体は、modes/ 以下に1つずつファイルがあります。起動するタイミングに従って振り分け、そのファイルを読み、記載内容に従ってください。このファイルの内容はすべてのモードに適用され、各モードのファイルでは繰り返しません。

• モード record → modes/record.md を読み、記載内容に従ってください。
• モード init → modes/init.md を読み、記載内容に従ってください。
• モード audit → modes/audit.md を読み、記載内容に従ってください。

CONTEXT.md の形式

CONTEXT.md は、プロダクトの内容と、その言葉の意味を定める唯一の情報源です。短い概要に続けて、ドメイン駆動設計のユビキタス言語を記載します。仕様書でも、ステータスファイルでも、README でもありません。

# <Context name>

<1–2 sentence description of this context.>

## Overview

### What it is
<3 lines or fewer.>

### Who it is for
<3 lines or fewer.>

### The problem it solves
<3 lines or fewer.>

### Core capabilities
- <7 bullets or fewer, one capability each>

### Non-goals
- <3 lines or fewer: what the product deliberately does not do>

## <Optional grouping subheading>

### <Term>
<Tight definition. What it *is*, in 1–2 sentences.>
_Avoid: <synonym to reject>, <another>_

概要。 用語集の枠組みを示し、1 画面に収まる内容にします。

• 次の 5 項目を順番に記載します。 プロダクトの内容、対象者、解決する課題、中核となる機能、対象外のこと。各項目は 3 行以内とし、中核となる機能は 7 項目以内にします。
• プロダクトの内容は必須です。 所有者が重要でないと判断した場合は、ほかの項目を省略できます。
• 目的と対象者を記載し、使い方は記載しません。 概要では、プロダクトが存在する理由と対象者を説明します。README にあるインストールや使い方の説明を繰り返さず、代わりに README へリンクしてください。
• 既存ファイルでは任意です。 概要のない CONTEXT.md も有効です。init では概要の追加を提案しますが、概要がないことだけを理由にファイルに警告を出すことはありません。

用語集。 ## Overview 以外の各 ## セクションには、用語を記載します。

• 記載できる内容。 このプロジェクトのドメインに固有の用語や、作業に固有の概念。
• 記載できない内容。 どれほど頻繁に使われていても、タイムアウト、エラーの種類、ユーティリティパターンなど、一般的なプログラミングの概念は記載しません。ドメイン固有でなければ、ここには含めません。
• 定義の形式。 用語が「何であるか」を定義し、「何をするか」は定義しません。1 文または 2 文で記述します。
• 明確な方針を示します。 1 つの概念に複数の呼び方がある場合は、最適なものを選び、ほかの呼び方は _Avoid_ に記載します。
• 長さの上限はありません。 用語集はドメインに合わせて拡張します。長さの目標を満たすために、実際の用語を削除しないでください。

コンテンツのルール：概要と用語集のみ。 ステータス、段階、ロードマップ、指標は記載しません。古くなりやすく、トラッカーで管理するためです。意思決定も記載しません。意思決定は ADR に記録し、用語から、それを形作った ADR にリンクすることはできます。インストールや使い方の手順も記載しません。それらは README に記載します。

複数のコンテキスト。 境界づけられたコンテキストが明確に分かれている場合は、リポジトリのルートに CONTEXT-MAP.md を置き、各コンテキスト、そのファイルの場所、コンテキスト間の関係を記載します。分割は急がず、1 つのファイルでは整合性を保てなくなった時点で行います。複数のコンテキストがあるプロジェクトでは、プロダクト全体について説明する ## Overview ブロックを、コンテキスト一覧より前の CONTEXT-MAP.md に置きます。各コンテキストの CONTEXT.md には、概要を設けず、1～2 文の説明と用語集を記載します。

ADR 決定記録の形式

ADR は docs/adr/ に置き、NNNN-adr-<slug>-YYYY-MM-DD.md という形式を使用します。番号はゼロ埋めで連番にします：0001-adr-use-postgres-2026-07-23.md、0002-adr-adopt-event-log-2026-07-24.md、… 先頭に番号を置くことで、一覧が決定順に並び、他の docs/ 内の成果物が持つ通し番号とも一致します。決定順を示すのは番号で、ISO 形式の接尾辞は作成日です。後からステータスが変わったという理由で ADR の名前を変更してはいけません。新しい ADR に番号を付けるには、docs/adr/ で既存の決定番号の最大値を調べ、1 を加えます。ADR が旧形式の adr-NNNN-<slug>-YYYY-MM-DD.md のままのリポジトリでは、既存の番号はそのままにし、新しい形式で ADR を作成してください。旧形式の ADR の名前を変更するには、repokit の docs モード（インストール済みの場合）を使うようユーザーに案内してください。ディレクトリは、最初の ADR が必要になるまで作成しないでください。並行するブランチで同じ番号が使われることがあります。その場合はマージ時に後から作成された ADR の番号を変更し、それへの参照（その ADR の名前を記載した Status 行を含む）も更新してください。

# NNNN: <Title>

<1–3 sentences: what the context was, what was decided, and why.>

## Status
proposed | accepted | accepted, supersedes ADR-NNNN | deprecated | superseded by ADR-NNNN

## Considered Options
- <rejected alternative worth remembering, and why it lost>

## Consequences
- <non-obvious downstream effect>

タイトル、コンテキスト／決定／理由を説明する段落、および Status があれば、ADR は完成です。すべての新しい記録で Status は必須です。後からの置き換え時に変更する必要があるためです。Considered Options と Consequences は任意です。価値がある場合にのみ記載してください。他の ADR を置き換える記録では、自身の Status 行にその旨を記載します：accepted, supersedes ADR-NNNN。

次の 3 つすべてに当てはまる場合にのみ、ADR を作成してください：

1. 元に戻しにくい。 後から方針を変更すると、実質的なコストがかかります。
2. 背景がなければ意外に感じる。 将来の読者が、コードだけではそのアプローチを疑問に思うでしょう。
3. 実質的なトレードオフがある。 現実的な代替案が存在し、比較検討されています。

典型的な該当例：アーキテクチャ構造（モノレポの構成、イベントソーシング）、コンテキスト間の統合アプローチ、切り替えコストが高い技術の選択（データベース、認証プロバイダー）、境界とスコープの定義、慣例から意図的に逸脱する判断、コードからは見えない制約（コンプライアンス、パフォーマンス）、および代替案を採用しない明白でない理由。

注意事項

• 自動で実行される場合も、同意は必要です。 モデルから呼び出されたからといって、促されていない内容を書いてよいわけではありません。必ず最初に提案してください。
• 基準を高く保ちます。 本当に用語が衝突する場合や、真に取り消せない決定である場合にのみ実行し、あらゆる名詞について逐一確認することは避けてください。迷った場合は何もせずにおきます。
• ファイルシステムやシェルを使えない場合（たとえばブラウザー上のエージェントの場合）は、提案する用語集の項目、ADR、または CONTEXT.md 全体をコードブロックに出力し、ユーザーが保存できるようにして、ファイルへの書き込みは行いません。git log がない場合、audit は現在のツリーのみを比較対象とします。それ以外に変更はありません。