| name | develop |
| description | gaze の開発ワークフロー。機能追加・バグ修正の計画から実装、テスト、PR作成までを一貫して行う。 |
| disable-model-invocation | false |
| argument-hint | ["やりたいことの概要"] |
gaze 開発ワークフロー
このスキルは gaze の開発を計画からPR作成まで一貫して行います。
計画フェーズでは ultrathink を用いて深い分析を行い、見落としを最小化します。
現在のリポジトリ状態
- ブランチ: !
git branch --show-current
- Git状態: !
git status --short
- 直近コミット: !
git log --oneline -5
フェーズ間のユーザー確認ルール
- 確認必須: Phase 1（計画）、Phase 2（ブランチ作成）、Phase 7（レビュー）、Phase 8（コミット・PR）
- 自律実行可: Phase 3（実装）、Phase 4（テスト）、Phase 5（ドキュメント）、Phase 6（品質チェック）
- ただし問題が発生した場合や判断に迷う場合はユーザーに確認すること
ワークフロー
Phase 1: 要件整理と計画 [確認必須]
- ユーザーの要望
$ARGUMENTS を受け取る
- CLAUDE.md のアーキテクチャセクションを参照し、関連モジュールを特定する
- 特定した関連モジュールのソースコードを読み、現在の実装を理解する。具体的には:
- 変更対象モジュールのソースコード全体
- 変更対象モジュールが依存しているモジュールの公開インターフェース（関数シグネチャと呼び出し箇所）
- 変更対象モジュールに対応する既存テストファイル
- 過去のレビュー知見の確認:
.claude/review-lessons.md が存在する場合は読み込み、今回の変更に関連するレビュー指摘パターンがないか確認する。関連するパターンがあれば、計画段階で対策を織り込む
- 影響分析: 変更による既存機能への影響を構造的に分析する
a. 呼び出し元追跡: 変更・追加する関数名で Grep し、全ての呼び出し元を列挙する
b. 層境界分析: 変更が Clean Architecture の層境界（domain ← usecase ← adapter/infrastructure）に違反しないか確認する
c. ポートインターフェース影響: usecase 層のポートインターフェース（
RendererPort, ImageLoaderPort 等）のシグネチャ変更が必要か、変更する場合は全実装箇所を列挙する
d. 影響を受ける機能の列挙: 上記から影響を受ける可能性のあるユーザー向け機能を具体的に列挙する
e. エッジケースの洗い出し: 以下の観点でエッジケースを検討する
- ターミナルサイズが極端に小さい場合（幅/高さが0やごく小さい値）
- 画像ファイルが破損・不正な場合のエラーハンドリング
- 対応外の画像フォーマットの場合
- ズーム倍率やパンオフセットの境界値（最大/最小/ゼロ）
- Kitty Graphics プロトコル非対応のターミナルでの挙動
- Viewport の float64 精度に関する問題
- 以下の観点で計画を整理し、ユーザーに提示する:
- 目的: 何を実現するか
- 影響モジュール: どのファイルを変更するか（CLAUDE.md のモジュール責務と照合）
- 実装方針: どのように実装するか（既存パターンに従う）
- 影響分析結果:
- 層境界: domain/usecase/adapter のどの層に変更が入るか
- ポートインターフェース: 変更があるか、影響する実装は何か
- 影響を受けるモジュールと機能
- エッジケース: 検討した結果と対策
- 過去レビュー知見: 関連するパターンがあれば、対策をここに記載する
- テスト方針: どの関数をテストするか
- ドキュメント更新: README.md / CLAUDE.md のうちどれを更新するか、更新する内容の概要
- 懸念事項・リスク: 既存機能への影響、エッジケース
- 代替案: 別のアプローチがあれば提示
- 変更規模が大きい場合（影響モジュールが4つ以上、または新規モジュール追加を含む場合）は複数PRへの分割を提案する
- ユーザーとの対話で計画を洗練させる（合意に至るまで繰り返す）
重要: 計画段階では絶対にコードを書かないこと。Read/Grep/Glob のみ使用する。
Phase 2: ブランチ作成 [確認必須]
計画合意後：
- 作業ツリーの状態を確認する
- クリーンな場合: そのまま続行
- 未コミットの変更がある場合: 変更内容をユーザーに報告し、stash するか commit するか指示を仰ぐ。勝手に変更を破棄しないこと
- main ブランチを最新に更新する:
git fetch origin && git checkout main && git pull origin main
- 変更の種類に応じたブランチを作成する:
- 機能追加:
feat/<簡潔な説明> (例: feat/add-webp-support)
- バグ修正:
fix/<簡潔な説明> (例: fix/viewport-zoom-overflow)
- リファクタリング:
refactor/<簡潔な説明>
- ドキュメント:
docs/<簡潔な説明>
- ブランチ名はユーザーに提案し、確認を取ってから作成する
Phase 3: 実装 [自律実行可]
- 計画に従いコードを実装する
- 既存のコーディングパターンに従うこと:
- Clean Architecture: domain 層に外部パッケージの import を追加してはならない。usecase は domain のみに依存。adapter/infrastructure は usecase のポートインターフェースを実装する
- エラーハンドリング: エラーは必ずハンドリングし、
fmt.Errorf("doing X: %w", err) でラップする。_ でエラーを無視しない
- 命名規則: Go 標準の命名規則に従う（camelCase, 頭文字語は大文字）。インターフェース名は動詞+er または役割名（例:
RendererPort, ImageLoaderPort）
- Viewport: float64 オフセットによるスムーズなパン操作
- 実装時のチェック観点:
- 重複ロジックの検索: 新しいロジックを書く前に、既存コードに同等の処理がないか Grep で検索する。ある場合は既存実装を再利用する
- 層境界違反の防止: domain 層に外部パッケージを import していないか確認する。adapter から domain への直接依存がないか確認する
- ポートインターフェースの整合性: ポートインターフェースを変更した場合、全ての実装が更新されているか確認する
- エラーパスの網羅: 新しいエラーが発生しうるパスで、適切なエラーラップとハンドリングがされているか確認する
- Bubbletea v1 API:
tea.MouseMsg は msg.Button / msg.Action を使用する（非推奨の msg.Type は使わない）
- 一連の関連する編集が完了した区切りごとに
make fmt でフォーマットする
- 実装完了後、既存テストを実行して既存機能を壊していないか確認する:
make test
Phase 4: テスト [自律実行可]
- 変更対象モジュールの既存テストファイル（
*_test.go）を読み、テストのスタイル・構造・ヘルパーの使い方を把握してから新規テストを書く
- 新規・変更した関数に対するテストを追加する
- テストファイルの配置: 対象ファイルと同一パッケージに
*_test.go として配置する
- テストパターン: Go 標準の table-driven tests を使用する
tests := []struct {
name string
}{
{"case name", },
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
})
}
- テスト不要の判断基準: 以下の全てを満たす関数はテスト不要
- 条件分岐やデータ変換を含まない
- 外部ライブラリの API を1つ呼ぶだけのラッパー
- 戻り値の加工をしない
- 回帰テスト確認: Phase 1 で「影響を受ける機能」として列挙した項目について、既存テストでカバーされていることを確認する。カバーされていない影響範囲がある場合は、回帰テストを追加する
- アサーション品質の確認: テストが意図した動作を実際に検証しているか確認する
- 機能を無効化してもテストがパスする場合、アサーションが不十分
- 浮動小数点の比較は許容誤差（tolerance）を使用する:
math.Abs(got-want) > 0.001
- エラーケースでは
t.Errorf / t.Fatalf を適切に使い分ける
- テスト追加後
make fmt でフォーマットし、テストを実行:
make test
Phase 5: ドキュメント更新 [自律実行可]
以下のドキュメントそれぞれについて更新が必要か判断し、必要なものを更新する。
- README.md: ユーザー向けドキュメント。新機能・設定オプション・キーバインドの追加時に更新する。
- CLAUDE.md: アーキテクチャに影響する変更（新モジュール追加、モジュール責務の変更、ポートインターフェースの変更）時に更新する。
実装とドキュメントの整合性チェック:
- CLI ヘルプテキスト（cobra コマンドの
Short/Long/Use フィールド）が実際の動作と一致しているか
- キーバインド説明が実際のキーマッピングと一致しているか
- 設定オプションのデフォルト値がドキュメントと config.go の定義で一致しているか
- 対応画像フォーマットの記載が実装と一致しているか
いずれのドキュメントも更新不要と判断した場合はその理由をユーザーに説明すること。
Phase 6: 品質チェック [自律実行可]
すべてのチェックを実行し、全てパスすることを確認する:
make ci
これは以下を順次実行する:
golangci-lint run ./... (lint)go test -race -coverprofile=coverage.out ./... (tests with race detector)go build -o ./bin/gaze ./cmd/gaze (build)
全チェックがパスするまで次に進まないこと。
失敗時の対応:
- エラー内容を分析し、修正を試みる
- 修正後
make ci を再実行する
- 3回連続で失敗した場合: エラー内容をユーザーに提示し、対処方針について相談する。自力での修正を続けないこと
Phase 7: 変更レビュー [確認必須]
git diff で変更内容を確認する- レビュー結果をユーザーに提示する:
- 変更ファイル一覧と各ファイルの変更行数
- 各変更の概要
- 潜在的な問題点（正確性、既存機能との整合性、エッジケース）
- 過去レビュー知見チェック:
.claude/review-lessons.md が存在する場合、記録されているパターンに該当する問題が diff に含まれていないか確認する
- 頻出チェックリスト（diff を以下の観点で確認する）:
Phase 8: コミットとPR作成 [確認必須]
ユーザーの承認後：
- コミット分割計画をユーザーに提示する。以下のルールで分割する:
- 1コミット = 1つの論理的変更
- 分割単位（優先度順）:
- コア実装の変更（1モジュール1コミットが目安。密結合した複数モジュールの変更は1コミットにまとめてよい）
- テストの追加（対応する実装コミットとは別にする）
- ドキュメントの更新（1コミットにまとめる）
- コミットメッセージ: Conventional Commits 形式 (
feat:, fix:, refactor:, test:, docs:)
- ユーザーの承認後にコミットを実行する
- draft PRを作成する。PR本文は pr-template.md に従う
- PRタイトル・本文は日本語で記述する（コード例・変数名・ファイルパスは英語のまま）
- コミットメッセージは英語の Conventional Commits 形式を維持する
- PR作成後、URLをユーザーに共有する
注意事項
- 破壊的な操作（force push, reset --hard, checkout ., clean -f 等）は絶対に行わないこと
- domain 層に外部パッケージの import を追加してはならない
- 新しい外部依存を追加する際は必要性を検討し、ユーザーに確認すること
