以下の内容はhttps://techblog.forgevision.com/entry/2026/03/12/134635より取得しました。

【AI時代のDocs運用】 Kiro × Hooks × MkDocsでドキュメントを継続的に更新・管理する②

AWS Kiro

こんにちは、AWSグループの藤岡です。

前回の記事では、AI時代のDocs運用の1つのアプローチとして、hooksを活用した以下構成のDocs基盤について紹介・解説しました。

GitとKiroのダブルフックによる自動検証と、MKDocsによる閲覧・検索

techblog.forgevision.com

本記事では、各構成のセットアップと動作確認を行います。

セットアップ①Kiroエージェントフック

まずは文脈的なチェックを担うKiroフックのセットアップを行います。

.kiro/hooks配下に以下のように作成します。（どちらもKiro IDEから生成しています）

validate-semantic-consistency.kiro.hook

{
  "enabled": true,
  "name": "意味的整合性の検証",
  "description": "ドキュメント編集後に意味的整合性を検証します。タイトルと本文の一致、矛盾した記述の有無をチェックします。",
  "version": "1",
  "when": {
    "type": "fileEdited",
    "patterns": [
      "docs/**/*.md"
    ]
  },
  "then": {
    "type": "askAgent",
    "prompt": "編集されたドキュメントについて、以下の意味的整合性を検証してください：\n\n1. タイトルと本文の内容が一致しているか\n2. ドキュメント内に矛盾した記述がないか\n3. メタデータ（title, owner, status, last_reviewed）が正しく保持されているか\n\n問題があれば具体的に指摘し、修正案を提示してください。\n\n詳細なルールは .kiro/rules/ai-validation-rules.md を参照してください。"
  }
}

validate-tone-consistency.kiro.hook

{
  "enabled": true,
  "name": "文体一貫性の検証",
  "description": "ドキュメント編集後に文体の一貫性を検証します。敬体と常体の混在をチェックします。",
  "version": "1",
  "when": {
    "type": "fileEdited",
    "patterns": [
      "docs/**/*.md"
    ]
  },
  "then": {
    "type": "askAgent",
    "prompt": "編集されたドキュメントについて、以下の文体一貫性を検証してください：\n\n1. 敬体（です・ます）と常体（だ・である）が混在していないか\n2. 両方が3箇所以上ある場合は混在と判定\n3. コードブロック内は除外\n\n問題があれば具体的に指摘し、統一された文体に修正してください。\n\n詳細なルールは .kiro/rules/ai-validation-rules.md を参照してください。"
  }
}

今回は、ドキュメントの意味的整合性と文体一貫性をチェックする２つのフックを用意しました。それぞれの細かいルールはフックに直接定義せずに、.kiro/rules配下のMarkdownに記載しています。

セットアップ② Gitフック

次は機械的なチェックを担うGitフックのセットアップを行います。

ドキュメントの正常な状態の定義

まず最初に、「ドキュメントがどういった状態であれば適切にメンテナンスされている状態とみなすか」を判断するための基準を決めます。

今回の検証では、以下を正式仕様の条件としました。

①ドキュメントに以下のメタデータが記録されていること
　☑️ title
　☑️ owner
　☑️ status
　☑️ last_reviewed

② ドキュメントのステータスが"approved"であること

③ ドキュメントの最終更新日が一定の期限内であること(Ex. 半年以内)

このように定義を決めることで、何をもってドキュメントが正常に管理されている状態であるかを機械的に判定できるようになります。

Gitフックの設定

Gitコミット時に自動的にバリデーターを実行することで、ドキュメントが正式仕様であるかを判定します。.git/hooks/pre-commit として以下のように設定します。

#!/bin/bash
# Git pre-commit hook for documentation validation

# ステージされた Markdown ファイルを取得（.kiro/ 配下を除外）
STAGED_MD_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.md$' | grep -v '^\.kiro/')
if [ -z "$STAGED_MD_FILES" ]; then
  exit 0
