🌱

Spec Kit で SRE AI Agent を開発する長い旅の始まり

に公開
AI
SRE
Spec Kit
tech

こんにちは。
ご機嫌いかがでしょうか。
"No human labor is no human error" が大好きな吉井 亮です。

個人的なミッションとして ”SRE AI Agent” を開発し本番運用させることを掲げています。
"SRE AI Agent" とは、SRE（Site Reliability Engineering）業務を支援するための自律的 AI エージェントです。
このエージェントは、システムの監視、障害対応、パフォーマンス最適化などのタスクを自動化し、SRE チームの負担を軽減することを目指しています。

SRE AI Agent の本番運用化はとても恩恵が大きな取り組みです。
運用自動化・半自動化を人間の手をかけることなく実現することはまさに "No human labor is no human error" の精神にかなっています。

Spec Kit とは

SRE AI Agent の本番運用化という夢とは別の夢である ”スペック駆動開発” に挑戦したいと思います。

今回は GitHub が提供する Spec Kit を使って SRE AI Agent の開発を進めていきます。
Spec Kit を使うと、プロジェクト憲法〜仕様〜実装計画〜タスク細分化〜実装〜テスト〜修正までを一貫して AI によって支援してもらうことができます。

https://github.com/github/spec-kit

スペック駆動開発(SDD)とは

そもそも SDD とは何でしょうか？
Spec Kit から引用します。

Spec-Driven Development flips the script on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: specifications become executable, directly generating working implementations rather than just guiding them.

「コードは王様でした」 良いですね。心に刺さるフレーズです。
仕様は足場であり、本格的なコーディングが始まると捨て去られたと言われています。少々大袈裟かもしれませんが、言いたいことは理解できます。

SDD はこれを逆転する考えで、コードが仕様に仕えるという原則があります。
仕様と実装のギャップはソフトウェア開発現場の大きな悩みでしたが、SDD では仕様と実装計画からコードが生成されるため、ギャップが解消されます。

Spec Kit インストール

本格的なコーディングの経験が無い私が SDD でどこまでのコードを作ることができるのか、試してみましょう。

早速 Spec Kit をインストールします。

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Spec Kit を使うための環境を初期化します。

specify init <PROJECT_NAME>

初期化プロセス中にコーディングエージェントを選択する画面が表示されます。記事執筆時点で対応しているコーディングエージェントは以下の通りです。
ほとんどの需要に対応しているように思います。

Agent Support Notes
Claude Code ✅
GitHub Copilot ✅
Gemini CLI ✅
Cursor ✅
Qwen Code ✅
opencode ✅
Windsurf ✅
Kilo Code ✅
Auggie CLI ✅
CodeBuddy CLI ✅
Roo Code ✅
Codex CLI ✅
Amazon Q Developer CLI ⚠️ Amazon Q Developer CLI does not support custom arguments for slash commands.

初期化が終わると <PROJECT_NAME> ディレクトリに以下のファイル群が作成されます。(バージョンによって異なるはずですので参考程度に)

.claude
└── commands
    ├── speckit.analyze.md
    ├── speckit.checklist.md
    ├── speckit.clarify.md
    ├── speckit.constitution.md
    ├── speckit.implement.md
    ├── speckit.plan.md
    ├── speckit.specify.md
    └── speckit.tasks.md
.specify
├── scripts
│   └── bash
│       ├── check-prerequisites.sh
│       ├── common.sh
│       ├── create-new-feature.sh
│       ├── setup-plan.sh
│       └── update-agent-context.sh
└── templates
    ├── agent-file-template.md
    ├── checklist-template.md
    ├── plan-template.md
    ├── spec-template.md
    └── tasks-template.md

プロジェクトの原則を確立する

/speckit.constitution コマンドが最初のステップです。
この後の開発のガイドとなる管理原則と開発ガイドラインを作成します。

/speckit.constitution コード品質、テスト基準、ユーザーエクスペリエンスの一貫性、パフォーマンス要件、テスト駆動開発に焦点を当てた原則を作成して。全てのドキュメントは日本語で書くこと。

コマンドを実行すると .specify/memory/constitution.md に原則が作成されるようです。
会社やプロジェクトのポリシーに合わせて修正していきましょう。

仕様を作成する

/speckit.specify コマンドで仕様を作成します。ここでは技術要素を避け What と Why に焦点を当てて記述します。
私なりの発見なのですが、全ての仕様を一気に確定させるのではなく、部品部品で細かく仕様を定義して実装していったほうがスムーズに開発が進むような気がします。
LLM はコンテキスト保持に限界がありますし、他のコーディングエージェントでは修正を繰り返していくと迷走するといった経験があります。
それを踏まえて段階的開発に挑戦することにしました。結果がどうなるかは現段階では未知です。

