Menu
設計ドキュメントに対し、汎用的なソフトウェア設計原則に基づいてレビューを行う。
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
dev workflow 向けの最終チェック。PR 前に品質ゲート、docs 整合、設計書昇格、Issue 更新をまとめて確認する。
docs-only workflow 向けの最終チェック。docs 整合と Issue 状態を確認し、PR に進めるか判定する。
docs review の指摘に対応し、ドキュメントのみを修正する。コードやテストは変更しない。
docs-only の変更をレビューし、事実整合性・実装整合性・運用整合性の観点から判定する。
docs-only の更新を行う。コードやテストは変更せず、現行実装・CLI・運用方針との整合を確認しながら docs を修正する。
docs review の指摘が適切に修正されたかを確認する。新規指摘は行わない。
| description | 設計ドキュメントに対し、汎用的なソフトウェア設計原則に基づいてレビューを行う。 |
| name | issue-review-design |
重要: このスキルは実装/設計を行ったセッションとは 別のセッション で実行することを推奨します。 同一セッションで実行すると、実装時のバイアスがレビュー判断に影響する可能性があります。
実装フェーズに入る前に、設計ドキュメントの品質を検証します。 特定の実装詳細（How）に依存せず、要件（What）、制約（Constraints）、および利用者視点（UX）が明確に定義されているかを確認します。
| タイミング | このスキルを使用 |
|---|---|
| 設計完了後、実装開始前 | ✅ 必須 |
| 仕様変更時の再レビュー | ⚠️ 推奨 |
ワークフロー内の位置: design → review-design → (fix → verify) → implement
常に注入される変数:
| 変数 | 型 | 説明 |
|---|---|---|
issue_id | str | 正規化済み Issue ID（GitHub 数値または local ID） |
issue_ref | str | 人間可読の Issue 参照（GitHub では #<issue_id>、local では bare ID） |
step_id | str | 現在のステップ ID |
条件付きで注入される変数:
| 変数 | 型 | 条件 | 説明 |
|---|---|---|---|
cycle_count | int | サイクル内ステップのみ | 現在のイテレーション番号 |
max_iterations | int | サイクル内ステップのみ | サイクルの上限回数 |
$ARGUMENTS = <issue_id>
コンテキスト変数 issue_id が存在すればそちらを使用。
なければ $ARGUMENTS の第1引数を issue_id として使用。
issue_ref はハーネス経由ではプロンプトに自動注入される（harness が provider 別に整形する）。手動実行時は issue_id から導出する: GitHub 数値 ID なら #<issue_id>、local-* 形式なら bare ID（# を付けない）。
以下のドキュメントを Read ツールで読み込んでから作業を開始すること。
docs/dev/testing-convention.mddocs/reference/python-standards.mddocs/dev/kaji-workflow.md_shared/worktree-resolve.md の手順に従い、 Worktree の絶対パスを取得すること。以降のステップではこのパスを使用する。
設計書の読み込み:
cat [worktree_dir]/draft/design/issue-[issue_id]-*.md
一次情報の記載を確認:
設計書に以下が明記されているか確認：
設計書に一次情報の記載がない、または不十分な場合は、レビュー本体に入らず以下のコメントを投稿して終了：
uv run kaji issue comment [issue_id] --commit --body-file - <<'EOF'
# 設計レビュー：一次情報の記載が必要
## 指摘事項
設計書に**一次情報（Primary Sources）の記載がありません**。
設計レビューを行うには、以下を設計書に追記してください：
### 必要な情報
1. **参照した一次情報の一覧**
- 公式ドキュメント、RFC、API仕様書、ライブラリのソースコード等
- URLまたはファイルパスを明記
2. **一次情報から得た根拠**
- 設計判断の裏付けとなる情報を引用または要約
### 例
\`\`\`markdown
## 参照情報（Primary Sources）
| 情報源 | URL/パス | 根拠（引用/要約） |
|--------|----------|------------------------|
| Python公式ドキュメント | https://docs.python.org/... | 「〜を使用することで...」（該当箇所の引用） |
| Pydantic 2 Migration | https://docs.pydantic.dev/... | 〜が推奨されている（要約） |
\`\`\`
## 判定
❌ **Changes Requested** - 一次情報を追記後、再度レビューを依頼してください。
### 次のステップ
\`/issue-fix-design [issue_id]\` で一次情報を追記
EOF
この時点でレビュー終了。Step 2以降は実行しない。
一次情報が記載されている場合のみ、このステップに進みます。
重要: レビュー時は設計書の記述だけでなく、一次情報を実際に参照して整合性を確認してください。
一次情報にアクセスできない場合は Changes Requested として設計者に対応を求めてください。
対応方法は issue-design の「一次情報のアクセス可能性ルール」を参照：
Issue ラベルから type:* ラベルを 配列として 取得し、共通観点の重み付けを調整する:
uv run kaji issue view [issue_id] --json labels --jq '[.labels[].name] | map(select(startswith("type:")))'
cardinality チェック（先に判定）:
/issue-review-ready への差し戻しを Must Fix として投稿する（observation: 複数 type ラベル付与）。Changes Requested で停止する/issue-review-ready への差し戻しを Must Fix として投稿する（observation: type ラベル未付与）type 値による分岐:
type:feature / type:bug / type:refactor / type:docs） → 対応する重み付けを適用type:test / type:chore / type:perf / type:security など） → type:feature と同等に扱う（フォールバック規則）type 別重み付け（共通観点 1〜5 に対する強調度）:
| 観点 | feat | bug | refactor | docs |
|---|---|---|---|---|
| 1. 抽象化と責務の分離 | 高（IF 設計が中心） | 中 | 高（責務再編が主題） | — |
| 2. インターフェース設計 | 高（使用例・命名・idiom 必須） | 低（IF 原則不変） | 中（IF 不変の確認） | — |
| 3. 信頼性とエッジケース | 高（新規ロジックのエラー系） | 高（OB/EB 整合・同根の漏れ） | 低（振る舞い非変更） | — |
| 4. 検証可能性（テスト戦略） | 高（S/M/L 網羅） | 高（再現テスト必須） | 高（safety net・bridging test） | — |
| 5. 影響ドキュメント | 高 | 中 | 中 | 高（docs-only なら主題） |
type 固有の追加観点:
/i-doc-review の守備範囲。dev workflow の review-design に来るのは誤経路 → /i-doc-update への差し戻しを検討重み付けの運用: 上表で「高」にあたる観点で不足があれば Must Fix として CR 判定。「低」は Should Fix に留める。type に関係しない観点（共通）の指摘は従来通り Must / Should を内容に応じて判断する。
以下の汎用的な原則に基づいてレビューしてください。
抽象化と責務の分離 (Abstraction & Scope):
インターフェース設計 (Interface Design):
信頼性とエッジケース (Reliability):
検証可能性 (Testability):
docs/dev/testing-convention.md 準拠）:
uv pip install -e . など副作用のある検証を行う場合、隔離方針が明記されているかtesting-convention.md の「実行時の振る舞いを変える変更」節参照）: ドメインロジック追加・条件分岐追加・データ変換仕様変更・API 契約変更・過去障害の再発防止。これらに該当する変更でテストを省略している場合は Changes Requested影響ドキュメント:
Issue 本文に ## 完了条件 セクションがある場合、設計が完了条件を充足できる構造になっているか確認する。
確認対象の例:
確認結果は Step 3 の Issue コメントに含めて後段への証跡とする。
レビュー結果をGitHub Issueにコメントします。
uv run kaji issue comment [issue_id] --commit --body-file - <<'EOF'
# 設計レビュー結果
## 参照した一次情報
（レビュー時に確認した一次情報とその確認結果）
| 情報源 | 確認結果 |
|--------|----------|
| [URL] | ✅ 設計と整合 / ⚠️ 差異あり |
## 概要
(設計の明確さと、実装着手の可否判定)
## 指摘事項 (Must Fix)
- [ ] **項目**: 指摘内容
- (要件の欠落、論理的な矛盾、不明確なインターフェースなど)
- **一次情報との関連**: （該当する場合）
## 改善提案 (Should Fix)
- **項目**: 提案内容
- (より良い命名、将来性を考慮した構造の提案など)
## 完了条件の段階確認
設計段階の完了条件に対する充足判定:
- [ ] (条件1): ✅ 設計書の○○で対応 / ❌ 不足（理由）
- [ ] (条件2): ✅ / ❌
## 判定
[ ] Approve (実装着手可)
[ ] Changes Requested (設計修正が必要)
EOF
以下の形式で報告してください:
## 設計レビュー完了
| 項目 | 値 |
|------|-----|
| Issue | [issue_ref] |
| 判定 | Approve / Changes Requested |
### 次のステップ
- Approve: `/issue-implement [issue_id]` で実装を開始
- Changes Requested: `/issue-fix-design [issue_id]` で修正
実行完了後、以下の形式で verdict を出力すること:
---VERDICT---
status: PASS
reason: |
設計品質基準を満たしている
evidence: |
一次情報との整合性確認済み、テスト戦略 S/M/L 網羅
suggestion: |
---END_VERDICT---
重要: verdict は stdout にそのまま出力 すること。Issue コメントや Issue 本文更新とは別に、最終的な verdict ブロックは stdout に残す。
| status | 条件 |
|---|---|
| PASS | Approve |
| RETRY | Changes Requested |
| ABORT | 重大な問題 |