documentation-audit

ドキュメント監査

概要

ドリフトが検出された場合に、ドキュメントを包括的に同期します。コードベースを分析し、すべてのドキュメント成果物を作成または更新して、完全な同期を実現します。

基本原則： ドキュメントは実態を反映していなければなりません。このスキルは両者の整合性を保ちます。

開始時に通知： 「documentation-audit を使用して、すべてのドキュメントを現在のコードベースと同期します。」

このスキルが呼び出される条件

次の場合に、このスキルが呼び出されます。

トリガー	ソース
API ドキュメントのドリフト	api-documentation スキル
機能ドキュメントのドリフト	features-documentation スキル
ドキュメントファイルの不足	すべてのドキュメントチェック
手動リクエスト	ユーザーまたはオーケストレーター

監査プロセス

フェーズ 1：検出

echo "=== Documentation Audit: Discovery Phase ==="

# Find all documentation files
DOC_FILES=$(find . -name "*.md" -o -name "*.yaml" -o -name "*.json" | \
  grep -E "(doc|api|swagger|openapi|feature|guide|readme)" | \
  grep -v node_modules | grep -v .git)

echo "Found documentation files:"
echo "$DOC_FILES"

# Find API documentation
API_DOC=$(find . -name "openapi.yaml" -o -name "swagger.yaml" -o -name "openapi.json" | head -1)
echo "API Documentation: ${API_DOC:-MISSING}"

# Find features documentation
FEATURE_DOC=$(find . -name "features.md" -o -name "FEATURES.md" | head -1)
echo "Features Documentation: ${FEATURE_DOC:-MISSING}"

フェーズ 2：API 監査

API エンドポイントが存在する場合：

echo "=== Documentation Audit: API Phase ==="

# Detect API framework
detect_api_framework() {
  if grep -r "express" package.json 2>/dev/null; then echo "express"; return; fi
  if grep -r "fastify" package.json 2>/dev/null; then echo "fastify"; return; fi
  if grep -r "@nestjs" package.json 2>/dev/null; then echo "nestjs"; return; fi
  if grep -r "fastapi" requirements.txt 2>/dev/null; then echo "fastapi"; return; fi
  if grep -r "flask" requirements.txt 2>/dev/null; then echo "flask"; return; fi
  if [ -f "go.mod" ]; then echo "go"; return; fi
  echo "unknown"
}

FRAMEWORK=$(detect_api_framework)
echo "Detected framework: $FRAMEWORK"

# Extract all endpoints from code
extract_endpoints() {
  case "$FRAMEWORK" in
    express|fastify)
      grep -rh "app\.\(get\|post\|put\|delete\|patch\)" --include="*.ts" --include="*.js" | \
        sed "s/.*app\.\([a-z]*\)('\([^']*\)'.*/\1 \2/"
      ;;
    nestjs)
      grep -rh "@\(Get\|Post\|Put\|Delete\|Patch\)" --include="*.ts" | \
        sed "s/.*@\([A-Za-z]*\)('\([^']*\)'.*/\1 \2/"
      ;;
    fastapi)
      grep -rh "@app\.\(get\|post\|put\|delete\|patch\)" --include="*.py" | \
        sed "s/.*@app\.\([a-z]*\)(\"\([^\"]*\)\".*/\1 \2/"
      ;;
    *)
      echo "Unknown framework - manual inspection required"
      ;;
  esac
}

ENDPOINTS=$(extract_endpoints)
echo "Found endpoints:"
echo "$ENDPOINTS"

フェーズ 3：機能監査

echo "=== Documentation Audit: Features Phase ==="

# Find user-facing components
find_features() {
  # React components in pages/views
  find . -path "*/pages/*" -name "*.tsx" -o -path "*/views/*" -name "*.tsx" | \
    xargs -I {} basename {} .tsx 2>/dev/null

  # Feature flags
  grep -rh "featureFlag\|feature:" --include="*.ts" --include="*.tsx" | \
    sed "s/.*['\"]feature[':]\s*['\"]?\([^'\"]*\)['\"]?.*/\1/" 2>/dev/null

  # Config options exposed to users
  grep -rh "config\.\|settings\." --include="*.ts" | \
    grep -v "import\|require" | \
    sed "s/.*\(config\|settings\)\.\([a-zA-Z]*\).*/\2/" 2>/dev/null | sort -u
}

FEATURES=$(find_features)
echo "Discovered features:"
echo "$FEATURES"

フェーズ 4：不足しているドキュメントの生成

OpenAPI が存在しない場合に作成

# Template for new OpenAPI file
openapi: 3.0.3
info:
  title: [PROJECT_NAME] API
  description: |
    API documentation for [PROJECT_NAME].
    Generated by documentation-audit skill.
  version: 1.0.0
  contact:
    name: API Support
