go-ci-workflow skill 解析¶

go-ci-workflow 是一套面向 Go 仓库 GitHub Actions CI 的设计与重构框架。它的核心设计思想是：CI 设计应先判断仓库是什么形状、本地怎么跑、哪些任务值得进 PR gate、哪些任务必须降级或延后，然后再把这些事实翻译成诚实、可维护、可复现的 CI 结构。 因此它把 仓库形态、本地一致性、安全与权限、执行真实性、降级输出 和结构化报告串成一条明确流程。

1. 定义¶

go-ci-workflow 用于：

• 创建或重构 .github/workflows/*.yml
• 将仓库结构映射到 CI job 设计
• 让 GitHub Actions 尽量复用 Makefile 或其他已提交的本地任务入口
• 设计 core gate、integration、e2e、docker-build、vuln scan 等 job 的拆分策略
• 在仓库缺少 Makefile / task runner 时输出诚实的 fallback workflow
• 审查已有 CI 工作流的触发、权限、安全与本地等价性

它输出的不只是 YAML，还包括：

• 仓库形状分类
• 每个 job 的 execution path
• trigger 配置
• permissions 与 secret 假设
• 工具版本来源
• 缺失的本地入口或任务 target
• 实际验证情况
• 在 parity 不完整时的后续建议

从设计上看，它更像一个“Go 仓库 CI 架构决策器”，而不是一个单纯的 GitHub Actions 模板生成器。

2. 背景与问题¶

这个 skill 要解决的，不是“大家不会写 GitHub Actions YAML”，而是 Go 仓库里的 CI 经常存在三类更本质的问题：

• CI 和本地运行方式脱节
• 仓库结构判断错误，workflow 架构跟仓库真实形态不匹配
• 缺少显式降级，仓库明明没有稳定入口，却仍被写成“完整本地等价”

如果没有清晰框架，常见失真通常集中在 8 类：

go-ci-workflow 的设计逻辑，就是先把“仓库怎么跑”查清楚，再把“CI 应该怎么对应”系统化。

3. 与常见替代方案的对比¶

先看它与几种常见做法的区别：

它的价值，不只是能写 workflow，而是把 CI 设计从模板复制，提升成仓库驱动的工程决策过程。

4. 核心设计逻辑¶

4.1 仓库形态门禁必须先于 workflow 设计¶

go-ci-workflow 的第一道强制门禁是仓库形态门禁。它要求先判断仓库到底是：

• single-module application
• single-module library
• multi-module repository
• monorepo with multiple apps/packages
• Docker-heavy repository
• reusable-workflow candidate

这一步特别关键，因为 CI 架构不是脱离仓库形状存在的。service 和 library 的触发、matrix、docker、integration、release 诉求完全不同；单模块和多模块仓库在 go.mod、cache、路径、job ownership 上也完全不同。

如果这一步做错，后面的 job 拆分、触发策略和路径过滤都会建立在错误前提上。

4.2 先用 discovery 脚本拿仓库事实¶

skill 明确要求先运行 scripts/discover_ci_needs.sh，用它收集：

• Makefile target
• 其他 repo task 入口
• Dockerfile
• integration / e2e 目录形态
• Go module 结构
• workflow 现状
• 被 Makefile 和 scripts/ 下 shell 脚本显式引用的工具线索

这层设计的价值在于，它把“仓库现状”从模型猜测变成可复现证据。这样做能避免两个典型问题：

• 模型以为某个 make ci 存在，实际上并不存在
• 模型以为仓库是单模块，实际上有 nested go.mod

这也是为什么 go-ci-workflow 比“熟悉 GitHub Actions 语法”的普通提示词更可靠。它先查仓库事实，再做架构决策。

4.3 本地一致性门禁 是这个 skill 的核心¶

go-ci-workflow 最重要的设计之一，是 本地一致性门禁。它要求每个 job 都明确标记执行路径属于：

• make target
• repo task
• inline fallback

这个设计的价值非常大，因为很多 CI 方案在表面上能跑，但它们并不具备“本地怎么跑，CI 就怎么跑”的可维护性。本地一致性门禁 实际上解决的是：

• 排障时开发者能否直接复现
• CI 行为是否能被本地入口约束
• 仓库演进时 CI 是否会和本地脚本逐渐分叉

评估报告里最明显的增量，也来自这一层：with-skill 能显式记录 parity 与 fallback；without-skill 即使产出 YAML，也很少把这件事说清楚。

4.4 优先 Make-driven delegation vs 优先 inline commands¶

执行优先级 明确规定：

1. 优先 Makefile target
2. 其次 committed task runner / scripts
3. 最后才是 controlled inline fallback

这是一种非常成熟的工程选择。inline command 的问题不是不能用，而是：

• 本地和 CI 行为容易漂移
• 参数、版本、环境变量更容易分散
• 仓库维护者很难知道“正确入口”到底在哪

因此，skill 的默认目标不是“把命令写进 workflow”，而是“让 workflow 复用仓库已经承诺的入口”。只有当仓库本身缺少稳定入口时，才允许降级到 inline fallback，并要求显式记录这种不完整性。

4.5 降级输出门禁¶

当仓库没有 Makefile、repo task、稳定脚本或完整本地入口时，go-ci-workflow 明确要求：

• 不要假装 full parity 存在
• 输出 scaffold 或 inline fallback
• 明确写出缺失 targets / scripts / recommended follow-ups

这层设计非常关键，因为很多 CI 生成类方案最大的问题，不是功能不全，而是把“临时能跑”包装成“结构完整”。评估中的场景 3 就是最好的例子：with-skill 明确标注 inline fallback 和 Local parity: PARTIAL，而 without-skill 则直接写出一份看起来正常的 workflow，却没有告诉读者它缺少 repo-native entrypoint。

这也是为什么 go-ci-workflow 的降级处理在评估里拉开了最大差距。

4.6 触发规则 会强调“按成本和信任边界分层”¶

go-ci-workflow 并不主张“所有 job 在每个 PR 上都跑一遍”。它明确区分：

• pull_request：核心 gate、低风险验证、避免 fork secret 风险
• push：更广泛的验证
• schedule：昂贵或全面 sweep
• workflow_call：真正存在复用价值时才抽 reusable workflow

这个设计体现了一个很成熟的原则：触发策略是成本模型和信任模型的交汇点。

PR gate 太重，会拖慢反馈；secret-dependent job 暴露到 fork PR，又会造成安全风险。trigger 设计因此不是语法问题，而是运行成本与信任边界的设计问题。

4.7 安全与权限 Gate 不只是“加一个 contents: read”¶

这个 skill 不把安全理解成“默认写一行 permissions 就行了”，而是要求先判断：

• 触发事件是什么
• fork PR 能不能碰到 secrets
• 最小权限是什么
• reusable workflow / self-hosted runner 有没有改变 trust boundary

这层设计很重要，因为 GitHub Actions 的风险不只在 job 里运行了什么，还在于谁触发、在哪个边界内触发、是否拿到 secrets 或 write 权限。

它也解释了为什么 skill 在简单场景下仍会强调 permissions: contents: read，而在更复杂场景下要求按需加载 advanced patterns：核心不是“写得更安全一点”，而是让安全边界在 workflow 设计阶段就被显式处理。

4.8 Go Setup 和 Tool Pinning 要成为统一规则¶

go-ci-workflow 对 Go 与工具版本的默认规则是：

• application 场景默认使用 go-version-file: go.mod
• 不要随意硬编码单一 Go 版本；如果是需要覆盖多版本兼容性的 library，才考虑显式 matrix
• go install 的工具版本必须精确锁定
• 版本尽量与 Makefile 或 repo-native install script 保持一致

这层设计解决的是两个非常真实的问题：

• 仓库升级 Go 版本后，CI 还停留在旧版本或私自先跑新版本
• CI 和本地工具版本不一致，导致 lint / vulncheck / codegen 结果漂移

从维护角度看，Go 版本和工具版本都应该尽量有清晰可信来源；CI 不应该在没有仓库依据时再创造一套随意的版本事实。

4.9 作业架构规则 要把 core gate 和慢任务拆开¶

skill 明确要求：

• core gate 保持快
• 慢任务、环境敏感任务、昂贵任务拆出去
• needs: 只在真正有顺序依赖时才使用
• 每个 job 都有 timeout
• 用 concurrency 避免冗余运行

这层设计非常工程化。很多 CI 反模式的问题，不在于缺某个工具，而在于 job 颗粒度错误：

• 单 job 过大，失败定位慢
• 慢任务阻塞核心反馈
• 高成本任务在每次 PR 上都运行

把 job architecture 规则显式化，就是在把“反馈速度”“成本控制”“可定位性”同时纳入 workflow 设计。

4.10 references 要按场景选择性加载¶

go-ci-workflow 的 references 分层很清晰。按当前 SKILL.md 约定：

• workflow-quality-guide.md 和 golden-examples.md 是基础参考资料
• repository-shapes.md 只在 monorepo / 多模块时加载
• github-actions-advanced-patterns.md 只在复杂信任边界或高级行为时加载
• fallback-and-scaffolding.md 只在缺少本地入口时加载
• monorepo / service containers / PR review 也各有单独资料

这说明 skill 的设计非常重视上下文成本控制。标准仓库不需要一上来就加载 monorepo、service containers、fork security 的全部细则；只有场景触发时才展开。这种“基础规则常驻 + 重场景按需加载”的结构，是生产级 skill 可扩展性的关键。

4.11 诚实报告输出契约¶

go-ci-workflow 的 输出契约 要求返回：

• changed files
• repository shape classification
• 每个 job 的 execution path
• trigger configuration
• permissions and secret assumptions
• tool versions used
• missing targets or entrypoints
• validation performed
• parity 不完整时的 follow-up work

这层设计的价值在于，它把 workflow 变更从“只看 YAML diff”升级成“看清设计前提、运行入口和已知缺口”。这对于：

• 团队 review
• 后续维护
• 诊断“为什么 CI 跑法和本地不一致”

都非常重要。评估也表明，baseline 模型在生成 YAML 上并不差，但缺少这种结构化说明，因此很难形成长期可维护的工作流设计记录。

5. 这个设计解决了哪些具体问题¶

结合当前 SKILL.md、references、脚本和评估报告，可以把它解决的问题归纳为：

6. 主要亮点¶

6.1 它把“仓库怎么跑”放在“CI 怎么写”前面¶

这是整个 skill 最重要的设计点。CI 不是独立模板，而是仓库运行模型的映射。

6.2 Make-driven delegation 做得非常坚决¶

很多 workflow 方案会在仓库明明有 Makefile 时，仍直接写 inline 命令。go-ci-workflow 明确把这种情况当成次优路径处理。

6.3 对降级处理非常诚实¶

这也是它在评估里差距最大的一项。它不会因为能拼出 inline command，就假装仓库已经具备完整 local parity。

6.4 对 GitHub Actions 的安全边界有真实工程意识¶

permissions、fork PR、secret exposure、workflow trigger、reusable workflow trust boundary，这些都被当成 workflow 设计的一部分，而不是附加备注。

6.5 输出契约 很适合长期维护¶

workflow 改动在团队里最怕“改完只剩 YAML，为什么这么改没人记得”。结构化输出正好补了这一层。

6.6 当前版本的核心价值，比评估快照更像“CI 设计方法论”¶

评估报告最强地验证了它在 Make-driven delegation、降级处理、输出契约 和 local-equivalence markers 上的价值。与此同时，当前 skill 已经通过 references 和 discovery 脚本，把 repo shape、advanced trust boundary、fallback scaffolding 等内容进一步工程化。因此当前版本不只是“会写更好 YAML”，而是在提供一套更完整的 Go CI 设计方法论。

7. 什么时候适合用，什么时候不该硬用¶

8. 结论¶

go-ci-workflow 的真正亮点，不是它会写 GitHub Actions 语法，而是它把 Go 仓库 CI 设计里最容易被忽略的工程判断系统化了：先识别仓库形状，再确认本地入口和 trust boundary，然后决定 job 架构、trigger 分层、工具版本来源和降级路径，最后用结构化输出把整个设计前提和缺口记录下来。

从设计上看，这个 skill 非常清楚地体现了一条原则：好的 CI 不是“看起来规范”，而是“与仓库真实运行方式一致，在做不到完全一致时也能诚实地标出来”。 这也是它特别适合 Go 仓库 workflow 设计与重构的原因。

9. 文档维护¶

当以下内容发生变化时，这份文档应该同步更新：

• skills/go-ci-workflow/SKILL.md 中的 执行优先级、强制门禁、触发规则、输出契约 或 作业架构规则 发生变化。
• skills/go-ci-workflow/references/workflow-quality-guide.md、golden-examples.md、repository-shapes.md、github-actions-advanced-patterns.md 或 fallback-and-scaffolding.md 中的关键规则发生变化。
• skills/go-ci-workflow/scripts/discover_ci_needs.sh 的输出字段、分类逻辑或工具检测方式发生变化。
• evaluate/go-ci-workflow-skill-eval-report.zh-CN.md 中支撑本文判断的核心结果发生变化。
• skill 在 local parity、fallback 或 advanced GitHub Actions 安全策略上有明显重构。

建议按季度复查一次；如果 go-ci-workflow 的 gate、fallback 机制或 discovery 脚本有明显重构，则应立即复查。

10. 相关阅读¶

• skills/go-ci-workflow/SKILL.md
• skills/go-ci-workflow/references/workflow-quality-guide.md
• skills/go-ci-workflow/references/golden-examples.md
• skills/go-ci-workflow/references/repository-shapes.md
• skills/go-ci-workflow/references/github-actions-advanced-patterns.md
• skills/go-ci-workflow/references/fallback-and-scaffolding.md
• skills/go-ci-workflow/scripts/discover_ci_needs.sh
• evaluate/go-ci-workflow-skill-eval-report.zh-CN.md