把 ToppleCat 加進 Java 專案¶

ToppleCat 0.2.0 已發布到 Maven Central。直接把 Gradle plugin 和 JUnit library 加進現有專案即可，不必下載 ToppleCat 原始碼，也不用自己 build。

ToppleCat 的 runtime 與 Gradle/plugin 執行需要 JDK 21 或 25。發布的 artifact 以 Java 21 為 target，維護者的 release build 使用 JDK 25。使用端專案可以使用 Java 17、21 或 25 source target，但執行 JDK 必須是 21 或 25；只使用 JDK 17 執行 ToppleCat 不受支援。

目前不承諾 Gradle daemon JDK 與 consumer contract compiler JDK 不同的組合。現有 custom contract compiler 使用 daemon 的 system compiler；要擴大這項承諾，必須先有獨立且經測試的 compiler seam。

加入新的 LTS 時，會先加入 CI，再標示最舊的支援 runtime 為 deprecated；移除前必須有文件化的 migration window 與 release boundary。相依套件升級若提高 Java floor，也遵循同樣的相容性變更規則。

這一頁會帶你完成三件事：安裝 ToppleCat、讓 AI 能把已確認的規則寫成可執行檢查，並知道功能完成後該用哪個指令驗證。

它在檢查什麼¶

結帳規則是：使用 SAVE100 優惠券時，訂單小計折 100 元。開發者先把規則寫成一般的 Java/JUnit 驗收方法：

@ToppleAcceptanceTest("AC-CART-COUPON")
@DisplayName("使用 SAVE100 折抵訂單小計")
void appliesCoupon(ToppleCase c, ToppleScenario scenario, CouponStage coupon) {
    scenario.given(coupon).a_payable_cart(c.input("cart", Cart.class));
    scenario.when(coupon).checks_out();
    scenario.then(coupon).receipt_shows_discount_and_discounted_subtotal(c);
}

JSON 或 YAML 案例列提供一台具體購物車，以及預期收到的收據。這個方法和案例列合在一起，就是公開的可執行契約。實作 AI 可以讀它，也可以在開發時執行 ./gradlew test。

正式驗證時，ToppleCat 會用審閱者另外選出的案例重跑同一個公開方法。AI 不需要先知道那些案例，仍然可以照公開規則完成實作。

把 ToppleCat 和撰寫契約的 skill 加到專案¶

如果要讓實作 AI 和 ToppleCat 一起工作，要準備兩樣東西：

Gradle plugin 在 Java/JUnit 專案裡執行 ToppleCat。
topplecat-acceptance skill 告訴 AI，怎麼把你選定的驗收條件寫成 Java/JUnit 能執行的驗收方法與案例。

ToppleCat 的正式套件已發布到 Maven Central。先在 settings.gradle.kts 設定 plugin marker 與 library 的來源：

pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
    }
}

dependencyResolutionManagement {
    repositories { mavenCentral() }
}

再到 build.gradle.kts 加入 plugin 與 JUnit dependencies：

plugins {
    java
    id("io.github.samzhu.topplecat") version "0.2.0"
}

dependencies {
    testImplementation("io.github.samzhu.topplecat:topplecat-junit:0.2.0")
    testImplementation("org.junit.jupiter:junit-jupiter:6.1.1")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher:6.1.1")
}

tasks.test { useJUnitPlatform() }

接著，把這個 skill 安裝到 AI 要工作的專案：

npx skills@latest add samzhu/topplecat --skill topplecat-acceptance

在讓 agent 讀寫專案前，先讀 skill 原始碼。它不會替你補寫需求。它會協助 AI 問清楚規則，再把你選定的規則綁成 ToppleCat 可以執行的 Java/JUnit 驗收內容。

和 AI 準備一次交付¶

ToppleCat 可以和任何 SDD 開發流程一起用。團隊原本怎麼談需求、寫 Spec、安排工作、叫 AI 實作，就照原本方式進行；那些事仍由你的工作流負責。ToppleCat 從你選定驗收條件後才加入：它把條件寫成 Java/JUnit 可執行檢查，等 AI 說做完後再獨立驗證。

下面用 Matt Pocock 的 skills 示範一條完整流程。你使用別的 SDD 工作流也沒關係，照同樣的 ToppleCat 步驟即可。

先安裝需要的 skills¶

在 Codex 或其他 coding agent 裡，先把 Matt Pocock 的 skills 安裝到專案：

npx skills@latest add mattpocock/skills