/speckit.specify 仕様001 Slack Bot を通じて 'SRE AI Agent' を操作する。'SRE AI Agent' は AWS 上で稼働しているシステムの運用タスクを半自動化するものである。段階的な機能開発をする。仕様001 では Slack Bot の呼びかけに対して "Hello, World!" と返答する機能を実装する。

SPEC.md ファイルが specs/<NUMBER>/ ディレクトリに作成されます。
ここに仕様が書かれています。仕様の追加や変更はこのファイルを編集していくことになるのですが、直接編集するよりも /speckit.specify コマンドを使ったほうが良いでしょう。
この後、複数のファイルがこのディレクトリに追加されていきます。整合が取れた状態で保つ必要があります。直接編集すると整合が取れなくなるリスクがあるように感じます。

$ tree agent/specs/001/
agent/specs/001/
└── SPEC.md

技術実装計画を作成する

/speckit.plan コマンドで技術要素を指定します。私は初心者なので仕様を作る段階で技術的な話をしそうになりましたが、やっとここで技術的な話をして良いことになります。

/speckit.plan 仕様001 の実装計画を作成して
- Slack → API Gateway → Lambda の構成（コーディング対象は Lambda）
- Python 3.13 で実装
- lambda_function.py をエントリポイントとする
- 主要ロジックは main.py に実装
- メンテナンス性や可読性を意識して適宜モジュール化すること
    - 例) AWS リソースに対する操作は aws.py
    - 例) アプリケーションのロギングは logger.py
- アプリケーションログは標準出力へ出力すること

ファイルが増えました。各ファイルの簡単な説明を追記しています。が、おそらくこれまでの指示によって多少は変わると予想します。
RESEARCH.md を眺めていると、きちんと調べてくれているのだなと感心すると同時に実装の確からしさが増すであろうという期待が高まります。

$ tree agent/specs/001/
agent/specs/001/
  ├── PLAN.md          # 機能仕様
  ├── SPEC.md
  ├── RESEARCH.md      # 実装に必要な技術的決定事項とベストプラクティス
  ├── DATA-MODEL.md    # データモデル設計
  ├── QUICKSTART.md    # 開発環境のセットアップから Lambda 関数のデプロイ、Slack アプリの設定までを説明
  └── contracts/
      └── slack-events.json  # SlackアプリとLambda関数間のイベント通信コントラクト

タスクへブレイクダウン

/speckit.tasks コマンドでタスクへブレイクダウンします。1つ上の実装計画を基にタスクが作成されます。

/speckit.tasks  仕様001のタスクを作成

TASKS.md ファイルが追加されました。細分化されたタスクが記述されています。
この後、実装の指示を出しますが、ここで細分化されたタスクごとに実装を進めていくことになります。
大き過ぎるタスクは分割するように指示をしたほうが精度は高いでしょう。時間はかかりますがバランスを取る必要があります。

$ tree agent/specs/001/
agent/specs/001/
  ├── TASKS.md    # New
  ├── PLAN.md
  ├── SPEC.md
  ├── RESEARCH.md
  ├── DATA-MODEL.md
  ├── QUICKSTART.md
  └── contracts/
      └── slack-events.json

実装開始！

/speckit.implement コマンドで実装を開始します。「まとめて実装しますか？1つ1つ実装しますか？」と聞かれたパターンもありました。
繰り返しですが、タスクは1つ1つ進めていくのがお勧めです。コンテキストサイズの限界、切り戻しの容易さ、レビューの容易さを考慮するとそう思います。
また、タスクが1つ終わったら git commit しておくことのが良いでしょう。

/speckit.implement 仕様001の実装を開始

コード修正

当然ながら一発で完璧なコードが生成されるわけではありません。ローカルで実施可能な単体・結合テストをしながら実装が進んでいくので、まったくの的外れなコードにはならないはずですが、それでも修正は必要です。
単体・結合テストを通らない箇所は特に注意が必要です。

コードを修正したいのですが、その気持ちは抑えましょう。人間がコードを修正してはいけません。なぜなら「仕様が王様」だからです。
仕様を先に修正します。修正した仕様に合わせたタスクを作成し、タスク単位の実装を進めていきます。

以下は例です。

# 仕様の作り直し
/speckit.plan 仕様001の実装計画を以下の仕様を盛り込んで作り直して。
- 環境変数 'AWS_REGION' は AWS の予約語であり Lambda 関数では使用できないため、'AWS_LAMBDA_REGION' に変更する
- 'AWS_LAMBDA_REGION' が指定されていない場合、デフォルトで 'ap-northeast-1' を使用する

# タスクの作成
/speckit.tasks 環境変数 'AWS_REGION' を 'AWS_LAMBDA_REGION' に変更した仕様001を実装するためのタスクを作成して

