quality-gate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Quality Gate

quality gateは固定bundleではない。

何をcheckするか、どのtest levelまで要求するかを、projectの実stack、framework/runtimeのcurrent official guidance、変更surface、release riskからcompileする。

このSkillは通常taskのvalidationだけでなく、初期化時にquality infrastructureそのものを設計・導入・修復する責務を持つ。

quality gate 不是固定 bundle。

根据项目的实际 stack、framework/runtime、当前官方指导、变更范围和 release risk，综合确定要检查什么以及要求达到哪个 test level。

这个 Skill 不仅通常用于 task 的 validation，还负责在初始化时设计、引入和修复 quality infrastructure 本身。

1. Initialization / recompile

初回

/init

、major framework/runtime upgrade、test architecture変更、CI/CD変更時はquality profileを再設計する。

実repoから検出:

languages / frameworks / SDKs / versions
package/workspace structure
app type: web / API / CLI / desktop / mobile / library / IaC
architecture boundaries
persistence / queue / cache / external services
auth / network / filesystem boundaries
existing test/lint/type/build scripts
generated-code boundary
browser / OS / CPU architecture targets
release/deploy target
GitHub PR topology: independent / stacked / release trunk

次に実versionに対応するcurrent official documentationを調査する。

優先順位:

framework/runtime/SDK official quality/testing guidance
official examples/templates/starters
official first-party Actions / CI examples
official language/toolchain guidance
coherent existing project configuration
established maintained ecosystem tooling
custom tooling

存在しない「公式推奨」を捏造しない。

首次

/init

、framework/runtime 大版本升级、test architecture 变更或 CI/CD 变更时，重新设计 quality profile。

从实际 repo 中检测：

语言 / frameworks / SDKs / 版本
package/workspace 结构
应用类型：web / API / CLI / desktop / mobile / library / IaC
架构边界
persistence / queue / cache / external services
auth / network / filesystem 边界
现有 test/lint/type/build scripts
generated-code 边界
browser / OS / CPU architecture targets
release/deploy target
GitHub PR topology：independent / stacked / release trunk

接下来调查与实际 version 对应的 current official documentation。

优先级：

framework/runtime/SDK 官方 quality/testing 指导
官方 examples/templates/starters
官方 first-party Actions / CI examples
官方 language/toolchain 指导
连贯一致的现有 project configuration
成熟且持续维护的 ecosystem tooling
custom tooling

不得捏造不存在的「官方推荐」。

2. Verification taxonomy

project固有profileへ最低限、必要なtest levelの意味を定義する。

名称はframework慣習に合わせて変更できるが、責務を混同しない。

为 project 专属 profile 定义最低限度的必要 test level 含义。

名称可以按 framework 惯例修改，但不得混淆职责。

Unit test

1つの小さいlogic/component/moduleのbehaviorを、外部boundaryを最小化して高速に検証する。

主な対象:

pure/domain logic
parser / validator / scheduler / algorithm
state transition
isolated component behavior
error handling branch

目的:

logic regressionを局所的・高速に検出
failure locationを狭くする

unit testだけでDB/API/runtime wiringの正しさを証明しない。

在最小化外部 boundary 的前提下，快速验证一个小 logic/component/module 的 behavior。

主要对象：

pure/domain logic
parser / validator / scheduler / algorithm
state transition
isolated component behavior
error handling branch

目的：

局部、快速地检测 logic regression
缩小 failure location

仅靠 unit test 无法证明 DB/API/runtime wiring 正确。

Smoke / connectivity test（疎通テスト）

Smoke / connectivity test（连通性测试）

systemまたは主要serviceが起動し、主要boundaryが最低限接続可能で、critical pathの入口が成立することを安価に検証する。

主な対象:

process/service startup
health/readiness endpoint
application -> DB connection
application -> cache/queue connection
frontend -> API basic request
required migration/schema availability
desktop/mobile app launch
packaged artifact startup

疎通testはdeep behavior correctnessではなく「配線が成立しているか」を見る。

unit/integration testがgreenでも、設定・DI・port・env・migration・packagingが壊れていればsmoke testで落とす。

以较低成本验证 system 或主要 service 能够启动、主要 boundary 至少可以连接，并且 critical path 的入口成立。

主要对象：

process/service startup
health/readiness endpoint
application -> DB connection
application -> cache/queue connection
frontend -> API basic request
required migration/schema availability
desktop/mobile app launch
packaged artifact startup

连通性 test 检查的是「接线是否成立」，而不是深层 behavior correctness。

即使 unit/integration test 为 green，如果配置、DI、port、env、migration 或 packaging 已损坏，也应通过 smoke test 拦截。

Integration test（結合テスト）

Integration test（结合测试）

2つ以上のreal boundary/componentを組み合わせ、interface・data flow・transaction等が実際に成立することを検証する。

主な対象:

API + service + database
repository + real/test DB
queue producer + consumer
auth middleware + endpoint
filesystem/network adapter + domain
frontend data layer + API contract
migration + application read/write

mockだけでboundary contractを再現したtestをreal integration testと偽らない。

外部SaaSはsandbox/test double/contract testを選択できるが、何をrealに検証しているか明示する。

组合两个或更多 real boundary/component，验证 interface、data flow、transaction 等实际成立。