fi

echo "🔍 Validating documentation metadata..."

# 各ファイルを検証
for file in $STAGED_MD_FILES; do
  python3 tools/validate_docs.py "$file"
  if [ $? -ne 0 ]; then
    echo "❌ Validation failed for: $file"
    echo "Please fix the issues before committing."
    exit 1
  fi
done

echo "✅ All documents validated successfully"
exit 0

バリデーターの実装

次に、決定した正式定義であるかを検証するためのバリデーターを、スクリプトで実装します。

import datetime
import pathlib
import re
from typing import List
  
import yaml
  
  
DOCS_ROOT = pathlib.Path(__file__).resolve().parents[1] / "docs"
APPROVED_MAX_AGE_DAYS = 180
REQUIRED = ("title", "owner", "status", "last_reviewed")
ALLOWED_OWNERS = {"platform-team", "dev-team", "security-team"}
  
def validate_file(path: pathlib.Path, today: datetime.date) -> List[str]:
    """単一ファイルの検証エラーメッセージ一覧をリターン"""
  
    rel = str(path.relative_to(DOCS_ROOT)) if DOCS_ROOT in path.parents else path.name
    print(f"Validating {rel}...")
    txt = path.read_text(encoding="utf-8")
  
    # YAML フロントマターのインライン解析（以前は _parse_frontmatter）
    m = re.match(r"^---\s*\n(.*?)\n---\s*\n", txt, re.DOTALL)
    data = yaml.safe_load(m.group(1)) or {}
    meta = {str(k): v for k, v in data.items()} if isinstance(data, dict) else {}
  
    errs: List[str] = []
  
    for k in REQUIRED:
        if meta.get(k) is None or str(meta.get(k)).strip() == "":
            errs.append(f"{rel}: 承認済みドキュメントに必須キー '{k}' がありません。")
  
    status = str(meta.get("status", "")).strip().lower()
    if status != "approved":
        errs.append(f"{rel}: status は 'approved' である必要があります（現在: '{status or 'blank'}'）。")
  
    owner = str(meta.get("owner", "")).strip().lower()
    if owner not in ALLOWED_OWNERS: 
        errs.append(f"{rel}: owner は実在の人物またはチームである必要があります（現在: '{owner or 'blank'}'）。")
  
    lr = meta.get("last_reviewed")
    if lr is not None and str(lr).strip() != "":
        try:
            d = datetime.date.fromisoformat(str(lr))
        except Exception:
            errs.append(f"{rel}: last_reviewed の日付形式が無効です: '{lr}'。YYYY-MM-DD を使用してください。")
        else:
            if (today - d).days > APPROVED_MAX_AGE_DAYS:
                errs.append(f"{rel}: ドキュメントが古くなっています（last_reviewed {(today-d).days}日前 > {APPROVED_MAX_AGE_DAYS}日）。")
  
    return errs
  
  
def main() -> int:
    today = datetime.date.today()
  
    errors: List[str] = []
    for p in DOCS_ROOT.rglob("*.md"):
        errors.extend(validate_file(p, today))
  
    if errors:
        print("ドキュメント検証に失敗しました:")
        for e in errors:
            print(f"- {e}")
            return 1
    else:
        print("OK: ドキュメント検証に合格しました。")
        return 0
  
if __name__ == "__main__":
    main()

以上でGitフックの準備は完了です。

セットアップ③MKDocs

まずはインストールです

pip install mkdocs

次にMKDocsの設定ファイルを作成します。シンプルなので、Kiroに指示するとあっという間に出来上がります。

site_name: API Server Spec (PoC)
site_url: http://localhost:8000/
theme:
  name: mkdocs

nav:
  - Home: index.md
  - Overview:
      - API Boundary: 00_overview/api-boundary.md
      - Auth: 00_overview/auth.md
  - API:
      - Endpoints: 10_api/endpoints.md
      - Errors: 10_api/errors.md
  - ADR:
      - ADR-0001 Error Format: 30_adr/adr-0001-error-format.md

