graceful-shutdown
アプリケーションの安全な終了処理を実装するスキル。シグナルハンドリング、リソースクリーンアップ、リクエストドレイニングを含む完全な終了フローを設計。Anchors:• Release It! (Michael T. Nygard) / 適用: リソース管理・障害対応 / 目的: プロダクション環境での安全なシャットダウン• Node.js Design Patterns (Mario Casciaro) / 適用: 非同期処理の終了 / 目的: Promise/Stream/Workerの適切な終了Trigger:Use when implementing shutdown handlers, signal processing, resource cleanup, request draining, or application lifecycle management.graceful shutdown, SIGTERM, SIGINT, cleanup, resource draining, process exit, signal handler
When & Why to Use This Skill
The Graceful Shutdown skill is a specialized tool for implementing robust application lifecycle management. It enables developers to design and code secure termination sequences by handling system signals like SIGTERM and SIGINT. By focusing on resource cleanup, request draining, and idempotent shutdown flows, this skill prevents data loss, resource leaks, and service instability, ensuring production-grade reliability in environments such as Node.js, Docker, and Kubernetes.
Use Cases
- Web Server Request Draining: Implementing logic to stop accepting new connections while allowing active HTTP requests to complete before the server shuts down.
- Database Connection Management: Ensuring all database, cache, and file stream connections are closed properly to prevent data corruption and connection pool exhaustion.
- Cloud-Native Orchestration: Configuring signal handlers for containerized applications to respond correctly to Kubernetes pod termination and avoid abrupt process kills.
- Background Worker Checkpointing: Designing cleanup sequences for worker processes to finish critical tasks or save state before exiting during a deployment or scaling event.
- Resource Cleanup Automation: Automating the release of system resources like temporary files, locks, and network sockets to maintain system health over long-term operations.
| name | graceful-shutdown |
|---|---|
| description | | |
| • Release It! (Michael T. Nygard) / 適用 | リソース管理・障害対応 / 目的: プロダクション環境での安全なシャットダウン |
| • Node.js Design Patterns (Mario Casciaro) / 適用 | 非同期処理の終了 / 目的: Promise/Stream/Workerの適切な終了 |
graceful-shutdown
概要
アプリケーションの安全な終了処理を実装するスキル。シグナルハンドリング、リソースクリーンアップ、リクエストドレイニングを通じて、データ損失やリソースリークを防止する。
ワークフロー
Phase 1: 終了要件分析
目的: アプリケーションの特性から必要な終了処理を特定
アクション:
- アプリケーションタイプ(Web/Worker/CLI/Desktop)を確認
- 管理中のリソース(DB接続、ファイル、ネットワーク)を洗い出し
- 実行中のタスク(リクエスト、ジョブ、処理)を特定
- タイムアウト要件を定義
Task: agents/analyze-shutdown-requirements.md を参照
Phase 2: シャットダウンフロー設計
目的: 適切な順序での終了処理シーケンスを設計
アクション:
references/shutdown-patterns.mdで適用パターンを選択- シグナルハンドラーの実装方針を決定
- リソースクリーンアップの優先順位を定義
- タイムアウト処理とフォールバックを設計
Task: agents/design-shutdown-flow.md を参照
Phase 3: 実装と検証
目的: 終了処理の実装と動作検証
アクション:
- シグナルハンドラーを実装
- リソースクリーンアップロジックを実装
- テスト用スクリプトで動作確認
scripts/log_usage.mjsで使用記録を保存
Task: agents/implement-validate.md を参照
Task仕様ナビ
| Task | 起動タイミング | 入力 | 出力 |
|---|---|---|---|
| analyze-shutdown-requirements | Phase 1開始時 | アプリケーション仕様 | 終了要件定義 |
| design-shutdown-flow | Phase 2開始時 | 終了要件定義 | シャットダウンフロー設計書 |
| implement-validate | Phase 3開始時 | 設計書 | 実装コードと検証結果 |
詳細仕様: 各Taskの詳細は agents/ ディレクトリの対応ファイルを参照
ベストプラクティス
すべきこと
- 複数シグナルをハンドル(SIGTERM/SIGINT両方に対応)
- べき等なクリーンアップ(複数回呼ばれても安全)
- タイムアウト設定(推奨: 30秒)
- エラーをログに記録
- プロセス終了コード明示(正常0、エラー1)
- リソース解放の順序制御(接続→ファイル→キャッシュ)
- 新規リクエスト拒否(シャットダウン開始後は503を返す)
避けるべきこと
- process.exit() 直接呼び出し(クリーンアップが実行されない)
- 同期的な無限待機(デッドロックの原因)
- シグナルハンドラー内の重い処理(タイムアウトでKILLされる)
- エラー時の即座終了(部分的なクリーンアップで状態が不整合に)
- Promise未解決のまま終了(データ損失の原因)
リソース参照
references/(詳細知識)
| リソース | パス | 内容 |
|---|---|---|
| 基礎知識 | See references/basics.md | 概念とシグナル |
| パターン集 | See references/shutdown-patterns.md | 終了パターン4種 |
| 環境別実装 | See references/environment-specific.md | Node/Docker/k8s |
| テストガイド | See references/testing-guide.md | テスト手法 |
scripts/(決定論的処理)
| スクリプト | 用途 | 使用例 |
|---|---|---|
validate-shutdown.mjs |
実装検証 | node scripts/validate-shutdown.mjs src/shutdown.ts |
log_usage.mjs |
フィードバック記録 | node scripts/log_usage.mjs --result success |
assets/(テンプレート)
| テンプレート | 用途 |
|---|---|
shutdown-handler.ts |
Node.js/TypeScript用ハンドラー |
変更履歴
| Version | Date | Changes |
|---|---|---|
| 2.0.0 | 2026-01-02 | 18-skills.md仕様完全準拠、構造再編成 |
| 1.0.0 | 2025-12-31 | 初版 |