ビジネスロジック検証

​

概要

Kody · Business Logic #291 · Ticket SLA badge — 修正が必要: 不足している要件 2 件

	要件	この PR
✅ MET	チケットのヘッダーに、SLA の残り時間を示すバッジが表示される。	TicketPanel.tsx:40 · ヘッダーにバッジが表示され、“SLA Xh Ym” と表示されます。
❌ MISSING	残り時間が 1 時間未満になるとバッジが赤くなる。	SlaBadge.tsx:14 · バッジは常に “info” のトーンです。Do: 60 分未満で danger のトーンに切り替えてください。
❌ MISSING	解決済みのチケットにはバッジを表示しない。	TicketPanel.tsx:40 · ステータスに関係なく表示されます。Do: チケットが解決済みのときは非表示にしてください。

​

前提条件

• Plugins で接続されたタスク管理ツール: Linear、Jira (Atlassian Rovo)、Notion、Git Issues、またはカスタムプラグイン。
• Kody はタスクを ID で読み取るだけで、タスクがリンクしているもの (親タスク、サブタスク、添付ドキュメント) も読み取ります。タスクを検索したり、タスク管理ツールに書き込んだりすることはありません。
• タスク管理ツールがなくても、コマンドにタスクのテキストを貼り付けることができます (後述)。

​

有効化

reviewOptions:
  business_logic: true

​

Kody がタスクを見つける方法

• PROJ-123 のようなキー (Jira、Linear、およびほとんどのタスク管理ツール)
• #123 と owner/repo#123 (Git issues。プルリクエストの番号は無視されます)
• AB#123 (Azure Boards)
• Linear、Jira、Notion、GitHub/GitLab の issue、Azure の work item へのリンク

• 親タスク (Linear の sub-issue、Jira のサブタスク、ClickUp のサブタスク): PR は、このタスクのタイトルが対象とする親タスクの要件と照合されます。「親を参照」とだけ書かれた sub-issue もチェックされます。
• サブタスク: いずれかのサブタスクが実現する要件は CHECK MANUALLY (“Delivered by KOD-20”) として表示され、不足として扱われることはありません。
• タスクに添付されたドキュメント (Linear docs): 受け入れ基準を含め、タスクの一部として読み取られます。

​

PR でのタスクの示し方

• “Closes PROJ-1”、またはタイトルやブランチ内のキー: PR はタスク全体と照合されます。
• “Part of PROJ-1”: PR はタスクの一部を実現するものです。不足分は一覧に表示されますが、マージ前に対応すべきものとしては扱われません。
• 説明文の “Refs PROJ-1”、“see PROJ-1”、“related to PROJ-1”: 言及です。PR が他のタスクを挙げていない場合にのみ、PR 自身のタスクとしてチェックされます。
• 1 つの PR につき最大 3 つのタスクがチェックされ、タスクごとに 1 セクションになります。それ以上を記載した PR (リリースやマージなど) はスキップされます。

​

5 つの状態

​

ギャップを表示する前に

• タスクに書かれているとおりの要件。 タスクが一切触れていない入力やエッジケース (負の金額、別のコードパス、言及されていないフォーマット) によって行が PARTIAL になることはありません。変更後に起こること (PR がキューに入れたメッセージを既存のジョブが送信すること、PR が埋めたシリアライザーをルートが使うこと) によっても同様です。
• diff だけでなく、PR が呼び出すコード。 ルールが PR から呼び出されるが変更されていないコード (バリデーター、ヘルパー、レスポンスを組み立てる mapper) にある場合、Kody は何かを表示する前に PR の head 時点のリポジトリでそれを読みます。MISSING、PARTIAL、CHECK MANUALLY のすべての行についても同じことを行います。行が MET になるのは Kody が読んだファイルと行がある場合のみで、diff の外ですでにコードに存在することが示されます。行が MISSING になるのは、Kody が PR の依存するコードを読み、ルールが欠けている行を示した場合のみです。リポジトリで判断できないものは元の状態のままです。
• 別の場所に属する作業。 サブタスクが実現する要件や、チームのガイダンスでここではチェックしないとされている要件は CHECK MANUALLY のままで、不足として再判定されることはありません。

​

プルリクエスト上での動作

• Kody は最初のレビューで PR をチェックします。その後は、誰かが @kody -v business-logic とコメントしたとき、または @kody review --force を実行したときに再チェックします。Re-check は、何かが不足している間の push のたび (修正すれば誰かが依頼しなくてもコメントが更新されます)、または push のたびに設定することもできます。どちらも push ごとに検証が 1 回増えます。
• @kody -v business-logic でいつでも再チェックできます。同じコメントが編集され、Kody が 2 つ目のコメントを投稿することはありません。
• タスクを満たしている PR には、1 行のコメント (”✅ 4 of 4 met”) と手動で確認すべき項目が投稿され、チェック済みであることが作成者にわかります。こうした場合にコメントしないようにするには、Comment when every requirement is met をオフにします。
• どのプラットフォームでもコメントがシグナルです。Kody は check や status を書き込まないため、それ自体でマージをブロックすることはありません。コメントのヘッダーに、修正が必要な項目が示されます。

​

コメントへの返信

