新機能を追加

クライアントのフィーチャーリクエストが月曜日の朝にプロジェクト管理ツールに届きます。金曜日までにステージングに入れる必要があります。それがアウトソーシングのリズムです。明確な要件、タイトなウィンドウ、試行錯誤の余地なし。Sun Agent Kitはフィーチャー開発サイクル全体を構造化します。実際のコードベースに照らし合わせてアプローチを計画し、小さく検証されたステップで実装し、テストし、PRに送る前にレビューを受けます。

概要

目標: クライアントが要求したフィーチャーをチケットからレビュー済み・テスト済み・マージ可能なコードへと届ける
所要時間: 30〜120分（手動では4〜16時間）
使用エージェント: planner、implementer、tester、reviewer
コマンド: /sk:plan、/sk:cook、/sk:test、/sk:code-review

前提条件

• Sun Agent Kitがインストール済みで、プロジェクトが事前にインデックス済みであること
• 明確なフィーチャーの説明 — チケットのテキスト、受け入れ基準、またはクライアントのメッセージで可
• 開始前にプロジェクトがコンパイルされ、既存テストが合格していること（npm test で確認）
• フィーチャーブランチをチェックアウト済みであること（git checkout -b feature/your-feature-name）

ステップバイステップのワークフロー

ステップ1：実際のコードベースに照らしてフィーチャーを計画する

/sk:plan "add a dark mode toggle to the user dashboard — persists the preference in the database, applies via a CSS class on the root element, respects the system OS preference on first visit"

処理内容: エージェントが以下を実行します：

1. 関連するコンポーネント、フック、エンドポイント、データベーステーブルを見つけるためコードベースを分析
2. 順序付きステップ（DBマイグレーション、API、フック、UIコンポーネント）を含む実装計画を作成
3. 影響を受けるモジュールをインポートしているファイルを特定し、監査対象としてフラグ
4. 実装前のレビュー用に計画を plans/ に保存

ステップ2：フィーチャーを実装する

/sk:cook "implement dark mode toggle per the plan in plans/phase-dark-mode.md"

処理内容: エージェントが計画に従ってステップバイステップで実行します：

1. 新しいカラムを追加するデータベースマイグレーションを作成
2. 新しいフィールドを受け入れて永続化するためにAPIエンドポイントを更新
3. すべてのモードをサポートするためフロントエンドフックを拡張し、依存コンポーネントを監査
4. UIコンポーネントを作成してレイアウトに統合
5. コンパイルエラーがゼロであることを確認するためタイプチェックを実行

ステップ3：テストスイートを実行する

/sk:test "test the dark mode feature: theme persistence, API endpoint, hook behavior, and the system preference detection"

処理内容: エージェントが以下を実行します：

1. APIエンドポイント、フックの動作、UIコンポーネントをカバーするテストケースを作成
2. 既存のテストスイートと並行して新しいテストを実行し、リグレッションを確認
3. 変更されたファイルのカバレッジをレポート

ステップ4：コードレビューを依頼する

/sk:code-review "review the dark mode implementation for code quality, edge cases, and anything I should fix before the PR"

処理内容: エージェントが以下を実行します：

1. ロジックの正確性、セキュリティ、エッジケースについて変更された各ファイルをレビュー
2. 潜在的な問題をフラグ（例：サーバーサイドレンダリングでのFOUC、ローディング状態の欠落）
3. 分類された指摘事項を含むレビューレポートを plans/reports/ に保存

ステップ5：レビューフィードバックを反映してリリースする

/sk:cook "apply the 2 review fixes: prevent flash of unstyled content on initial render, add loading state to the theme toggle during the PATCH request"

処理内容: エージェントがレビューレポートの各修正を適用し、その後テストスイートを再実行してリグレッションがないことを確認します。

完全な実例：クライアントがダッシュボードにダークモードトグルを求めている

シナリオ: クライアントのデザインチームからFigmaリンクとチケットが届きます。「ユーザーからダークモードのリクエストがあります。上部ナビバーにトグルを設置し、プロフィールに保存し、デフォルトはシステム設定に従ってください。」チケットは木曜日までにステージングに入れる必要があります。現在は火曜日です。

火曜日の朝 — フィーチャー開発サイクル全体:

