Back to Details

ci-integration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CI Integration

CI集成

Value: Feedback -- CI pipelines produce signals. Deterministic interaction patterns ensure those signals are received, classified, and acted on correctly. Undisciplined CI interaction (pushing over failing runs, ignoring flaky tests) degrades the signal until the pipeline is noise.
价值： 反馈——CI流水线会生成信号。确定性交互模式可确保这些信号被正确接收、分类并采取行动。无规范的CI交互（在运行失败时仍推送代码、忽略不稳定测试）会削弱信号价值，最终让流水线沦为无效噪音。

Purpose

目标

Teaches disciplined CI/CD interaction: one pending run at a time, structured failure triage, automated self-healing for mechanical failures, and structured evidence output for pipeline consumption. Prevents the most common CI failure mode: pushing again before understanding why the last run failed.
传授规范化的CI/CD交互方式：一次仅保留一个待处理运行任务、结构化故障分类、针对机械故障的自动化自修复、以及供流水线使用的结构化证据输出。避免最常见的CI故障模式：在未理解上一次运行失败原因的情况下再次推送代码。

Practices

实践规范

Push-and-Wait Discipline

推送等待原则

One pending CI run at a time. Never push while a run is in progress.
  1. Push the commit
  2. Poll or wait for the CI run to complete
  3. Read the full result before taking any action
  4. Only after the run completes (pass or fail) may you push again
Do:
  • Wait for CI completion before starting new work that would require a push
  • Read the complete CI output, not just the status badge
Do not:
  • Push a "fix" while the previous run is still pending
  • Assume a run will pass and push follow-up commits
  • Cancel a run to push a new one (unless the run is clearly stale)
一次仅保留一个待处理CI运行任务。运行进行中绝不要推送新代码。
  1. 提交并推送代码
  2. 轮询或等待CI运行完成
  3. 在采取任何行动前完整查看运行结果
  4. 仅在运行完成（成功或失败）后才可再次推送代码
需要做：
  • 在开始需要推送代码的新工作前，等待CI运行完成
  • 查看完整的CI输出，而非仅状态标识
不要做：
  • 在上一次运行仍在处理时推送“修复代码”
  • 假设运行会成功并推送后续提交
  • 取消当前运行以推送新代码（除非运行明显已失效）

Failure Triage

故障分类

Classify every CI failure before attempting a fix. The classification determines the fix strategy.
ClassificationSignalFix Strategy
test-failure
Test assertions failRoute to 
debugging-protocol
lint-failure
Linter or formatter errorsAuto-fix: run formatter, commit, re-push
build-failure
Compilation or dependency errorsDependency analysis, check lockfiles
flaky-test
Test fails then passes on retry without code changesFlag and track (see below)
infra-failure
Network, runner, or service errorsRetry (max 2), then escalate
Read the full CI log to classify. Do not guess from the status alone.
在尝试修复前，对每一个CI故障进行分类。分类结果将决定修复策略。
分类信号修复策略
test-failure
测试断言失败转至
debugging-protocol
lint-failure
代码检查或格式化工具报错自动修复：运行格式化工具，提交并重新推送
build-failure
编译或依赖项报错依赖项分析，检查锁定文件
flaky-test
无代码变更时，重试后测试从失败转为成功标记并跟踪（见下文）
infra-failure
网络、运行器或服务报错重试（最多2次），若仍失败则升级处理
查看完整的CI日志以进行分类，不要仅通过状态猜测。

Self-Healing

自修复

Mechanical failures that have deterministic fixes should be resolved automatically:
  1. Lint/format failures: Run the project's formatter or linter with auto-fix, commit the result, re-push. This is a single retry -- if the formatter does not resolve the issue, classify as 
    build-failure
    .
  2. Infra failures: Retry the CI run (max 2 retries). If all retries fail, escalate to the user with the infra error details.
  3. Test failures: Never auto-retry. Route to 
    debugging-protocol
    for investigation. A test failure is a signal, not noise.
  4. Build failures: Check dependency lockfiles, build configuration, and environment differences. Do not blindly retry.
具有确定性修复方案的机械故障应自动解决：
  1. 代码检查/格式化故障： 运行项目的格式化或代码检查工具并启用自动修复，提交结果后重新推送。仅重试一次——若格式化工具无法解决问题，则归类为
    build-failure
    。
  2. 基础设施故障： 重试CI运行（最多2次）。若所有重试均失败，则向用户提交基础设施错误详情并升级处理。
  3. 测试故障： 绝不自动重试。转至
    debugging-protocol
    进行调查。测试故障是有效信号，而非噪音。
  4. 构建故障： 检查依赖项锁定文件、构建配置以及环境差异。不要盲目重试。

Flaky Test Detection

不稳定测试检测

