create-github-action-workflow-specification

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create GitHub Actions Workflow Specification

创建GitHub Actions工作流规范

Create a comprehensive specification for the GitHub Actions workflow:

${input:WorkflowFile}

This specification serves as a specification for the workflow's behavior, requirements, and constraints. It must be implementation-agnostic, focusing on what the workflow accomplishes rather than how it's implemented.

为GitHub Actions工作流

${input:WorkflowFile}

创建一份全面的规范。

本规范用于定义工作流的行为、要求和约束。它必须与实现无关，重点关注工作流要实现什么，而非如何实现。

AI-Optimized Requirements

针对AI优化的要求

Token Efficiency: Use concise language without sacrificing clarity
Structured Data: Leverage tables, lists, and diagrams for dense information
Semantic Clarity: Use precise terminology consistently throughout
Implementation Abstraction: Avoid specific syntax, commands, or tool versions
Maintainability: Design for easy updates as workflow evolves

令牌效率：使用简洁语言，同时不失清晰度
结构化数据：利用表格、列表和图表呈现密集信息
语义清晰度：全程使用精准且一致的术语
实现抽象：避免提及特定语法、命令或工具版本
可维护性：设计需便于随工作流演进进行更新

Specification Template

规范模板

Save as:

/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]]
---

保存路径：

/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

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

Jobs & Dependencies

Job Name	Purpose	Dependencies	Execution Context
job-1	[Purpose]	[Prerequisites]	[Runner/Environment]
job-2	[Purpose]	job-1	[Runner/Environment]

Job Name	Purpose	Dependencies	Execution Context
job-1	[Purpose]	[Prerequisites]	[Runner/Environment]
job-2	[Purpose]	job-1	[Runner/Environment]

Requirements Matrix

Functional Requirements

ID	Requirement	Priority	Acceptance Criteria
REQ-001	[Requirement]	High	[Testable criteria]
REQ-002	[Requirement]	Medium	[Testable criteria]

ID	Requirement	Priority	Acceptance Criteria
REQ-001	[Requirement]	High	[Testable criteria]
REQ-002	[Requirement]	Medium	[Testable criteria]

Security Requirements

ID	Requirement	Implementation Constraint
SEC-001	[Security requirement]	[Constraint description]

ID	Requirement	Implementation Constraint
SEC-001	[Security requirement]	[Constraint description]

Performance Requirements

ID	Metric	Target	Measurement Method
PERF-001	[Metric]	[Target value]	[How measured]

ID	Metric	Target	Measurement Method
PERF-001	[Metric]	[Target value]	[How measured]

Input/Output Contracts

Inputs

yaml

undefined

yaml

undefined

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]

undefined

paths: [list of path filters] branches: [list of branch patterns]

undefined

Outputs

yaml

undefined

yaml

undefined

Job Outputs

job_1_output: string # Description: [purpose] build_artifact: file # Description: [content type]

undefined

job_1_output: string # Description: [purpose] build_artifact: file # Description: [content type]

undefined

Secrets & Variables

Type	Name	Purpose	Scope
Secret	SECRET_1	[Purpose]	Workflow
Variable	VAR_1	[Purpose]	Repository

Type	Name	Purpose	Scope
Secret	SECRET_1	[Purpose]	Workflow
Variable	VAR_1	[Purpose]	Repository

Execution Constraints

Runtime Constraints

Timeout: [Maximum execution time]
Concurrency: [Parallel execution limits]
Resource Limits: [Memory/CPU constraints]

Timeout: [Maximum execution time]
Concurrency: [Parallel execution limits]
Resource Limits: [Memory/CPU constraints]

Environmental Constraints

Runner Requirements: [OS/hardware needs]
Network Access: [External connectivity needs]
Permissions: [Required access levels]

Runner Requirements: [OS/hardware needs]
Network Access: [External connectivity needs]
Permissions: [Required access levels]

Error Handling Strategy

Error Type	Response	Recovery Action
Build Failure	[Response]	[Recovery steps]
Test Failure	[Response]	[Recovery steps]
Deployment Failure	[Response]	[Recovery steps]

Error Type	Response	Recovery Action
Build Failure	[Response]	[Recovery steps]
Test Failure	[Response]	[Recovery steps]
Deployment Failure	[Response]	[Recovery steps]

Quality Gates

Gate Definitions

Gate	Criteria	Bypass Conditions
Code Quality	[Standards]	[When allowed]
Security Scan	[Thresholds]	[When allowed]
Test Coverage	[Percentage]	[When allowed]

Gate	Criteria	Bypass Conditions
Code Quality	[Standards]	[When allowed]
Security Scan	[Thresholds]	[When allowed]
Test Coverage	[Percentage]	[When allowed]

Monitoring & Observability

Key Metrics

Success Rate: [Target percentage]
Execution Time: [Target duration]
Resource Usage: [Monitoring approach]

Success Rate: [Target percentage]
Execution Time: [Target duration]
Resource Usage: [Monitoring approach]

