decisions-to-specs

Decisions → Specs

人間専用。 人間から明示的に名前を指定された場合にのみ、これを開始してください。別のスキルからここにたどり着いた場合は、停止し、いずれかの手順を実行する前に明示的な確認を得てください。

/wayfinder は、GitHub issue に意思決定を記録します。その時点での会話を記録したものです。これらの issue は記録であり、意思決定が 存在する場所 ではありません。このスキルは、wayfinder マップをもとに、確定した意思決定をリポジトリ内の長期的に維持される仕様ファイルに落とし込みます。これにより、次の手順である /specs-to-tickets が具体的に切り分けられるものを用意します。

意思決定の参照には GitHub を使い、仕様の記述にはリポジトリを使います。この2つの場所は意図的に分けています（場所を分ける理由を参照）。このスキルはその橋渡しのみを行います。issue の作成も、仕様のトラッカーへの移動も行いません。

リポジトリへの書き込みは、専用のワークツリーで行ってください。 他のセッションはプライマリチェックアウトを共有しており、このスキルはツリー内のあちこちにある仕様を編集します。共有チェックアウトで作業すると、書きかけの仕様が他の人のビルドに混入したり、他の人が作業中のブランチを切り替えたりするおそれがあります。以下のリポジトリへの書き込みはすべて、このスキルが作成した専用ブランチ上のワークツリーで行います。手順4を参照してください。手順1〜3では GitHub とツリーを読み取るだけなので、どこで行っても安全です。

意思決定を確定すると、そのチケットは置き換えられます。 issue はある会話のスナップショットです。確定後、意思決定は仕様に記録され、その後の意思決定、レビュー、実装によって更新されるのは仕様だけです。そのため、数か月後に読み返す意思決定チケットは古くなっている可能性が高く、手順8ではそれぞれに、対応する仕様を示す置き換え済みバナーを付けます。issue は根拠をたどるためにクローズしたままにし、仕様は /specs-to-tickets が実装チケットに切り分ける対象となります。

承認は仕様ではなくトラッカーに記録します。 このスキルの実行中に人間が何かを確定する場合（名称の承認、仕様の保存先、ある項目を破棄する判断など）は、記録先について approval-policy スキルに従ってください。仕様には、そこから導かれたルールを記載します。誰が、いつ、何に対して承認したかは、意思決定チケットまたはマップに記録します。ツリー内で検討した代替案を記載する場所は ADR の検討した代替案セクションだけです。ここには会話の記録ではなく、意思決定の記録として記載します。

プロセス

1. マップとその意思決定を読み込む

引数（issue の URL または番号）からマップを特定します。指定がない場合は、wayfinder:map ラベルが付いたオープン issue を探します。その本文にある Destination と Decisions so far を読みます。記載されているすべての意思決定について、子チケットを取得し、クローズ時に /wayfinder が記録した回答（解決コメント）を読みます。

完了条件： Decisions-so-far にある確定済みの意思決定すべてについて、回答を確認できていること。長期的な影響のない意思決定（行き止まりや、明示的な「変更なし」など）は、仕様に無理に反映せず、注記を添えて除外します。

2. 既存の仕様の配置状況を把握する

何かを書き始める前に、仕様がすでにどこに置かれているかを確認します。意思決定を重複ではなく更新できるようにするためです。

• パッケージ／アセンブリの spec/ フォルダー（およびコードにより近い場所にある仕様）
• ルートの spec/ — 複数領域にまたがる仕様
• spec/adr/ — 既存の ADR（ADR フォルダーは、その意思決定を扱う spec/ のスコープ内にある仕様フォルダーのサブフォルダーです）

CONTEXT.md と、これらの意思決定が影響する領域に関係する ADR を読みます。作成するすべての内容で用語集の用語を使います。意思決定が ADR と矛盾する場合は、黙って上書きせず、その矛盾を明らかにします。

完了条件： 各意思決定について、該当する仕様ファイルを特定できているか、まだ存在しないことを明示できていること。

3. 各決定の配置先を決める — 書き込む前に確認する

配置ルールを適用して、各決定の置き場所を決めます。更新する既存の仕様、新たに作成する仕様、または ADR のいずれかです。「妥当ならコードに近い場所にする」は判断を要するため、すべての振り分け（決定 → 対象ファイル → 新規作成／更新）を提示し、ファイルを1つも書き込む前にユーザーの確認を得てください。

**完了条件：**ユーザーがすべての決定の配置先を承認していること。

4. 書き込む前に worktree にブランチを作成する