主要对象：

API + service + database
repository + real/test DB
queue producer + consumer
auth middleware + endpoint
filesystem/network adapter + domain
frontend data layer + API contract
migration + application read/write

不要把仅用 mock 复现 boundary contract 的 test 虚报为 real integration test。

对于外部 SaaS，可以选择 sandbox/test double/contract test，但必须明确哪些内容是实际验证的。

Contract / schema test

projectに意味がある場合は独立levelとして使う。

対象:

OpenAPI / GraphQL / protobuf
DB schema compatibility
event/message schema
generated client/server compatibility
public SDK/API contract

如果对 project 有意义，可以作为独立 level 使用。

对象：

OpenAPI / GraphQL / protobuf
DB schema compatibility
event/message schema
generated client/server compatibility
public SDK/API contract

E2E / system test

user-visibleまたはsystem-level critical flowを、productionに近い境界構成でend-to-endに検証する。

主な対象:

sign-in -> operation -> persistence -> rendered result
purchase/scheduling/upload等のcritical journey
browser/native interaction
cross-service workflow
release-like environment smoke + critical scenarios

E2Eですべてのedge caseを網羅しない。slow/flakyなE2Eでunit/integrationの責務を代替しない。

在接近 production 的 boundary 构成中，端到端验证 user-visible 或 system-level critical flow。

主要对象：

sign-in -> operation -> persistence -> rendered result
purchase/scheduling/upload 等 critical journey
browser/native interaction
cross-service workflow
release-like environment smoke + critical scenarios

E2E 不需要覆盖所有 edge case。不得用 slow/flaky 的 E2E 替代 unit/integration 的职责。

Manual / visual verification

UI/UX、native platform、hardware integration等でautomationが十分でない場合のみ明示的gateとして定義する。

manual verificationを暗黙の「見た感じOK」にしない。手順・期待結果・artifactを残す。

仅当 UI/UX、native platform、hardware integration 等场景无法得到充分 automation 时，才将其明确定义为 gate。

不要将 manual verification 隐式地视为「看起来没问题」。应保留步骤、预期结果和 artifact。

Verification Executor / native environment

verificationはimplementation workerと同じworkspace topologyを必須にしない。ADR-0020に従い、検証対象をimmutable candidate identityへpinし、environment identityとevidence provenanceを記録する。

最低限のevidence shape:

text

candidate_identity
environment_identity
procedure_or_command
observed_result
evidence_artifacts
source_mutation_observed

Windows-native、macOS-native、GUI application、physical device、installed build、CI runner等のsingleton environmentは、必要ならexclusive lease / serializationで安全に使用する。worktreeを作れないこと自体をverification skip理由にしない。

unexpectedなtracked source/config mutationが確認されたvalidationは、current candidateのclean evidenceとして扱わずreconcile/re-runする。

verification 不一定需要与 implementation worker 使用相同的 workspace topology。按照 ADR-0020，将验证对象固定到 immutable candidate identity，并记录 environment identity 和 evidence provenance。

最低限度的 evidence shape：

text

candidate_identity
environment_identity
procedure_or_command
observed_result
evidence_artifacts
source_mutation_observed

对于 Windows-native、macOS-native、GUI application、physical device、installed build、CI runner 等 singleton environment，必要时可通过 exclusive lease / serialization 安全使用。不能仅仅因为无法创建 worktree，就将其作为跳过 verification 的理由。

如果发现 validation 期间出现了意外的 tracked source/config mutation，则不得将其视为 current candidate 的 clean evidence，而应执行 reconcile/re-run。

3. 動作確認ゲートを変更riskから決める

3. 根据变更风险决定验证 gate

全ticketに全test levelを機械的に要求しない。

変更前に最低限判定する:

変更したlogic
変更したboundary
runtime/configuration変更
persistence/schema変更
user-visible flow変更
deployment/package変更
security-sensitive path変更
failure時のimpact

代表的なdefault:

Change	Minimum verification candidate
pure/domain logic	unit
API/service behavior	unit + integration
DB query/schema/migration	integration + migration/schema check + smoke
runtime/env/DI/network wiring	smoke + relevant integration
frontend component local behavior	unit/component
user journey/navigation/auth	integration/contract + E2E
external API adapter	unit + contract/integration + failure-path test
build/package/container	build/package + smoke
release branch	full applicable integration + critical E2E/smoke + release-specific checks
security fix	regression test + vulnerable-path verification + applicable integration/E2E + affected `security-audit` coverage revalidation when applicable

これはfixed universal matrixではない。framework official guidanceとproject architectureでcompileする。

不要机械地要求每个 ticket 都执行所有 test level。

变更前至少要判断：

变更的 logic
变更的 boundary
runtime/configuration 变更
persistence/schema 变更
user-visible flow 变更
deployment/package 变更
security-sensitive path 变更
失败时的影响

典型 default：

Change	Minimum verification candidate
pure/domain logic	unit
API/service behavior	unit + integration
DB query/schema/migration	integration + migration/schema check + smoke
runtime/env/DI/network wiring	smoke + relevant integration
frontend component local behavior	unit/component
user journey/navigation/auth	integration/contract + E2E
external API adapter	unit + contract/integration + failure-path test
build/package/container	build/package + smoke
release branch	full applicable integration + critical E2E/smoke + release-specific checks
security fix	regression test + vulnerable-path verification + applicable integration/E2E + affected `security-audit` coverage revalidation when applicable

