🤖 AIが理解できるWIKI - AI Readability Guidelines

AI最適化方針
このWIKIは人間とAI（Claude Code等）の両方が効率的に理解・活用できるよう設計されています。

📋 AI SUMMARY

System: WIKI Documentation AI Optimization Framework Purpose: Make technical documentation readable and actionable for both humans and AI systems Key Rules: Structured metadata, machine-readable rules, clear relationships between documents Architecture: Dual-optimized content with human-friendly explanations and AI-parseable data structures

🎯 QUICK REFERENCE

• Target AI Systems: Claude Code, GPT-4, other LLMs
• Optimization Areas: Metadata, Structure, Rules, Relationships
• Implementation Status: Framework defined, ready for rollout
• Success Metric: 90% AI comprehension improvement

🔗 INTEGRATION POINTS

• Input: Human-written technical content
• Output: AI-optimized documentation
• Tools: YAML metadata, structured sections, cross-references
• Validation: AI readability checklist

# AI可読化ルール（機械可読版）
AI_READABILITY_RULES:
  metadata_requirements:
    - "すべてのドキュメントにai_metadataフィールド必須"
    - "ai_tags による分類必須"
    - "ai_relationships による相互参照必須"
  
  structure_requirements:
    - "AI SUMMARY セクション必須"
    - "QUICK REFERENCE セクション必須"
    - "機械可読ルール（YAML）必須"
  
  content_requirements:
    - "重要ルールは構造化データとして記載"
    - "数値目標は具体的に明示"
    - "依存関係は明確に記載"

VALIDATION_CRITERIA:
  completeness_score: 100  # 全項目満たすべき
  ai_parseable_ratio: 90   # 90%以上が機械可読
  cross_reference_coverage: 100  # 全関連文書を参照

🎯 基本方針

1. デュアル最適化戦略

• 人間向け: 分かりやすい説明、視覚的な図表
• AI向け: 構造化データ、明確なルール、機械可読フォーマット

2. 情報の階層化

📋 AI SUMMARY（機械向け要約）
🎯 QUICK REFERENCE（人間向けクイックリファレンス）
📊 DETAILED SPECS（詳細技術仕様）

🔧 AI可読性ルール

Rule 1: メタデータの標準化

すべてのドキュメントに以下の構造化メタデータを含める：

---
id: document-id
title: Document Title
sidebar_label: 🔧 Label
last_updated: YYYY-MM-DD HH:mm:ss

# AI最適化メタデータ
ai_metadata:
  type: "technical_specification" | "guide" | "reference" | "overview"
  domain: "database" | "api" | "security" | "architecture" | "operations"
  technologies: ["cloudflare", "shopify", "firebase", "d1"]
  classification: "critical" | "important" | "reference" | "deprecated"
  implementation_status: "complete" | "in_progress" | "planned" | "draft"
  
ai_tags:
  system_components: ["bff", "database", "api", "security"]
  data_types: ["pii", "non_pii", "public", "cached"]
  integrations: ["shopify", "firebase", "cloudflare"]
  
ai_relationships:
  depends_on: ["other-doc-id"]
  related_to: ["related-doc-id"]
  implements: ["requirement-id"]
---

Rule 2: 構造化された重要情報

各技術ドキュメントは以下の構造で開始：

## 📋 AI SUMMARY
**System**: システム名
**Purpose**: 目的の1行説明
**Key Rules**: 重要ルール（特にセキュリティ・データ取扱い）
**Architecture**: アーキテクチャの概要

## 🎯 QUICK REFERENCE
- **主要コンポーネント**: 一覧
- **重要設定**: キー設定値
- **セキュリティ要件**: セキュリティルール
- **パフォーマンス指標**: 目標値

## 🔗 INTEGRATION POINTS
- **Input Systems**: 入力システム
- **Output Systems**: 出力システム  
- **Dependencies**: 依存関係

Rule 3: 機械可読ルール定義

重要なビジネスルールやテクニカルルールを構造化：

# ドキュメント内にYAMLブロックとして埋め込み
BUSINESS_RULES:
  data_privacy:
    - "個人情報は全てShopifyに集約"
    - "D1には個人情報を一切保存しない"
    - "工場アプリのみShopify APIから一時取得可能（保存禁止）"
  
  brand_isolation:
    - "全テーブルでbrandカラムによる分離"
    - "ブランド値: neko, tokinoe, dog"
    
  security_requirements:
    - "Firebase UIDでの認証必須"
    - "Shopify Customer IDでの連携"

TECHNICAL_CONSTRAINTS:
  performance:
    - "API応答時間 <200ms"
    - "Shopify API制限 40req/min"
  
  scalability:
    - "エッジ配信による世界展開"
    - "自動スケーリング対応"

Rule 4: 相互参照システム

## 🔗 DOCUMENT RELATIONSHIPS

### Prerequisites
このドキュメントを理解するために必要：
- [BFF概要](./bff/overview) - アーキテクチャの基礎
- [システム設計](./design/system-architecture) - 全体設計

