# CuePaste 開発ガイドライン

## 目的と適用範囲

- このファイルは、CuePaste の設計・実装・検証で継続して守る作業ルールを定義する。
- 現行仕様の正本は `docs/promptpaste_spec.md` とする。
- 仕様と実装が食い違う場合は、推測で補完せず差分を明示して確認する。

## 言語方針

- ドキュメント、作業ログ、引き継ぎメモは日本語で記載する。
- コード上の識別子は Swift と Apple プラットフォームの慣習に従う。

## 実装原則

- KISS / YAGNI / DRY を優先し、現在の要件に必要な範囲だけ実装する。
- 原因を特定せずにフォールバック、互換分岐、設定項目を追加しない。
- 不具合は根本原因に対する最小変更で修正する。
- 将来拡張を見越した抽象化は、具体的な要件が出るまで追加しない。
- 無関係なリファクタ、命名変更、大規模整形を同じ変更に含めない。
- SwiftUI と AppKit の責務を分け、既存の macOS 標準 API で足りる処理に独自の仕組みを増やさない。

## プロダクト前提

- CuePaste は macOS 向けのメニューバー常駐アプリである。
- MVP は、キーワードに対応する `.md` / `.txt` を検索し、クリップボードへコピーして前面アプリへ `⌘V` を送る。
- 検索は設定されたプロンプトフォルダを基準とし、同名なら `.md` を `.txt` より優先する。
- スラッシュを含むキーワードでは、プロンプトフォルダ配下のサブフォルダを検索する。
- ファイル未検出または読込失敗時は、クリップボードと前面アプリを変更しない。
- 自動ペーストにはアクセシビリティ権限が必要であり、未許可時はペーストせず案内を表示する。
- サンドボックス化や配布方式は、仕様として決定する前に先回り実装しない。

## 作業手順

1. 事前確認
   - `docs/promptpaste_spec.md` と関連コードを読み、対象範囲と完了条件を確認する。
   - 不具合対応では、再現条件と実際に失敗している処理を先に特定する。
2. ブランチ作成
   - 作業開始時に、目的が分かる作業ブランチを作成する。
   - `main` へ直接変更を加えない。
3. テスト方針決定
   - 変更する挙動と、壊してはいけない既存挙動を先に列挙する。
   - 実機でしか確認できない項目は、手動確認手順を先に定義する。
4. テスト作成
   - コード変更では、可能な範囲で失敗するテストを先に追加する。
   - 回帰不具合は、再現テストを追加してから修正する。
5. 実装
   - テストまたは確認条件を満たす最小実装を行う。
   - 観測できていない失敗を想定した回避分岐は追加しない。
6. 検証
   - 自動テスト、ビルド、静的確認、および必要な実機確認を行う。
   - 実施できなかった確認と残るリスクを明示する。
7. ドキュメント更新
   - 仕様や操作が変わる場合は、関連する `docs/` を同じ変更で更新する。
   - 実装または仕様を変更した作業では、`docs/dev-log.md` を同じ変更で更新する。

## 開発ログ

- `docs/dev-log.md` に、作業日、変更内容、変更理由、検証結果を簡潔に記録する。
- 未確認事項や既知リスクがある場合は、確認済みの事実と分けて記録する。
- 調査だけで変更しなかった場合は、今後の判断に必要な結論があるときだけ記録する。
- パス、プロンプト本文、クリップボード内容などの機微情報は記録しない。

## テスト・検証観点

- キーワード検索で `.md` が `.txt` より優先されること。
- サブフォルダを含むキーワードが正しいファイルへ解決されること。
- ファイル未検出と読込失敗で、クリップボードと前面アプリが変更されないこと。
- 読み込んだ UTF-8 テキストが欠落や意図しない変換なくコピーされること。
- グローバルショートカットで入力画面が表示され、Enter で実行、Esc で閉じること。
- 実行後に入力画面が閉じ、元の前面アプリへペーストされること。
- アクセシビリティ権限の許可済み・未許可の両方で仕様どおり動作すること。
- 設定したプロンプトフォルダとショートカットが反映されること。
- 権限ダイアログ、フォーカス遷移、キーイベント送信は macOS 実機でも確認すること。

## 調査とデバッグ

- Apple API の挙動判断は、Apple 公式ドキュメントなどの一次情報を優先する。
- 権限、フォーカス、キーイベントの問題は、どの処理段階で失敗したかを切り分けてから修正する。
- 必要なログは最小限とし、プロンプト本文やユーザーのクリップボード内容を記録しない。
- 実機情報が必要な場合は、確認手順と取得したい事実を具体的にユーザーへ示す。

## 役割分担

- 依存関係のインストール、macOS のシステム設定変更、権限付与はユーザーが実行する。
- エージェントは、必要なコマンドまたは操作手順と目的を明示して依頼する。
- テスト環境の構築が必要な場合は、先に必要性と手順を示してユーザーへ依頼する。

## Git 運用

- コミットは目的ごとに小さく保ち、短い命令形のメッセージを使用する。
- ユーザーの明示的な依頼なしに push、rebase、force push を行わない。
- ユーザーの未コミット変更を取り消さず、競合する場合は内容を確認して共存させる。

## 禁止事項

- 原因未特定の当てずっぽう修正。
- 根拠のない後方互換レイヤーや代替処理の追加。
- 要件未定義の最適化、抽象化、設定追加。
- 依頼範囲外の大規模改修。
- プロンプト本文、クリップボード内容、個人パスなどの機微情報をログやテスト成果物へ残すこと。

## 完了報告

- 変更内容、検証結果、未確認事項、既知リスクを分けて報告する。
- 確認済みの事実と推測を区別し、実機確認が残る場合は具体的な確認項目を示す。