这不是固定的通用矩阵。应结合 framework official guidance 和 project architecture 进行综合确定。

4. Quality profileをproject-localにcompileする

4. 将 Quality profile 编译为 project-local 配置

通常taskで毎回再調査しなくて済むよう、再現可能なcanonical quality profileをrepository-controlled stateとして必ず保存する。

profileはproject conventionsに合う場所へ置く。標準候補は

quality/profile.yaml

、

quality/profile.json

、または同等のmachine-readable project-local configとし、既存のcanonical configがある場合はそれを再利用する。

profileには最低限:

```
schema_version
```
profile version / updated-at or source revision
detected framework/runtime/SDK versions
official guidance source referencesと確認時点
test taxonomyとproject内の具体例
change-type -> required verification mapping
fast worker gate
ticket integration gate
stack reconciliation/revalidation policy
release gate
canonical validation entry points
configured CI checks when present
coverage policy when meaningful
browser/device/OS/architecture matrix
native/device/GUI verificationのcandidate materializationとenvironment ownership policy
CI trigger semantics (
```
pull_request
```
/
```
push
```
/ schedule / dispatch / comment/review event)
runner policyとplatform matrixの起動条件
expensive/native/platform-specific gateの適用条件
concurrency / cancellation / timeout policy
artifact/report pathsとretention policy
repository visibility / included usage / billing modelを踏まえたCI resource policy
expected CI usage/cost modelまたはbudget guardrail（意味があるprojectのみ）
failure policy

を持たせる。

worker / integration / releaseの各gateには、agentとCIが同じsemanticsで呼べるstable deterministic entry pointを必須で定義する。

例:

text

validate:fast
validate:integration
validate:release

実command名はproject conventionに合わせる。

例外として、platform制約等で1つのlocal commandへ完全統合できない場合は、profileにその適用条件・runner/platform・required evidenceを明示し、agent/CIが別々の暗黙gateを選ばないようにする。

为了避免在每次常规 task 中重复调查，必须将可复现的 canonical quality profile 保存为 repository-controlled state。

profile 应放在符合 project conventions 的位置。标准候选包括

quality/profile.yaml

、

quality/profile.json

，或等价的 machine-readable project-local config；如果已有 canonical config，则复用它。

profile 至少应包含：

```
schema_version
```
profile version / updated-at or source revision
检测到的 framework/runtime/SDK versions
official guidance source references 及确认时间
test taxonomy 及 project 内的具体示例
change-type -> required verification mapping
fast worker gate
ticket integration gate
stack reconciliation/revalidation policy
release gate
canonical validation entry points
configured CI checks（如存在）
coverage policy（如有实际意义）
browser/device/OS/architecture matrix
native/device/GUI verification 的 candidate materialization 与 environment ownership policy
CI trigger semantics（
```
pull_request
```
/
```
push
```
/ schedule / dispatch / comment/review event）
runner policy 与 platform matrix 的启动条件
expensive/native/platform-specific gate 的适用条件
concurrency / cancellation / timeout policy
artifact/report paths 与 retention policy
根据 repository visibility / included usage / billing model 制定 CI resource policy
expected CI usage/cost model 或 budget guardrail（仅对有意义的 project）
failure policy

对于 worker / integration / release 的每个 gate，都必须定义一个 stable deterministic entry point，使 agent 和 CI 能以相同 semantics 调用。

示例：

text

validate:fast
validate:integration
validate:release

实际 command name 应遵循 project convention。

例外情况是受 platform 约束，无法完全集成为一个 local command。此时应在 profile 中明确其适用条件、runner/platform 和 required evidence，避免 agent/CI 各自选择不同的隐式 gate。

4.1 Semantic validation evidence verification

commit / PRのcombined statusが

success

であることだけをquality gate成功の証拠にしない。

repository policy / quality profileは、release・ticket・runtime等の各candidateに対して どのvalidationがapplicableか をmachine-readableまたは一意に判定可能な形で持つ。validation identityはlocal deterministic commandでもCI job/checkでもよく、CIの存在や成功を全project共通の必須条件にはしない。

CI/checkが存在する場合は最低限、次を確認する:

check context / job名がcandidate SHA上に実在する
checkが検証対象のcurrent SHA / current PR headを対象としている
known failureを無視していない
skipped / neutral / cancelled / unrelated bot successをapplicable validationの代替にしない
同名checkでも別workflow / 別event semanticsなら誤同定しない
Draftのためreviewをskipしたbot status等をrelease validation成功として数えない
current SHAへ更新後、staleな以前のgreenを再利用しない

validation implementation exists と branch protection enforcement は別invariantとして扱う。

ADR-0016のdefault

main

protectionではfixed required status checksを設定しない。workflowやdeterministic gateが存在しても、それをrulesetのrequired statusへ自動登録しない。repositoryが明示的に安定したrequired status checkを採用する場合だけ、quality profileにそのidentityと適用範囲を記録する。

release-source制約は架空のrequired checkで補わず、merge executor / release automationが

base == main