ここから先、リポジトリに変更を加える作業はすべて、このスキル専用の worktree で行います。リモートから新たに作成してください。プライマリのチェックアウトでは決して作業せず、main に直接変更を加えないでください。

git fetch origin
git worktree add <worktree-path> -b docs/specs-<map-number> origin/main

リポジトリの隣ではなく、リポジトリ内に作成し、マップにちなんだ名前を付けてください。 セッションをプロジェクト外のディレクトリに移動する際、多くのハーネスではツールの権限とは別に人間の承認が必要になります。この作業とは無関係な確認が発生します。作業ディレクトリ内にパスを作成すれば、こうした確認を回避できます。リポジトリですでに使われているブランチ名と worktree 名の規則に従い、どの作業に属するものか一目で分かるよう、両方にマップにちなんだ名前を付けてください。

Claude Code の場合 — .claude/worktrees/specs-<map-number>を使ってください。ハーネス独自の worktree の保存先なので、新たに信頼を設定する必要がありません。EnterWorktreeのpath引数を使って移動してください。これは worktree がすでにgit worktree listに表示されている必要があるため、上記の順序で進めてください。

その他のエージェントの場合 — ツールがすでに無視するよう設定されている、リポジトリ内のディレクトリを使ってください。.worktrees/specs-<map-number>が安全な既定値です。追跡対象の.gitignoreに触れずに、.git/info/excludeで除外できます。その後、ハーネスが提供する方法で、以下の書き込み作業すべてにそのディレクトリを作業ディレクトリとして使ってください。移動する手段がない場合は、誤ってプライマリのチェックアウトに書き込まないよう、パスを明示的に指定してください（git -C <worktree-path> …）。

フェッチによりベースがステップ2で確認した内容より進んでいた場合は、ここで仕様の全体像を読み直してください。書き込み先はプライマリのチェックアウトではなく、worktree です。

一部のハーネスでは、worktree 内でのシェルのリダイレクトが制限されています。heredoc や>が拒否された場合は、無理に使おうとせず、ファイル書き込みツールと単一目的のコマンドを使ってください。

**完了条件：**セッションが新しいブランチ上のクリーンな worktree 内にあり、以降の書き込みがすべてそこに行われること。

5. 作成・更新する

• **既存の仕様を更新する場合：**該当するセクションに決定を組み込んでください。会話の内容を繰り返さないでください。経緯は issue に、確定した決定は仕様に記載します。
• 新しい仕様を作成する場合：/to-ticketsが同じ方法で処理できるよう、新規仕様の形式に従ってください。
• ADR の場合：ADR の形式に従ってください。

各決定から、その根拠となった GitHub issue にリンクしてください。仕様は「何を」、issue は「なぜその決定に至ったか」を記載するものです。

**完了条件：**ステップ3で振り分けたすべての決定が、worktree 内のファイルに反映されていること。

6. /concise-copyで簡潔にする

変更したすべてのファイルに対して/concise-copyを実行してください。仕様は繰り返し読まれるものなので、簡潔にまとめてください。

7. 仕様をコミットしてPRを作成する

仕様が、このセッションからしか見えないワークツリーに置かれている間は、まだ確定していません。/draft-commit-message でメッセージを下書きしてください。コミットの規約はこのスキルが定めています。その指示に従い、ここでフォーマットを繰り返さないでください。

このスキルだけでは判断できない情報を渡してください。つまり、対象のイシューと、今回のコミットにおけるそれぞれの役割です。

• マップは、この作業が属するチケットです。
• ファイルの作成につながった決定イシューは、その詳細です。
• どのイシューもクローズしません。 会話の終了時に/wayfinderが決定イシューをクローズしており、マップは/specs-to-ticketsがこれらの仕様を分割するまでオープンのままです。

その後、ワークツリーでコミットし、ブランチをプッシュして、mainに対するPRを作成してください。

このスキルがマージすることはありません。 /squash-merge-and-clean-upがPRをマージし、ブランチとワークツリーを削除します。それが実行されるまでは、両方を残してください。

完了条件： ステップ5で作成したすべてのファイルが、このスキルのブランチにコミットされ、PRがオープンになっていること。

8. 各決定チケットに置き換え済みの印を付ける

仕様につながった各決定イシューに戻り、次のバナーを本文の先頭に追加してください。再実行する場合は、既存のバナーを置き換えてください。

> **Superseded by spec — do not build from this ticket.**
> This decision now lives in `src/<Package>/spec/<feature>.md`, which is the source of truth and has almost certainly moved on since this was written. Below is *why* the decision was made; build from the spec.