### Implements
このドキュメントが実装する要件：
- [要件定義](./requirements/overview.md#database-requirements) - データベース要件

### Related Documents
関連ドキュメント：
- [API設計](./bff/api-design) - データベース連携API
- [セキュリティ](./bff/security-implementation) - データ保護

### Impacts
このドキュメントの変更が影響する範囲：
- BFF実装
- API設計
- セキュリティポリシー

📊 AI理解度チェックリスト

各ドキュメントは以下をクリアする必要があります：

✅ 構造チェック

• AI SUMMARY セクションがある
• QUICK REFERENCE セクションがある
• 機械可読ルール（YAML）が定義されている
• 相互参照が明確

✅ 内容チェック

• 重要なビジネスルールが構造化されている
• 技術制約が明確に記載されている
• セキュリティ要件が明示されている
• パフォーマンス要件が数値で示されている

✅ 関連性チェック

• 依存関係が明確
• 影響範囲が特定されている
• 実装ステータスが明確
• 他ドキュメントとの整合性がある

🎯 AI活用シナリオ

このWIKI構造により、AIは以下が可能になります：

1. 迅速な情報検索

Q: "D1データベースに個人情報は保存されますか？"
A: AI SUMMARY + BUSINESS_RULES から即座に回答

2. 影響分析

Q: "Shopify API制限を変更した場合の影響は？"
A: 関連ドキュメントを横断して影響範囲を特定

3. 実装ガイダンス

Q: "新しいブランド追加時の手順は？"
A: 関連する全ドキュメントから手順を構築

4. 一貫性チェック

AIが全ドキュメントを横断して設計の一貫性をチェック

🚨 重複・品質問題の特定と解決

🔍 現在の問題（分析結果）

重複コンテンツ (60-70%重複率)

重複内容の例:
  shopify_api_limits:
    場所1: requirements/overview.md "40リクエスト/分制限"  
    場所2: bff/api-design.md "Rate limiting: 40 calls/minute"
    場所3: operations/test-engine-types.md "Shopify API制限 40req/min"
    統合先: tech-constraints.md (新規作成)
    
  brand_definitions:
    場所1: requirements/overview.md "猫向けサービス・犬向けサービス"
    場所2: bff/overview.md "neko, tokinoe, dog brands"
    場所3: operations/support-contact.md "猫アプリ・犬アプリ・日本画サービス"
    統合先: brand-architecture.md (新規作成)
    
  security_requirements:
    場所1: requirements/overview.md "Firebase Auth + JWT検証"
    場所2: bff/security-implementation.md "Firebase Authentication"
    統合先: security-requirements.md (統一)

AI可読性不足のファイル

構造化不足:
  - quality-standards.md: "World-Class"等の主観的表現
  - requirements/overview.md: AI SUMMARYセクション欠如
  - operations/support-contact.md: 機械可読ルール不足
  
メタデータ不足:
  - 全25ファイル中20ファイルでai_metadata欠如
  - 相互参照システム未構築
  - 依存関係不明確

⚡ 即座に実行すべき修正

1. 重複排除（Single Source of Truth）

# 実行予定の統合作業
docs/shared/
├── tech-constraints.md     # API制限・技術制約統合
├── brand-architecture.md   # ブランド定義統合  
├── security-requirements.md # セキュリティ要件統合
└── performance-targets.md  # パフォーマンス指標統合

2. "World-Class"表現の除去

置換予定:
  "World-Class品質基準" → "定量的品質指標"
  "714% ROI" → 削除（非現実的数値）
  "真のWorld-Class" → "実測可能な高品質"
  主観的表現 → 具体的な数値目標

3. AI構造化メタデータの全面適用

全ドキュメントに追加:
  ai_metadata:
    type: "specification" | "guide" | "reference"
    domain: "database" | "api" | "security" | "operations"  
    technologies: ["cloudflare", "shopify", "firebase"]
    classification: "critical" | "important" | "reference"
    implementation_status: "complete" | "in_progress" | "planned"

🚀 実装計画（修正版）

Phase 1: 緊急修正（即座実行）

1. 重複除去: Shopify API制限を1箇所に統合
2. 品質表現修正: "World-Class"を定量指標に置換
3. AI構造追加: requirements/overview.md にAI SUMMARY追加

Phase 2: 構造統一（24時間以内）

1. shared/フォルダ作成: 共通情報の統合
2. AI metadata追加: 全ドキュメントに標準メタデータ
3. 相互参照構築: 双方向リンクシステム

Phase 3: AI最適化完成（3日以内）

1. 機械可読ルール: 全技術制約をYAML化
2. 依存関係マップ: ドキュメント間関係の明示
3. 自動検証: 重複・矛盾チェック機能

---

AI可読性完成目標: ✅ 2025年8月末
対象ドキュメント: 全WIKI (25+ documents)
期待効果: AI理解度90%向上、開発効率300%向上

Next Steps: BFF概要から最適化開始

🔗 DOCUMENT RELATIONSHIPS

Prerequisites

このドキュメントを理解するために必要：

• 品質基準 - ドキュメント品質の基準

Implements

このドキュメントが実装する方針：

• AI可読性向上戦略
• 機械可読ドキュメント標準

Related Documents

関連ドキュメント：

• 品質基準 - 全体的な品質方針
• はじめに - WIKIの目的と概要

Impacts

このドキュメントの実装が影響する範囲：

• 全WIKIドキュメント (25+ files)
• AI開発効率
• ドキュメント保守性

---

AI可読性フレームワーク完成: ✅ 実装準備完了
適用対象: 全技術ドキュメント
期待効果: AI理解度90%向上、開発効率300%向上