のとき

head == current release-*

を検証する。

不要仅以 commit / PR 的 combined status 为

success

作为 quality gate 成功的证据。

repository policy / quality profile 必须以 machine-readable 或可唯一判断的形式，记录 release、ticket、runtime 等每个 candidate 适用哪些 validation。validation identity 可以是 local deterministic command，也可以是 CI job/check；不应将 CI 的存在或成功作为所有 project 共通的必需条件。

如果存在 CI/check，至少确认：

check context / job 名实际存在于 candidate SHA 上
check 验证的是 current SHA / current PR head
未忽略已知 failure
不以 skipped / neutral / cancelled / unrelated bot success 替代 applicable validation
即使 check 同名，若 workflow / event semantics 不同，也不得错误识别
不将因 Draft 而跳过 review 的 bot status 等计为 release validation 成功
current SHA 更新后，不得复用之前留下的 stale green result

应将 validation implementation exists 与 branch protection enforcement 视为两个不同的 invariant。

根据 ADR-0016，

main

的默认 protection 不设置 fixed required status checks。即使存在 workflow 或 deterministic gate，也不应自动将其注册到 ruleset 的 required status。只有 repository 明确采用稳定的 required status check 时，才在 quality profile 中记录其 identity 和适用范围。

不要用虚构的 required check 弥补 release-source 约束；应由 merge executor / release automation 验证当

base == main

时，

head == current release-*

。

5. 調査だけで終わらず実装する

5. 不要止于调查，必须实施

初期化完了とはrecommendation reportを書くことではない。

必要なら実際に追加・修復する:

formatter / linter / static-analysis config
compiler / type-check config
unit/component test infrastructure
smoke/connectivity test infrastructure
integration/contract/E2E infrastructure
framework/platform-specific validation
documentation tests
dependency/static analysis
coverage configuration
schema/migration validation
browser/device/OS/architecture matrices
production build/package checks
code/dependency/security checks
project-local specialized Agent Skills
```
.github/workflows/*
```
required CI check structure

既存の高品質な構成を理由なく置換しない。

初始化完成并不等于写一份 recommendation report。

必要时，应实际添加或修复：

formatter / linter / static-analysis config
compiler / type-check config
unit/component test infrastructure
smoke/connectivity test infrastructure
integration/contract/E2E infrastructure
framework/platform-specific validation
documentation tests
dependency/static analysis
coverage configuration
schema/migration validation
browser/device/OS/architecture matrices
production build/package checks
code/dependency/security checks
project-local specialized Agent Skills
```
.github/workflows/*
```
required CI check structure

不得无理由替换已有的高质量配置。

6. Framework-native checksを優先する

6. 优先采用 Framework-native checks

一般toolを機械的に追加する前にframework/runtimeの標準checkを確認する。

同じ責務のtoolを重複導入しない。

frameworkが特定領域をE2E/real runtimeで検証することを推奨する等、test levelにofficial constraintがある場合はgateへ反映する。

在机械式添加通用 tool 之前，先检查 framework/runtime 的标准 check。

不要重复引入职责相同的 tool。

如果 framework 建议在特定领域使用 E2E/real runtime 进行验证等 test level official constraint，应将其反映到 gate 中。

7. Agent Skills / toolingもstack-awareにする

7. Agent Skills / tooling 也应具备 stack awareness

必要なspecialized workflowについてofficial / maintained Agent Skills、CLI、LSP、plugin、MCP等を調査する。

優先:

existing deterministic project command
framework/runtime official CLI
short project-local Skill wrapping deterministic tools
native agent capability
明確な優位があるplugin/MCP

针对必要的 specialized workflow，调查 official / maintained Agent Skills、CLI、LSP、plugin、MCP 等。

优先级：

existing deterministic project command
framework/runtime official CLI
包装 deterministic tools 的简短 project-local Skill
native agent capability
具有明确优势的 plugin/MCP

7.1 Delivery-estimation integration

agent-delivery-estimation

がdelivery forecastを行う場合、quality gateは次の観測値を提供できる形にする。

validation level / required gate
CI started/completed duration
queue / retry / failure
E2E / manual verification wait
release-only validation cost
current-SHA revalidationによる追加round

これらはforecast inputであり、estimateを短縮するためにrequired gateを削除・skip・弱体化してはならない。 delivery forecastはquality requirementへ従い、逆にquality requirementをforecastへ合わせない。

当

agent-delivery-estimation

进行 delivery forecast 时，quality gate 应能够提供以下观测值：

validation level / required gate
CI started/completed duration
queue / retry / failure
E2E / manual verification wait
release-only validation cost
current-SHA revalidation 产生的额外 round

这些是 forecast input，不得为了缩短 estimate 而删除、skip 或弱化 required gate。

delivery forecast 应遵循 quality requirement，不能反过来让 quality requirement 迎合 forecast。

8. GitHub Actions / CI resource efficiency

GitHub Actionsを使用するprojectではlocal gateとCI gateを同じsemanticsへ揃える。

CI resource efficiencyもquality invariantとして扱う。品質を落としてActionsを節約するのではなく、同じverification signalを必要な境界で一度だけ実行する。

