aif-docs

ドキュメント — プロジェクトドキュメント生成ツール

ランディングページとしての README と、詳細なドキュメントディレクトリで構成される形式に従って、プロジェクトドキュメントを生成、維持、改善します。

基本原則

1. README はランディングページであり、マニュアルではありません。 目安は約 80〜120 行です。第一印象、インストール、簡単な例、詳細へのリンクを含めます。
2. 詳細は解決されたドキュメントディレクトリ（paths.docs、デフォルトは docs/）に記載します。各ファイルは自己完結型にし、1 つのトピックを 1 ページで扱います。ユーザーがドキュメントファイルを 1 つ読むだけで、そのトピックの全体像を把握できるようにします。
3. 重複させません。 解決されたドキュメントディレクトリに情報がある場合、README ではそれを繰り返さず、リンクします。例外として、ユーザーは README にあることを期待するため、インストールコマンドは両方に記載できます。
4. ナビゲーション。 解決されたドキュメントディレクトリ内の各ドキュメントファイルには、ドキュメント一覧の順序に従った前後ページへのリンクを含むヘッダー行を設けます：[← Previous Page](prev.md) · [Back to README](<docs-to-readme-link>) · [Next Page →](next.md)。最初のページには前のページへのリンクを設けず、最後のページには次のページへのリンクを設けません。すべてのページの末尾に、関連ページを 2〜3 件リンクする「関連項目」セクションを設けます。
5. 相互リンクには相対パスを使用します。 README からは、解決されたドキュメントディレクトリのパスにリンクします（デフォルトでは docs/workflow.md など）。同じディレクトリにあるドキュメントページ間では、workflow.md を使用します。
6. ざっと読める構成にします。 表、箇条書き、コードブロックを使用します。長い段落は避けます。ユーザーは精読するのではなく、必要な情報を探して読みます。

ワークフロー

Step 0: 設定とプロジェクトコンテキストの読み込み

最初に： .ai-factory/config.yaml が存在する場合は読み込み、以下を確認します。

• パス： paths.description、paths.architecture、paths.docs
• 言語： プロンプトには language.ui、生成ドキュメントには language.artifacts

config.yaml が存在しない場合は、以下のデフォルト値を使用します。

• DESCRIPTION.md：.ai-factory/DESCRIPTION.md
• ARCHITECTURE.md：.ai-factory/ARCHITECTURE.md
• ドキュメントディレクトリ：docs/
• 言語：en（英語）

注： README.md は引き続きプロジェクトルートのランディングページとして使用します。詳細なドキュメントは、解決された paths.docs ディレクトリ（デフォルト：docs/）に作成します。

次に： .ai-factory/DESCRIPTION.md（設定ファイルで指定されたパスを使用）が存在する場合は読み込み、以下を把握します。

• 技術スタック（言語、フレームワーク、データベース）
• プロジェクトの目的とアーキテクチャ
• 主な機能と規約

また、.ai-factory/ARCHITECTURE.md（設定ファイルで指定されたパスを使用）が存在する場合は読み込み、ドキュメントをプロジェクトの構造と境界に沿ったものにします。

コードベースを調査します。

• package.json、composer.json、requirements.txt、go.mod、Cargo.toml などを読み込みます。
• src/ の構造を調べて、アーキテクチャを把握します。
• 既存のドキュメント、コメント、API エンドポイント、CLI コマンドを確認します。
• 既存の README.md と、解決されたドキュメントディレクトリを確認します。

.ai-factory/skill-context/aif-docs/SKILL.md を読み込みます — ファイルが存在する場合は必須です。

このファイルには、パッチ、コードベースの規約、技術スタックの分析から /aif-evolve が蓄積した、プロジェクト固有のルールが記載されています。これらのルールは現在のプロジェクトに合わせたものです。

skill-context ルールの適用方法：

