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

## ワークフロー概要

**目的**: [ワークフローの主要目標を1文で説明]
**トリガーイベント**: [トリガー条件リスト]
**対象環境**: [環境スコープ]

## 実行フロー図

```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	[要件]	High	[テスト可能な基準]
REQ-002	[要件]	Medium	[テスト可能な基準]

セキュリティ要件

ID	要件	実装制約
SEC-001	[セキュリティ要件]	[制約説明]

パフォーマンス要件

ID	メトリクス	目標値	測定方法
PERF-001	[メトリクス]	[目標値]	[測定方法]

入出力契約

入力

# 環境変数
ENV_VAR_1: string  # 目的: [説明]
ENV_VAR_2: secret  # 目的: [説明]

# リポジトリトリガー
paths: [パスフィルターリスト]
branches: [ブランチパターンリスト]

出力

# ジョブ出力
job_1_output: string  # 説明: [目的]
build_artifact: file  # 説明: [コンテンツタイプ]

シークレットと変数

タイプ	名前	目的	スコープ
Secret	SECRET_1	[目的]	Workflow
Variable	VAR_1	[目的]	Repository

実行制約

ランタイム制約

• タイムアウト: [最大実行時間]
• 並行実行: [並行実行の制限]
• リソース制限: [メモリ/CPU制約]

環境制約

• ランナー要件: [OS/ハードウェア要件]
• ネットワークアクセス: [外部接続要件]
• 権限: [必要なアクセスレベル]

エラーハンドリング戦略

エラータイプ	対応	復旧アクション
ビルド失敗	[対応]	[復旧ステップ]
テスト失敗	[対応]	[復旧ステップ]
デプロイ失敗	[対応]	[復旧ステップ]

品質ゲート

ゲート定義

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

監視と可観測性

主要メトリクス

• 成功率: [目標パーセンテージ]
• 実行時間: [目標時間]
• リソース使用量: [監視方法]

アラート

条件	重大度	通知先
[条件]	[レベル]	[誰/どこ]

統合ポイント

外部システム

システム	統合タイプ	データ交換	SLA要件
[システム]	[タイプ]	[データ形式]	[要件]

依存ワークフロー

ワークフロー	関係	トリガー機構
[ワークフロー]	[タイプ]	[トリガー方法]

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

監査要件

• 実行ログ: [保持ポリシー]
• 承認ゲート: [必要な承認]
• 変更管理: [更新プロセス]

セキュリティコントロール

• アクセス制御: [権限モデル]
• シークレット管理: [ローテーションポリシー]
• 脆弱性スキャン: [スキャン頻度]

エッジケースと例外

シナリオマトリックス

シナリオ	予想される動作	検証方法
[エッジケース]	[動作]	[検証方法]

検証基準

ワークフロー検証

• VLD-001: [検証ルール]
• VLD-002: [検証ルール]

パフォーマンスベンチマーク

• PERF-001: [ベンチマーク基準]
• PERF-002: [ベンチマーク基準]

変更管理

更新プロセス

1. 仕様書更新: まずこのドキュメントを修正
2. レビューと承認: [承認プロセス]
3. 実装: ワークフローに変更を適用
4. テスト: [検証方法]
5. デプロイ: [リリースプロセス]

バージョン履歴

バージョン	日付	変更内容	作成者
1.0	[日付]	初期仕様書	[作成者]

関連仕様書

• [関連ワークフロー仕様書へのリンク]
• [インフラストラクチャ仕様書へのリンク]
• [デプロイ仕様書へのリンク]

## 分析手順

ワークフローファイルを分析する際:

1. **中核目的の抽出**: ビジネス目標を特定
2. **ジョブフロー のマッピング**: 実行順序を示す依存グラフを作成
3. **契約の特定**: 入出力とインターフェースを文書化
4. **制約の把握**: タイムアウト、権限、制限を抽出
5. **品質ゲートの定義**: 検証と承認ポイントを特定
6. **エラーパスの文書化**: 失敗シナリオと復旧を追跡
7. **実装の抽象化**: 構文ではなく動作に焦点を当てる

## Mermaid 図ガイドライン

### フロータイプ
- **順序実行**: `A --> B --> C`
- **並行実行**: `A --> B & A --> C; B --> D & C --> D`
- **条件分岐**: `A --> B{Decision}; B -->|Yes| C; B -->|No| D`

### スタイリング
```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. 一貫した略語: 1度定義して再利用
3. 箇条書き: 散文段落を避ける
4. コードブロック: ナレーティブではなく構造化データ
5. 相互参照: 情報の重複ではなくリンクで参照

ワークフロー更新のドキュメントかつテンプレートとして機能する仕様書の作成に注力してください。