初期化時とCI/CD変更時にcurrent official GitHub Actions guidance、billing/usage model、framework/runtime公式CI exampleを確認する。GitHub Actionsのrunner価格、included usage、rounding、public/privateの扱い等は変化し得るため、固定価格をpolicyへ埋め込まない。

对于使用 GitHub Actions 的 project，应使 local gate 与 CI gate 保持相同 semantics。

CI resource efficiency 也是 quality invariant。不要为了节省 Actions 而降低质量，而应在必要的 boundary 上仅执行一次相同的 verification signal。

初始化和 CI/CD 变更时，应确认 current official GitHub Actions guidance、billing/usage model 以及 framework/runtime 官方 CI example。GitHub Actions 的 runner 价格、included usage、rounding、public/private 处理方式等可能发生变化，因此不要在 policy 中嵌入固定价格。

8.1 実測してから最適化する

8.1 实际测量后再优化

workflow run回数だけでcostやquota消費を判断しない。

最低限、次を使ってactual usageを評価する:

repository visibility
workflow / event / branch
job count
runner label / OS / architecture
job started/completed timeまたはbillable duration
success / failure / cancelled / skipped
同一commit/SHAに対する重複run
artifact / cache usage when relevant
billing/usage画面または利用可能なusage API

基本モデルは次で考える:

text

expected CI usage ≈ trigger frequency × started jobs × billed duration × runner cost/weight

単なる

workflow runs = N

をusage量として報告しない。

不要仅根据 workflow run 次数判断 cost 或 quota 消耗。

至少应使用以下信息评估 actual usage：

repository visibility
workflow / event / branch
job count
runner label / OS / architecture
job started/completed time 或 billable duration
success / failure / cancelled / skipped
针对同一 commit/SHA 的重复 run
artifact / cache usage（如相关）
billing/usage 页面或可用的 usage API

基本模型：

text

expected CI usage ≈ trigger frequency × started jobs × billed duration × runner cost/weight

不要仅将

workflow runs = N

作为 usage 量报告。

8.2 trigger duplicationを避ける

8.2 避免 trigger duplication

同じvalidationを同じcommitに対して意味なく

push

と

pull_request

の両方で実行しない。

通常のdefault:

ticket/feature branch:
```
pull_request
```
でintegration gate
```
main
```
/ release trunk / tag:
```
push
```
でpost-mergeまたはrelease-specific gate
manual deep verification:
```
workflow_dispatch
```
periodic verificationに実際の意味がある場合のみ
```
schedule
```

push.branches: ['**']

pull_request

のような構成を、同じfull CIを二重起動するdefaultにしない。

両eventが必要な場合は、それぞれ異なる責務を持つことをprofileへ明示する。

stacked PRでも同じ原則を適用し、immediate predecessorへのPR validationとbranch push validationを無意味に重複させない。

不要针对同一个 commit 无意义地同时通过

push

和

pull_request

执行同一 validation。

通常的 default：

ticket/feature branch：通过
```
pull_request
```
执行 integration gate
```
main
```
/ release trunk / tag：通过
```
push
```
执行 post-merge 或 release-specific gate
manual deep verification：使用
```
workflow_dispatch
```
仅当 periodic verification 具有实际意义时使用
```
schedule
```

不要将

push.branches: ['**']

pull_request

这样的配置作为重复启动同一 full CI 的 default。

如果两个 event 都需要，应在 profile 中明确它们各自承担的不同职责。

stacked PR 也应遵循相同原则，避免无意义地重复执行 immediate predecessor 的 PR validation 和 branch push validation。

8.3 fast PR gateとexpensive platform gateを分離する

8.3 分离 fast PR gate 与 expensive platform gate

通常PRのfeedback loopでは、変更surfaceを十分検証できる最小のrepresentative gateを優先する。

Windows/macOS/native/device/browser matrix等のexpensive platform verificationは削除せず、必要条件へ移す。

代表的な起動条件:

platform/native関連pathが変更された
platform-specific behavior / packaging / process invocationが変更された
release candidate / release trunk / tag
explicit label / manual dispatchによるfull verification
required compatibility matrixを定期的に再確認する必要がある

platform-specific defect riskが常に高いprojectではPRごとのmatrixを維持してよい。その場合もcostを認識した明示的decisionとしてprofileへ記録する。

在常规 PR feedback loop 中，应优先选择足以验证变更范围的最小 representative gate。

不要删除 Windows/macOS/native/device/browser matrix 等 expensive platform verification，而应将其转为在必要条件下触发。

典型启动条件：

platform/native 相关 path 发生变化
platform-specific behavior / packaging / process invocation 发生变化
release candidate / release trunk / tag
通过 explicit label / manual dispatch 触发 full verification
需要定期重新确认 required compatibility matrix

如果 project 始终面临较高的 platform-specific defect risk，可以保留每个 PR 的 matrix。即便如此，也应将成本纳入考量，并把该决定明确记录在 profile 中。

8.4 expensive jobはrunner allocation前にgateする

8.4 在分配 runner 前 gate expensive job

高コストjobを起動してからstep内で「対象変更ではない」と判定して終了する設計を避ける。

可能なら次を使い、runnerを必要としない段階またはjob start前に不要実行を除外する:

workflow
```
paths
```
/
```
paths-ignore
```
event / branch filter
job-level
```
if
```
lightweight preflight jobからのoutputを使ったdependent expensive jobの条件分岐

