docs: 成果物間の矛盾・判断の揺れは実装着手前にPO確認を挟む運用を明文化 - #57
Conversation
このリポジトリの品質保証は「壊れたらCIが赤くなる」に依存しているが、 方針そのものが製品の意図と逆でもCIは緑になる。ここだけは機械が止められない ため、実装着手前のPO確認をゲートとして置く。 - docs/decision-policy.md を新設。止まる/進むの境界を「判断が逆だったとき 成果物(docs/*.md)の書き換えが要るか」の一問で切る。確認が必須の5条件と 確認不要の4条件、経路の使い分け(AskUserQuestion / Issueコメント+Blocked)、 提示に書く5点、待っている間の振る舞い、Opusで特に徹底する理由を記載 - CLAUDE.md: ドキュメント一覧・「絶対に守ること」・モデルの使い分け節から参照 - docs/prd.md: 8章冒頭に「方針の誤りは機械が止められない」旨を追記(v0.7) - docs/permissions.md: マトリクスが他成果物と食い違って見えたときの導線を追加 - pr-review-flow skill: 「PRを出す前に」節を追加。レビューボット4体とCIは 方針の誤りを検出できないことを明記 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
Warning Review limit reached
Next review available in: 23 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
📝 WalkthroughWalkthrough成果物間の矛盾や曖昧な設計判断を対象に、実装前のPO確認、判断記録、確認待ち中の制限、モデル間のエスカレーション手順を追加した。PRDと関連する開発手順も更新した。 Changes設計判断確認ポリシー
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
レビュー結果このPRは
そのため今回は主に文書としての一貫性・運用としての実効性を確認した。 良い点
気になった点(nit、ブロッカーではない)
総評コード変更を伴わない運用ドキュメントPRとして、内容の一貫性・自己適用の妥当性ともに問題は見当たらなかった。CIも |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/decision-policy.md`:
- Around line 62-64: Update the reversibility criteria in
docs/decision-policy.md to require that changes do not modify existing or new
persistent data, cause external side effects, or alter public APIs; otherwise
route the decision to PO confirmation. Keep the existing exclusions for
migrations, artifact descriptions, and published specifications aligned with
this expanded condition.
- Around line 40-43: Update the artifact-editing rule in docs/decision-policy.md
to limit confirmation requirements to changes affecting product intent, public
specifications, or data semantics. Explicitly exempt obvious typos and missed
follow-up updates from confirmation, and align the related guidance in the
surrounding exception section so these cases consistently permit agent-only
fixes.
- Around line 59-61: Update the decision-recording guidance in the section
containing the誤記・追従漏れ rule so the chosen correction is recorded in an Issue
comment, while the PR body only links to that Issue. Align the related guidance
around lines 87-89 with this same Issue-as-canonical-record requirement and
remove the instruction to record the rationale only in the PR body.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 9074d086-4c6c-4966-a32e-172ae4c4ae95
📒 Files selected for processing (5)
.claude/skills/pr-review-flow/SKILL.mdCLAUDE.mddocs/decision-policy.mddocs/permissions.mddocs/prd.md
- 一問の境界ルールと「誤記・追従漏れは確認不要」の例外が矛盾して読めた点を解消。 例外を境界ルールの直後に明記し、「書き換えの前に選択が要るなら確認対象」と補足 (CodeRabbit) - 「コードを消せば戻る」の判定に永続的な副作用を追加。既定値・書き込まれる行・ 論理削除のフラグ・外部副作用・公開APIの形は、コードを戻しても元に戻らないため 確認側に回す(CodeRabbit) - 「記録の置き場所は常にIssue」の適用範囲を「確認を挟んだ判断」に限定。誤記の修正で Issueコメントを義務化しないことを明示(CodeRabbit) - pr-review-flow skillの理屈の重複を削り、decision-policy.mdへの参照に置換(Claude) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Draft 1周目のレビュー指摘の分類本物の修正(2件・対応済み)1. 境界ルールと例外が矛盾して読める(CodeRabbit, 指摘は妥当。「成果物の書き換えが要るなら確認する」という一問の境界ルールと、「明らかな誤記・追従漏れは確認なしで直してよい」という例外が、同じケースに別の手順を与えていた。誤字を1つ見つけたエージェントが境界ルールに素直に従うと止まってしまう。 ただし提案パッチ(境界ルールを「製品の意図・公開仕様・データ意味論を変更する成果物の書き換え」に限定する)はそのままは採らなかった。一問で切れる簡潔さがこのルールの効き目そのもので、3項の判定に置き換えると「これはデータ意味論か?」という新しい迷いを増やす。代わりに境界ルールの直後に例外を1つだけ明示し、 2. 「コードを消せば戻る」の判定に永続的な副作用が抜けている(CodeRabbit, L62-64) 指摘は妥当で、しかもこのリポジトリでは実害が大きい。マイグレーションを伴わなくても、既定値の反転・行の書き込み・論理削除フラグは永続データを変える。コードをrevertしても、既に書かれた行は戻らない。CLAUDE.mdが「参加登録の公開設定はデフォルト非公開。既定値を反転させても何もエラーにならない」とわざわざ警告している対象がまさにこれで、元の書き方だとこの repo で一番静かに壊れるケースが「確認不要」に分類されてしまう。永続データ・外部副作用・公開APIの形を除外条件に追加し、CLAUDE.mdの該当記述への参照を付けた。 妥当なnitpick(2件・対応済み。ただし提案とは別の形)3. 記録の正本がIssueとPR本文で割れている(CodeRabbit, L59-61 / L87-89) 割れて読める点は事実なので直したが、提案(誤記の修正もIssueコメントに記録し、PR本文はリンクにする)は採らなかった。誤記の修正はそもそもPO確認を挟まない経路で、記録すべき「決定」が存在しない。「章番号のずれを直した」ためにIssueコメントを1つ起こす運用は、このPRが守ろうとしている自律性を削る側に働く。 代わりに 4. skillに理屈が重複していて追従漏れのリスクがある(Claude, そのとおり。PR本文で「バックストップに限定した」と設計意図は書いたが、書いた分量が実際には理屈の要約になっていた。理屈を削って 誤検知なし。 静的解析で拾えたか(
|
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| - **Opusは判断がタスクの入口にあり、そのまま実装・テスト・CIまで一気通貫で進むため、 | ||
| 判断を外したときの手戻りが最も大きい。**成果物間の矛盾やどちらとも取れる判断に | ||
| 出くわしたら、実装に着手する前にPOに確認する(`docs/decision-policy.md`)。 | ||
| Sonnet/Haikuが同じ状況に出くわしたらタスクの分類自体が誤っているので、自分で選ばずOpusに上げる。 |
There was a problem hiding this comment.
この4行はdocs/decision-policy.md「Opus担当タスクで特に徹底する理由」節とほぼ同じ理由付け(判断がタスクの入口にある/方針決定から実装・テスト・CIまで一気通貫で進むため誤りに気づく機会がない/Sonnet・Haikuが同じ状況に出くわしたらタスクの分類自体が誤っているのでOpusに上げる)を書き写しています。
このPR自身が.claude/skills/pr-review-flow/SKILL.mdの「PRを出す前に」節では同種の重複(レビューボット4体が方針の逆転を検出できない、という理由付け)をCodeRabbitの指摘で検出し、理由を削ってdecision-policy.mdへの参照に置き換える形で修正済みです(「理屈をここに書き写さない。片方だけ古くなる」)。ここも同じパターンで、decision-policy.md側の理由付け(PR #52の実例、手戻りの単位の列挙など)が将来変わったときに、この4行だけ追従されずに残るリスクがあります。
PR本文の設計判断表では「CLAUDE.mdへは1〜3行のポインタだけを置く」方針が明記されていますが、ここは他の2箇所の追加(ドキュメント一覧・絶対に守ること、いずれも2〜3行の要約+参照)より長く、理由の再掲になっていて、その方針からも外れています。docs/decision-policy.mdへの参照+短い一文程度に縮めることを提案します。
(nit) 同じ段落の「Sonnet/Haikuが同じ状況に出くわしたら…自分で選ばずOpusに上げる」は、この直後にある既存のエスカレーション項目「一段上のモデルにエスカレーションする(Haiku→Sonnet→Opus)」と厳密には整合しません。Haikuの一段上はSonnetのはずですが、ここではHaikuから直接Opusに上げる形になっています。Haikuは元々この種の判断を含むタスクの対象外(common/の2経路同期・権限/RLS・データモデルの意味判断を一切含まないタスクに限る、という制約)なので実害は小さいですが、一段上ルールとの関係を一言補足したほうが誤読を防げます。
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/skills/pr-review-flow/SKILL.md:
- Around line 22-24: SKILL.md
の該当説明で「このフロー」を「機械的なチェック」に置き換え、問題が未確認判断の確認工程ではなく、レビューボットとCIによる機械的検証だけでは検出できない点を明確にしてください。関連する文脈と
docs/decision-policy.md への参照は維持してください。
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 02079ea5-ea93-4c5c-b80e-cc28be8b731f
📒 Files selected for processing (2)
.claude/skills/pr-review-flow/SKILL.mddocs/decision-policy.md
レビュー結果このPRは
そのため文書としての一貫性・自己適用の妥当性を中心に確認した。既に1周目でCodeRabbit/Claudeの指摘4件(境界ルールと例外の矛盾、可逆性判定に永続的副作用が抜けている、記録先の不統一、SKILL.mdの理由重複)がすべて反映済みであることも確認した。 良い点
指摘(インラインコメント参照)
参考として検討したが指摘に至らなかった点
静的解析で拾えたか いずれも自然言語の運用ルールどうしの整合性に関する指摘で、markdownlintが検査する構文の話ではない。ルール化の余地はない。 総評 指摘のうち1点(CLAUDE.mdの理由重複)は、このPRが確立しようとしている「本体は1箇所、各所はポインタ」という設計原則そのものからの逸脱であり、直す価値があると判断する。他はnit。ブロッカーにするかは指摘の対応者の判断に委ねる。 |
- CLAUDE.mdのモデル使い分け節が decision-policy.md「Opus担当タスクで特に徹底する 理由」節をほぼ書き写していたため、結論とポインタに縮約。同節で直したのと同じ 「理屈を2箇所に書かない」原則を、指摘元と同じ形で適用した(Claude) - Sonnet/HaikuからOpusへの持ち上げが、既存の「一段上にエスカレーション(Haiku→ Sonnet→Opus)」「3回試して駄目なら」と読み合わせると矛盾して見えた点を補足。 この場合は3回ルールを待たず一段ずつでもなくOpusまで上げる(Claude) - skillの「このフロー」が pr-review-flow 全体(今回追加した確認工程を含む)を 指すように読めたため「機械的なチェック」に変更(CodeRabbit) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Draft 2周目のレビュー指摘の分類本物の修正(2件・対応済み)1. CLAUDE.mdのモデル使い分け節が 指摘は妥当で、しかも**1周目で自分が直したのと同じパターンをもう1箇所で犯していた。**1周目に 指摘した側が「このPR自身が同種の重複を1周目で修正済み」と根拠に挙げてきたのが的確で、直す理由が明確だった。 2. Sonnet/Haiku → Opus の持ち上げが既存のエスカレーション規定と整合しない(Claude, 同上・nit扱いだが採用) nitとして挙がっていたが、読み合わせると本当に矛盾する。CLAUDE.mdの既存規定は「同じ問題を3回試して解決しない場合、一段上のモデルに(Haiku→Sonnet→Opus)」である。一方こちらは「Haikuでも直接Opusへ」を要求していた。両立しない指示が同じファイルの近接した箇所に並ぶのは、まさにこのPRが問題にしている状態そのものなので、nitではなく整合性の問題として直した。 妥当なnitpick(1件・対応済み)3. 「このフロー」の指す範囲が曖昧(CodeRabbit, SKILL.md L22-24) 「このフローが検出できない唯一の穴」の「このフロー」は 誤検知なし。 静的解析で拾えたか3件とも**拾えない。**1・2はドキュメント間およびファイル内の主張の重複・矛盾、3は日本語の指示語の曖昧さで、いずれも構文検査の対象外。ルール化の余地はない。 所感2周を通じて出た7件の指摘のうち5件が「このPRで定義しようとしたルール自身の穴」だった。運用ルールを自然言語で書く作業には、コードにおける tsc / lint に相当するゲートが存在しない。レビューボットが実質的にその代役を務めた形で、Draft先行で反復する運用がドキュメントPRでも効いている。 検証
指摘が尽きたと判断し、Ready化してCopilotの最終レビューを受ける。 |
| 1. **成果物どうしが両立しない。**どちらかを書き換えないと実装できない | ||
| 2. **一つの記述に2通り以上の解釈が成り立ち、選び方で外から観測できる挙動が変わる。** | ||
| 権限の可否、既定値、保存・削除されるデータ、画面に出る/出ない(issue #34 はこれ) | ||
| 3. **`docs/prd.md` の本文を書き換えることになる。**PRDは製品の意図そのもの |
There was a problem hiding this comment.
条件3「docs/prd.md の本文を書き換えることになる」が無条件のトリガーとして書かれていますが、本PR自身が docs/prd.md の8章冒頭に新規の説明文(ポリシーの背景説明)を書き加えており、これは「例外」として明記されている誤字・追従漏れ(45〜47行目)には当たりません。
条件1・2・4・5はいずれも「製品の意図・仕様上の選択」に関わるもの(権限、既定値、スコープ、データモデルの意味)である一方、条件3だけは「PRD本文への書き込み」という手段で切られており、対象が揃っていません。issueの完了条件どおりに書くだけの、選択の余地がないPRD追記(今回のケースなど)もこの条件を字面どおり満たしてしまいます。
今後別のエージェントがこの表を読んだとき、「PRDに何か書く」だけで機械的に確認ゲートに入れるべきか、それとも条件1・2・4・5と同様に「製品の意図の選択を伴うPRD編集」に限定すべきか、条文だけでは判定できません。後者に絞る一文(例:「解釈の選択を伴う場合に限る」)を条件3に足しておくと、本PRのような『issueで内容が確定しているPRD追記』と、実際に製品判断を要するPRD書き換えを区別できます。
|
|
||
| 開発の大半をAIエージェントに任せる前提のため、「人間が差分を読んで品質を担保する」方式は採らない。代わりに**壊れたときに機械が止める仕組み**を先に用意する。 | ||
|
|
||
| ただし**この方式で唯一止められないものがある。方針そのものが製品の意図と逆だった場合、機械はすべて緑になる。**静的解析もテストもCIも「決めた方針どおりに動いているか」しか見ていないためである。したがって、成果物間で記述が矛盾している場合やどちらとも取れる判断が必要な場合は、実装に着手する前にプロダクトオーナーに確認する運用を置く(止まる/進むの境界、確認の経路と書き方は `docs/decision-policy.md`)。 |
There was a problem hiding this comment.
この段落は docs/decision-policy.md「なぜこれが必要か」の理屈(「方針が製品の意図と逆でもCIは緑になる」「決めた方針どおりに動いているかしか見ていない」)をほぼそのまま書き写しています。同じ文言はCLAUDE.mdの「絶対に守ること」節にもあります。
このPRの本文(設計判断の表)では「各docsの冒頭に同じ内容を書くのは採らなかった。4ファイルに同じ内容を書くと片方だけ直される」と明記されており、実際に .claude/skills/pr-review-flow/SKILL.md では同種の重複をレビュー指摘で削ってdocs/decision-policy.mdへの参照に置き換えています(コミット 7bda5d9)。しかしprd.md 8章のこの追記と、CLAUDE.mdの該当箇所は、その原則が適用されずに理屈がそのまま複製されたままです。
docs/decision-policy.md の理由づけを将来更新したとき(例えば例外条件を1つ増やすなど)、こことCLAUDE.mdのコピーが追従せず古いままになるおそれがあります。「唯一止められない誤りである」旨だけ一言残し、理由の詳細はdocs/decision-policy.mdへの参照に留める(SKILL.mdと同じ形)方が、このPRが自ら立てた重複回避の原則と整合します。
レビュー総評本PRはコード変更を含まないドキュメント専用PR( 代わりに、本PRの内容そのもの(「成果物間の矛盾を機械的チェックでは検出できない」という主張)を、その基準に照らして自己適用する形でレビューした。 良い点
指摘(インラインコメント参照)
いずれもドキュメントの整合性に関する指摘であり、内容の方向性自体(実装着手前のPO確認ゲートを置く)には異論なし。 |
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.claude/skills/pr-review-flow/SKILL.md (1)
18-20: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win実装着手前の停止条件を明記してください。
現在の記述は、未確認の設計判断を「PRを出す前」に確認すればよいように読めます。
docs/decision-policy.mdは、PO確認前に判断へ依存する実装を開始しないことを定義しています。対象はコードだけではありません。マイグレーション、RLS、生成型、テスト、文書も含めてください。確認が必要な場合は、確認完了まで依存する作業を停止すると明記してください。
根拠は、参照先ポリシーが確認前の判断依存実装を禁止していることです。
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.claude/skills/pr-review-flow/SKILL.md around lines 18 - 20, Update the design-decision guidance in the skill instructions to require stopping before implementation begins whenever docs/decision-policy.md indicates PO confirmation is needed. Explicitly cover code, migrations, RLS, generated types, tests, and documentation, and state that dependent work must remain paused until confirmation is complete; do not limit the requirement to the period before opening a PR.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In @.claude/skills/pr-review-flow/SKILL.md:
- Around line 18-20: Update the design-decision guidance in the skill
instructions to require stopping before implementation begins whenever
docs/decision-policy.md indicates PO confirmation is needed. Explicitly cover
code, migrations, RLS, generated types, tests, and documentation, and state that
dependent work must remain paused until confirmation is complete; do not limit
the requirement to the period before opening a PR.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 489e9940-0117-4f78-b8d9-847cc23819dc
📒 Files selected for processing (2)
.claude/skills/pr-review-flow/SKILL.mdCLAUDE.md
- 確認必須の条件3「prd.mdの本文を書き換えることになる」が、選択の余地のないPRD追記 (本PR自身の8章追記がまさにそれ)まで機械的にゲートに入れてしまうため、 「解釈の選択を伴う形で」に限定。他の4条件と対象の揃え方を合わせた(Claude) - prd.md 8章の追記が decision-policy.md の理屈を複製していたため、事実の宣言と 参照に縮約。skill / CLAUDE.md で直したのと同じ形に揃えた(Claude) - skillの「PRを出す前に」節が、PR作成時の確認で足りると読めた点を明示的に否定。 本来の確認点は実装着手前で、対象もコードに限らないことを追記(CodeRabbit) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
レビュー結果このPRは
ドキュメント内容の確認CLAUDE.mdの「同期を保つことを禁止」原則(
以上、指摘したい問題点は見つからなかった。ドキュメントの追記のみでコード側の作法チェックは対象外という前提を明記した上で、LGTMとする。 (補足: サンドボックスの権限制約により |
Draft 3周目のレビュー指摘の分類本物の修正(2件・対応済み)1. 確認必須の条件3が広すぎて、このPR自身を誤って捕まえる(Claude, 今回で一番鋭い指摘。条件3は「 さらに指摘のとおり、条件1・2・4・5は「製品の意図・仕様上の選択」という基準で切られているのに、条件3だけ「PRD本文を触るか」という手段で切られていて、対象の揃え方が一貫していなかった。Issueで内容が確定している追記や、他の記述に追従させるだけの修正までゲートに入ってしまう。
2. prd.md 8章の追記が 妥当。同じ指摘を受けて直すのがこれで3箇所目(skill → CLAUDE.md → prd.md)で、自分で「4ファイルに同じ内容を書くと片方だけ直される」とPR本文に書きながら、実際には3箇所に理屈を複製していた。事実の宣言(方針が逆でも機械は緑になる)だけ残し、理由の説明は なお 妥当なnitpick(1件・対応済み)3. 「PRを出す前に」節が、PR作成時の確認で足りると読める(CodeRabbit, SKILL.md) 指摘のとおり。節のタイトルからして「PR前に確認すればよい」と読め、 対象の列挙を1行入れた点だけCodeRabbitの提案より踏み込んでいる。判断の重複を避ける原則からすると 誤検知なし。 静的解析で拾えたか3件とも拾えない。1は条件の粒度の不揃い、2は自然言語の意味的な重複、3は節タイトルと本文の含意のずれ。いずれも構文検査の対象外。 レビュー状況
3周で計10件の指摘を処理し、Claudeが指摘ゼロに収束したためReady化してCopilotの最終レビューを受ける。 |
There was a problem hiding this comment.
Pull request overview
成果物間の矛盾や解釈の揺れが発生した際に、実装に入る前にPO確認を挟む（=機械的チェックでは止められない唯一の失敗を人間ゲートで塞ぐ）運用を、リポジトリの標準手順として文書化するPR。
Changes:
- 新規ドキュメント
docs/decision-policy.mdを追加し、「止まる/進む」の判定基準・確認経路・記録の置き場所を定義 CLAUDE.md/docs/prd.md/docs/permissions.md/pr-review-flowskill から新ドキュメントへの導線を追加して運用を定着
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| docs/decision-policy.md | 成果物矛盾/判断揺れ時に「実装着手前にPO確認」を挟むための判定基準・手順・記録ルールを新設 |
| CLAUDE.md | 既存の原則・運用導線に decision-policy を追加し、常時参照される場所でゲート条件を明文化 |
| docs/prd.md | v0.7へ更新し、品質方針(8章)に「方針誤りは機械が止められない」→PO確認ゲートの位置づけを追記 |
| docs/permissions.md | 権限マトリクス直下に、矛盾検知時は自己解釈せず decision-policy に従う導線を追加 |
| .claude/skills/pr-review-flow/SKILL.md | PR提出前の最終チェック（最後の砦）として decision-policy 参照を追記 |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Copilot最終レビューの結果指摘なし。 **quota失敗ではないことを確認済み。**PR #35 で発生したquota上限による失敗は「中身のないコメントだけが投稿される」形になるが、今回はPRの意図の要約とファイル単位の変更内容が5ファイル分すべて具体的に記述されており、実際にレビューされたうえで指摘ゼロと判定されている。したがって 分類
Draft 3周でClaude / CodeRabbit から出た計10件を処理した結果、Ready時点で新規指摘なしに収束した。 マージ判定
|
Closes #53
何をしたか
成果物(
docs/prd.md/docs/data-model.md/docs/permissions.md/docs/roadmap.md/CLAUDE.md)の記述が矛盾している、またはどちらとも取れる判断が必要なときに、実装に着手する前にPOへ確認を挟む運用を明文化した。権限マトリクスに限定しない、判断全般を対象とする。設計判断
1. なぜこの運用が要るのか(根拠の置き方)
「出戻りが起きたから確認しよう」ではなく、このリポジトリの品質保証モデルの穴として位置づけた。
CLAUDE.md冒頭の原則は「壊れたらCIが赤くなることで品質を担保する」「迷ったら『これは機械が止められるか？』を先に考える」である。この問いを今回のケースに当てると答えはNoになる。lint / tsc / テスト / レビューボット4体は「決めた方針どおりに動いているか」しか見ておらず、方針が製品の意図と逆でも全部緑になる。つまり成果物間の矛盾は、このリポジトリで唯一、機械が止められない種類の誤りである。だからここだけは人間への確認がゲートになる、という形で既存の原則に接続した。
2. どこに書くか
新規ドキュメント
docs/decision-policy.mdを作り、各所からは1〜3行のポインタだけを置いた。docs/decision-policy.md(新設)docs/への導線という既存の構成(permissions / lint-policy / testing と同じ)に揃えたCLAUDE.mddocs/permissions.mdの権限マトリクス直下にだけ、2行の導線を置いたpr-review-flowskilldocs/prd.md3. 止まる/進むの境界(自律性を殺さないための閾値)
何でも確認すると自律性が失われるので、一問で切れる判定にした。
成果物は製品の意図を書いた場所でエージェントが単独で書き換えてよいものではなく、逆に成果物を触らずに済む判断は実装の裁量の内側にある、という線引き。issue #34 のケースは実際に
docs/prd.mdの書き換えを伴ったので、この基準なら「止まる」側に正しく分類される。その上で、確認必須の5条件(成果物どうしが両立しない/解釈の違いが外から観測できる挙動を変える/PRD本文を書き換える/MVPとフェーズ2の線引きが動く/データモデルの意味が変わる)と、確認不要の4条件(実装の裁量に閉じる/正しい側が一意に決まる誤記・追従漏れ/コードを消せば戻る範囲/前例に揃えるだけ)を列挙した。
グレーの扱いは「確認側に倒す」とした上で、自律性は確認の回数ではなく粒度で守ることを明記した。1タスクで複数の判断が割れているなら1つずつ聞かずまとめて1回で聞く。「気になるたびに手を止める」ではなく「割れているものを全部並べて一度に確認する」が正しい止まり方。
4. 確認の経路(AskUserQuestion / Issueコメント)
判断の重さではなく、POが今応答できるかどうかで使い分ける形にした。両方使う。
AskUserQuestionで選択肢提示。その場で待つStatusをBlockedにして別Issueへ移るただし記録の置き場所は常にIssueとした。
AskUserQuestionの応答はセッションの外に残らず、次に同じ判断をするモデルがまた同じところで割れるため、口頭確認した場合も決定と理由をIssueに書き写す運用にした。5. Opusで特に徹底する理由
手戻りコストが構造的に大きいことを3点で明記した。判断がタスクの入口にあるため外れると入口からやり直しになること、方針決定〜実装〜テスト〜CIまで一気通貫で進み途中に人間もモデルの交代も挟まらないため誤りに気づく機会が構造的に存在しないこと、手戻りの単位がマイグレーション+RLS+
common/+両層のテスト+成果物の書き換えとまとまって大きいこと。あわせて、Sonnet/Haikuがこの判定に引っかかったらタスクの分類自体が誤っている(彼らに回るのは「方針が
docs/に書かれていてそれに沿って実装するだけ」の作業のはず)ため、自分で選ばずCLAUDE.mdのエスカレーション手順でOpusに上げる、と書いた。他モデル層に「確認しなくてよい」と読まれないようにするため。変更ファイル
docs/decision-policy.md(新規)CLAUDE.md— ドキュメント一覧 / 絶対に守ること / モデルの使い分け節docs/prd.md— 8章冒頭、付録、更新履歴(v0.6 → v0.7)docs/permissions.md— 権限マトリクス直下に導線.claude/skills/pr-review-flow/SKILL.md— 「PRを出す前に」節検証
yarn lint(ESLint + markdownlint-cli2) /yarn typecheck/yarn testすべてgreenこの判断自体をPO確認に回さなかった理由
本PRの運用を本PR自身に適用した結果、確認不要側と判定した。理由は、issue #53 が完了条件として「明文化すること」「境界を具体的に書くこと」「権限マトリクスに限定しないこと」「Opusで徹底する理由を書くこと」の4点をすでに指定しており、成果物間に矛盾がなく、判断が「どう書くか」に閉じているため。ただし判定が誤っている可能性を残して、上記のとおり選択肢と採用理由を全部書き出してある。異論があればこのPRで指摘してほしい。
Summary by CodeRabbit