mcpField
C
create-github-action-workflow-specification

create-github-action-workflow-specification

github.com/githubクラウド・DevOps40.5k10.8k 回インストール今日更新
リポジトリ

create-github-action-workflow-specification について

GitHub Actions ワークフローを分析し、動作仕様を作成するスキルです。CI/CD の要件を記録するチーム向けで、実装方法より目的や制約を記述します。

主な機能

  1. 01目的とジョブの流れの抽出
  2. 02入出力とインターフェースの記録
  3. 03制約と品質ゲートの特定
  4. 04失敗経路と復旧の記述
  5. 05図と構造化仕様の作成

活用シーン

  1. 01既存ワークフローの仕様化
  2. 02ジョブ依存関係と実行順の整理
  3. 03シークレット、変数、トリガーの記録

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/github/awesome-copilot --skill create-github-action-workflow-specification

インストール後、Claude Code で/create-github-action-workflow-specificationを入力して読み込まれたか確認します。

詳細

GitHub Actions ワークフロー仕様の作成

GitHub Actions ワークフロー ${input:WorkflowFile} の包括的な仕様を作成します。

この仕様は、ワークフローの動作、要件、制約に関する仕様として機能します。実装に依存しないものでなければならず、どのように実装されるかではなく、ワークフローが何を達成するかに焦点を当てます。

AI に最適化された要件

  • トークン効率: 明確さを犠牲にすることなく、簡潔な表現を使用する
  • 構造化データ: 密な情報を表現するために表、リスト、図を活用する
  • 意味の明確さ: 正確な用語を一貫して使用する
  • 実装の抽象化: 特定の構文、コマンド、ツールのバージョンを避ける
  • 保守性: ワークフローの進化に合わせて容易に更新できるように設計する

仕様テンプレート

保存先: /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]
シークレットと変数
種類名前目的スコープ
SecretSECRET_1[目的]ワークフロー
VariableVAR_1[目的]リポジトリ

実行制約

ランタイム制約
  • タイムアウト: [最大実行時間]
  • 同時実行: [並列実行の制限]
  • リソース制限: [メモリ/CPU の制約]
環境制約
  • ランナー要件: [OS/ハードウェアの要件]
  • ネットワークアクセス: [外部接続の要件]
  • 権限: [必要なアクセスレベル]

エラー処理戦略

エラーの種類対応復旧アクション
ビルド失敗[対応][復旧手順]
テスト失敗[対応][復旧手順]
デプロイ失敗[対応][復旧手順]

品質ゲート

ゲートの定義
ゲート基準バイパス条件
コード品質[標準][許可される場合]
セキュリティスキャン[しきい値][許可される場合]
テストカバレッジ[パーセンテージ][許可される場合]

監視と可観測性

主要な指標
  • 成功率: [目標パーセンテージ]
  • 実行時間: [目標時間]
  • リソース使用量: [監視のアプローチ]
アラート
条件重大度通知先
[条件][レベル][誰に/どこに]

連携ポイント

外部システム
システム連携の種類データ交換SLA 要件
[システム][種類][データ形式][要件]
依存するワークフロー
ワークフロー関係トリガーの仕組み
[ワークフロー][種類][トリガー方法]

コンプライアンスとガバナンス

監査要件
  • 実行ログ: [保持ポリシー]
  • 承認ゲート: [必要な承認]
  • 変更管理: [更新プロセス]
セキュリティ制御
  • アクセス制御: [権限モデル]
  • シークレット管理: [ローテーションポリシー]
  • 脆弱性スキャン: [スキャン頻度]

エッジケースと例外

シナリオマトリックス
シナリオ期待される動作検証方法
[エッジケース][動作][検証方法]

検証基準

ワークフロー検証
  • VLD-001: [検証ルール]
  • VLD-002: [検証ルール]
パフォーマンスベンチマーク
  • PERF-001: [ベンチマーク基準]
  • PERF-002: [ベンチマーク基準]

変更管理

更新プロセス
  1. 仕様の更新: 最初にこのドキュメントを修正します
  2. レビューと承認: [承認プロセス]
  3. 実装: ワークフローに変更を適用します
  4. テスト: [検証アプローチ]
  5. デプロイ: [リリースプロセス]
バージョン履歴
バージョン日付変更内容作成者
1.0[日付]初版仕様[作成者]

関連仕様

  • [関連するワークフロー仕様へのリンク]
  • [インフラ仕様へのリンク]
  • [デプロイ仕様へのリンク]

## 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

トークン最適化戦略

  1. テーブルを使用する: 構造化された形式で情報を密にまとめます
  2. 一貫して省略する: 一度定義し、全体で使用します
  3. 箇条書き: 文章形式の段落を避けます
  4. コードブロック: 説明的な記述よりも構造化データを使用します
  5. 相互参照: 情報を繰り返す代わりにリンクします

ワークフローの更新におけるドキュメントとテンプレートの両方の役割を果たす仕様の作成に焦点を当てます。

コメント

Markdown 対応