「Kiroを使ってドキュメント管理を少し楽にしてみた」というタイトルで登壇しました #opsmethod

「Kiroを使ってドキュメント管理を少し楽にしてみた」というタイトルで登壇しました #opsmethod

2026.06.01

2026/05/15 に開催された 勉強会 opsmethod #2 「その運用、自動化しよう」クラスメソッド大阪オフィス にて 「Kiroを使ってドキュメント管理を少し楽にしてみた」 というタイトルで発表しました。

この記事では登壇内容の概要と、Hooks, Skills のプロンプトをご紹介します。

登壇資料

はじめに

最近Kiroを使ってAWSのマルチアカウント環境の運用していて、この環境を継続的に運用するために色々なドキュメントを管理しています。
このドキュメント管理がなかなか面倒で、ドキュメントの更新等が億劫でいつも悩まされています。
また、最近では構成が複雑になってきたため、「なぜこの構成になっているのか?」「なぜあの時、変更したのか?」というような、変更の背景が追えないという課題がありました。

そこで、せっかくKiroを使っているなら、ドキュメント管理もKiroでいい感じにできないかな?ということで、今回はKiroのHooksとSkillsを使って課題の解決に取り組んでみました。

Kiroで実装する範囲

今回は一例として、追加要件が発生してから社内で構成変更を検討し、最終的に本番環境へ適用するまでの一連の流れを想定します。

そのなかで、構成決定後本番適用後にドキュメントを生成/更新することで、課題を解決したいと思います。
CleanShot 2026-05-29 at 14.51.38@2x

変更理由のドキュメント

まずは運用している中で、あれ、なんでこの構成にしたんだっけ?という背景が欠落する課題があります。
変更を行なってから時間が経ち、なぜ変更したのか思い出せないということはよくあります。
これは、変更に対する意思決定の背景をテキストとして残していないことが原因と考えられます。
では、変更の意思決定を何かしらの方法でドキュメントとして残すことが必要になります。
gitのcommitメッセージから変更箇所程度であれば分かるかもしれませんが、その背景を追うのはなかなか骨が折れます。

この解決策として今回はソフトウェアアーキテクチャの意思決定をドキュメント化する際に用いられることがあるADR(Architectural Decision Record)という方法を使うことにしました。
CleanShot 2026-05-29 at 14.55.58@2x
ADRはAWSのドキュメントにも解説ページがありますが、アーキテクチャを選択する際、なぜそれを選択したのか?その背景や結果を残すためのドキュメントです。
https://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/architectural-decision-records/adr-process.html
主にソフトウェアアーキテクチャの文脈で利用されることが多いようですが、インフラでも応用できそうです。
今回はこのADRをKiroでなるべく工数をかけずに作りたいと思います。

まずKiroでADR作成を自動化するにあたり、構成変更における意思決定がどの時点で発生するかを把握する必要があります。
自身のプロジェクトを振り返ると、追加要件から構成決定までは基本的にミーティングの場で意思決定が行われることが多かったです。
ということで、ミーティングの議事録や文字起こしをデータソースとしてKiroにADRを作成してもらえば良さそうです。
CleanShot 2026-05-30 at 20.33.47@2x
Kiroに作ってもらうのはいいのですが、都度手動でプロンプトを打つのは面倒なので、こういった毎回同じフローはKiroのSkillsで仕組み化します。
Skillsは上記のような定型作業を自動化できる機能です。
実際に使用したSkillsを貼り付けます。

---
name: adr-from-meeting
description: 議事録(文字起こし・手書きメモ等)からADRテンプレートに沿ってArchitectural Decision Recordを自動生成する。
---

# 議事録からADR自動生成

議事録(文字起こし・手書きメモ等)を読み込み、ADRテンプレートに沿って構造化する。

## 1. ファイルの特定
- ユーザーがファイルを指定している場合(チャットで `#File` 等)はそのファイルを使用
- 指定がない場合は、現在開いているアクティブファイルを対象とする
- それも不明な場合は、`**/voice/` ディレクトリ内の最新の `.md` ファイルを自動検出し、ユーザーに確認する

## 2. テンプレートの読み込み
`references/adr-template.md` を読み込み、出力の雛形とする。

## 3. 議事録からADR要素を抽出
議事録の内容を分析し、以下を抽出する:

| ADRセクション      | 議事録から抽出する情報                                                         |
|-------------------|------------------------------------------------------------------------------|
| 背景・課題         | 議題の前提説明、「なぜ今これを決める必要があるか」に該当する発言                    |
| 検討した選択肢     | 比較・検討された案(サービス名、構成案、方式等)。メリデメ・コストの言及があれば含める |
| 決定事項           | 「これで行こう」「Xを採用する」等の合意・結論の発言                               |
| 影響・トレードオフ  | 決定に伴うリスク、制約、懸念として挙がった発言                                    |

**抽出時の注意:**
- 議事録に含まれない情報は勝手に埋めない。空欄のままにする
- 決定が出ていない(検討中で終わった)場合、決定事項は「未決定」と記載する
- 複数の独立した決定がある場合は、ADRを分割する(1 ADR = 1決定)

## 4. ADRファイルの生成

1. テンプレートに抽出した情報を埋めてADRを生成する
2. 出力先: プロジェクトルートの `docs/adr/` ディレクトリに `ADR-{連番}_{決定の件名}.md` として保存する
   - ディレクトリが存在しない場合は作成する
   - 連番は `docs/adr/` 内の既存ADRファイルから自動採番する(なければ0001から)
