agile-refinement

リファインメント

このスキルでは、計画成果物を検証し、コード品質をレビューします。計画のリントとコードレビューの 2 つのモードで動作します。

スラッシュコマンド経由で受け取った初期コンテキスト：$ARGUMENTS

$ARGUMENTS が入力されている場合（例：ファイルパス、ブランチ、「planning」、「code」）、それをモードを決定する出発点として使用します。 空の場合は、計画成果物とコード変更のどちらを検証するか、ユーザーに尋ねてください。

言語

レポートはすべてユーザーの言語で作成してください。適切な文法と、必要な発音区別符号や各言語固有の文字を使用してください。ユーザーの言語が明確でない場合は、出力を作成する前に尋ねてください。

プロジェクトルート

このスキルが成果物を作成するパスは、エージェントの現在の作業ディレクトリではなく、作業が行われるリポジトリであるプロジェクトルートからの相対パスです。

• プロジェクト内から実行する場合は、このスキルに記載されている相対パスを使用します。
• 別のディレクトリ（例：隣接するリポジトリ、またはプロジェクトが別の場所にある場合）から実行する場合は、すべての成果物パスの先頭に <project-root>/ を付けます。
• プロジェクトルートが不明確な場合は、書き込みの前にハーネスの質問ツールを使ってユーザーに確認してください。

プロンプト

CLAUDE.md / AGENTS.md に記載されているプロジェクト全体の規約（「Skill Prompting Conventions」）に従ってください。以下の判断が必要な場面では、ハーネスの構造化質問ツール（Claude Code の AskUserQuestion、Codex の ask_user_question、または OpenCode の question）を使用してください。

判断項目	構造化する理由	推奨される選択肢
対象	ワークフローが分岐します	計画成果物 · コード · 両方
深度	レビューにかける労力が変わります	リントのみ · フルレビュー · セキュリティ重視

自由形式のプロンプト（構造化ツールなし）：

• レビュー対象のファイルパス
• 具体的な懸念事項

一時停止なしモード：ユーザーがスキルの途中での確認を明示的に無効にしている場合は、構造化プロンプトをすべて「未解決の質問」（または同等の項目）に記載し、停止せずに続行してください。

目的

• 計画成果物の一貫性、完全性、正確性を検証する
• コード変更のセキュリティ、一貫性、スコープ、品質をレビューする
• 実行中に問題が発生する前に発見する
• 一般論ではなく、具体的で実行可能なフィードバックを提供する

使用する場面

• 実装を始める前 — 計画成果物をリントする
• コードをコミットする前 — 差分をレビューする
• プルリクエストを作成するとき — 品質ゲートとして使用する
• AI が生成したコードをレビューするとき — 人間同等のレビューを行う
• 定期的に — 古くなった内容、壊れた相互参照、対応する参照元のない成果物を確認する
• エピックのマージまたは完了時 — すべての要素が整合していることを検証する

使用しない場面

• 計画成果物を作成する場合 — /agile-intake、/agile-epic、/agile-story、/agile-roadmap を使用する
• 作業をストーリーに分解する場合 — /agile-epic を使用する（現在は分解にも対応しています）
• デリバリーの進捗を追跡する場合 — /agile-status を使用する
• スプリントを計画する場合 — /agile-sprint を使用する

モード 1：計画のリント

以下の項目に照らして計画成果物を検証します。

相互参照

• Origin フィールドが存在するファイルを指している
• 参照されているエピック、ストーリー、タスクが存在する
• 相互参照に記載されたファイルパスが正しく、ファイルが存在する

依存関係

• ストーリー／タスク間で宣言された依存関係が存在する
• 循環依存がない
• 依存関係の順序がロードマップ／エピックの順序と一致している

完全性

• 必須セクション（Context、Files、Detail、Tasks、Verification）が存在する
• 必須フィールドに空欄がない
• 受け入れ基準が定義され、検証可能である
• タスクが具体的で実行可能である（曖昧でない）

プロダクトのトレーサビリティ