ただしpreflight自体のminimum billing/latencyも考慮し、単純なpath filterで十分なら余計なjobを増やさない。

不要先启动高成本 job，再在 step 内判断「与本次修改无关」并将其结束。

可能的情况下，应使用以下机制，在不需要 runner 的阶段或 job 启动前排除不必要执行：

workflow
```
paths
```
/
```
paths-ignore
```
event / branch filter
job-level
```
if
```
使用 lightweight preflight job 的 output 对 dependent expensive job 进行条件分支

但也应考虑 preflight 本身产生的 minimum billing/latency；如果简单的 path filter 已足够，就不要增加多余 job。

8.5 comment/review-driven automationを事前filterする

8.5 预先过滤 comment/review-driven automation

issue_comment

、

pull_request_review_comment

、

pull_request_review

等でAI assistantやautomationを起動する場合、すべてのcomment/review eventでrunnerを確保し、action step内部のtrigger phrase判定だけに依存してはいけない。

可能ならjob-level条件で最低限:

explicit trigger phrase / command
intended event type
trusted actor / permission条件 when necessary
bot-generated noiseの除外

を判定してからrunnerを起動する。

如果通过

issue_comment

、

pull_request_review_comment

、

pull_request_review

等事件启动 AI assistant 或 automation，不要为所有 comment/review event 分配 runner，也不能只依赖 action step 内部的 trigger phrase 判断。

可能的情况下，应通过 job-level 条件至少判断：

explicit trigger phrase / command
intended event type
必要时的 trusted actor / permission 条件
排除 bot-generated noise

然后再启动 runner。

8.6 superseded CIをcancelする

8.6 取消已被取代的 CI

新commitで価値を失うvalidationには

concurrency

と

cancel-in-progress: true

を原則設定する。

concurrency identityはworkflow + PR identityまたはref等、同一feedback streamを正しく表すものにする。

ただしdeploy、migration、release publish等のside effectを伴うjobは安易に途中cancelしない。idempotency/recovery policyと合わせて個別設計する。

对于会因新 commit 而失去价值的 validation，原则上应设置

concurrency

和

cancel-in-progress: true

。

concurrency identity 应由 workflow + PR identity 或 ref 等组成，正确表示同一个 feedback stream。

但是，不要轻易中途取消 deploy、migration、release publish 等具有 side effect 的 job。应结合 idempotency/recovery policy 单独设计。

8.7 timeoutを明示する

8.7 明确 timeout

各jobへ実測に基づく

timeout-minutes

を設定する。

通常実行時間に合理的marginを加える。GitHubの大きなdefault timeoutをfailure recovery policyの代わりにしない。

hung process / deadlock / unavailable serviceで数十分〜数時間runnerを保持する状態を防ぐ。

为每个 job 设置基于实际测量结果的

timeout-minutes

。

通常执行时间之上应留出合理 margin。不要将 GitHub 较大的 default timeout 当作 failure recovery policy。

避免因 hung process / deadlock / unavailable service 而持续占用 runner 数十分钟至数小时。

8.8 artifact / cacheは目的別に管理する

8.8 按用途管理 artifact / cache

PR verificationの一時artifactとrelease artifactを同じretention policyにしない。

CI evidence / debug artifact: 必要な期間だけ短く保持
release deliverable: release policyに従う
artifactが不要ならuploadしない
cacheは実測でbuild/test時間を改善する場合に使う

storage削減とActions minutes削減を混同しない。現在のbottleneckをusage dataから判断する。

不要让 PR verification 的临时 artifact 与 release artifact 使用相同的 retention policy。

CI evidence / debug artifact：只在必要期间内短暂保留
release deliverable：遵循 release policy
不需要 artifact 时不要上传
只有实测能够改善 build/test 时间时才使用 cache

不要混淆 storage 节省与 Actions minutes 节省。应根据 usage data 判断当前 bottleneck。

8.9 CIを削るのではなく境界を再配置する

8.9 不要削减 CI，而应重新定位 boundary

禁止:

quota不足を理由にrequired verificationを無断削除する
native/platform testを単に消してgreenにする
required verificationをdisableしてusage問題を隠す
self-hosted runnerへ移せば安全性検討不要とみなす

高コストverificationが必要なら、PR every-commitからrelease gate / change-sensitive gate / manual full gateへ移せないか評価する。

self-hosted runnerを使う場合はActions minutesだけでなく、untrusted code execution、credential exposure、host persistence、availability、maintenance costを含めて判断する。

禁止：

以 quota 不足为由擅自删除 required verification
简单删除 native/platform test 以获得 green 结果
禁用 required verification 来掩盖 usage 问题
认为迁移到 self-hosted runner 后便无需评估安全性

如果确实需要高成本 verification，应评估能否将其从 PR 的每次 commit 转移到 release gate / change-sensitive gate / manual full gate。

使用 self-hosted runner 时，除了 Actions minutes，还应综合评估 untrusted code execution、credential exposure、host persistence、availability 和 maintenance cost。

8.10 budgetはlast guardrailにする

8.10 将 budget 作为最后一道 guardrail

