duck-patch

パッチの実行 🦆。まずは最小限で安全な差分から。

目的

修正方針が決まった後、範囲を絞ったコード変更を実行します。

哲学に関するガードレール（スキル固有）

references/GUARDRAILS.md の共通ガードレールを引き継ぎます。

コメントとドキュメントの整合性

• 長期にわたって有効な制約、不変条件、契約、動作を記録します。
• コードコメントや通常のドキュメントに開発の経緯を記載しません。
• 却下したアプローチ、「以前はこうだった」という履歴、直近の変更に関する文脈、レビュー、テスト、セッションへの言及が、変更の経緯を説明するだけのものであれば削除するか、要対応として示します。
• セッション限りの決定、承認フラグ、一時的なマーカーを、長期的に維持する成果物に残しません。
• 履歴情報は、ADR や変更履歴など、履歴を記録することを目的とした長期的な成果物にのみ残します。
• テストやレビューへの言及は、長期的に有効な制約や検証要件を示す場合にのみ残します。

スキル固有の追加事項：

• 範囲を限定した実装のみを実行します。プロダクトやアーキテクチャに関する決定はユーザーに委ねます。

起動条件

ユーザーが対象を絞ったコード編集を依頼し、変更範囲が明確な場合（またはすぐに明確化できる場合）に使用します。

方法

サブエージェント実行モード

ユーザーチャネルを持たないサブエージェントとして実行する場合（例：duckling 経由）は、編集やコマンド実行を行いません。範囲の確認、Duck Ladder、パッチの導出を分析として行い、「最小限で安全な差分を適用する」と「合意した最小限のチェックを実行する」を、承認パッケージの内容（ファイルごとに導出した差分ブロックと検証計画）に置き換えます。ホストラッパーの契約に従って出力します（事前確認＋差分＋承認依頼＋ステータスフッター）。

1. 範囲を確認する（不完全な場合）

• 文脈が不十分な場合は、対象を絞った確認質問を1～3件行います
• 根拠が不足している場合は、前提を明示します

変更を伴う操作のゲート： ワークスペースを変更する操作（変更の種類に応じた承認が必要です）：

意味的変更（実行に対する完全な承認が必要です）：

• コード／ロジックの変更
• ドキュメント／計画の変更（README、Markdown ドキュメント、ADR、CONTEXT.md、手順書、設計メモ）。ただし、コード以外のテキストファイルにおける誤字のみの修正を除きます
• 設定／スキーマの変更（設定、環境変数、ビルド設定）
• 依存関係の変更（package.json、requirements.txt など）
• ファイル操作（作成、削除、移動）
• 変更を伴うコマンド（git commit、install、build、deploy）
• 実装／パッチ作成のタスク委任

外観上の変更（簡易確認が必要です）：

• フォーマット／空白文字のみの変更
• コード以外のテキストファイルにおける誤字の修正
• 確認文：「[フォーマット変更／誤字修正]を進めてよいですか？」

例外的なケース：

• コードファイル内の JSDoc／docstring の変更は、生成されるドキュメントやコードの契約に影響するため、意味的変更です
• コード内のロジックを説明するコメントの変更は、保守性の理解に影響するため、意味的変更です
• 設定ファイル内のコメントの変更は、解釈に影響するため、意味的変更です
• ドキュメント（ADR、CONTEXT.md）の更新は、意味的変更です
• README 内のコードスニペットの例は、ユーザーがコピーして貼り付けるため、意味的変更です

承認ワークフロー： 意味的変更を行う前に、実行の承認を得る必要があります：

1. 事前確認（承認を求める際は毎回必須です。項目が不足している場合は、確認の質問を1つしてください。）
   • 対象フェーズ：
     • フェーズ 1：スタブ／スケルトン／インターフェイス
     • フェーズ 2：配線／統合
     • フェーズ 3：具体的な実装
   • フェーズ適合の説明（この差分がフェーズの制約に合致する理由）
   • 対象ファイル（選択したフェーズに応じて範囲を限定）
   • 期待される動作の変更
   • 最小限の検証チェック
2. ファイルごとに変更一覧をフォーマット済みの差分として提示
   • ファイルが存在する場合：統合差分（---／+++／@@ のハンク、-／+ のプレフィックス）
   • ファイルが存在しない場合：ファイルパスをヘッダーとしたフェンス付きコードブロックに全内容を記載
   • 差分ブロックはファイルごとに1つ
   • 各変更を説明する注釈を差分のハンクより前に記載
   • フェーズの制約に違反するファイルがある場合は、分割して再提案してから承認を求める
3. 承認の確認：この範囲を承認しますか？（例：approve/ok/confirm）
4. 承認を待つ：ユーザーが明確な承認の意図を示すまで、編集／コマンド／タスクの委任に進まない

ルール：

• ユーザーの承認／確認なしに、ワークスペースを変更する操作を行わない

承認の意図を示すトークン：

• 承認の意図として受け付ける：「approve」、「approved」、「ok」、「go ahead」、「confirm」、「yes」
• 選択肢を参照した承認の文も受け付ける：「ファイル X と Y について、オプション B で進めてください。」「承認します。提案された検証計画を実行してください。」
• 例はすべてを網羅するものではありません。明確な承認の意図があれば受け付けます。
• 承認を伴わない継続の合図は承認として扱わない：「continue」のみ、選択肢の文字のみ（「B」）、または「next」のみ。承認を示す動詞も範囲の指定もない場合は承認ではありません。

範囲のルール：

• フェーズごとの上限（デフォルト）：

  • フェーズ 1（スタブ／スケルトン／インターフェイス）：最大 6 ファイル
  • フェーズ 2（配線／統合）：最大 4 ファイル
  • フェーズ 3（具体的な実装）：最大 2 ファイル

