agents-docs-sync 0.2.1

コミットするごとにテスト実行・ドキュメント生成・AGENTS.md の自動更新を行うパイプライン

agents-docs-sync

agents-docs-syncは、Python で実装された CI/CD パイプラインの補助ツールです。
GitHub Actions 等に組み込むことで、コードをコミットするたびに以下が自動的に行われます。

• テスト実行 – pytest（pyproject.toml に uv で管理）とカバレッジ計測 (pytest-cov) を使用してすべてのユニット・統合テストを走らせ、失敗時はビルドを中断します。
• ドキュメント生成 – pyyaml によって YAML で定義されたエージェント構成から Markdown / MkDocs のページを自動作成し、最新の API ドキュメントと設定例を常に同期させます。
• AGENTS.md 自動更新 – プロジェクト内の全てのエージェント定義（agents/*.py, config/**/*.yaml など）から情報を抽出し、概要・使用方法・依存関係をまとめた AGENTS.md を再生成します。
• レポート作成 – テスト結果とカバレッジ統計は GitHub の Actions レポートに添付されるほか、必要に応じて Slack やメールで通知できます。

主なファイル構造

agents-docs-sync/
├─ scripts/          # コマンドラインスクリプト (sync.py, generate_docs.sh)
├─ agents/           # エージェント実装（Python）
├─ config/           # YAML 設定・テンプレート
└─ docs/             # MkDocs / Sphinx 用の静的ファイル生成先

実行方法

# 依存関係をインストール (uv を使用)
uv sync

# 手動で同期実行（CI の代わりにローカルテスト）
uv run scripts/sync.py --all

--all オプションは、全てのステップ（テスト・ドキュメント生成・AGENTS.md 更新）を順次走らせます。
GitHub Actions では actions/setup-python@v5, github/codeql-action/upload-sarif@v1.0.3 等と組み合わせることで、CI パイプラインに簡単に統合できます。

主なメリット

• ドキュメントの整合性維持：コード変更ごとに自動生成されるため、手作業で更新するミスが減ります。
• 品質保証：テスト失敗時は即座にビルドを停止し、デプロイ前に問題点を検出できます。
• 開発者体験向上：AGENTS.md にエージェントの概要と使用例が自動でまとめられるため、新規メンバーも迅速に理解できるようになります。

依存関係

# pyproject.toml (uv)
[tool.uv]
dev-dependencies = [
    "pyyaml>=6.0.3",
    "pytest>=7.4.0",
    "pytest-cov>=4.1.0",
    "pytest-mock>=3.11.1"
]

これらはすべて uv sync で解決され、CI 環境でも同一バージョンが保証されます。

graph TB
    %% Auto-generated architecture diagram

    subgraph agents_docs_sync [fa:fa-python agents-docs-sync]
        direction TB
        subgraph docgen [docgen]
            direction TB
            docgen_collectors["collectors"]:::moduleStyle
            subgraph docgen_utils [utils]
                direction TB
                docgen_utils_llm["llm"]:::moduleStyle
            end
            class docgen_utils moduleStyle
            subgraph docgen_cli [cli]
                direction TB
                docgen_cli_commands["commands"]:::moduleStyle
            end
            class docgen_cli moduleStyle
            docgen_models["models"]:::moduleStyle
            subgraph docgen_archgen [archgen]
                direction TB
                docgen_archgen_detectors["detectors"]:::moduleStyle
                docgen_archgen_generators["generators"]:::moduleStyle
            end
            class docgen_archgen moduleStyle
            docgen_benchmark["benchmark"]:::moduleStyle
            docgen_detectors["detectors"]:::moduleStyle
            subgraph docgen_generators [generators]
                direction TB
                docgen_generators_services["services"]:::moduleStyle
                docgen_generators_parsers["parsers"]:::moduleStyle
            end
            class docgen_generators moduleStyle
            docgen_validators["validators"]:::moduleStyle
            subgraph docgen_rag [rag]
                direction TB
                docgen_rag_strategies["strategies"]:::moduleStyle
            end
            class docgen_rag moduleStyle
            docgen_config["config"]:::moduleStyle
        end
        class docgen moduleStyle
    end

    docgen_collectors --> docgen_models
    docgen_collectors --> docgen_utils
    docgen_utils --> docgen_detectors
    docgen_utils --> docgen_models
    docgen_utils_llm --> docgen_models
    docgen_cli --> docgen_archgen
    docgen_cli --> docgen_generators
    docgen_cli --> docgen_rag
    docgen_cli --> docgen_utils
    docgen_cli_commands --> docgen_rag
    docgen_cli_commands --> docgen_utils
    docgen_archgen --> docgen_detectors
    docgen_archgen --> docgen_generators
    docgen_archgen --> docgen_models
    docgen_archgen --> docgen_utils
    docgen_archgen_detectors --> docgen_models
    docgen_archgen_generators --> docgen_models
    docgen_benchmark --> docgen_models
    docgen_benchmark --> docgen_utils
    docgen_detectors --> docgen_models
    docgen_detectors --> docgen_utils
    docgen_generators --> docgen_archgen
    docgen_generators --> docgen_collectors
    docgen_generators --> docgen_detectors
    docgen_generators --> docgen_models
    docgen_generators --> docgen_utils
    docgen_generators_parsers --> docgen_detectors
    docgen_generators_parsers --> docgen_models
    docgen_generators_parsers --> docgen_utils
    docgen_validators --> docgen_detectors
    docgen_validators --> docgen_generators
    docgen_validators --> docgen_models
    docgen_validators --> docgen_utils
    docgen_rag --> docgen_utils
    docgen_rag_strategies --> docgen_utils

    classDef pythonStyle fill:#3776ab,stroke:#ffd43b,stroke-width:2px,color:#fff
    classDef dockerStyle fill:#2496ed,stroke:#1d63ed,stroke-width:2px,color:#fff
    classDef dbStyle fill:#336791,stroke:#6b9cd6,stroke-width:2px,color:#fff
    classDef moduleStyle fill:#f9f9f9,stroke:#333,stroke-width:2px

