创建 GitHub Actions 工作流规范
为 GitHub Actions 工作流：${input:WorkflowFile} 创建一份全面的规范。
该规范作为工作流行为、需求和约束的规范说明。它必须与实现无关，聚焦于工作流要达成什么，而不是如何实现。
面向 AI 优化的要求
- Token 效率：使用简洁的语言，同时不牺牲清晰度
- 结构化数据：利用表格、列表和图表来承载密集信息
- 语义清晰：始终一致地使用精确术语
- 实现抽象：避免具体语法、命令或工具版本
- 可维护性：设计时考虑随工作流演进便于更新
规范模板
保存为：/spec/spec-process-cicd-[workflow-name].md
---
title: CI/CD Workflow Specification - [Workflow Name]
version: 1.0
date_created: [YYYY-MM-DD]
last_updated: [YYYY-MM-DD]
owner: DevOps Team
tags: [process, cicd, github-actions, automation, [domain-specific-tags]]
---
## Workflow Overview
**Purpose**: [One sentence describing workflow's primary goal]
**Trigger Events**: [List trigger conditions]
**Target Environments**: [Environment scope]
## Execution Flow Diagram
```mermaid
graph TD
A[Trigger Event] --> B[Job 1]
B --> C[Job 2]
C --> D[Job 3]
D --> E[End]
B --> F[Parallel Job]
F --> D
style A fill:#e1f5fe
style E fill:#e8f5e8
作业与依赖关系
| 作业名称 | 用途 | 依赖项 | 执行上下文 |
|---|
| job-1 | [用途] | [前置条件] | [运行器/环境] |
| job-2 | [用途] | job-1 | [运行器/环境] |
需求矩阵
功能需求
| ID | 需求 | 优先级 | 验收标准 |
|---|
| REQ-001 | [需求] | 高 | [可测试的标准] |
| REQ-002 | [需求] | 中 | [可测试的标准] |
安全需求
| ID | 需求 | 实现约束 |
|---|
| SEC-001 | [安全需求] | [约束描述] |
性能需求
| ID | 指标 | 目标 | 测量方法 |
|---|
| PERF-001 | [指标] | [目标值] | [如何测量] |
输入/输出契约
输入
# Environment Variables
ENV_VAR_1: string # Purpose: [description]
ENV_VAR_2: secret # Purpose: [description]
# Repository Triggers
paths: [list of path filters]
branches: [list of branch patterns]
输出
# Job Outputs
job_1_output: string # Description: [purpose]
build_artifact: file # Description: [content type]
密钥与变量
| 类型 | 名称 | 用途 | 作用域 |
|---|
| Secret | SECRET_1 | [用途] | 工作流 |
| Variable | VAR_1 | [用途] | 仓库 |
执行约束
运行时约束
- 超时：[最大执行时间]
- 并发：[并行执行限制]
- 资源限制：[内存/CPU 约束]
环境约束
- 运行器要求：[操作系统/硬件需求]
- 网络访问：[外部连接需求]
- 权限：[所需访问级别]
错误处理策略
| 错误类型 | 响应 | 恢复操作 |
|---|
| 构建失败 | [响应] | [恢复步骤] |
| 测试失败 | [响应] | [恢复步骤] |
| 部署失败 | [响应] | [恢复步骤] |
质量门禁
门禁定义
| 门禁 | 标准 | 豁免条件 |
|---|
| 代码质量 | [标准] | [何时允许] |
| 安全扫描 | [阈值] | [何时允许] |
| 测试覆盖率 | [百分比] | [何时允许] |
监控与可观测性
关键指标
- 成功率：[目标百分比]
- 执行时间：[目标时长]
- 资源使用：[监控方法]
告警
| 条件 | 严重级别 | 通知目标 |
|---|
| [条件] | [级别] | [何人/何处] |
集成点
外部系统
| 系统 | 集成类型 | 数据交换 | SLA 要求 |
|---|
| [系统] | [类型] | [数据格式] | [要求] |
依赖的工作流
合规与治理
审计要求
- 执行日志：[保留策略]
- 审批门禁：[所需审批]
- 变更控制：[更新流程]
安全控制
- 访问控制：[权限模型]
- 密钥管理：[轮换策略]
- 漏洞扫描：[扫描频率]
边界情况与例外
场景矩阵
| 场景 | 预期行为 | 验证方法 |
|---|
| [边界情况] | [行为] | [如何验证] |
验证标准
工作流验证
- VLD-001: [验证规则]
- VLD-002: [验证规则]
性能基准
- PERF-001: [基准标准]
- PERF-002: [基准标准]
变更管理
更新流程
- 规范更新：首先修改本文档
- 审查与批准：[批准流程]
- 实施：将更改应用到工作流
- 测试：[验证方法]
- 部署：[发布流程]
版本历史
相关规范
- [相关工作流规范的链接]
- [基础设施规范的链接]
- [部署规范的链接]
## Analysis Instructions
When analyzing the workflow file:
1. **Extract Core Purpose**: Identify the primary business objective
2. **Map Job Flow**: Create dependency graph showing execution order
3. **Identify Contracts**: Document inputs, outputs, and interfaces
4. **Capture Constraints**: Extract timeouts, permissions, and limits
5. **Define Quality Gates**: Identify validation and approval points
6. **Document Error Paths**: Map failure scenarios and recovery
7. **Abstract Implementation**: Focus on behavior, not syntax
## Mermaid Diagram Guidelines
### Flow Types
- **Sequential**: `A --> B --> C`
- **Parallel**: `A --> B & A --> C; B --> D & C --> D`
- **Conditional**: `A --> B{Decision}; B -->|Yes| C; B -->|No| D`
### Styling
```mermaid
style TriggerNode fill:#e1f5fe
style SuccessNode fill:#e8f5e8
style FailureNode fill:#ffebee
style ProcessNode fill:#f3e5f5
复杂工作流
对于包含 5 个以上作业的工作流，请使用子图：
graph TD
subgraph "Build Phase"
A[Lint] --> B[Test] --> C[Build]
end
subgraph "Deploy Phase"
D[Staging] --> E[Production]
end
C --> D
Token 优化策略
- 使用表格：以结构化格式呈现密集信息
- 一致缩写：定义一次，全文使用
- 项目符号：避免散文式段落
- 代码块：使用结构化数据而非叙述
- 交叉引用：链接而非重复信息
专注于创建一份既可作为文档、又可作为工作流更新模板的规范。