# ステップ1: 何かを書く前に既存の実装を理解する
/sk:scout "what theming or CSS variable infrastructure already exists in this project? Any partial dark mode work? Check the design system, globals.css, and any theme context."

# ステップ2: そのコンテキストを踏まえて計画する
/sk:plan "dark mode toggle: DB persistence to user_preferences, CSS variable-based theming, system preference default, toggle in DashboardLayout navbar, smooth transition on switch"

# ステップ3: 計画に従って実装する
/sk:cook "implement dark mode per plans/phase-dark-mode.md — follow the plan exactly, don't add anything not in the plan"

# ステップ4: 徹底的にテストする — クライアントが直接QAを行う
/sk:test "full test coverage for dark mode: API, hook, component, SSR flash prevention, accessibility"

# ステップ5: PRを上げる前にレビューする
/sk:code-review "review dark mode implementation — focus on edge cases: users with no preference set, users switching from system to explicit, the SSR hydration path"

# ステップ6: コミットしてプッシュ
/sk:git cm

結果: フィーチャーは水曜日の午後にステージングに入り、締め切りの1日前です。クライアントは木曜日の朝にレビューして承認します。手動での見積もり：2〜3日。

時間の比較

ベストプラクティス

1. 不慣れな領域では /sk:plan の前に必ず /sk:scout を実行する ✅

計画はコンテキストの質によってのみ良いものになります。触れたことのないモジュールに追加する場合は、まずスカウトしてください。5分のスカウトで、計画が既存のインフラを考慮していないことによる1時間の手戻りを防ぎます。

2. cook プロンプトを計画のスコープに限定する ✅

/sk:cook に計画ファイルに従うよう伝えてください。フィーチャーを口頭で説明すると、計画で定めたものとは異なるアーキテクチャ上の判断をする可能性があり、計画とコードの間にずれが生じます。

3. PRを上げる前にレビューフィードバックを修正する ✅

レビュアーエージェントの出力はPR前のゲートであり、任意のコメントではありません。些細に思えても指摘された問題を修正してください。クライアントのレビューに達する「non-blocking」の問題は、未完成の作業のように見えます。

4. /sk:cook に求めていないものを追加させる ❌

計画が「テーマトグルを追加する」と言っているのに、cookが6つの新しいファイルを含む完全なテーミングシステムを生成する場合は、/sk:cook "implement only what is in the plan, nothing extra" を実行してください。実装のスコープクリープはレビューとテストのスコープクリープにつながります。

5. レビュー修正後に /sk:test を実行しない ❌（このステップをスキップする）

レビュー修正はコードを変更します。変更されたコードはテストを壊すことがあります。修正が些細に見えても、レビューフィードバックを適用した後には必ず /sk:test を実行してください。

トラブルシューティング

問題：/sk:cook が計画から逸脱して余分なスコープを追加する

解決策: 計画ファイルを明示的に参照してください: /sk:cook "implement only the steps in plans/phase-dark-mode.md step 2 — nothing else"。

問題：/sk:test がすべてをモックしてほとんど意味のないテストを書く

解決策: テストエージェントを誘導してください: /sk:test "write integration tests that test the actual database write and read for theme preference — no mocking the DB layer"。

問題：/sk:code-review が問題を指摘するが修正方法を提示しない

解決策: 直接聞いてください: /sk:ask "how should I fix the FOUC issue flagged in plans/reports/review-dark-mode.md — what's the standard pattern for this in Next.js?"。

問題：フィーチャーがローカルでは動作するがCIビルドで失敗する

解決策: /sk:fix "CI build failing after dark mode feature — error: [paste error]" を実行してください。エージェントはローカルとCI間の環境差異を処理します。

次のステップ

• バグを体系的に修正 — フィーチャーがリグレッションを引き起こし、構造化された調査が必要な場合
• REST APIを構築 — フィーチャーが先に新しいAPIレイヤーの構築を必要とする場合
• 認証を実装 — ユーザーのアイデンティティと認可に依存するフィーチャーの場合

重要なポイント: フィーチャーが締め切りに遅れるのはエンジニアが遅いからではありません。計画されていない実装が予期しない複雑さに直面するからです。/sk:plan は1行も書く前に驚きをなくします。