update-docs

ドキュメント更新ワークフロー

コードが変更され、プロジェクトのドキュメントを最新の状態にする必要がある場合は、このワークフローを使用します。エージェントは git を使って、直近のドキュメントコミット以降の変更を検出し、差分を分析して、影響を受けるドキュメントのみを更新します。

このワークフローはプロジェクトに依存しません。プロジェクトのルートとドキュメントの場所を自動検出します。

---

ステップ 1 — 概要を把握する：プロジェクトを検出する

// turbo 以下を実行して、プロジェクトのルートと基本的な構成を確認します。

# Project root and current branch
git rev-parse --show-toplevel && git branch --show-current

# Last 5 commits (so we can pick the baseline)
git log --oneline -5

次に、ドキュメントの場所を見つけます。

# Look for common doc directory patterns
find "$(git rev-parse --show-toplevel)" -maxdepth 3 -type d \
  \( -name "docs" -o -name "doc" -o -name "wiki" -o -name "pages" \) \
  ! -path "*/.git/*" ! -path "*/node_modules/*" ! -path "*/.venv/*"

# Also check for top-level markdown files
find "$(git rev-parse --show-toplevel)" -maxdepth 1 -name "*.md" -type f

結果から、以下を特定します。

• $ROOT：git ルートディレクトリ
• $DOCS_DIR：ドキュメントファイルの場所（例：docs/src/、docs/、wiki/）

$DOCS_DIR を自動的に特定できない場合は、ユーザーに 「ドキュメントファイルはどこにありますか？（例：docs/、docs/src/、または README.md のみ）」 と尋ねます。

---

ステップ 2 — 基準コミットを見つける

// turbo ドキュメントディレクトリに変更を加えた、最も新しいコミットを見つけます。

git log --oneline --all -- "$DOCS_DIR" | head -5

最初のハッシュを控え、<baseline> とします。これは、ドキュメントが最新だった最後の時点です。

ドキュメント関連のコミットがない場合は、初回コミットを基準として使用します。

git log --oneline --all | tail -1

---

ステップ 3 — 基準コミット以降のコード差分を取得する

// turbo まず、ソースコード（ドキュメントを除く）の変更内容を簡潔にまとめます。

git diff <baseline> HEAD --stat -- . \
  ':!'"$DOCS_DIR" ':!*.md' ':!*.rst' ':!*.txt' ':!*.json'

差分の量が適切であれば、完全な差分を取得します。

git diff <baseline> HEAD -- . \
  ':!'"$DOCS_DIR" ':!*.md' ':!*.rst' ':!*.txt' ':!*.json'

ヒント：差分が約 400 行を超える場合は、次のコマンドを使ってファイルごとに分析します。

git diff <baseline> HEAD -- path/to/file.py

次の点に注目します：クラスや関数の追加・削除、メソッドシグネチャの変更、新しいモジュール、設定キーの変更、新しいデータファイル。

---

ステップ 4 — 既存のドキュメント構成を確認する

ステップ 1 で見つけたドキュメントファイルを読みます。以下を把握します。

• 各ファイルが扱うトピック
• 各ファイルが説明するモジュール／コンポーネント／概念
• 執筆スタイル（言語、見出しレベル、コードブロックや表の使用方法）

編集時は既存のドキュメントと同じスタイルと言語を維持します。

---

ステップ 5 — 変更内容を影響するドキュメントに対応付ける

変更されたファイルまたはモジュールごとに、更新が必要なドキュメントファイルを特定します。

一般的な対応付けの目安（プロジェクト固有の構成に合わせて調整してください）：

コードの変更の種類	更新する内容
新しいクラスまたはモジュールの追加	そのレイヤーを扱うアーキテクチャ／概要ドキュメントに追加し、依存関係図を更新する
クラスまたは関数の削除	言及しているすべてのドキュメントから削除するか、取り消し線を付ける
メソッドシグネチャ／パラメーターの変更	コード例、パラメーター表を更新する
新しい設定キーまたは環境変数	設定ドキュメントを更新する
新しい外部依存関係の追加	セットアップ／インストール手順を更新する
データスキーマの変更（DB、JSON、Pydantic など）	データモデルのドキュメントを更新する
新しい CLI コマンドまたはフラグ	CLI リファレンス／使用方法のドキュメントを更新する
動作の変更（アルゴリズム、ビジネスロジック）	設計／アーキテクチャのドキュメントを更新する
テストカバレッジの追加（大規模な新規テスト）	通常、テストガイドがある場合を除き、ドキュメントの更新は不要です

---

ステップ 6 — 影響を受けたドキュメントを最小限修正する

古くなっているセクションのみを更新します。現状でも正確なセクションは書き直さないでください。

編集ルール：

• 差分に追加された項目（クラス、メソッド、パラメーター、設定キー）を追加します
• 名前が変更された、削除された、またはリファクタリングされた項目の説明を削除または修正します
• 新しい実態を反映するよう、フロー図、ステップごとのパイプライン、表を更新します
• 差分の影響を受けていないセクションはすべて維持します。不必要な書き直しはしないでください
• 既存ドキュメントの文体（言語、書式、コードフェンスのスタイル）に正確に合わせます

---

ステップ 7 — 変更を要約し、必要に応じてコミットする

すべての編集後、簡潔な要約を表示します。

• 変更したドキュメントファイル
• 各ファイルで追加／削除／更新した内容

次にユーザーに尋ねます：「文档已更新。是否要将这些改动提交到 Git？(Y/n)」

はいの場合、次の形式でコミットメッセージを提案します：

docs: update <DOCS_DIR> to reflect changes since <baseline-short-hash>

次に、以下を実行します（<DOCS_DIR> と <message> を適宜置き換えてください）：

git add <DOCS_DIR> && git commit -m "<message>"

いいえの場合は、すべてのファイルがすでに保存されており、後から次のコマンドでコミットできることをユーザーに伝えます：

git add <DOCS_DIR> && git commit -m "docs: ..."