• 異議を唱える: 「useDrag.ts で対応済みです」。Kody は指摘された箇所を再チェックし、MET にするか、何を確認したかを説明したうえで状態を維持します。
• 指摘を受け入れる (PR の作成者以外の人。GitHub ではリポジトリへの書き込み権限を持つ人、GitLab ではリポジトリで Developer 以上の権限を持つ人、Bitbucket・Azure Repos・Forgejo ではプラットフォームが返す組織のメンバー): 「キーボードでの並べ替えはスコープ外のため SAA-102 に移しました」。Kody は SAA-102 が存在することを確認し、その行を受け入れた人とともに ACCEPTED にします。その行は修正対象から外れます。この判断は、Kody が要件を少し違う言い回しで書いた場合も含め、タスクの本文が変わらない限り以降の再チェックでも維持されます。タスクが編集された場合は、もう一度受け入れる必要があります。

​

Kody がコメントしない場合

​

オンデマンド実行

• @kody -v business-logic: PR が参照するタスクを再チェック
• @kody -v business-logic PROJ-123 またはタスクへのリンク: そのタスクと照合
• @kody -v business-logic の後に要件をテキストで記述: 書いた内容と照合 (タスク管理ツールは不要)

​

設定

• Task source: 接続されているすべてのタスク管理ツール (ClickUp などのカスタムタスクプラグインを含む)、または 1 つのプラグイン。カスタムプラグインの場合は、ID で 1 つのタスクを読み取るツールを選択します。読み取り専用のツールのみが表示されます。ページ右側に固定された Try it (この設定の編集権限が必要) を使うと、タスクのみの場合は Kody がそこから何を読み取るかが表示され、プルリクエストの場合は画面上の設定 (保存済みかどうかを問わず) でチェック全体を投稿せずに実行します。Post to the pull request は、表示された結果を再実行せずに、テストごとに 1 回だけ投稿します。テスト後にプルリクエストへ新しいコミットがあった場合は投稿が拒否されるので、先にテストを再実行してください。
• Custom task id format (任意): Kody が自動では見つけられない ID のための正規表現。T(\d{4}) は T1234 をタスク 1234 として読み取ります。SAA-96、#12、AB#8、CU-… のようなキーとタスク管理ツールのリンクはこの設定がなくても見つかります。ブランチ名の sc-123 のような小文字のキーも同様です。タイトルや説明文の小文字のキーは、Linear または Jira にそのチームやプロジェクトがある場合にのみ有効です。それ以外のツールでは形式を設定してください。形式が取り出した数字は、Git Issues がタスクソースの場合にのみ Git の issue として読まれます。接続されているすべてのツールを使う設定では、T1234 がリポジトリの issue #1234 になることはありません。
• Where acceptance criteria live: 自動検出 (受け入れ基準のフィールド、チェックリスト、または説明内のリスト)、説明内の見出しの下、またはカスタムフィールド。そのフィールドがないタスクは説明から読み取られます。Under a heading を Acceptance criteria に設定すると、次のタスクは 3 つの箇条書きと照合され、その上の段落は背景情報として扱われます:
  Agents should see at a glance how much time is left on a ticket's SLA.
  
  ## Acceptance criteria
  - The ticket header shows a badge with the remaining SLA time.
  - The badge turns red when less than 1 hour is left.
  - Resolved tickets show no badge.
  
• Comment when every requirement is met (デフォルトでオン): タスクを満たした PR には 1 行のコメントが付きます。オフにするとコメントは付きませんが、不足点は引き続き投稿されます。
• Ask for a task when the PR references none: Kody はスキップする代わりに、PR がどのタスクに対応するかを尋ねる (またはタイプミスを指摘する) コメントを投稿します。Dependabot や Renovate などの bot が作成した PR には何もしません。タスク管理ツールのダウンは対象外です。
• Re-check: リクエスト時のみ (デフォルト)、何かが不足している間の push のたび、または push のたび。各チェックはレビューと同じく組織のモデルで実行されるため、push のたび を選ぶと push ごとに検証 1 回分のコストがかかります。
• Skipped pull requests: コードレビューがスキップする PR はここでもスキップされます。無視するキーワードを含むタイトル (ignoredTitleKeywords、たとえば wip) と、runOnDraft がオフの場合のドラフトです。@kody -v business-logic のコメントは常に実行されます。
• Team guidance: Kody が判断するときに従うメモ。たとえば「フィーチャーフラグは、フラグが存在しデフォルトでオフになっていれば実装済みとみなす」。判定の形式を変えたり、Kody に要件を作り出させたりすることはできません。

​

よくある設定

businessLogic:
  taskSource: 'auto'              # またはプラグインの integration id
  taskSourceTool: 'get_ticket'    # カスタムプラグインのみ: ID で 1 つのタスクを読み取るツール
  taskIdPattern: 'T(\d{4})'       # 任意: Kody が自動で見つけられない ID
  criteriaLocation: 'heading'     # auto | heading | field
  criteriaHeading: 'Acceptance criteria'
  # criteriaField: 'Acceptance Criteria'   # criteriaLocation: 'field' と併用
  teamGuidance: 'Feature flags count as implemented when the flag exists and defaults to off.'
  commentWhenMet: true
  recheckOn: 'request'            # request | failing | push
  requireTask: false

​

CLI から

kodus pr business-validation --task-id AB#8
kodus pr business-validation --task-id AB#8 --format json

​

Cockpit