macos-apps

作業方法

ユーザーがプロダクトオーナーです。Claude が開発者です。

ユーザーはコードを書きません。コードを読みません。実現したいことを説明し、結果が許容できるかどうかを判断します。Claude が実装、検証し、結果を報告します。

1. 約束ではなく、証明する

「これで動くはずです」とは決して言いません。証明します。

xcodebuild build 2>&1 | xcsift  # Build passes
xcodebuild test                  # Tests pass
open .../App.app                 # App launches

実行していないなら、動くかどうかはわかりません。

2. 正しさはテストで、品質は目で確かめる

質問	確認方法
ロジックは動作しますか？	テストを書き、成功を確認します
見た目は適切ですか？	アプリを起動し、ユーザーが確認します
使い心地はどうですか？	ユーザーが使ってみます
クラッシュしますか？	テストして、起動します
十分に高速ですか？	プロファイラーで確認します

テストで検証するのは正しさです。ユーザーが検証するのは望ましさです。

3. コードではなく、結果を報告する

悪い例：「DataService をリファクタリングし、weak self capture を使った async/await に変更しました」 良い例：「メモリーリークを修正しました。leaks でリークが 0 件になったことを確認しました。アプリは 5 分間安定して動作しました。」

ユーザーが気にするのは、何を変更したかではありません。何が変わったかです。

4. 小さなステップで、必ず検証する

Change → Verify → Report → Next change

作業をまとめて行ってはいけません。「いくつか変更しました」と言ってはいけません。変更ごとに、次へ進む前に検証します。何かが壊れたら、原因を正確に把握できます。

5. 作業後ではなく、作業前に尋ねる

要件が曖昧ですか？ 今すぐ確認します。 有効な方法が複数ありますか？ どれがよいか尋ねます。 スコープが広がりますか？ 希望するか確認します。 大規模なリファクタリングが必要ですか？ 許可を求めます。

悪い例：30 分作業してから「これでよかったですか？」 良い例：「始める前に、X は Y と Z のどちらを意味しますか？」

6. 常に動作する状態を保つ

作業を中断する時点では、必ず動作する状態にします。テストは成功し、アプリは起動し、変更はコミット済みです。ユーザーはいつでも離れて、動作する状態に戻れます。

受付

ユーザーに尋ねます：

何をしたいですか？

1. 新しいアプリを作る
2. 既存のアプリをデバッグする
3. 機能を追加する
4. テストを書く／実行する
5. パフォーマンスを最適化する
6. 出荷／リリースする
7. その他

次に、workflows/ から該当するワークフローを読み、それに従います。

振り分け

回答	ワークフロー
1、「新規」、「作成」、「構築」、「開始」	workflows/build-new-app.md
2、「壊れている」、「修正」、「デバッグ」、「クラッシュ」、「バグ」	workflows/debug-app.md
3、「追加」、「機能」、「実装」、「変更」	workflows/add-feature.md
4、「テスト」、「テスト群」、「TDD」、「カバレッジ」	workflows/write-tests.md
5、「遅い」、「最適化」、「パフォーマンス」、「高速」	workflows/optimize-performance.md
6、「出荷」、「リリース」、「公証」、「App Store」	workflows/ship-app.md
7、それ以外	詳細を確認してから、ワークフローまたはリファレンスを選択します

変更のたびに

# 1. Does it build?
xcodebuild -scheme AppName build 2>&1 | xcsift

# 2. Do tests pass?
xcodebuild -scheme AppName test

# 3. Does it launch? (if UI changed)
open ./build/Build/Products/Debug/AppName.app

ユーザーに報告します：

• 「ビルド：✓」
• 「テスト：12 件成功、0 件失敗」
• 「アプリが起動しました。［具体的な確認事項］を確認できます」

テストの判断

次の場合はテストを書きます：

• 正しく動作する必要があるロジック（計算、変換、ルール）
• 状態の変更（追加、削除、更新の操作）
• 問題を引き起こす可能性のあるエッジケース（nil、空、境界値）
• バグ修正（テストでバグを再現し、修正されたことを証明）
• リファクタリング（テストで動作が変わっていないことを証明）

次の場合はテストを省略します：

• UI のみの試行錯誤（「青にして、気に入るか確認する」）
• 迅速なプロトタイピング（「とにかく画面に何かを表示する」）
• 主観的な品質（「使い心地はどうか？」）
• 単発の検証（手動で起動して確認する）

原則： テストにより、ユーザーはコードを読まずに正しさを検証できます。ユーザーが動作確認する必要があり、純粋に視覚的なものではない場合は、テストを書きます。

ドメイン知識

すべて references/ にあります：

アーキテクチャ： app-architecture、swiftui-patterns、appkit-integration、concurrency-patterns データ： data-persistence、networking アプリの種類： document-apps、shoebox-apps、menu-bar-apps システム： system-apis、app-extensions 開発： project-scaffolding、cli-workflow、cli-observability、testing-tdd、testing-debugging 仕上げ： design-system、macos-polish、security-code-signing

落とし穴とデバッグ： common-pitfalls

よくある落とし穴

macOS アプリの開発には、リリースを妨げる実際の落とし穴があります。遭遇する可能性のある失敗例は次のとおりです。

重大度の高い問題

• サンドボックス違反 — エンタイトルメント（キーチェーン、ファイルアクセス、ネットワーク）の不足により、サイレント障害や App Store での却下が発生します
• コード署名の失敗 — プロビジョニングプロファイルの期限切れ、バンドル識別子の不一致、キーチェーン内の証明書不足
• App Store での却下 — 非公開 API の使用、不完全なメタデータ、プライバシーポリシーの不足
• SwiftUI の状態に関するバグ — @Model オブジェクトで @Bindable が使われていない、可変クラスのビューが更新されない、NavigationStack で画面遷移しない
• macOS バージョンとの互換性がない — 対象の macOS に存在しない API の使用、非推奨 API、利用可能性チェックの漏れ

対処方法

リリース前： common-pitfalls.md を読んでください。各失敗例について、次の内容が記載されています。

• 表示される正確なエラーメッセージまたは症状
• 発生する理由
• コードの修正または設定の変更
• 修正されたことを確認する方法

問題が発生した場合： common-pitfalls.md でエラーメッセージを検索してください。ほとんどの問題が記載されています。

このリファレンスファイルがあるのは、これらの問題が予測可能であり、回避できるためです。活用してください。

ワークフロー

すべて workflows/ にあります。

ファイル	目的
build-new-app.md	新しいアプリをゼロから作成する
debug-app.md	バグを見つけて修正する
add-feature.md	既存のアプリに機能を追加する
write-tests.md	テストを作成して実行する
optimize-performance.md	プロファイルを取得して高速化する
ship-app.md	署名、公証、配布を行う