# タスク単位の実装
/speckit.implement 仕様001 Phase 7: 環境変数仕様更新 の実装を開始

カバレッジ分析

/speckit.analyze コマンドは SPEC.md、PLAN.md、TASKS.md の3つの主要な成果物間で非破壊的な相互整合性と品質分析を実行します。
タスク作成の後、実装の前に実行すると良いそうです。

/speckit.analyze

# 4つのクリティカルな問題が見つかり、修正案を提案してくれるようです
# このメッセージの重要なポイントは、AIが自動的には編集を適用しないということです。レビューと承認のために正確な編集コマンドを提供するとしています。
Remediation Offer
Would you like me to suggest concrete remediation edits for the top 4 critical issues (C2, C3, C4, C5)? Specifically:
1. Complete ENVIRONMENT cleanup: Remove from all code files to match spec
2. Fix task numbering: Renumber TASK-041/042 to fill gap
3. Fix phase completion: Update Phase 5 status or task checkboxes
4. Constitution guidance: Provide minimal constitution template for SRE AI Agent project
Note: I will NOT apply these edits automatically. I will provide the exact edit commands for your review and approval.

カスタム品質チェックリストを生成

/speckit.checklist コマンドは、要件に基づいて現在の機能に対するカスタムチェックリストを生成します。
仕様書そのものの品質を保証するためのツールです。

Spec Kit のチェックリストは以下の概念があります。

  • ✅ 正しい目的: 要件書の品質をテストする
    • 「視覚的階層の要件は測定可能な基準で定義されているか？」
    • 「『目立つ表示』は具体的なサイズ/位置で数値化されているか？」
  • ❌ 間違った目的: 実装の動作をテストしない
    • 「ボタンが正しくクリックできるかを確認する」
    • 「APIが200を返すかをテストする」
/speckit.checklist	

# チェックリストの目的を聞かれています
仕様001「Slack Bot 基本応答機能」のチェックリスト生成について、以下の質問にお答えください：
Q1: チェックリストの目的と深さ
このチェックリストは何のために使用しますか？
Option	目的	深さの特徴
A	著者による自己レビュー	軽量、実装前の最終確認
B	ピアレビュー（PR時）	標準的、品質ゲートとして使用
C	リリース前の品質ゲート	厳格、本番デプロイ前の最終検証
D	セキュリティ/コンプライアンスレビュー	専門的、セキュリティ要件に特化
回答: B, C, D のいずれか（またはその他を指定）

# 重点領域を聞かれています
Q2: 重点的にチェックすべきリスク領域
仕様001の分析結果から、以下のリスク領域が検出されました。どの領域を必須チェック項目として含めるべきですか？
リスク領域	検出された問題	重要度
セキュリティ要件	Secrets Manager移行が「TODO」、Slack署名検証の詳細が不明確	🔴 High
非機能要件の測定可能性	「95パーセンタイル3秒」「80%カバレッジ」の測定方法が未定義	🟡 Medium
ヘルスチェック実装	/healthエンドポイントが仕様に記載されているが実装タスクが欠如	🟡 Medium
エッジケースカバレッジ	エラー処理、リカバリーフローの要件が部分的	🟡 Medium
回答: すべて含める / High のみ / カスタム選択（具体的に指定）

# スコープを聞かれています
Q3: スコープの境界
この仕様001は「基本応答機能」ですが、チェックリストに含めるべきスコープは？
Option	スコープ	含まれる項目
A	モジュール単体の正確性	Slack連携、Lambda、基本応答のみ
B	システム統合ポイント含む	AWS連携、CloudWatch、API Gateway、Secrets Managerとの統合
C	将来拡張性の考慮	次フェーズ（AI応答、複雑な対話）への拡張性も評価

回答: A, B, C のいずれか
デフォルト値（回答がない場合）:
目的: B（ピアレビュー用）
リスク領域: High のみ
スコープ: B（システム統合含む）

ご回答をお願いします。または「デフォルトで進めて」とお答えください。

Q1~3 に複数の選択肢が含まれており、多様な観点でチェックリストを作れそうです。
ここは「デフォルトで進めて」と答えてみました。

検出されたクリティカル問題
CHK001: Secrets Manager要件が「TODO」のまま未形式化
CHK039: 環境変数使用と非推奨通知の矛盾
CHK040: Secrets Manager移行タイムラインが不明確
CHK045: 憲法準拠問題（シークレット保管方法）

📋 次のアクション
CHK039, CHK040, CHK041（移行戦略の曖昧性）を解決
Secrets Manager要件を形式化（CHK001-CHK006）
憲法準拠性を検証（CHK045-CHK048）
セキュリティ失敗シナリオを包括的に定義（CHK024-CHK027）
このチェックリストは要件の品質をテストするものであり、実装の動作をテストするものではありません。各項目は仕様書が明確で、完全で、測定可能かを検証します。

