はじめに

この記事は 身の回りの困りごとを楽しく解決！ by Works Human Intelligence Advent Calendar 2025 および みすてむずアドベントカレンダー 2枚目 の8日目の記事です。

おハム(この挨拶は、はやらない)
塩ハム(d)です

OSSを作りたかったので作りました(どや)
とはいっても今はやりのバイブコーディングで作ったのでほぼAI製なんですけどね←

バイブコーディングの知見もたまったので後ほどそれについても書きたいと思います(車輪の再々々……々発明)

では作ったものですが、

🎯 解決したかった課題

AGENTS.mdの管理めんどくさくね？
README.mdもめんどk(ry
要はドキュメント更新がめn(ry

これについてはいろいろなプロジェクトに携わってきた皆様の方が詳しいと思います
かつては自動化するにしても、テンプレートマッチングや簡単なドキュメントの自動化しかできなかったのだろうと思いますが

今は我々には つおい(諸説) 味方がおります

そう、生成AIです

🛠 作ったもの（ツール紹介）

ツール名：agents-docs-sync
実行環境（例：Python / uv / LLM API(cloud or local) / git hooksなど）
主な機能
- AGENTS.mdおよびREADME.mdを自動生成
- プロジェクト内の関数を解析し、ベクトルDBに
- ドキュメント生成を Git Hooks に組み込み
- JavaScriptやGo、その他言語にも(一応)対応

🚀 デモ

コマンドで更新する場合

uv run agents_docs_sync

デモ動画

🎨 アーキテクチャ構成

自動生成図です

プロジェクトに取り込むことで、あなたのプロジェクトにも同様のロジックで生成されます(たぶん)

使用技術

ここも自動生成です

言語: python
依存関係: anthropic, hnswlib, httpx, jinja2, openai, outlines, pydantic, pytest, pytest-cov, pytest-mock, pyyaml, ruff, sentence-transformers, torch

🔍 技術的なポイント・こだわり

pythonとシェルスクリプトのみで構成(PYPIで配布、依存関係少)
ドキュメントのテンプレ化(テンプレートはJinja2テンプレートなのでお手入れ可能)
README自動更新、コミット前のテスト、バイブコーディングのドキュメント自動化まで、さまざまな用途に対応可(docgen/config.tomlで設定可能)
テンプレート生成のみの使用も可能(スペックが低くても簡易的な自動化が可能)
ローカルLLMを使用可能(セキュリティを気にする場合でもローカルで完結可能)

🧪 使い方

インストール

pip install agents_docs_sync
# or
uv add agents_docs_sync

初期設定

python3 agents_docs_sync init
# or
uv run agents_docs_sync init

実行方法

python3 agents_docs_sync
# or
uv run agents_docs_sync

git hooksを有効化する場合

# pre-commitで同様に生成されコミット前にステージングされるように
python3 agents_docs_sync hooks enable
# or
uv run agents_docs_sync hooks enable

docgen/hooks.tomlを設定することで、動作の変更が可能です

git hooksを無効化する場合

python3 agents_docs_sync hooks disable
# or
uv run agents_docs_sync hooks disable

などです

詳しくは--helpコマンドで見てください

📈 導入効果

実際に運用してみて…

〇〇時間の削減！
更新漏れがゼロに！
プロジェクト管理が楽に！
チームメンバーのレビューが簡単に！

……というようなご報告をお待ちしております()

(まだこのプロジェクトの管理しかできていません、自分でもこれからいろいろなプロジェクトに導入して試していきたいと思いますが、IssueやPullリクエストお待ちしております)

📚 今後の展望

運用してバグを減らしていく
言語対応について精度を上げていく
そのほか以下のような機能を追加していく
- アーキテクチャ図の出力
- DEVELOPERS_GUIDEの自動生成
- アーキテクチャ図の高精度化(LLMでの構造化)

まとめ

めんどくさかったんです、ドキュメントの管理が
めんどくさかったんです、AGENTS.mdの管理が
めんどくさかったんです、プロジェクトの管理が
だから作りました、それらをなるべく自動化できるものを

OSS、作ってみたかったですしね

私はこれを使って自分のコーディング環境を少しずつ整っていきたいと思います
皆さんのコーディングにも、幸がありますように