Alerting

Condition	Severity	Notification Target
[Condition]	[Level]	[Who/Where]

Condition	Severity	Notification Target
[Condition]	[Level]	[Who/Where]

Integration Points

External Systems

System	Integration Type	Data Exchange	SLA Requirements
[System]	[Type]	[Data format]	[Requirements]

System	Integration Type	Data Exchange	SLA Requirements
[System]	[Type]	[Data format]	[Requirements]

Dependent Workflows

Workflow	Relationship	Trigger Mechanism
[Workflow]	[Type]	[How triggered]

Workflow	Relationship	Trigger Mechanism
[Workflow]	[Type]	[How triggered]

Compliance & Governance

Audit Requirements

Execution Logs: [Retention policy]
Approval Gates: [Required approvals]
Change Control: [Update process]

Execution Logs: [Retention policy]
Approval Gates: [Required approvals]
Change Control: [Update process]

Security Controls

Access Control: [Permission model]
Secret Management: [Rotation policy]
Vulnerability Scanning: [Scan frequency]

Access Control: [Permission model]
Secret Management: [Rotation policy]
Vulnerability Scanning: [Scan frequency]

Edge Cases & Exceptions

Scenario Matrix

Scenario	Expected Behavior	Validation Method
[Edge case]	[Behavior]	[How to verify]

Scenario	Expected Behavior	Validation Method
[Edge case]	[Behavior]	[How to verify]

Validation Criteria

Workflow Validation

VLD-001: [Validation rule]
VLD-002: [Validation rule]

VLD-001: [Validation rule]
VLD-002: [Validation rule]

Performance Benchmarks

PERF-001: [Benchmark criteria]
PERF-002: [Benchmark criteria]

PERF-001: [Benchmark criteria]
PERF-002: [Benchmark criteria]

Change Management

Update Process

Specification Update: Modify this document first
Review & Approval: [Approval process]
Implementation: Apply changes to workflow
Testing: [Validation approach]
Deployment: [Release process]

Specification Update: Modify this document first
Review & Approval: [Approval process]
Implementation: Apply changes to workflow
Testing: [Validation approach]
Deployment: [Release process]

Version History

Version	Date	Changes	Author
1.0	[Date]	Initial specification	[Author]

Version	Date	Changes	Author
1.0	[Date]	Initial specification	[Author]

Related Specifications

[Link to related workflow specs]
[Link to infrastructure specs]
[Link to deployment specs]

undefined

[Link to related workflow specs]
[Link to infrastructure specs]
[Link to deployment specs]

undefined

Analysis Instructions

分析说明

When analyzing the workflow file:

Extract Core Purpose: Identify the primary business objective
Map Job Flow: Create dependency graph showing execution order
Identify Contracts: Document inputs, outputs, and interfaces
Capture Constraints: Extract timeouts, permissions, and limits
Define Quality Gates: Identify validation and approval points
Document Error Paths: Map failure scenarios and recovery
Abstract Implementation: Focus on behavior, not syntax

分析工作流文件时：

提取核心目标：确定主要业务目标
映射工作流：创建展示执行顺序的依赖图
识别契约：记录输入、输出和接口
捕获约束：提取超时、权限和限制条件
定义质量门：识别验证和审批节点
记录错误路径：映射故障场景和恢复流程
抽象实现细节：聚焦行为而非语法

Mermaid Diagram Guidelines

Mermaid图表指南

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

顺序执行：
```
A --> B --> C
```
并行执行：
```
A --> B & A --> C; B --> D & C --> D
```

条件分支：

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

mermaid

style TriggerNode fill:#e1f5fe
style SuccessNode fill:#e8f5e8
style FailureNode fill:#ffebee
style ProcessNode fill:#f3e5f5

Complex Workflows

复杂工作流

For workflows with 5+ jobs, use subgraphs:

mermaid

graph TD
    subgraph "Build Phase"
        A[Lint] --> B[Test] --> C[Build]
    end
    subgraph "Deploy Phase"  
        D[Staging] --> E[Production]
    end
    C --> D

对于包含5个及以上任务的工作流，使用子图：

mermaid

graph TD
    subgraph "Build Phase"
        A[Lint] --> B[Test] --> C[Build]
    end
    subgraph "Deploy Phase"  
        D[Staging] --> E[Production]
    end
    C --> D

Token Optimization Strategies

令牌优化策略

Use Tables: Dense information in structured format
Abbreviate Consistently: Define once, use throughout
Bullet Points: Avoid prose paragraphs
Code Blocks: Structured data over narrative
Cross-Reference: Link instead of repeat information

Focus on creating a specification that serves as both documentation and a template for workflow updates.

使用表格：以结构化格式呈现密集信息
统一缩写：定义一次后全程使用
项目符号：避免冗长段落
代码块：优先使用结构化数据而非叙述性文字
交叉引用：使用链接而非重复信息

重点在于创建一份兼具文档功能和工作流更新模板作用的规范。