private repository等でmetered usageがある場合、必要に応じてaccount/org/repositoryのbudget/alertを設定する。

budgetはworkflow設計の代替ではない。

推奨運用:

included usageとactual monthly burnを確認
trigger duplication / unnecessary platform jobs / runaway jobsを先に修正
optimized baselineを1 billing cycle観測 4.通常利用 + 合理的headroomにbudgetを設定
usage spike時は「回数」ではなくrunner/job単位で再計測

对于 private repository 等存在 metered usage 的场景，必要时应在 account/org/repository 层级设置 budget/alert。

budget 不能替代 workflow 设计。

推荐流程：

确认 included usage 和 actual monthly burn
优先修复 trigger duplication / unnecessary platform jobs / runaway jobs
观察一个 billing cycle 的 optimized baseline
根据正常用量与合理 headroom 设置 budget
usage spike 时，不要按「次数」，而应按 runner/job 重新测量

8.11 反復テストの適応的な頻度制御

8.11 对重复测试进行自适应频率控制

初期化・再整備時は既存runnerの差分実行とcacheを優先して調査する。必要であれば、決定的な任意workerテストだけに履歴ベースの頻度減衰をopt-inで導入する（実装例と適用条件、ADR-0033）。

検証入力・環境・commandの同一性が不明、または変更・失敗・履歴欠損時は実行する。延期は成功ではない。required worker / integration / CI / release / security / native / deviceのgateは減衰によって省略しない。

quality profileに対象check、入力・環境の識別、最大間隔、強制実行入口、延期結果、測定・撤去条件を残す。状態はworkerごとに隔離し、他の環境へ流用しない。

初始化或重新整理时，应优先调查在现有 runner 上执行 differential run 以及使用 cache。必要时，仅对确定性的可选 worker test opt-in 引入基于历史数据的频率衰减（实现示例与适用条件、ADR-0033）。

如果无法确认验证输入、环境和 command 是否相同，或者内容发生变化、验证失败、历史记录缺失，则必须执行。延期不等于成功。不得通过频率衰减省略 required worker / integration / CI / release / security / native / device gate。

quality profile 中应记录目标 check、输入与环境 identity、最大间隔、强制执行入口、延期结果，以及测量和撤销条件。状态应按 worker 隔离，不得复用到其他环境。

9. Worker gate

workerは担当scopeの高速feedbackを得る。

canonical quality profileのworker entry pointと変更risk mappingからfocused test/checkを選択する。

Worker gateはIntegration gateの代替ではない。

worker 用于快速获得其负责 scope 的 feedback。

根据 canonical quality profile 的 worker entry point 和变更风险映射，选择 focused test/check。

Worker gate 不能替代 Integration gate。

10. Ticket integration gate

clean integration candidateで、canonical integration entry pointからticketに必要なverificationを実行する。

PR topologyは固定しない:

independent ticket:
```
<issue-number> -> release-x-y-z
```

stacked dependent ticket:

<issue-number> -> <immediate-predecessor-ticket-branch>

どちらでもticketは共通のtarget release trunkを持つ。

最低限:

acceptance criteriaに対応するverification
changed boundaryに必要なunit/smoke/integration/contract/E2E
formatter/lint/type/static/build等のapplicable checks
required CI checks
current head SHAまたはcurrent head SHA / snapshotにprovenanceで結び付いたimmutable artifact identityとvalidation evidenceの一致
immediate PR base / target release trunkとのstaleness確認

「all unit tests green」だけをintegration completionにしない。

在 clean integration candidate 上，通过 canonical integration entry point 执行 ticket 所需的 verification。

PR topology 不固定：

independent ticket：
```
<issue-number> -> release-x-y-z
```

stacked dependent ticket：

<issue-number> -> <immediate-predecessor-ticket-branch>

无论哪一种，ticket 都应共享同一个 target release trunk。

至少包括：

与 acceptance criteria 对应的 verification
changed boundary 所需的 unit/smoke/integration/contract/E2E
formatter/lint/type/static/build 等 applicable checks
required CI checks
current head SHA，或通过 provenance 绑定到 current head SHA/snapshot 的 immutable artifact identity，与 validation evidence 相互一致
对 immediate PR base / target release trunk 的 staleness 检查

不要仅以「all unit tests green」作为 integration completion 的依据。

11. Stack reconciliation gate

stack predecessorがreview/rebase/updateで変化した場合、affected downstream branchをdependency orderでreconcileする。

必須:

previous
```
validated_sha
```
とcurrent head SHAを比較
SHAが変わったdownstream ticketではaffected required verificationを再実行
old green resultをcurrent headのpassとして流用しない
configured CI/checksが存在する場合はcurrent headで再評価
predecessor contract/API/schema変更時はdependent contract/integration testを優先して再評価

単なるbranch ref名ではなくresolved immutable SHAをvalidation identityにする。

当 stack predecessor 因 review/rebase/update 而发生变化时，按 dependency order 对受影响的 downstream branch 进行 reconcile。

必须：

比较 previous
```
validated_sha
```
与 current head SHA
对 SHA 已变化的 downstream ticket 重新执行受影响的 required verification
不将 old green result 作为 current head 的 pass 复用
如果配置了 CI/checks，则在 current head 上重新评估
predecessor 的 contract/API/schema 发生变化时，优先重新评估 dependent contract/integration test