• このスキルの一般的な指示に対するプロジェクトレベルの上書きルールとして扱います。
• skill-context ルールがこの SKILL.md に記載された一般ルールと競合する場合は、skill-context ルールを優先します（より具体的なコンテキストが優先されます。ネストされた CLAUDE.md ファイルと同じ原則です）。
• 競合しない場合は、SKILL.md の一般ルールと skill-context のプロジェクトルールの両方を適用します。
• skill-context ルールがこのスキルのデフォルトと矛盾しているように見えても、無視しないでください。プロジェクトでの経験から、デフォルトでは不十分だと判明したために存在しています。
• 重要： skill-context ルールは、README.md、ドキュメントページ、およびそれらのテンプレートを含む、このスキルのすべての出力に適用されます。この SKILL.md のテンプレートは基本構造です。skill-context ルールに「ドキュメントには X を必ず含めること」や「README にはセクション Y が必要」とある場合は、それに従ってテンプレートを拡張する必要があります。skill-context ルールに違反するドキュメントを生成することはバグです。

遵守の確認： 出力成果物を生成したら、すべての skill-context ルールに照らして確認します。ルール違反がある場合は、ユーザーに提示する前に出力を修正します。

プロジェクトルートに散在する Markdown ファイルを調べます。

Glob を使用して、プロジェクトルートにあるすべての *.md ファイルを検索します（node_modules/、.ai-factory/、エージェントのディレクトリは除外します）。

CHANGELOG.md, CONTRIBUTING.md, ARCHITECTURE.md, DEPLOYMENT.md,
SECURITY.md, API.md, SETUP.md, DEVELOPMENT.md, TESTING.md, etc.

各ファイル、そのサイズ、内容の簡単な概要を記録します。この一覧はステップ 1.1 で使用します。

Step 0.1: フラグの解析

--web  → Generate HTML version of documentation

Step 1: 現在の状態を確認

既存のドキュメントを確認します。

State A: No README.md                        → Full generation (README + docs dir)
State B: README.md exists, no docs dir      → Analyze README, propose split into docs dir
State C: README.md + docs dir exist         → Depends on flags (see below)

--web フラグがある状態 C の場合 — ユーザーに尋ねます：

Documentation already exists (README.md + resolved docs directory).

AskUserQuestion: What would you like to do?

Options:
1. Generate HTML only — build site from current docs as-is
2. Audit & improve first — check for issues, then generate HTML
3. Audit only — check for issues without generating HTML

選択に応じて：

• HTML のみ生成 → ステップ 1.1、ステップ 2、ステップ 4 をスキップし、ステップ 3（HTML の生成）に進んで完了します
• 最初に監査と改善を実施 → ステップ 1.1 → ステップ 2（状態 C）→ ステップ 3 → ステップ 4 → ステップ 4.1 を実行します
• 監査のみ → ステップ 1.1 → ステップ 2（状態 C）→ ステップ 4 → ステップ 4.1 を実行します（ステップ 3 はスキップします）

--web フラグがない状態 C の場合 → 通常どおりステップ 2（状態 C）を実行します。

ステップ 1.1：散在している Markdown ファイルを確認する

プロジェクトのルートに散在している .md ファイルが見つかった場合（ステップ 0 で確認）、解決済みの docs ディレクトリにまとめることを提案します。

解決済みの docs ディレクトリに移動すべき一般的なファイル：

ルートのファイル	docs ディレクトリ内の移動先	統合または移動
CONTRIBUTING.md	<resolved docs dir>/contributing.md	移動
ARCHITECTURE.md	<resolved docs dir>/architecture.md	移動
DEPLOYMENT.md	<resolved docs dir>/deployment.md	移動
SETUP.md	<resolved docs dir>/getting-started.md	統合（既存の内容に追記）
DEVELOPMENT.md	<resolved docs dir>/getting-started.md または <resolved docs dir>/contributing.md	統合
API.md	<resolved docs dir>/api.md	移動
TESTING.md	<resolved docs dir>/testing.md	移動
SECURITY.md	<resolved docs dir>/security.md	移動

ルートに残すファイル（標準的な慣例）：

• README.md — 常に残します
• CHANGELOG.md — 標準的なルートレベルのファイルです。そのまま残します
• LICENSE / LICENSE.md — 標準的なルートレベルのファイルです。そのまま残します
• CODE_OF_CONDUCT.md — 標準的なルートレベルのファイルです。そのまま残します

散在しているファイルが見つかった場合は、ユーザーに尋ねます：

Found [N] markdown files in the project root:

  CONTRIBUTING.md (45 lines) — contribution guidelines
  ARCHITECTURE.md (120 lines) — system architecture overview
  DEPLOYMENT.md (80 lines) — deployment instructions
  SETUP.md (30 lines) — setup guide (overlaps with getting-started)

