review-issue
Epic全体を見て行うレビューと、自動で直す仕組み(自動修正ループ)、review-knowledge.mdへの知識のまとめ方
EpicEpic複数のIssueをまとめる、いちばん大きな作業単位。用語集で見る全体を見て行うレビューが、このスキルの一番の特徴です。
「Epic全体を見る」とは、今レビューしているIssue単体の差分(diff)だけを見るのではなく、その親のEpic・
Sub-EpicSub-EpicEpicをさらに小分けした単位。機能のまとまりや担当領域ごとに分けます。用語集で見る・兄弟Issue(同じ親を持つ他のIssue)も一緒に見る、という意味です。
さらにshared-contextパック(チームで共有している前提知識のファイル群)、特にreview-knowledge.mdも
読み込んだうえでレビューします。
コマンドと主なオプション
/architect:review-issue [item] [--epic=<id>] [--max-fix-rounds=N] [--base=<branch>] [--no-fix] [--dry-run] [--auto] [--lang=en|ja]| オプション | 意味 |
|---|---|
item |
レビュー対象。I1.2.3・#<iid>・URLで指定する。省略時はstatus::doing / status::reviewのアイテムを拾い、確認を求める |
--epic |
対象Epicを絞り込む |
--max-fix-rounds=N |
自動修正ループの上限回数。既定は3 |
--base |
PR/MRのベースブランチ |
--no-fix |
自動修正をせず、レビュー結果を出すだけにする |
--dry-run |
PR/MRを作らず、何を作るかだけ報告する |
--auto |
途中の確認を省略する |
--lang |
コメントやレポートの出力言語 |
severity(重大さ)の3段階
見つかった問題には、severity(重大さのレベル)が3段階でつきます。段階によって、何が起きるか・対応が 必要かが変わります。
マージマージPR/MRの変更を取り込むこと。一度実行すると元に戻しにくい操作です。用語集で見るを止める問題です。直るまでマージできず、自動修正ループの対象になって 自動で直そうとします。
記録には残りますが、マージは止めません。対応するかどうかは後で判断できます。
レビューする側が気づいた疑問点です。対応する必要はありません。
自動修正ループ
blocker(マージを止める問題)が見つかると、直るまで「修正 → 再レビュー」を繰り返します。ただし、 繰り返す回数には上限があります。
つまり流れはこうなります。blockerが0件になれば、PR/MRPR/MRPull Request / Merge Request。変更をレビューしてもらい、取り込んでもらうための提出。用語集で見るを作って次の
工程に進みます。一方、繰り返しの上限(既定3回)に達しても直らない場合や、同じ問題が2回連続で直らない
場合(no-progress、進んでいない状態)は、そこで処理を止めてstatus::blockedにし、人が判断できるように
します。
review-knowledge.mdへの知識のまとめ方(蒸留)
各ラウンドで見つかった問題の記録(finding)は、そのままreports/backlog/reviews/review-<issue>-round<N>.md
に残ります。それに加えて、[B](blocker)や[S](important)の問題は「蒸留(じょうりゅう)」という形でも
残します。蒸留とは、詳しい記録の中から、他のIssueにも当てはまりそうな一般的なルール(KN-<n>)だけを
取り出してまとめることです。同じルールのエントリが既にあれば、occurrences(発生した記録)に追記する
だけで、重複したエントリは増えません。
KN-1: クライアント指定のアクター/オーナーフィールドは偽装可能
ownerId, changedBy, roleなどの値は、利用者側(クライアント)から自由に指定できます。認証
(本人確認の仕組み)がない限り、これらの値は偽装可能(別人になりすまして書き換えられてしまう)です。
KN-2: エンドポイント全体に認証・認可が存在しない
認証(本人確認)・認可(その操作が許されているかの確認)が、そもそもどこにもない状態です。1つの Issueだけの問題ではなく、Epic全体に広がる恒常的ギャップ(一時的ではなく、ずっと空いたままの抜け穴) として扱われます。
KN-3: 多対多の中間テーブルには一意性制約が必要
多対多の関係を表す中間テーブルには、一意性制約(同じ組み合わせのデータを重複して登録できないように
する設定)が必要です。TeamMembershipで実際に起きた重複バグのように、この制約がないとデータが
簡単に壊れてしまいます。
KN-4: 外部キー参照パラメータは兄弟サービス間で対称的に存在確認すべき
外部キー(他のデータを指し示す参照値)を受け取ったときは、それが実際に存在するか確認する必要が あります。関連する複数のサービス(兄弟サービス)のうち片方だけがこの確認をしていると、非対称 (片方にしかない)なセキュリティホールになってしまいます。
review-knowledge.mdは、同じ問題を二度実装しないための仕組みとして機能します。