決定に関係したすべての仕様を記載してください。ステップ1で却下した決定にはバナーを付けません。置き換えたものがないためです。

完了条件： ステップ3で振り分けたすべての決定イシューにバナーがあり、仕様ファイルが記載されていること。

9. マップを更新してから報告する

実施内容の概要を、## Specs settled見出しの下にマップ本文へ記載してください（契約を参照）。これは次のステップである/specs-to-ticketsが読む、永続的なガイドです。マップは、作業の進捗を示す唯一の場所として維持します。

続けてユーザーに報告してください。どこに何を反映したか、仕様を含むPR、印を付けた決定イシュー、そしてPRのマージ後に次のステップとして/specs-to-tickets <map>を実行することを伝えてください。

完了条件： マップに## Specs settledセクションがあり、ステップ5で作成したすべてのファイルが記載されていること。

マップのSpecs-settledセクション

/specs-to-ticketsへの引き継ぎです。マップ本文に記載してください（見出しがなければ作成し、再実行時は更新します）。仕様ファイルごとに1行で、パス、処理内容、関係した決定イシューを記載します。

## Specs settled

- `src/<Package>/spec/<feature>.md` — new — decisions: #12, #15
- `spec/<cross-cutting>.md` — updated — decisions: #13
- `src/<Package>/spec/adr/0003-<slug>.md` — ADR — decision: #14

処理内容はnew、updated、またはADRです。ADRの行も記録しますが、次のステップで分割しないよう、目印を付けてください。

配置ルール（スコープの優先順位）

決定全体を包含する最小のスコープを優先してください。

1. パッケージ／アセンブリのspec/ — 決定が1つのパッケージに影響する場合です。読みやすさの観点から、モジュールの隣など、さらにコードに近い場所に置いてもかまいません。
2. ルートのspec/ — 複数のパッケージにまたがる場合や、システム全体の構造に関わる場合です。
3. spec/adr/（ADR） — 決定が覆しにくく、背景を知らないと意外で、実際のトレードオフの結果である場合です（MattのADR基準では、3つすべてを満たす必要があります）。3つ未満ならADRではありません。ADRフォルダーは、決定と同じスコープにあるspec/の下に配置します。パッケージ単位のADRは<package>/spec/adr/に、複数の領域にまたがるADRはルートのspec/adr/に置きます。

仕様とADRの違い： 仕様は何を構築するかを説明し、ADRは決定とその理由を記録します。1つの決定から両方を作成することもできます。つまり、「なぜ」を記録するADRと、「何を」を定める仕様です。ただし、それぞれが単独でも重要な内容を持つ場合に限り、分けてください。

新しい仕様の形式

/to-specのテンプレートに合わせてください。そうすれば/to-ticketsも同じ形式で読み取れます。決定から作成する仕様に不要なセクションは省略してください。

• Problem Statement — ユーザーの視点から記述
• Solution — ユーザーの視点から記述
• User Stories — As an <actor>, I want <feature>, so that <benefit>
• Implementation Decisions — モジュール、インターフェース、契約、スキーマ（ファイルパスやコードは含めない）
• Testing Decisions — テストの接点と、適切なテストでカバーする内容
• Out of Scope

ADR の形式

スイートの ADR 形式に従い、担当スコープの spec/adr/NNNN-slug.md に番号付きで作成します（そのフォルダー内を確認して最大の番号を調べ、1つ増やします）。タイトルに加え、背景、決定内容、その理由を1～3文で記述します。Status／Consequences は必要な場合にのみ追加します。ADR は1段落でも構いません。ADR の価値は、決定がなされた「こと」と「理由」を記録する点にあります。

サーフェスの分離

GitHub にはやり取り（wayfinder のマップと決定事項のイシュー）を置き、後から実装チケットも置きます。リポジトリには仕様書を置きます。両者を分けることが重要です。記録でリポジトリが肥大化せず、仕様書もイシュートラッカーに埋もれません。

フロー内での位置付け

/wayfinder → GitHub の決定事項イシュー（クローズ済み、根拠を記載し、置き換え済みの印を付ける）→ /decisions-to-specs → 作業ツリーのブランチ上にあるリポジトリの仕様書ファイルを PR として作成（マップに ## Specs settled を追加）→ /squash-merge-and-clean-up → /specs-to-tickets → /to-tickets → GitHub の実装チケット（新規作成し、決定事項のイシューとは区別）→ /implement。

任意：最終ステップを wayfinder マップの ## Notes に組み込むこともできます。「ルートが明確になったら、/decisions-to-specs を実行する」 と記載するか、決定事項が十分にまとまって確定できる状態になった時点で手動実行します。