Suggested actions:
  → Move CONTRIBUTING.md → <resolved docs dir>/contributing.md
  → Move ARCHITECTURE.md → <resolved docs dir>/architecture.md
  → Move DEPLOYMENT.md → <resolved docs dir>/deployment.md
  → Merge SETUP.md into <resolved docs dir>/getting-started.md

AskUserQuestion: Would you like to apply the consolidation?

Options:
1. Apply all suggestions
2. Let me pick which ones
3. Skip — keep files where they are

選択に応じた対応：

• すべての提案を適用 → リストにあるすべてのファイルを移動／統合し、ステップ 2 に進む
• 対象を選ばせてください → 各ファイルを個別に提示して承認を得て、選択されたものを適用する
• スキップ → ファイルを現在の場所に残し、ステップ 2 に進む

移動／統合する場合：

1. Documentation テーブルの順序に従った前／次のナビゲーションヘッダーと、「See Also」フッターを付けて、解決済みの docs ディレクトリに移動先ファイルを作成する
2. 既存のドキュメントに統合する場合は、新しいセクション見出しの下に内容を追記し、すでに記載されている情報との重複を避ける
3. 元のファイルはまだ削除しないでください — レビューの手順で配置を確認するまで残しておきます
4. README の Documentation テーブルに、新しいドキュメントページを README からの相対パスで追加する
5. 古いルートレベルのファイルを参照している他のファイル内のリンクを更新する
6. 移動／統合したファイルを記録する — このリストはステップ 4.1 で使用します

重要： ファイルの移動を強制してはいけません。必ず計画を提示し、事前にユーザーの承認を得てください。

ステップ 2（状態 A）：ゼロから生成する

README.md が存在しない場合は、ドキュメント一式を生成します。

2.1：ドキュメントのトピックを特定するためにプロジェクトを分析する

コードベースを調査し、ドキュメントのトピックを特定します：

Always include:
- getting-started.md    (installation, setup, quick start)

Include if relevant:
- architecture.md       (if project has clear architecture: services, modules, layers)
- api.md                (if project exposes API endpoints)
- configuration.md      (if project has config files, env vars, feature flags)
- deployment.md         (if Dockerfile, CI/CD, deploy scripts exist)
- contributing.md       (if open-source or team project)
- security.md           (if auth, permissions, or security patterns exist)
- testing.md            (if test suite exists)
- cli.md                (if project has CLI commands)

ユーザーに尋ねます：

I've analyzed your project and suggest these documentation pages:

1. getting-started.md — Installation, setup, quick start
2. architecture.md — Project structure and patterns
3. api.md — API endpoints reference
4. configuration.md — Environment variables and config

AskUserQuestion: Would you like to generate these documentation pages?

Options:
1. Generate all of these
2. Let me pick which ones
3. Add more topics

選択に応じた対応：

• すべて生成 → README.md と、リストにあるすべてのドキュメントファイルを解決済みの docs ディレクトリに生成する
• 選ばせてください → 各トピックを個別に提示して承認を得て、承認されたものだけを生成する
• トピックを追加 → 追加するトピックを尋ね、最終リストを確認してから生成する

2.2：README.md を生成する

構成（80～120 行程度を目安にします）：

# Project Name

> One-line tagline describing the project.

Brief 2-3 sentence description of what this project does and why it exists.

## Quick Start