A test is flaky if it passes on retry without any code changes.
When detected:
  1. Flag the test with its name, file, and the failure output from the flaky run
  2. Record in project memory (
    .factory/audit-trail/flaky-tests.json
    if factory mode is active, or project notes otherwise)
  3. Report to the user -- flaky tests erode CI trust and must be addressed
  4. Do not treat a flaky pass as a real pass for quality gate purposes until the flakiness is resolved
若在无代码变更的情况下，重试后测试从失败转为成功，则该测试属于不稳定测试。
检测到不稳定测试时：
  1. 标记该测试的名称、文件路径以及不稳定运行时的失败输出
  2. 记录到项目内存中（若启用工厂模式则记录至
    .factory/audit-trail/flaky-tests.json
    ，否则记录至项目笔记）
  3. 向用户报告——不稳定测试会削弱对CI的信任，必须予以处理
  4. 在不稳定问题解决前，不要将不稳定测试的通过视为质量门控的有效通过

Structured Output

结构化输出

Every CI interaction produces a 
CI_RESULT
evidence packet:
json
{
  "run_id": "string (CI run identifier)",
  "status": "string (passed | failed | cancelled)",
  "duration": "number (seconds)",
  "failure_type": "string (test-failure | lint-failure | build-failure | flaky-test | infra-failure) -- omit if passed",
  "failure_details": "string (summary of failure) -- omit if passed",
  "fixes_applied": ["string (description of each auto-fix applied)"],
  "retry_count": "number (0 if no retries)"
}
This packet is consumed by pipeline orchestrators and audit trails. Always produce it, even for passing runs.
每一次CI交互都会生成一个
CI_RESULT
证据包：
json
{
  "run_id": "string (CI run identifier)",
  "status": "string (passed | failed | cancelled)",
  "duration": "number (seconds)",
  "failure_type": "string (test-failure | lint-failure | build-failure | flaky-test | infra-failure) -- omit if passed",
  "failure_details": "string (summary of failure) -- omit if passed",
  "fixes_applied": ["string (description of each auto-fix applied)"],
  "retry_count": "number (0 if no retries)"
}
该数据包供流水线编排器和审计追踪系统使用。无论运行成功与否，都必须生成该数据包。

Enforcement Note

实施说明

This skill provides advisory guidance. It instructs the agent to follow push-and-wait discipline and structured triage but cannot mechanically prevent concurrent pushes. When used within a pipeline orchestrator, the pipeline can enforce the one-pending-run constraint. In standalone use, the agent follows these practices by convention.
本技能提供指导性建议。它会指示Agent遵循推送等待原则和结构化分类，但无法从机制上阻止并发推送。在流水线编排器中使用时，流水线可强制执行“仅一个待处理运行任务”的约束。在独立使用时，Agent会依照惯例遵循这些实践规范。

Verification

验证

After each CI interaction, verify:
  • Waited for the previous CI run to complete before pushing
  • Read the complete CI output (not just status)
  • Classified the failure type before attempting a fix
  • Applied the correct fix strategy for the classification
  • Did not retry a test failure (routed to debugging-protocol instead)
  • Lint/format auto-fixes were limited to one attempt
  • Infra retries did not exceed 2
  • Flaky tests were flagged and recorded
  • Produced a CI_RESULT evidence packet
If any criterion is not met, revisit the relevant practice before proceeding.
每次CI交互后，验证以下内容：
  • 推送前等待上一次CI运行完成
  • 查看完整的CI输出（而非仅状态）
  • 尝试修复前对故障类型进行了分类
  • 针对分类应用了正确的修复策略
  • 未重试测试故障（而是转至debugging-protocol）
  • 代码检查/格式化自动修复仅尝试了一次
  • 基础设施重试未超过2次
  • 不稳定测试已被标记并记录
  • 生成了CI_RESULT证据包
若有任何一项未满足，在继续操作前重新查看相关实践规范。

Dependencies

依赖项

This skill works standalone for any project with a CI/CD pipeline. It integrates with:
  • debugging-protocol: Test failures route to the debugging protocol for systematic investigation rather than blind fix attempts
  • tdd: CI failures during TDD cycles feed back into the RED-GREEN loop; a CI test failure means the cycle is not complete
  • pipeline: When used within factory mode, the pipeline orchestrator consumes CI_RESULT packets to evaluate quality gates
Missing a dependency? Install with:
npx skills add jwilger/agent-skills --skill debugging-protocol
本技能可独立用于任何拥有CI/CD流水线的项目。它可与以下技能集成：
  • debugging-protocol： 测试故障会转至调试协议进行系统性调查，而非盲目尝试修复
  • tdd： TDD周期中的CI故障会反馈至RED-GREEN循环；CI测试失败意味着周期未完成
  • pipeline： 在工厂模式下使用时，流水线编排器会消耗CI_RESULT数据包以评估质量门控
缺少依赖项？使用以下命令安装：
npx skills add jwilger/agent-skills --skill debugging-protocol