菜单
PR の探索的検証で 5 並列 subagent を category 別に kick する際の運用規約。 PDCA / MCP / 設定ファイル拡張 / CI ログ / apiDump / ticket 起票 / PR コメント / gradle 隔離 / working tree / 時間管理 / 他 KCP 比較 / 各 cat 役割 / ループ終了処理 / メンテナ反応 latency trace / close 後 handshake を含む。 各探索 iter で subagent を kick する前に必読。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | exploratory-pr-verification |
| description | PR の探索的検証で 5 並列 subagent を category 別に kick する際の運用規約。 PDCA / MCP / 設定ファイル拡張 / CI ログ / apiDump / ticket 起票 / PR コメント / gradle 隔離 / working tree / 時間管理 / 他 KCP 比較 / 各 cat 役割 / ループ終了処理 / メンテナ反応 latency trace / close 後 handshake を含む。 各探索 iter で subagent を kick する前に必読。 |
| model | opus |
PR の探索的検証で 5 並列 subagent を kick する際の標準ルール。 各 iter で subagent を起動する前に本ファイルを参照し、 prompt に必要事項を組み込む。
過去 phase で ユーザが 4 回以上繰り返し指摘した 最重要ルール。 §1 以降の細則より優先する:
1 ループ完了通知後に「次どうしますか?」 とユーザに聞き返す行為は 禁止。 §17 終了条件 list を機械的に通し、 未達なら次 iter を即 kick、 達成なら close 処理 → 終了報告。 メンテナ反応待ちで動的検証が薄い時間も止まらず ticket 整理 / FINAL-SUMMARY update / cluster 分析で deadline まで埋める。
過去事例: 4 回繰り返し指摘されるまで §17 が skill 化されず、 各 iter 完了後に聞き返す事故で総合効率 -20-30%。
ユーザが運用上の指摘 (新ルール / 追加観点 / プロセス改善) を 1 回でも すれば、 即本 SKILL.md に反映する。 ad-hoc に適用 (= memory / 一時 prompt 調整) で済ませると、 次 iter 以降 drift する。
反映 flow:
過去事例: skill 化 lag = 平均 5-10 iter (全 20 iter の 25-50%)、 反省会自体も PR 作成後に依頼される始末。
git fetch origin <branch> + git rev-list --count HEAD..origin/<branch> で force-push 検出git reset --hard origin/<branch>)、 working tree が dirty なら revert してからmodel: opus、 run_in_background: true)⚠️ 止まらないこと: 1 ループ完了通知後に「次どうしますか?」 とユーザに聞き返さない。 §17 の終了条件 check list を機械的に回し、 未達なら自動で次 iter (= step 1 から) に戻る。 メンテナ反応待ちの場合は ticket 整理 / FINAL-SUMMARY update / cluster 分析 / 既存 ticket の重複統合などで時間を埋め、 deadline まで一切止まらない。
各 iter で 5 並列、 各 cat に autonomous な angle 選択権 を渡す:
| cat | 担当領域 | gradle 必要 | 主な活動 |
|---|---|---|---|
| cat1 | ソースコード静的 | ✗ | KDoc / SoT 違反 / type design / silent failure / comment drift / brittleness / semver |
| cat2 | PR・環境・docs・CI | ✗ | PR description / README / docs site / CI ログ + warning grep / api dump 静的 / ChangeLog |
| cat3 | 動的 build / test | ✓ (隔離 cache) | 主要 task 再走 / apiDump roundtrip / publishToMavenLocal jar 検査 / compat-k* |
| cat4 | e2e / happy path | ✓ (隔離 cache) | MCP 必須 (Playwright/Maestro/jetbrains/claude-in-chrome)、 dev module 改造で end-to-end |
| cat5 | 比較 / 残角度 | ✗ or ✓ | 他 KCP 比較 (Metro/Compose Compiler/kotlinx.serialization/Power-Assert/kotlinx-rpc/SKIE/Koin Compiler/Mokkery/Poko) / stress 残 / locale / interop |
cat5 は飽和したら他比較に rotate (現方針)。
cat3/cat4/cat5 等 動的検証時は 5 段階で実施:
build.gradle.kts (各 module + root + buildLogic)settings.gradle.kts (composite build / module 構成 / includeBuild)gradle.properties (kotlin compiler options / android settings / org.gradle.jvmargs / kotlin.code.style 等)libs.versions.toml (version catalog / Kotlin / AGP / Compose 切替)apiValidation { ... } ブロック / ignoredPackages / ignoredKlibPackages / nonPublicMarkerslocal.properties (sdk path 等)consumer-rules.pro / proguard-rules.pro (Android).kotlin-version / .tool-versions:dev:jsBrowserDevelopmentRun で localhost 起動 + mcp__playwright__browser_navigate:dev:installDebug + mcp__maestro__list_devices mcp__maestro__launch_appmcp__jetbrains__execute_run_configuration 等mcp__claude-in-chrome__*mcp__playwright__browser_snapshot / browser_console_messages / browser_evaluatemcp__maestro__inspect_view_hierarchy / take_screenshotunzip -p ... | javap -v) で確認gh run list --branch <branch> --limit 10 --repo TBSten/compose-preview-lab
gh run view <run-id> --log --repo TBSten/compose-preview-lab > .local/.../log/iter<N>-cat2-ci-<run-id>.log
grep -i -E "warning|deprecated|unsafe|unchecked" <log>
CI が green でも warning が大量にあれば隠れた品質問題。 baseline からの増減を観察し、 メンテナの新 fix で warning 数の変化を tracking。
./gradlew apiDump --continue --project-cache-dir=.local/.../gradle-isolation/cat3 -Dorg.gradle.daemon=false
git diff --stat -- '*.api' '*.klib.api'
差分 0 が期待。 差分があれば BCV baseline と実装が drift = ticket 化候補。 検査後 git checkout -- '*.api' '*.klib.api' で revert。
integrationTest 側も同様に。
#0001, #0102 等)ls problems/ | grep -E "^[0-9]{4}-" | sort | tail -1 で確認)problems/<NNNN>-<slug>.md — activeproblems/resolved/<NNNN>-<slug>.md — メンテナ fix で解消されたものproblems/methodology/<NNNN>-<slug>.md — 探索 process / subagent 運用系problems/non-pr/<NNNN>-<slug>.md — PR 由来でない外部要因# NNNN. <タイトル>
## 重要度
P0 / P1 / P2 / P3
## 担当
cat1 (iter 14) — autonomous source 探索
## 場所
- `path/to/file.kt:line`
## 詳細
(再現手順 / 根拠 / 修正案)
## 修正案
案 (a) / 案 (b) ...
ls problems/ で確認してから起票5 並列で番号衝突を避けるため、 主管側が事前に reserve range を割り当て、 subagent prompt に明記する:
NNNN+0 〜 NNNN+2 (3 件 reserve / iter)NNNN+3 〜 NNNN+5NNNN+6 〜 NNNN+8NNNN+9 〜 NNNN+11NNNN+12 〜 NNNN+14各 cat 内で 1-2 件の起票で OK (= 短時間モード)、 3 件全部使う必要なし。 reserve 範囲外は次 iter に持ち越し。 衝突発生時は SKILL.md 既存ルール (= 後発側を後ろにずらして renumber + 内部 H1 修正) で復旧。
gh pr comment <NNN> --repo <repo> --body "$(cat <<'EOF'
## Iter <N> 探索 — P1 課題 X 件
...
EOF
)"
resolved/ に移動、 投稿は次 P1 まで保留修正案を含む PR コメントを投稿する場合、 投稿前に最低 1 回は動的 PoC で検証する。 過去事例: iter 17 cat2 の修正案 @get: qualifier 提案が iter 18 cat3 で Kotlin compiler に構文禁止 と 5 platform 全 fail で disprove、 自己訂正コメントを次 iter で投稿する経路を強いた。
検証 checklist:
.local/<exploration-name>/tmp/iter<N>-poc/):compileKotlin* を回すPoC が通れば PR コメント投稿、 通らなければ修正案を変えて再 PoC、 もしくは「fix 不能 = 明文化」 に切り替え。
各 cat に独立した project-cache:
--project-cache-dir=.local/.../gradle-isolation/cat<N>
-Dorg.gradle.daemon=false
注意: --project-cache-dir は .gradle/ のみ隔離、 <module>/build/ は project root で 物理共有。 並列 build で task race の可能性あり (= 同 task が複数 cat で同時に走ると <module>/build/ の output file が衝突する known issue)。
git checkout -- <files>rm -rf <untracked dirs>.local/.../tmp/ に集約git status --porcelain で確認、 log に記録.api / .klib.api (apiDump 後 revert)dev/ integrationTest/ (revert)integrationTest/uiLib/.../sample/cat5stress*/ のみ並列 subagent が main project tree の source code を直接改変すると、 別 cat の build を block する事故が発生する (= cat3 が一時 probe file を残置 → cat4 の dev module build が e: 数件で fail した実例あり)。
source 改変が必要な場合は 必ず sandbox に隔離:
.local/<exploration-name>/tmp/iter<N>-cat3/sandbox-app/ 等の専用 dir.local/<exploration-name>/tmp/iter<N>-cat4/sandbox/ 等src/) は read-only、 一時 file 残置禁止検証完了時に sandbox dir を削除 + git status --porcelain で main project tree が clean を確認、 完了レポートに状態明記。
timeout 30m で killユーザから deadline 変更指示が来た場合 (例: 「12:00 → 5:00 に変更」):
CronDelete → 新時刻で CronCreate (= one-shot、 deadline 直前 3 min fire 推奨)過去事例: ユーザ「5 時超えたら一旦終了」 で 12:00 → 5:00 へ変更、 cron e566872c 削除 + edc9068e 新設で対応。 但し protocol が事前 skill 化されていなかったため判断が遅れた。
deadline 残 1.5h を切ったら、 5 並列 kick を禁止し sequential mode に自動切替:
主管側が iter kick 前に date で残時間を計算、 < 1.5h なら sequential prompt template を選択。
各 cat 起動時に subagent prompt で以下を必読指示:
<repo-root>/.claude/skills/exploratory-pr-verification/SKILL.md) — 必ず最初に.local/<exploration-name>/FINAL-SUMMARY.md (最新スナップショット、 例: .local/exploratory-pr-186-187/FINAL-SUMMARY.md)主管側 (= subagent kick する側) も 各 iter 開始前に本 SKILL.md を Read で再読する (= ユーザ追加指示の取りこぼし防止)。
各探索の iter 1 で以下の sweep を default 実行 (= release blocker / docs gap の早期発見):
grep -rn "<主機能 keyword>" docs/ README.md CHANGELOG.md で 0 件 hit を確認 (= release blocker 候補、 過去事例 #0177 で iter 19 まで遅延)gh pr view <NNN> --json body --jq .body | grep "BREAKING" で破壊的変更の明示確認git diff --stat -- '*.api' '*.klib.api' で baseline drift 即確認gh run view <run-id> --log | grep -ic warning で baseline 数を記録、 後 iter で増減観察find . -name "CHANGELOG*" で 0 件なら #0186 系の C-7 family 候補)これらは static で時間 < 5 min、 iter 1 cat1 / cat2 で必ず回す。
cat3 / cat4 / cat5 の動的検証で実行する gradle / mcp / gh command の出力は、 完全保存:
./gradlew apiDump --continue > .local/<exploration-name>/tmp/iter<N>-cat<X>-<ts>-apiDump.log 2>&1
gh run view <run-id> --log > .local/<exploration-name>/tmp/iter<N>-cat<X>-<ts>-gh-run.log
禁止事項 (= 出力が多くても全文保存する方針への違反):
| grep / | head / | tail などのパイプによる 出力切り捨て (warning / deprecated info も保存対象)OK な書き方 (= 推奨例で使っている 2>&1 は stderr を stdout に合流して保存 する用途であり、 切り捨てではない):
> file 2>&1 (stderr を stdout にマージしつつ全文を file に保存)tee (画面出力と file 保存の両立)切り捨てたいケースでも、 raw log を まず file に全文保存 してから別 step で grep / head するか、 awk '/pattern/' "$logfile" で本文ファイルから抽出する形にする。
完了後、 末尾と冒頭を Read で確認、 必要箇所を ticket file の ## 動的 evidence に引用。
mcp__deepwiki__ask_question で k2 対応 + メンテナンスされてる KCP (Kotlin Compiler Plugin) と設計比較:
@Composable 変換、 snapshot system@Serializable FIR/IR 責務分担data class 風 boilerplate 削減各比較で:
CliOptionProcessingException 採用有無対象 PR の現実装と対比し、 設計優劣を判定。 ticket 化候補があれば起票。
過去事例で cat5 を iter 14 から「他 KCP 比較」 に rotate した結果、 iter 1-13 で P1 として扱った #0079 (KLIB IdSignature cross-jar dedup) が iter 17 cat5 で「Metro も同 limitation = release blocker から除外可能」 と判明、 P 評価を 12-13 iter 後に修正。 = 早期に他 KCP 業界 norm を確認していれば P 評価の妥当性が初期段階で確保できた。
iter 1 cat5 配分:
cat1-4 と並行して iter 1 から比較を回し、 設計選択の妥当性を early に audit。
各 cat は固定 task ではなく、 既存 ticket / iter 履歴を見て 自分で角度を選ぶ:
「何を探すか」 をユーザに聞き返さない (= autonomous 探索の本旨)。
git fetch && git rev-list --count HEAD..origin/<branch> で force-push 検出git show --stat で確認、 既存 ticket への影響整理_resolved- を経由して resolved/ サブディレクトリへgit fetch 後 git rev-list --count HEAD..origin/<branch> が 0 でない、 かつ既存 commit が squash 統合 されている場合:
git log --oneline origin/<branch> -10 で commit history 確認feat! + chore(bcv)!: ... のように複数 commit が 1 commit に squash されるパターン)<old-hash> で fix」 等 hash 参照しているものを new hash で update (= traceability 維持)git reset --hard origin/<branch> で syncgh pr view <NNN> --json comments) を読み、 内容重複を避けるPR 探索の signal 強度を測る指標。 各 PR コメント投稿後の メンテナ着弾 latency を tracking し、 メンテナの探索受領度合いを判定:
| 投稿 → 着弾 latency | メンテナ状態 | 推奨アクション |
|---|---|---|
| < 1h | active 修正 phase | P1 cluster の追加投稿 ROI 高 (但し noise リスク) |
| 1-3h | 通常 review phase | 1 iter 1 通の原則維持 |
| 3-9h | review pending / 別作業中 | 探索継続、 ticket 整理で時間埋め |
| > 9h | low priority / 反応薄 | 投稿頻度を下げ、 P1 でも cluster 待ち |
latency 短縮 (例: 9h → 40min) は メンテナ active phase 入りの signal、 deadline 直前修正集中を示唆 → 探索 phase close 検討材料。
各 iter 完了時に gh pr view <NNN> --json comments --jq '.comments[-1].createdAt' で前回投稿の latency を計算、 FINAL-SUMMARY に記録。
5 並列 cat 全完了 (= 主管側に最終結果が揃った瞬間) の直後、 必ず以下を機械的に実行:
CronList で全 job 列挙 → deadline 通知 cron 以外をすべて CronDelete、 <<autonomous-loop>> <<autonomous-loop-dynamic>> 系 sentinel が close 後に fire する事故を防止 (= 過去事例で b6efca95 autonomous-loop が close 後に fire、 静かに終了したが整理不足)git status --porcelain で untracked が想定内のもののみ)この 5 段の check は 各 iter の閉じ際 に必ず通る。 ここを skip すると loop が止まる原因になる (= 過去事例)。
cron / ScheduleWakeup 経由で <<autonomous-loop-dynamic>> sentinel が fire した場合:
ScheduleWakeup を call しない)deadline 直前の最終 iter は 5 並列ではなく 1-2 cat focus の sequential mode で回す:
§17 で close 処理が発動した後、 残 deadline 期間中の挙動:
git fetch を発動的に、 新 commit があれば既起票 ticket への影響を update (= ticket 文書整理)過去 phase で どのテーマがユーザに何回指摘されたか を記録し、 重要度判断と次 phase の skill 改善に使う:
| 指摘テーマ | ユーザ指摘回数 | 反映先 section | skill 化 lag |
|---|---|---|---|
| 止まらない (loop 継続) | 4 | §0 Constraint A + §17 | iter 17 以降 (= 80% 経過) |
| skill 化 cycle | 7 | §0 Constraint B + §17 step 5 | iter 13 以降 |
| MCP / PDCA 活用 | 4 | §3 | iter 13 以降 |
| 他 KCP / Metro 比較 | 3 | §12 | iter 14 (= 70% 経過) |
| CI ログ / api dump | 3 | §4 / §5 | iter 8 / iter 13 |
| 設定ファイル幅広く | 1 | §3 step 2 | 同 turn |
| 並列数 / 競合 | 1 | §8 | 同 turn |
| ライブラリユーザ pattern | 1 | context/04 (= 個別 phase) | 同 turn |
| deadline 動的変更 | 1 | §10 | 同 phase 内 |
| 反省会 cycle | 1 | §17 step 5 | 同 phase 内 (PR 作成後) |
= ユーザが繰り返し指摘するルールほど skill 化が遅れる傾向 (= 知見の depth と skill 化の coupling 不足)。
各探索 phase 終了時に cluster を整理し、 follow-up PR の scope 設計材料にする。 family 分類例 (= 一般的に再利用可能な分類軸):
*.api *.klib.api baseline と実装の drift、 nonPublicMarkers 設定漏れ新発見は family のいずれかに分類するか、 新規 family として独立扱い。
本 SKILL.md は探索の累積知識を集約した snapshot。 ユーザの追加指示があれば随時 update。
Nightly Checking ワークフロー上で 60 分 budget の単発探索的検証を行う運用規約。 PR 差分ではなく main の最新を対象に、 ライブラリ本体・integrationTest・docs 全体を 多角的に揺さぶり、発見都度 `.local/nightly-exploration/issues/` へ Markdown 起票する。 Kotlin / Compose / Gradle / AGP の最新 release 情報も探索範囲に含める。 Use when requested: "nightly 探索", "夜間探索的検証", "exploratory-nightly".
複数の GitHub Pull Request を並行管理する際、 各 PR の CI ステータスと未対応 review コメントを 1 回のループで一括チェックし、 失敗 check の種類 (lint / binary compat / build / test / transient infra) を自動判定して対応する fix-ci-* skill (lint=fix-ci-lint, binary=fix-ci-binary, build=fix-ci-build, test=fix-ci-test, comments=fix-ci-pr-comments) に委譲、 review コメントは取得 → 修正 → commit → push → resolve まで実行する。 stack 関係 (PR Y の base が PR X のブランチ) があれば自動で rebase 連鎖。 `/loop` skill と組み合わせれば 10 分間隔などで自動化できる (5 回連続「変化なし」 で 終了)。 ユーザーが「複数 PR を見ながら修正」「PR ループ」「PR fix loop」「stacked PR を順番に green に」「PR を寝かせている間に CI 修正したい」「複数 PR の CI と review comment を自動で対応」 などと言ったら 必ずこの skill を使う。 単一 PR でも、 CI fix と review comment 対応をワンセットで自動化したい文脈なら trigger してよい。
ユーザーがプルリクエストの作成、PRの準備、またはコードレビュー用の変更案の作成を要求した際に使用するエージェントです。これには、ユーザーが明示的にプルリクエストの作成/オープン/ドラフトを依頼する場合が含まれます。 例: - <example> Context: ユーザーが新機能の実装を完了し、プルリクエストを作成したい。 user: "新しいsealed classのコピー関数機能の実装が完了しました。PRを作成してもらえますか？" assistant: "Taskツールを使用してpr-creatorエージェントを起動し、変更のプルリクエストを準備・作成します。" <commentary>ユーザーがPR作成を要求しているため、pr-creatorエージェントを使用してプルリクエストの準備と作成プロセスを処理します。</commentary> </example> - <example> Context: ユーザーが変更をコミットし、レビューの準備ができていることを述べる。 user: "バグ修正をコミットしました。レビューしてもらいましょう。" assistant: "Taskツールを使用してpr-creatorエージェントを起動し、バグ修正のプルリクエストを作成します。" <commentary>ユーザーはコードレビューの準備ができていることを示しており、これにはPR作成が必要です。pr-creatorエージェントを使用してこれを処理します。</commentary> </example> - <example> Context: ユーザーが日本語でPR作成を直接要求。 user: "Pull Requestを作成する。" assistant: "Taskツールを使用してpr-creatorエージェントを起動し、プルリクエストを作成します。" <commentary>PR作成の直接的な要求。pr-creatorエージェントを使用してプルリクエストのワークフローを処理します。</commentary> </example>
working tree にある差分を適切な粒度でコミット
バイナリ互換性チェック（./gradlew apiCheck）が失敗した時の診断と修正を行う。public API の差分を確認し、必要に応じて apiDump で API ダンプを更新する。Use when "apiCheck が失敗", "binary compatibility エラー", "API ダンプを更新", "公開 API の互換性チェック".
Gradle ビルド（assembleDebug, compileKotlin など）が失敗した時の診断と修正を行う。コンパイルエラー、依存関係の問題、Convention Plugin の設定不備などを切り分けて修正する。Use when "ビルドが失敗", "Gradle build error", "コンパイルエラー", "compileKotlin が失敗".