servers:
  - url: http://localhost:3000
    description: Development server
  - url: https://api.example.com
    description: Production server
paths:
  # Endpoints will be added here
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

機能ドキュメントが存在しない場合に作成

# Features

> Generated by documentation-audit skill. Update with accurate descriptions.

## Overview

[Brief description of the product]

## Core Features

### [Feature 1]

**Description:** [What it does]

**How to Use:**
1. [Step 1]
2. [Step 2]

---

## Additional Features

[List additional features discovered]

---

*Last updated: [DATE]*
*Note: This file was auto-generated. Review and enhance descriptions.*

フェーズ 5：既存ドキュメントの更新

検出された項目のうち、ドキュメント化されていないものについて、以下を行います。

1. API エンドポイント - OpenAPI 仕様に以下を追加します。

   • パスとメソッド
   • パラメーター（関数シグネチャから取得）
   • リクエストボディのスキーマ（DTO／型から取得）
   • レスポンスのスキーマ（戻り値の型から取得）
   • 基本的な説明

2. 機能 - 機能ドキュメントに以下を追加します。

   • 機能名
   • 基本的な説明
   • 使用方法のプレースホルダー
   • レビューと拡充が必要である旨の注記

フェーズ 6：検証

echo "=== Documentation Audit: Validation Phase ==="

# Validate OpenAPI
if [ -f "openapi.yaml" ]; then
  yq '.' openapi.yaml > /dev/null 2>&1 && echo "OpenAPI: Valid YAML" || echo "OpenAPI: Invalid YAML"
fi

# Validate Markdown
for file in docs/*.md; do
  if [ -f "$file" ]; then
    # Check for required sections
    if ! grep -q "^## " "$file"; then
      echo "WARNING: $file missing section headers"
    fi
  fi
done

# Check completeness
ENDPOINTS_DOCUMENTED=$(yq '.paths | keys | length' openapi.yaml 2>/dev/null || echo 0)
ENDPOINTS_IN_CODE=$(extract_endpoints | wc -l)

echo "Endpoints in code: $ENDPOINTS_IN_CODE"
echo "Endpoints documented: $ENDPOINTS_DOCUMENTED"

if [ "$ENDPOINTS_DOCUMENTED" -lt "$ENDPOINTS_IN_CODE" ]; then
  echo "WARNING: Some endpoints still undocumented"
fi

監査レポート

監査結果を GitHub Issue に投稿します。

## Documentation Audit Complete

**Audit Date:** [ISO_TIMESTAMP]
**Triggered By:** [api-documentation|features-documentation|manual]

### Summary

| Category | Before | After | Status |
|----------|--------|-------|--------|
| API Endpoints | [N] undocumented | [N] documented | [COMPLETE/PARTIAL] |
| Features | [N] undocumented | [N] documented | [COMPLETE/PARTIAL] |
| General Docs | [N] missing | [N] created | [COMPLETE/PARTIAL] |

### Files Created
- `openapi.yaml` - API documentation
- `docs/features.md` - Features documentation

### Files Updated
- `openapi.yaml` - Added [N] endpoints
- `docs/features.md` - Added [N] features

### Requires Manual Review
- [ ] Verify API response schemas
- [ ] Enhance feature descriptions
- [ ] Add usage examples
- [ ] Review security documentation

### Next Steps
1. Review generated documentation
2. Add detailed descriptions
3. Include examples
4. Validate with stakeholders

---
*documentation-audit skill completed*

チェックリスト

監査中：

• すべてのドキュメントファイルを検出した
• API フレームワークを検出した
• コードからすべてのエンドポイントを抽出した
• コードからすべての機能を抽出した
• 不足しているドキュメントファイルを作成した
• 既存のドキュメントを更新した
• すべてのファイルを検証した
• 監査レポートを Issue に投稿した
• 変更をコミットした

品質基準

生成されるドキュメントは、以下の基準を満たす必要があります。

基準	要件
網羅性	すべてのエンドポイント／機能が記載されている
妥当性	YAML／JSON の検証に合格する
構造	必須セクションが含まれている
プレースホルダー	手動レビュー用のマーカーが明確である
帰属表示	スキルによる生成であることが記載されている

統合

このスキルは、以下によって呼び出されます。

スキル	タイミング
api-documentation	API のドリフトが検出されたとき
features-documentation	機能のドリフトが検出されたとき
issue-driven-development	ドキュメント作成のステップ

このスキルでは、以下を使用します。

ツール	目的
Glob/Grep	コード成果物を検出する
Read	既存のドキュメントを分析する
Write	新しいドキュメントを作成する
Edit	既存のドキュメントを更新する
yq	YAML を検証する
jq	JSON を検証する