• UI の比重が大きいエピック／ストーリーでは、プロトタイプが存在する場合、プロトタイプのルート／画面を参照している
• ドメインの動作では、ビジネスルールが存在する場合、business/*.md のルール ID／ファイルを参照している
• プロトタイプに、内部実装やビジネスルールの説明をプロダクト上に表示する文言として含めていない
• プロトタイプのレビュー中に見つかったビジネスルールを、プロトタイプ以外に記録している
• 計画成果物に、秘密情報、プロバイダーキー、トークン、認証情報をそのまま記載していない

一貫性

• 関連する成果物間（エピック内のストーリー間）で、サイズの基準に一貫性がある
• ステータスフィールドが最新である
• ファイル間で命名規則が一致している

形式

• ファイル名が規則（00-overview.md、NN-story-name.md）に従っている
• フォルダー構成が規則（planning/<initiative>/epics/NN-<epic>/）に従っている
• テンプレートが適切に記入されている（プレースホルダーのテキストが残っていない）

スコープの競合

• 同じエピック内のストーリー間で、スコープが重複していない
• スコープ外の項目がタスクとして参照されていない

古いコンテンツ

• すべてのタスクが完了しているのに、ステータスが「進行中」のままの成果物がない
• 削除または移動されたファイルを参照していない
• 未完了のタスクがあり、最近の日次更新もない、30日を超える古い計画がない

プロセス

1. スコープを特定します。単一のファイル、エピックフォルダー、または planning/ ツリー全体です。
2. スコープ内のすべての成果物を読みます。
3. 上記の各チェック項目を実施します。
4. カテゴリーごとに分類し、具体的な問題と該当箇所を含むインラインレポートを作成します。

モード 2：コードレビュー

~/.agents/rules/code-review.md のチェックリストを適用して、変更されたコードをレビューします。

セキュリティ

• 入力が検証され、サニタイズされている
• SQL インジェクション、XSS、コマンドインジェクション、SSRF がない
• ハードコードされた秘密情報がない
• 該当する場合、認証と認可が正しい
• ログやレスポンスに機密データが露出していない

プロジェクトとの一貫性

• リポジトリのパターンと規約に従っている
• 既存のコンポーネント、ユーティリティ、ヘルパーを使用している
• 車輪の再発明をしていない
• コードベース全体で命名に一貫性がある
• インポートがプロジェクトの規約に従っている

過剰な設計

• 時期尚早な抽象化がない
• 起こり得ないシナリオへのエラー処理がない
• 仮定上の要件に対する汎用化がない

スコープ

• コードが依頼された内容だけを実行する
• 無関係なコードをリファクタリングしていない
• 依頼されていない機能を追加していない

品質

• テストが受け入れシナリオを網羅している
• 説明コメントがなくてもコードを読みやすい
• 関数が小さく、単一の責任を持っている
• ロジックの重複がない
• システム境界でエラーを処理している

完全性

• リントが通る
• 型チェックが通る
• テストが通る
• 差分全体を確認している

プロセス

1. スコープを特定します。ブランチ、ファイル、または作業ツリーの変更です。
2. 出力する前に、差分全体を読みます。
3. 各チェック項目を適用します。
4. カテゴリーごとに分類したインラインレポートを作成します。
5. 即時却下の根拠となる重大な問題を明示します。

出力

このスキルは保存済みの成果物を作成しません。次の内容を含むインラインレポートを作成します。

• カテゴリー別に分類された問題
• 重大度：重大な問題（却下）、警告（続行前に修正）、情報（検討）
• 該当する場合は、具体的なファイルと行の参照
• 各問題に対する実行可能な提案

ルール

• 出力する前に、スコープ内のすべてを読みます。
• 具体的に指摘します。「コードがよくない」は実行可能な指摘ではありません。「src/middleware/rate-limit.ts の 42 行目で RateLimitError を HttpError に置き換える」のように示します。
• AI によるコードレビューは、人間によるコードレビューに取って代わるものではありません。追加のゲートとして実施します。
• 計画のリントはいつでも実行できます。儀式ではなく、健全性チェックです。
• 曖昧で一般的なフィードバックは決してしません。すべての問題は検証可能である必要があります。

ワークフローとの関係

flowchart LR
    A["/agile-epic"] --> B["/agile-refinement<br>(planning lint)"]
    C["/agile-story"] --> D[execution]
    D --> E["/agile-refinement<br>(code review)"]
    E --> F["/agile-status"]

このスキルは、ワークフローのどの時点でも成果物とコードを検証します。計画成果物を作成するには /agile-epic または /agile-story を使用します。進捗を追跡するには /agile-status を使用します。