• フェーズの内容に関する制約（厳守）：

  • フェーズ 1（スタブ／スケルトン／インターフェイス）に含めてよいのは、次の内容のみです。
    • ファイル／モジュールの骨組み（フォルダー、エクスポート、セクション構成）
    • 型／インターフェイスの宣言
    • 関数／クラスのシグネチャ
    • プレースホルダーの戻り値／エラー／TODO マーカー
    • ビジネスロジックを含まない最小限の何もしない配線
  • フェーズ 1 に含めてはいけないもの：
    • 完全な機能／ビジネスロジック
    • 副作用を伴うフロー（DB／ネットワーク／認証／ファイル書き込み）
    • プレースホルダーを超える完全な UI の動作
  • フェーズ 2（配線／統合）に含めてよいもの：
    • ルート登録、DI／コンテナーの配線、モジュールの構成、イベントの接続
    • 既存コンポーネント間の適合用の接着コード
  • フェーズ 2 に含めてはいけないもの：
    • 新たな実質的なビジネスロジックのブロック
  • フェーズ 3（具体的な実装）に含めるもの：
    • ビジネスロジック、アルゴリズム、副作用、動作の完全な実装

• 新規ファイルのブートストラップルール：

  • 対象範囲に新機能のファイルが含まれる場合、最初の承認では Phase 1 のスタブ／骨組み／インターフェースのみを対象とします。
  • 本体の実装は、後続の Phase 2／3 の承認で行います。
  • 新規ファイルがスタブ／骨組みの範囲を超える場合は、そのファイルをスタブの作成と実装の後続作業に分けます。

• フェーズが上限を超える場合は、実行前に、より小さく範囲を限定した承認に分割します。

• レビュー疲れの客観的な判定基準：

  • Phase 1（スタブ／骨組み／インターフェース）：
    • 1 回の承認で提案する差分の変更行数（追加＋削除）が合計 180 行を超える場合、現在のフェーズの上限ファイル数を少なくとも 1 件減らします（上限は最低 1 ファイル）。
    • 単一ファイルの変更行数（追加＋削除）が 90 行を超える場合、そのファイルを個別の承認、または小規模な逐次編集に分割します。
  • Phase 2（配線／統合）：
    • 1 回の承認で提案する差分の変更行数（追加＋削除）が合計 120 行を超える場合、現在のフェーズの上限ファイル数を少なくとも 1 件減らします（上限は最低 1 ファイル）。
    • 単一ファイルの変更行数（追加＋削除）が 60 行を超える場合、そのファイルを個別の承認、または小規模な逐次編集に分割します。
  • Phase 3（具体的な実装）：
    • 1 回の承認で提案する差分の変更行数（追加＋削除）が合計 80 行を超える場合、現在のフェーズの上限ファイル数を少なくとも 1 件減らします（上限は最低 1 ファイル）。
    • 単一ファイルの変更行数（追加＋削除）が 40 行を超える場合、そのファイルを個別の承認、または小規模な逐次編集に分割します。
  • 同じバッチ内でレビュアーから 2 ファイルを超えて説明を求められた場合、次のバッチのファイル数を少なくとも 1 件減らします。

• 複雑さやレビュー疲れが増した場合は、上限をさらに引き下げ、より小さなバッチで続行します。

• 目的が変わらない場合でも、フェーズ間で実行の承認を再取得します。

• 承認後に対象範囲が変わった場合は、続行前に対象範囲の確認を再度行います。

• フェーズの例（適用）：

  • Phase 1 の例：5 ファイル、変更行数（追加＋削除）の合計 170 行、単一ファイルの最大変更行数（追加＋削除）80 行。上限と基準の範囲内なので、1 回の承認で進められます。
  • Phase 2 の例：4 ファイル、変更行数（追加＋削除）の合計 130 行。フェーズ全体の基準を超えるため、実行前に 2 回の承認に分割します。
  • Phase 3 の例：2 ファイルのうち 1 ファイルが変更行数（追加＋削除）45 行。単一ファイルの基準を超えるため、より小さな逐次編集に分割します。

2. Duck Ladder を適用する

新しい構造を導入する前に、最初に該当する段階で止めます：

1. 変更不要（YAGNI）
2. 既存のローカルヘルパー／パターンを再利用する
3. 標準ライブラリ／ネイティブ機能に置き換える
4. すでにインストールされている依存関係を使う
5. 安全性を保てる最小の差分に縮小する
6. その後で初めて、新しいコード／抽象化を追加する

コメントを追加または変更する場合は、後から読む人に必要な、長期的に有効な制約や動作のみを記述します。

3. パッチを実行する

1. 範囲を限定した作業内容と期待される動作を言い直します。
2. 共有される修正箇所のうち、最小の箇所に変更を加えます（呼び出し元ごとの個別パッチは避けます）。
3. 新しい抽象化を追加する前に、既存のローカルヘルパー／パターンを再利用します。
4. 安全性を保てる最小限の差分を適用します。
5. 合意した最小限のチェックを実行します。
6. 正確に報告します：変更ファイル、動作の差分、検証結果。

出力：

• 1 行の実行計画（ファイル（複数可）＋期待される動作）
• 最小限のパッチ概要（変更内容。長い説明は不要）
• 最小限の検証チェック 1 つとその結果
• ブロックされている場合：1 行の阻害要因＋次に必要な入力

境界

• セキュリティ、信頼境界、データ損失防止、アクセシビリティ、または明示的なユーザー要件を損なわないでください。
• 根本原因が不明確な場合は、推測で編集せず、必要に応じてトレースモードを使い、duck-debug に引き継ぎます。
• ローカルで検証を実行できない場合は、ユーザーが実行すべき正確なコマンドと、期待される結果を示します。