agentleFS
apokamoapokamo/kaji/.claude/skills/issue-fix-design/SKILL.md

issue-fix-design

Skill16 starsChanged 2 days agoApache-2.0View on GitHub

設計レビューの指摘事項に基づき、設計ドキュメントを修正または議論する。

The file

Files
SKILL.md

Issue Fix Design

設計レビューで指摘された内容に対し、論理的な妥当性を検討した上で、設計ドキュメントを更新します。

いつ使うか

タイミングこのスキルを使用
/issue-review-design で Changes Requested 後✅ 必須
一次情報の記載を求められた後✅ 必須

ワークフロー内の位置: design → review-design → (fix → verify) → implement

入力

ハーネス経由(コンテキスト変数)

常に注入される変数:

変数型説明
issue_idstr正規化済み Issue ID(GitHub 数値)
issue_refstr人間可読の Issue 参照(GitHub では #<issue_id>)
step_idstr現在のステップ ID

条件付きで注入される変数:

変数型条件説明
previous_verdictstrresume 指定ステップ前ステップの verdict
cycle_countintサイクル内ステップのみ現在のイテレーション番号
max_iterationsintサイクル内ステップのみサイクルの上限回数

手動実行(スラッシュコマンド)

$ARGUMENTS = <issue_id>

解決ルール

コンテキスト変数 issue_id が存在すればそちらを使用。 なければ $ARGUMENTS の第1引数を issue_id として使用。

issue_ref はハーネス経由ではプロンプトに自動注入される(prompt.py 側で provider 別に整形)。手動実行時は issue_id から #<issue_id> を導出する。

前提知識の読み込み

以下のドキュメントを Read ツールで読み込んでから作業を開始すること。

  1. テスト規約: docs/dev/testing-convention.md
  2. コーディング規約: docs/reference/python/python-style.md
    • 必要に応じて docs/reference/python/naming-conventions.md / type-hints.md / docstring-style.md / error-handling.md / logging.md を追加読込
  3. 開発ワークフロー: docs/dev/development_workflow.md

共通ルール

  • _shared/report-unrelated-issues.md — 作業中に発見した無関係な問題の報告ルール

実行手順

Step 1: コンテキスト取得

  1. _shared/worktree-resolve.md の手順に従い、Worktree の絶対パスを取得。
  2. レビュー結果の取得:
    1. コンテキスト変数 previous_verdict が存在する場合はそれを確認(ハーネス経由)
    2. 存在しない場合は Issue コメントから最新のレビュー結果を取得(手動実行時)
  3. レビュー内容の取得:
    kaji issue view [issue_id] --comments
    最新の「設計レビュー結果」を取得。
  4. 設計書の現状確認:
    cat [worktree_dir]/draft/design/issue-[issue_id]-*.md

Step 2: 対応方針の検討

各指摘事項について検討します。

一次情報の追記を求められた場合

設計書に「参照情報(Primary Sources)」セクションを追加:

## 参照情報(Primary Sources)

| 情報源 | URL/パス | 根拠(引用/要約) |
|--------|----------|-------------------|
| (公式ドキュメント名) | (URL) | (設計判断の裏付けとなる引用または要約) |

一次情報の例:

  • 公式ドキュメント(Python、Pydantic、typer 等)
  • RFC、仕様書
  • ライブラリのソースコード(GitHub URL)
  • API仕様書(OpenAPI等)

根拠の書き方:

  • 引用: 「〜である」(原文ママ)
  • 要約: 〜が推奨されている(要約)

アクセス可能性ルール:

レビュワー(agent)がアクセスできない一次情報は使用できません。

情報の種類対応方法
公開URLそのまま記載(推奨)
ログイン必須/有償ローカルにダウンロードしてリポジトリに配置、または該当箇所を引用
社内限定/NDA使用不可。公開版ドキュメントを探すか、該当箇所のスクリーンショット・引用で代替

その他の指摘事項

  • A: 修正する (Agree)
    • 指摘により設計がより明確になる、矛盾が解消される、使い勝手が向上する場合。
  • B: 反論する/議論する (Discuss)
    • 指摘が要件定義から逸脱している、実装コストが過大になる、あるいは別のトレードオフがある場合。
    • 設計には「正解」がないことが多いため、なぜその設計にしたかの Rationale(根拠) を明確にして回答する。

Step 3: 設計書の更新

指摘を受け入れる場合、設計書を修正します。

Step 4: コミット

cd [worktree_dir] && git add draft/design/ && git commit -m "docs: update design for [issue_ref]"

Step 5: 結果報告

Issueにコメントします:

verdict マーカーの無条件付与(必須): 判定コメントには 常に --verdict-step fix-design --verdict-status <STATUS> を付ける。<STATUS> は本 skill が「Verdict 出力」で返す status(PASS / ABORT)に置き換える。CLI が body 1 行目に <!-- kaji-verdict: step=fix-design status=<STATUS> --> を付け、kaji issue resolve-verdict --step fix-design と runner の comment fallback はこの marker で発行元 step を特定する。PASS でも省略しない(条件付きの付与は禁止。docs/dev/shared_skill_rules.md § verdict マーカー契約)。投稿前に判定を確定してから status を決める。

kaji issue comment [issue_id] --commit \
  --verdict-step fix-design --verdict-status <STATUS> \
  --body-file - <<'EOF'
# 設計修正報告

## 対応済み

- **(指摘内容)**
  - 修正: (どのように設計を変更したか)

## 議論/見送り

- **(指摘内容)**
  - 理由: (なぜその設計を維持するのか、トレードオフの説明)

## 次のステップ

`/issue-verify-design [issue_id]` で修正確認をお願いします。
EOF

Step 6: 完了報告

以下の形式で報告してください:

## 設計修正完了

| 項目 | 値 |
|------|-----|
| Issue | [issue_ref] |
| 対応済み | N 件 |
| 見送り | M 件 |

### 次のステップ

`/issue-verify-design [issue_id]` で修正確認を実施してください。

Verdict 出力

実行完了後、以下の形式で verdict を出力すること:

---VERDICT---
status: PASS
reason: |
  修正完了
evidence: |
  全指摘事項に対応済み
suggestion: |
---END_VERDICT---

重要: verdict は stdout にそのまま出力 すること。Issue コメントや Issue 本文更新とは別に、最終的な verdict ブロックは stdout に残す。

status の選択基準

status条件
PASS修正完了
ABORT修正不可能

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.