問題を検出してくれました。次にとるアクションまで提示してくれています。Secrets Manager 周りがまだ手付かずになっています。
解決するためのタスクを作成しましょう。

/speckit.tasks チェックリストで検出された問題を解決するためのタスクを作成して
1. CHK039, CHK040, CHK041（移行戦略の曖昧性）を解決
2. Secrets Manager要件を形式化（CHK001-CHK006）
3. 憲法準拠性を検証（CHK045-CHK048）
4. セキュリティ失敗シナリオを包括的に定義（CHK024-CHK027）

以下の通りタスクが生成されました。タスクごとの優先度が表示されるのが嬉しいです。推定工数はアテにしないことにします。
このような形で何をするにでもコマンドで指示を出していくのが Spec Kit の使いこなしだと感じています。

タスクサマリー
タスクID	タスク名	優先度	推定工数	チェックリスト対応
TASK-001-038	Secrets Manager移行戦略の明確化	🔴 高	45分	CHK039, CHK040, CHK041
TASK-001-039	Secrets Manager要件の形式化（基本）	🔴 高	30分	CHK001, CHK002, CHK003
TASK-001-040	Secrets Manager要件の形式化（エラー処理）	🔴 高	30分	CHK004, CHK005, CHK030
TASK-001-041	IAM権限要件の詳細化	🔴 高	20分	CHK006, CHK036, CHK048
TASK-001-042	Slack署名検証要件の詳細化	🔴 高	40分	CHK007-CHK011
TASK-001-043	セキュリティ失敗シナリオ要件の追加	🔴 高	35分	CHK024-CHK027
TASK-001-044	憲法準拠性の検証と文書化	🔴 高	25分	CHK045-CHK048
TASK-001-045	セキュリティチェックリストの更新	🟡 中	20分	全23項目マーク
TASK-001-046	セキュリティ要件レビュー会実施準備	🟡 中	15分	-
TASK-001-047	変更履歴とバージョンの更新	🟡 中	10分	-

次のアクション
TASK-001-038から順番に実行（依存関係あり）
各タスク完了後、対応するチェックリスト項目をマーク
Phase 6完了後、セキュリティレビュー会を実施
/speckit.analyzeで憲法準拠性を再検証

完了

PLAN、TASK、IMPLEMENT の各コマンドを繰り返しループしながら実装を進めていきます。
Hello, World が表示されたら仕様001は完了しましょう。

/speckit.plan 仕様001はすべての計画を完了する。
- ステージング環境へリソースをデプロイした
- Slack Bot からの基本応答機能が動作確認できた

完了報告書を作ってもらいました。ありがとうございます。

📋 仕様001 完了報告
仕様001「Slack Bot 基本応答機能」の計画を完了状態に更新しました。
✅ 更新内容

（省略）

3. COMPLETION.md 新規作成
包括的な完了報告書を作成しました：
エグゼクティブサマリー
実装成果（機能、技術仕様、品質メトリクス）
フェーズ別実施内容（Phase 1-8）
憲法準拠性検証
成功基準達成状況（総合達成率75%）
デプロイメント情報
課題と今後の対応
学んだ教訓
次のステップへの引き継ぎ事項

（省略）

🚀 次のステップ
仕様001の完了により、以下の基盤が整いました：
✅ Slack連携基盤
✅ セキュリティ基盤（署名検証、Secrets Manager、IAM）
✅ AWS統合基盤（Lambda、DynamoDB、CloudWatch）
✅ テスト基盤（TDD、高カバレッジ）
✅ ドキュメント基盤
推奨される次期機能:
仕様002: AWS Cost Explorer連携
仕様003: AWS Trusted Advisor連携
仕様004: CloudWatch Logs分析

まとめ

初めて SDD に挑戦しました。Spec Kit は素晴らしいツールです。

「仕様が王様」にして小さく実装を進めていくことで、LLM による迷走や手戻りを極力減らすことができると感じました。
もしかしたら、熟練の開発者の方にとってコーディングエージェントのコードは苦い顔をしたくなるかもしれません。
しかし、仕様を固めて仕様通りに実装を進める SDD + LLM の組み合わせは、これからシステム開発の選択肢の1つになるはずです。
しかし、仕様を固めて仕様通りに実装を進める SDD + LLM の組み合わせは、これからシステム開発の選択肢の1つになるはずです。
全てがこれになるとは思いません。選択肢の1つです。

Spec Kit に書いてありますが、

  1. GenAI の能力が飛躍的アップしたこと
  2. ソフトウェアの複雑さが増大し続けていること
  3. 要件の変化ペースが従来にないほど速くなっていること

これらに対応する手段になるという期待を持っています。

Discussion