plugins:
  - search

以上でセットアップは完了です。

動作を確認してみた

Kiro hooks

実際にMarkdownドキュメントを作成して、動作確認します。

Kiroに指示してドキュメント生成し、フックの発動を確認します。Kiroにドキュメント更新を指示すると、更新後に以下のようにフックによる自動検証がスタートします。

こうやって判定結果がグリーン✅になると安心感がありますね！

kiro/rulesで事前にエージェントの動きを縛るのも有効ですが、重要なのは使い分けです。hookやruleを試しがらブラッシュアップしていきましょう。

git hooks

Kiroのhooksが通ったドキュメントは、次にGitのhooksによってチェックされます。

あえてバリデーションを満たさない状態で、ドキュメントをコミットしてみます。すると以下のようにgit errorが発生してコミットできませんでした。

> git -c user.useConfigOnly=true commit --quiet --allow-empty-message --file -
🔍 Validating documentation metadata...
Validating index.md...
Validating 00_overview/auth.md...
Validating 00_overview/api-boundary.md...
Validating 30_adr/adr-0001-error-format.md...
Validating 10_api/endpoints.md...
Validating 10_api/errors.md...
ドキュメント検証に失敗しました:
- 00_overview/auth.md: 承認済みドキュメントに必須キー 'status' がありません。
- 00_overview/auth.md: status は 'approved' である必要があります（現在: 'none'）。
- 00_overview/api-boundary.md: 承認済みドキュメントに必須キー 'title' がありません。
- 00_overview/api-boundary.md: 承認済みドキュメントに必須キー 'owner' がありません。
- 00_overview/api-boundary.md: 承認済みドキュメントに必須キー 'last_reviewed' がありません。
- 00_overview/api-boundary.md: status は 'approved' である必要があります（現在: 'draft'）。
- 00_overview/api-boundary.md: owner は実在の人物またはチームである必要があります（現在: 'blank'）。
❌ Validation failed for: docs/10_api/errors.md
Please fix the issues before committing.

これによって、最低限ここだけは記入・更新してほしい点を確実に押さえることが可能です。

MKDocs

MKDocsをローカルで起動すると、サイト形式でドキュメントを確認できます。

$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  The following pages exist in the docs
           directory, but are not included in the
           "nav" configuration:
             - test_precommit.md
             - 10_api/register.md
INFO    -  Documentation built in 0.05 seconds
INFO    -  [13:23:50] Serving on
           http://127.0.0.1:8000/

アクセスすると、以下のように表示されました。

ドキュメント全体の検索も可能です。

プレビューでMarkdownを見るのは、個人開発する分には十分です。ですがMKDocsを使うと、手軽にリッチに見えて、チームでのドキュメントをベースとした議論もしやすくなります。

※MKDocsにはプラグインもあるため、カスタマイズ・拡張も可能です。

github.com

まとめ

前回と本記事で、Gitフック、Kiroフックを導入して、ドキュメントで自動で検証する仕組みをご紹介しました。

現状のドキュメンテーションに課題が少なくとも、今後コーディングエージェントの利用が増えることを見据えると、Hooksによる自動検証を設定することで、プロジェクトのDocs運用の効率と品質を両立する手助けになりそうです。

まずはKiroのHooks機能を使用してドキュメントの品質をチェックすることから導入しましょう。 そこからより高品質・高効率なドキュメントを目指す場合や、ドキュメンテーション文化をチームに醸成したい場合には、Gitフック・バリデーターやMKDocsを追加で導入するのがおすすめです。

以上です。皆さまも快適なAIコーディングとドキュメンテーションを！！



以上の内容はhttps://techblog.forgevision.com/entry/2026/03/12/134635より取得しました。
このページはhttp://font.textar.tv/のウェブフォントを使用してます
不具合報告/要望等はこちらへお願いします。
モバイルやる夫Viewer Ver0.14