3. 生成したADRの内容を表示する

## 5. 不足情報の提示

ADRとして不十分な箇所を一覧で提示する:

⚠ 不足している情報
• xxxが議事録に含まれていません
• 選択肢Bのデメリットが不明です

## ルール

- 議事録の発言をそのまま転記しない。ADRとして読める文章に再構成する
- 文字起こし特有のフィラー(「えっと」「あの」等)は除去する
- 技術用語・サービス名は正式名称に統一する(例: 「ラムダ」→「AWS Lambda」)

これでKiroを通して、なぜ構成変更が行われたのか?なぜこの構成が選択されたのかが調べられるようになりました。
CleanShot 2026-05-30 at 20.46.11@2x

ドキュメントの更新

次に、設定変更後のドキュメント更新です。
アーキテクチャに変更を加えると、多くの場合で何かしらのドキュメント更新を伴います。
しかし、都度更新対象のドキュメントを探して内容を考えて更新する。という一連の作業は意外と面倒な作業です。
ただし、この面倒な作業を放置しておくと、更新されないドキュメントが溜まって、気づいたときには実態と乖離したドキュメントだらけになってしまいます。
「ドキュメントが古くて信頼できない」という状態になると、そもそもドキュメントを参照しなくなり、管理する意味がなくなってしまいます。

この解決策としてKiroのHooksを使って自動的に関連するドキュメントを更新する方法を試してみました。
Hooksは特定のイベントをトリガーに定義したアクションを自動で実行する機能です。
今回は、インフラを定義している.tfファイルと.jsonファイルの変更をトリガーにドキュメントを更新するHooksで、ドキュメント更新を自動化してみました。
CleanShot 2026-05-30 at 22.30.21@2x

実際に使用したHooksを貼り付けます。

{
  "enabled": true,
  "name": "Terraform Spec 自動同期",
  "description": "Kiroの作業完了後、Terraformファイルの変更内容をspecファイル(requirements.md / design.md / tasks.md)に反映する必要があるか確認し、必要であれば更新する",
  "version": "1",
  "when": {
    "type": "fileEdited",
    "patterns": ["*.tf", "**/*.json"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "Terraformファイル(*.tf)が保存されました。変更されたファイルの内容を確認し、以下の4つのドキュメントを必要に応じて更新してください。\n\n**変更がない、またはドキュメントへの反映が不要な場合は、テキストを一切出力せずに即座に終了してください。**\n\n## 1. specファイルの更新\n`.kiro/specs/organizations/` 配下のspecファイルを以下の手順で更新してください:\n  1. 変更されたTerraformファイルの内容を確認する\n  2. requirements.md / design.md / tasks.md の内容と照合する\n  3. specに反映すべき変更(新リソース追加・構成変更・ポリシー変更など)があれば、該当するspecファイルを更新する\n  4. spec変更が不要であれば何もしない\n\n## 2. 概要ドキュメントの更新\n`docs/aws-organizations-overview.md` を以下の観点で確認し、必要であれば更新してください:\n  1. OU構成の変更(OUの追加・削除・移動)\n  2. アカウント一覧の変更(アカウントの追加・削除・OU変更)\n  3. SCP・宣言型ポリシーの変更(ポリシーの追加・削除・アタッチ先変更)\n  4. IAM Identity Centerの変更(ユーザー・グループ・許可セット・アサインメントの変更)\n  5. 変更が必要な場合のテーブルへの追記\n\n## 3. draw.io構成図の更新\n`organizations.tf` または `account.tf` が変更された場合のみ、`docs/organizations.drawio` を更新してください:\n  1. `organizations.tf` のOU構成と `account.tf` のアカウント配置を確認する\n  2. `docs/organizations.drawio` の現在の内容と照合する\n  3. OUの追加・削除・移動、またはアカウントの追加・削除・OU変更があれば、draw.ioのXMLを更新する(ファイルパス: `docs/organizations.drawio`)\n  4. 既存のスタイル(色・フォント・レイアウト)を維持しながら変更箇所のみ修正する\n  5. 変更がなければ何もしない\n\n## 4. Runbookの更新\n`docs/runbook.md` を以下の観点で確認し、必要であれば更新してください:\n  1. 新しいリソースタイプが追加された場合、対応する作業手順を追加する\n  2. ファイルパスやリソース名が変更された場合、手順内のコード例を修正する\n  3. 新しいプロバイダーやアカウントが追加された場合、前提条件やコード例を更新する\n  4. 変更がなければ何もしない\n\n更新した場合のみ、何を変更したか簡潔に報告してください。"
  },
  "workspaceFolderName": "org",
  "shortName": "sync-terraform-spec"
}

これで、tfファイルとjsonファイルの変更をトリガーにドキュメントを更新してくれるようになりました。
これだけでドキュメント更新が自動化されるので簡単ですね。

まとめ

今回はKiroを使った運用の自動化という内容で登壇しました。
どちらを使う場合も、まずは現在手動でやっていることを言語化することが重要だと思います。
言語化さえできれば、あとはやりたいことをKiroと壁打ちすればHooksもSkillsも簡単に実装してくれるので、やってみたい!と思ったらすぐにKiroに相談してみてください。

この記事をシェアする

AWSのお困り事はクラスメソッドへ

関連記事