\`\`\`bash
# Installation steps (1-3 commands)
\`\`\`

## Key Features

- **Feature 1** — brief description
- **Feature 2** — brief description
- **Feature 3** — brief description

## Example

\`\`\`
# Show a real usage example — this is where users decide "I want this"
\`\`\`

---

## Documentation

| Guide | Description |
|-------|-------------|
| [Getting Started](<readme-to-docs-dir>/getting-started.md) | Installation, setup, first steps |
| [Architecture](<readme-to-docs-dir>/architecture.md) | Project structure and patterns |
| [API Reference](<readme-to-docs-dir>/api.md) | Endpoints, request/response formats |
| [Configuration](<readme-to-docs-dir>/configuration.md) | Environment variables, config files |

## License

MIT (or whatever is in the project)

README の主なルール：

• プロジェクトにロゴやバッジがある場合は、先頭に配置する
• タグラインは引用として記載する
• クイックスタートには実際のインストールコマンドを記載する（パッケージマネージャーから判定）
• 主な機能を箇条書きにする（3～6 項目。ひと目でわかるようにする）
• 「すごさ」が伝わる実際の使用例を記載する
• 解決済みの docs ディレクトリへのリンクを含む Documentation テーブルを記載する
• 最下部にライセンスを記載する
• 長い説明、完全な API リファレンス、設定の詳細は記載しない

2.3: 解決済みの docs ディレクトリにドキュメントファイルを生成する

承認されたトピックごとに、ドキュメントファイルを作成します。

[← Previous Topic](previous-topic.md) · [Back to README](<docs-to-readme-link>) · [Next Topic →](next-topic.md)

# Topic Title

Content organized by subtopic with headers, code examples, and tables.
Keep each section self-contained.

## See Also

- [Related Topic 1](related-topic.md) — brief description
- [Related Topic 2](other-topic.md) — brief description

ナビゲーションリンクの順序は、README.md の Documentation テーブル（上から下）の順序に従います。最初のドキュメントページでは「← Previous」リンクを省略し、最後のページでは「Next →」リンクを省略します。解決済みの docs ディレクトリから README.md への正しい相対リンクを使用してください。デフォルトの docs/ レイアウトの例：

getting-started.md:  [Back to README](../README.md) · [Architecture →](architecture.md)
architecture.md:     [← Getting Started](getting-started.md) · [Back to README](../README.md) · [API Reference →](api.md)
api.md:              [← Architecture](architecture.md) · [Back to README](../README.md) · [Configuration →](configuration.md)
configuration.md:    [← API Reference](api.md) · [Back to README](../README.md)

トピックごとのコンテンツガイドライン：

getting-started.md：

• 前提条件（必要なランタイムのバージョン、ツール）
• インストール手順
• 初回実行／クイックスタート
• 動作確認（想定される出力）
• 次のステップへのリンク

architecture.md：

• 概要（必要に応じて図を使用）
• ディレクトリ構成と説明
• 主要なパターン（命名規則、インポート、エラー処理）
• データフロー

api.md：

• ベース URL／設定
• 認証
• リソースごとにまとめたエンドポイント
• リクエスト／レスポンスの例
• エラーコード

configuration.md：

• 説明とデフォルト値を含む、すべての環境変数
• 設定ファイルとその用途
• 機能フラグ

deployment.md：

• ビルド手順
• 環境設定
• CI/CD パイプラインの説明
• モニタリング／ヘルスチェック

ステップ 2（状態 B）：既存の README を解決済みの docs ディレクトリに分割する

README.md が存在するものの長く（150 行以上）、解決済みの docs ディレクトリがまだない場合です。

2.1: README の構成を分析する

README.md を読み、次を特定します。

• どのセクションを残すか（ランディングページの内容）
• どのセクションを解決済みの docs ディレクトリに移すか（詳細な内容）

README に残す内容：

• タイトル、タグライン、バッジ
• 「Why?」／主な機能の箇条書き
• クイックインストール（1～3 個のコマンド）
• 簡潔な例
• Documentation リンクテーブル
• 外部リンク、ライセンス

解決済みの docs ディレクトリに移す内容：

• 詳細なセットアップ手順 → getting-started.md
• アーキテクチャ／プロジェクト構成 → architecture.md
• API リファレンス全体 → api.md
• 設定の詳細 → configuration.md
• コントリビューションガイドライン → contributing.md
• 1 つのトピックを扱う約 30 行を超えるセクション

2.2: ユーザーに変更を提案する

Your README.md is [N] lines. I suggest splitting it:

README.md (~100 lines) — keep as landing page:
  ✓ Title + tagline
  ✓ Key features
  ✓ Quick install
  ✓ Example
  ✓ Documentation links table

Move to docs dir:
  → "Installation" section → <resolved docs dir>/getting-started.md
  → "Configuration" section → <resolved docs dir>/configuration.md
  → "API Reference" section → <resolved docs dir>/api.md
  → "Architecture" section → <resolved docs dir>/architecture.md

Proceed?

2.3: 分割を実行する

1. 解決済みの docs ディレクトリを作成します
2. README の内容に、前／次のナビゲーションヘッダー（Documentation テーブルの順序に従う）と「See Also」フッターを付けて、各ドキュメントファイルを作成します
3. README を Documentation リンクテーブル付きのランディングページに書き換えます
4. コンテンツが失われていないことを確認します — 古い README のすべてのセクションが、いずれかの場所に存在する必要があります

ステップ 2（状態 C）：既存のドキュメントを改善する

README.md と解決済みの docs ディレクトリの両方が存在する場合です。

2.1: 現在のドキュメントを監査する

次を確認します。

• README の長さ — ランディングページのままですか（150 行未満）？
• 不足しているトピック — プロジェクトに、まだドキュメント化されていない側面はありますか？
• 古くなった内容 — ドキュメントが、存在しなくなったファイル／API を参照していませんか？
• ナビゲーション — すべてのドキュメントに前／次のヘッダーリンクと「See Also」がありますか？
• リンク切れ — すべての内部リンクが、存在するファイル／アンカーを指していることを確認します
• 一貫性 — すべてのドキュメントで書式スタイルが統一されていますか？
• 標準への準拠 — 既存のドキュメントは現在のスキル標準に準拠していますか？（2.1.1 を参照）

2.1.1: 標準への準拠チェック

現在の Core Principles に照らして既存のドキュメントを確認し、不足箇所（ナビゲーションの不足、「See Also」の不足、古い形式など）を特定します。準拠状況の全表と自動修正ルールについては、references/REVIEW-CHECKLISTS.md の「Standards Compliance」セクションを読みます。

不足箇所が見つかった場合は、内容に関する問題と合わせて監査レポートに含めます（ステップ 2.2）。通常の改善として扱い、適用前に計画を提示してユーザーの承認を得ます。

2.2: 改善を提案する

Documentation audit results:

✅ README is lean (105 lines)
⚠️  Docs pages in the resolved docs directory are missing prev/next navigation — will add
⚠️  <resolved docs dir>/api.md is missing — project has 12 API endpoints
⚠️  <resolved docs dir>/configuration.md references old env var DB_HOST (now DATABASE_URL)
❌ <resolved docs dir>/getting-started.md links to setup.md which doesn't exist

Proposed fixes:
1. Add prev/next navigation to all doc pages in the resolved docs directory
2. Create <resolved docs dir>/api.md with endpoint reference
3. Update DATABASE_URL in <resolved docs dir>/configuration.md
4. Fix broken link in <resolved docs dir>/getting-started.md

Apply fixes?

ステップ 3：HTML 版を生成する（--web フラグ）

--web フラグが渡された場合は、Markdown ドキュメントから静的 HTML サイトを生成します。

3.1: docs-html/ ディレクトリを作成する

mkdir -p docs-html

3.2: HTML ファイルを生成する

各 Markdown ファイル（README.md + <resolved docs dir>/*.md）について、HTML 版を生成します:

templates/html-template.html から HTML テンプレートを読み込み、各ページに使用します。 カスタマイズ: {page_title}、{project_name}、{nav_links}、{content}。

3.3: Markdown を HTML に変換する

各ドキュメントファイルについて: Markdown を解析 → HTML 要素に変換 → .md リンクを .html に修正 → ナビゲーションバーを生成 → docs-html/ に書き込みます。

ファイルマッピング: README.md → index.html、<resolved docs dir>/*.md → *.html。

3.4: 結果を出力する

生成されたファイルのツリーと open docs-html/index.html のヒントを表示します。

Step 4: ドキュメントレビュー

コンテンツ変更後は必須（生成、分割、改善、ファイル統合）。このステップをスキップしないでください。

このステップをスキップするのは、「HTML のみ生成」が選択された場合のみです — コンテンツは変更されておらず、レビューするものはありません。

生成・変更されたすべてのファイルを読み込み、references/REVIEW-CHECKLISTS.md の両方のチェックリストに照らして評価します。2 つのチェックリスト: 技術的正確性 と 可読性と完全性。

見つかった問題は、ユーザーに結果を提示する前に修正してください。結果は、項目ごとに ✅/❌/⚠️ のステータスを付けたコンパクトな表として表示します。

Step 4.1: 移動されたファイルのクリーンアップ

Step 1.1 でファイルがルートから docs/ に移動・統合された場合のみ。

レビューで、すべてのコンテンツが docs/ に正しく配置されていることが確認された後、元のルートレベルのファイルを削除することを提案します:

The following root files have been incorporated into docs/:

  CONTRIBUTING.md → now in docs/contributing.md
  ARCHITECTURE.md → now in docs/architecture.md
  DEPLOYMENT.md → now in docs/deployment.md
  SETUP.md → merged into docs/getting-started.md

AskUserQuestion: These originals are no longer needed. Delete them?

Options:
1. Yes, delete all originals
2. Let me pick which ones to delete
3. No, keep them (I'll clean up later)

選択に基づいて:

• はい、すべて削除 → リストされた元のファイルをすべて削除（以下の「削除する場合」を参照）
• 選択させて → 各ファイルを個別に提示し、承認されたものだけを削除
• いいえ、保持する → 元のファイルをそのままにして、Step 5 に進む

削除する場合:

1. 対象の docs/ ファイルに元のファイルのすべてのコンテンツが含まれていることをもう一度確認する
2. ルートファイルを削除する
3. git status を実行して削除されたものを表示する — 必要であればユーザーは git checkout で復元できます

自動削除はしないでください。 常に確認してください。ユーザーは参照や差分比較のために元のファイルを一時的に保持したい場合があります。

Step 5: AGENTS.md を更新する

ドキュメント変更後は必ず、AGENTS.md の Documentation セクションを更新します（ファイルが存在する場合）。

AGENTS.md を読み込み、## Documentation セクションを見つけます。すべてのドキュメントファイルの現在の状態を反映するように更新します:

## Documentation
| Document | Path | Description |
|----------|------|-------------|
| README | README.md | Project landing page |
| Getting Started | `<resolved docs dir>/getting-started.md` | Installation, setup, first steps |
| Architecture | `<resolved docs dir>/architecture.md` | Project structure and patterns |
| API Reference | `<resolved docs dir>/api.md` | Endpoints, request/response formats |
| Configuration | `<resolved docs dir>/configuration.md` | Environment variables, config files |

ルール:

• README.md を最初にリストし、次に解決された docs ディレクトリ内のすべてのドキュメントファイルを、README の Documentation テーブルと同じ順序でリストする
• Step 1.1 でファイルがルートから移動・統合された場合は、新しい場所を反映する
• 新しいドキュメントページが作成された場合は、それらを追加する
• ドキュメントページが削除された場合は、それらを削除する
• 説明は簡潔に保つ（10 語以内）
• AGENTS.md が存在しない場合は、このステップを黙ってスキップする

コンテキストのクリーンアップ

必要に応じて、コンテキストスペースを解放することをユーザーに提案します: /clear（完全リセット）または /compact（履歴を圧縮）。

成果物の所有権

• 主な所有権: README.md、<resolved docs dir>/*、および AGENTS.md の Documentation セクション。
• 設定の使用: config.yaml は paths.description、paths.architecture、paths.docs、language.ui、language.artifacts を解決します。
• 読み取り専用のコンテキスト: .ai-factory/DESCRIPTION.md、.ai-factory/ARCHITECTURE.md、ロードマップ／ルール／リサーチの成果物。ただしユーザーが明示的により広範な編集を求めた場合を除きます。

重要なルール

1. 変更を加える前に必ず確認する — 既存のドキュメントに対しては、まず計画を提示する
2. コンテンツを削除しない — 別の場所に移動せずに削除してはいけません
3. 実際のプロジェクト情報を検出する — 機能をでっち上げず、package.json／設定ファイルを読む
4. プロジェクトの言語を使用する — プロジェクトの README がロシア語であれば、ドキュメントもロシア語で書く
5. 既存のバッジ／ロゴを保持する — 再構築中にそれらを削除しない
6. .gitignore に追加する — HTML を生成する場合は、docs-html/ を .gitignore に追加する
7. 所有権の境界 — このコマンドはドキュメント成果物（README.md、<resolved docs dir>/*、および AGENTS.md の Documentation セクション）を所有し、設定から解決されるロードマップ、RULES.md、リサーチ成果物は所有しません