Services

agents-docs-sync

• Type: python
• Description: コミットするごとにテスト実行・ドキュメント生成・AGENTS.md の自動更新を行うパイプライン
• Dependencies: anthropic, hnswlib, httpx, jinja2, mypy, openai, outlines, pip-licenses, psutil, pydantic, pytest, pytest-cov, pytest-mock, pyyaml, radon, ruff, sentence-transformers, torch, types-pyyaml

使用技術

• Python
• Shell

依存関係

• Python: pyproject.toml または requirements.txt を参照

セットアップ

前提条件

• Python 3.12以上

インストール

Python

# uvを使用する場合
uv sync

LLM環境のセットアップ

APIを使用する場合

1. APIキーの取得と設定

   • OpenAI APIキーを取得: https://platform.openai.com/api-keys
   • 環境変数に設定: export OPENAI_API_KEY=your-api-key-here

2. API使用時の注意事項

   • APIレート制限に注意してください
   • コスト管理のために使用量を監視してください

ローカルLLMを使用する場合

1. ローカルLLMのインストール

   • Ollamaをインストール: https://ollama.ai/
   • モデルをダウンロード: ollama pull llama3
   • サービスを起動: ollama serve

2. ローカルLLM使用時の注意事項

   • モデルが起動していることを確認してください
   • ローカルリソース（メモリ、CPU）を監視してください

ビルドおよびテスト

ビルド

uv sync
uv build
uv run python3 docgen/docgen.py

テスト

bash scripts/run_tests.sh
uv run pytest tests/ -v --tb=short

コマンド

プロジェクトで利用可能なスクリプト:

コマンド	説明
agents_docs_sync	docgen.docgen:main
agents-docs-sync	docgen.docgen:main

agents_docs_sync のオプション

オプション	説明
--config	設定ファイルのパス
--quiet	詳細メッセージを抑制
--detect-only	言語検出のみ実行
--no-api-doc	APIドキュメントを生成しない
--no-readme	READMEを更新しない
--build-index	RAGインデックスをビルド
--use-rag	RAGを使用してドキュメント生成
--generate-arch	アーキテクチャ図を生成（Mermaid形式）

agents-docs-sync のオプション

オプション	説明
--config	設定ファイルのパス
--quiet	詳細メッセージを抑制
--detect-only	言語検出のみ実行
--no-api-doc	APIドキュメントを生成しない
--no-readme	READMEを更新しない
--build-index	RAGインデックスをビルド
--use-rag	RAGを使用してドキュメント生成
--generate-arch	アーキテクチャ図を生成（Mermaid形式）

---

このREADME.mdは自動生成されています。最終更新: 2025-12-24 16:04:17