validation identity 应使用 resolved immutable SHA，而不是单纯的 branch ref 名。

12. Release gate

release-x-y-z -> main

前にcanonical release entry pointからticketより広いrelease-level verificationを行う。

必要に応じて:

full integration suite
clean production build/package
release artifact smoke test
critical user-journey E2E
supported browser/device/OS matrix
migration rehearsal
packaging/signing/notarization
deployment/IaC validation
upgrade/backward-compatibility
release-like environment smoke

在

release-x-y-z -> main

之前，通过 canonical release entry point 执行比 ticket 范围更广的 release-level verification。

必要时包括：

full integration suite
clean production build/package
release artifact smoke test
critical user-journey E2E
supported browser/device/OS matrix
migration rehearsal
packaging/signing/notarization
deployment/IaC validation
upgrade/backward-compatibility
release-like environment smoke

13. PR readiness gate

Issue acceptance criteriaを満たす
required verification levelを満たす
configured CI/checksが存在する場合はcurrent SHAで失敗を残していない
blocking review解消
known limitationを隠さない
target release trunk / immediate predecessorとのstaleness確認
stack update後のaffected revalidation完了
PR metadata / linked Issueがcurrent delivery stateと一致

このreadiness gateを満たしたopen PRはDraftのまま残さず、速やかにReady for reviewへ遷移する。userからの明示的なReady化指示を待たない。PR作成時点ですでにこのgateを満たしている場合は最初からReadyとして作成し、形式的なDraft -> Ready往復を行わない。Draftはこのgate未達でimplementation/integrationがactiveな場合だけ使用する。

Readyはticket Doneではない。 ticket-class PRは

github-delivery

/ ADR-0027に従ってそのままautonomous landingへ進み、target release trunk到達後のlinked Issue closeとsafe branch cleanupまで完了して初めてticket lifecycleが完遂する。release-classだけはReady後にexplicit release authorization gateで停止する。

满足 Issue acceptance criteria
达到 required verification level
如果配置了 CI/checks，则 current SHA 上没有遗留 failure
已解决 blocking review
不隐藏 known limitation
检查 target release trunk / immediate predecessor 的 staleness
完成 stack update 后受影响的 revalidation
PR metadata / linked Issue 与 current delivery state 保持一致

满足此 readiness gate 的 open PR 不应继续保持 Draft，而应迅速转为 Ready for review，无需等待用户明确发出 Ready 指令。如果在创建 PR 时已经满足该 gate，应直接以 Ready 状态创建，不要进行形式上的 Draft -> Ready 往返。仅当 gate 未满足且 implementation/integration 仍处于 active 状态时，才使用 Draft。

Ready 不等于 ticket Done。 ticket-class PR 应按照

github-delivery

/ ADR-0027 继续进入 autonomous landing；只有到达 target release trunk、完成 linked Issue close 和 safe branch cleanup 后，ticket lifecycle 才算完整结束。只有 release-class 会在 Ready 后停在 explicit release authorization gate。

14. False green禁止

14. 禁止 False green

禁止:

skipped test /
```
.only
```
blanket ignore/suppression
ignored exit code /
```
|| true
```
no-fail option
CI check disabling
broad generated-code excuse
mock-only testをreal integrationと報告
manual check未実施を「動作確認済み」と報告
coverage threshold低下や不当exclude
predecessor変更後にold SHAのgreen resultを流用

禁止：

skipped test /
```
.only
```
blanket ignore/suppression
ignored exit code /
```
|| true
```
no-fail option
CI check disabling
宽泛的 generated-code 借口
将 mock-only test 报告为 real integration
未执行 manual check，却报告为「已验证运行正常」
降低 coverage threshold 或不当 exclude
predecessor 变更后复用 old SHA 的 green result

15. Coverageは固定万能指標にしない

15. 不要将 Coverage 视为固定万能指标

coverageは有用なtestable sourceでproject-specific policyとして利用する。

framework guidance、risk、code type、existing baselineを優先する。

coverageが適切でない領域では別のdeterministic signalへ置き換える。

coverage 应用于有价值的可测试 source，并作为 project-specific policy。

应优先考虑 framework guidance、风险、代码类型和现有 baseline。

对于 coverage 不适合的区域，应改用其他 deterministic signal。

16. Re-evaluation triggers

次の場合はquality profileを再compileする:

framework/runtime upgrade
official testing guidance変更
architecture boundary変更
new app/platform target
CI workflow変更
PR/stack/release integration model変更
flaky/slow gateが開発速度を阻害
Actions usage/costが想定baselineから大きく乖離
included usage / runner billing model / repository visibility変更
escaped regressionがgateの穴を示した
release process変更

quality gate自体をversioned project configurationとして扱う。

出现以下情况时，应重新 compile quality profile：

framework/runtime upgrade
official testing guidance 变更
architecture boundary 变更
new app/platform target
CI workflow 变更
PR/stack/release integration model 变更
flaky/slow gate 阻碍开发速度
Actions usage/cost 明显偏离预期 baseline
included usage / runner billing model / repository visibility 变更
escaped regression 暴露了 gate 漏洞
release process 变更

应将 quality gate 本身视为 versioned project configuration。