安裝程式會讓你選 skill。請選 setup-matt-pocock-skills、to-spec、to-tickets 和 implement。implement 收尾時會使用 code-review，所以不用把 code review 當成 ToppleCat 另外要求的一步。

每個專案第一次使用時，再在 agent 對話裡執行：

$setup-matt-pocock-skills

它會詢問這個專案的工作追蹤位置和領域文件放在哪裡。也要安裝前一節的 ToppleCat acceptance skill；兩組 skills 都準備好後，再開始這次交付。

在同一段對話裡寫規則和可執行檢查¶

假設規則是：可以結帳的購物車使用 SAVE100 時，折 100 元。在同一段對話中一起使用：

$to-spec + $topplecat-acceptance

$to-spec 會把對話中已經談妥的規則整理成 Spec。$topplecat-acceptance 會把你選定的每一條 Acceptance Condition（AC）寫成 Java/JUnit 驗收方法和 ToppleCat 能執行的案例。它會準備實作 AI 可以看的公開內容，也會另外準備給審閱者的內容。

規則有兩種可能意思時，先回答問題，不要讓 AI 自己選。例如，優惠券是否能套用到含有排除商品的購物車？這種決定要由人寫回規則，skill 不能代替你決定。

這時你已經有寫下來的規則、公開的 Java 驗收程式和公開案例。下一步是看 Java 程式究竟會檢查什麼。

在終端機裡：檢視準備好的驗收內容¶

Spec 和 Java 驗收程式準備好後，執行：

./gradlew toppleCatReview --spec specs/checkout/spec.md

toppleCatReview 是 Gradle 指令，不是 agent skill。它會產生只給審閱者看的 Spec Review 頁面。你可以把選定的 Spec、Java 驗收方法編譯出的 Given/When/Then 呈現，以及案例放在一起閱讀。這份頁面沒有測試結果；它要回答的是「Java 程式寫的驗收內容，是否就是原本的規則？」

Review 會執行它需要的 Check，所以主流程不用再列 toppleCatCheck。如果只想快速檢查驗收方法和案例有沒有綁好，可以另外執行 ./gradlew toppleCatCheck --spec specs/checkout/spec.md。

在 agent 對話裡：需要時才拆票¶

如果已確認的 Spec 有好幾塊可以分開完成的工作，使用 $to-tickets。它會產生可以各自完成的工作票，並標示先後關係。小改動可以略過這一步，直接依 Spec 實作。

在終端機裡：實作前保護驗收內容¶

看完 Spec Review 後，執行：

./gradlew toppleCatSeal

Seal 會把只給審閱者看的原始碼移到本機保管區，並記錄當時完整的驗收內容與驗證設定。接下來實作 AI 只會看到公開專案。之後正式驗證時，ToppleCat 可以檢查這些內容或政策是否在 Seal 後被改動。

Seal 是內容完整性記錄，不是加密、作業系統隔離，也不是人已經接受最後交付。

在 agent 對話裡：實作已確認的工作¶

把 Spec 或 tickets 交給 $implement。它會在開發時使用專案原本的測試，並在收尾時使用 code-review。實作 AI 只根據公開驗收程式工作；不要把私人的 Spec Review、審閱者案例或審閱者原始碼交給它。

AI 說完成後，回到終端機進行正式驗證。

驗證交付結果¶

實作 AI 說工作完成後，執行：

./gradlew toppleCatVerify

toppleCatVerify 會重跑公開契約、執行每一道已啟用的獨立檢查，並產生只給審閱者看的 Verification Report。機器可讀的結論在 build/topplecat/evidence.json。這是 Gradle 指令，不是 agent skill。

審閱者若只想快速看這次交付，可以指定 Spec 或 AC ID；報告會清楚標示範圍。CI 應該使用不帶範圍的 toppleCatVerify，檢查完整契約。

根據證據做決定¶

PASS 表示封存政策要求的每一道檢查都在這次執行中通過。FAIL 表示某道完成的檢查找到阻擋問題。INCOMPLETE 表示 ToppleCat 沒有取得足夠、可信的當次證據。

如果是指定 Spec 或 AC 的有限範圍驗證，PASS 只涵蓋那次指定的範圍。這些結果都不會替人判斷原始業務規則是否完整。人要讀清楚跑了什麼、發生什麼，再決定是否接受交付。

準備導入專案時，接著讀把規則寫成可執行檢查。要解讀報告時，讀ToppleCat 如何檢查交付。