intent

name

intent

description

Intent-Driven Development (IDD) に基づき、ADR（Architecture Decision Record）形式の Intentドキュメントを作成するスキル。ユーザーの「こういう機能を作りたい」「この設計判断をした」 という意図をWhy/Whatに整理し、How（実装詳細）の混入を検出・分離して、docs/adr/ に連番の ADRファイルを生成する。 このスキルは以下の場合に必ず使用すること： - ユーザーが /intent と入力したとき - 「ADRを書きたい」「意図を記録したい」「intentを作成」「設計判断を残したい」「ADR作って」 「決定を記録」「なぜこうしたか残しておきたい」などと言ったとき - ユーザーが新機能やアーキテクチャの判断について議論し、それを文書化したいと示唆したとき Do NOT trigger for: バグ修正の記録、ルーチンなリファクタリング、意図が自明な些細な変更。

Intent（ADR）作成スキル

Intent-Driven Development (IDD) の考え方に基づき、設計判断をADR形式で記録する。 ADRは「その時点で何を、なぜ決めたか」を記録する不変のドキュメントであり、 仕様書のように現在の真実を主張するものではない。だからこそドリフトが構造的に起きない。

ワークフロー

Step 1: ユーザーの意図をヒアリングする

ユーザーの入力から以下を抽出する：

• Why（動機）: なぜこの変更が必要か？ビジネス上の理由、ユーザーの課題、技術的制約
• What（達成すべきこと）: 何を実現するか？観察可能な振る舞い、受け入れ条件、入出力の契約

情報が不足している場合は、具体的な質問で補う。一度に全部聞かず、最も重要な不明点から順に聞く。

Step 2: How-Leak を検出・分離する

ユーザーの入力にHow（実装詳細）が含まれていることは珍しくない。 開発者は自然と「Redisを使って」「REST APIで」「PostgreSQLに保存」のように考えるからだ。

以下はHowに該当するため、Intent本文から除外する：

• ライブラリ、フレームワーク、ツールの指定（例: Redis, PostgreSQL, JWT）
• 内部データ構造やアルゴリズム
• 処理手順や実行順序
• 実装を変えてもIntentが変わらないような詳細
• アーキテクチャパターン名にも注意: 「キャッシュ層」「メッセージキュー」「API Gateway」 などはグレーゾーン。それ自体が目的ではなく手段である場合はHowに該当する。 代わりに達成したい性能要件や振る舞い（「読み取りレイテンシをNms以下にする」 「非同期でイベントを処理する」）で表現できないか検討する。

検出方法（How-Leak Check）:

「すべての実装詳細を別の有効なアプローチに置き換えても、 このIntentは目標を正確に記述しているか？」

• Yes → Intentはクリーン
• No → How-leakがある。該当箇所を指摘し、WhyまたはWhatとして言い換えられるか確認する

How-leakを見つけたら、ユーザーに以下のように伝える：

以下の記述は実装詳細（How）に該当するため、Intentから分離しました：
- 「Redisでキャッシュする」→ これはConstraintsの「レスポンス時間 < 200ms」のような
  非機能要件として表現できるかもしれません。それとも実装メモとして別に残しますか？

分離したHowは捨てるのではなく、ユーザーに判断を委ねる。Constraintsセクションに 非機能要件として書き直せるものもあるし、コードコメントとして残すべきものもある。

Step 3: 採番する

docs/adr/ ディレクトリを確認し、既存ADRの最大番号の次を採番する。

• ディレクトリが存在しない場合は作成し、0001 から開始
• 番号は4桁ゼロ埋め（例: 0001, 0012）
• 一度使った番号は再利用しない

Step 4: ADRドラフトを生成してプレビューする

以下のテンプレートに沿ってドラフトを作成する：

# ADR-NNNN: <Title>

## Status

proposed

## Date

YYYY-MM-DD

## Context (Why)

なぜこの変更が必要か。
ビジネス上の動機、ユーザーの課題、技術的制約を記述する。

## Intent (What)

何を達成するか。
観察可能な振る舞い、受け入れ条件、入出力の契約を定義する。
実装方法（How）は書かない。

## Constraints

非機能要件や守るべき制約（パフォーマンス、セキュリティ、互換性など）。
解を制約するが、実装を規定しない。

## Alternatives Considered

検討して却下した選択肢とその理由。
（これは「Why not」— 将来の意思決定者にとって貴重なコンテキスト）

## Consequences

この判断から生じる帰結（ポジティブ・ネガティブ両方のトレードオフ）。

重要:

• ファイルに書き込む前に、必ずドラフト全文をユーザーに提示して確認を得る。
• 新規ADRのStatusは必ず proposed にする。accepted にしてはならない。 Statusを accepted に変更するのはユーザーの判断であり、ADR作成時の操作ではない。

Step 5: ファイルを書き込む

ユーザーの承認後、docs/adr/NNNN-kebab-case-slug.md として保存する。

ファイル名のslug部分は、タイトルから生成する：

• 英語のkebab-case
• 小文字のみ
• 簡潔に（3〜5単語程度）

既存ADRの上書き（Supersede）

ユーザーが過去の決定を覆したい場合：

1. 新しいADRを作成し、Statusに「proposed — supersedes ADR-NNNN」と記載
2. 旧ADRのStatusを直接編集する: docs/adr/NNNN-slug.md のStatusセクションのみ 「superseded by ADR-MMMM」に書き換える。 これが受理済みADRに許される唯一の編集であり、別ファイルで指示を出すのではなく 実際にファイルを編集すること。
3. 元のADRの他のセクション（Context, Intent, Constraints等）は一切変更しない（不変性の原則）

ADRを書くべきとき・書くべきでないとき

書くべきとき:

• 新機能や新しい能力の導入
• 持続的な影響を持つアーキテクチャ・設計判断
• 複数の実行可能なアプローチからの選択
• 過去の判断の変更・撤回

書くべきでないとき:

• バグ修正（コミットメッセージで十分）
• 設計判断を伴わないルーチンなリファクタリング
• 意図が自明な些細な変更

ユーザーの依頼がADRに適さないと判断した場合は、その理由を説明し、 代替手段（コミットメッセージ、コードコメント等）を提案する。

言語について

• ADR本文はユーザーの言語に合わせる（日本語で話しかけられたら日本語で書く）
• ファイル名のslugは常に英語のkebab-case