Codex use case
ドキュメントを最新に保つ方法
コードやその他の情報源を使って、ドキュメントの更新を自動化します。
Codex でソースコードの変更内容、公開ドキュメント、リリースノート、PR の背景情報を照合します。そのうえで、必要な箇所に絞ってドキュメントの更新案を作成し、公開前の検証手順をまとめます。
Best for
- 製品の動作が頻繁に変わり、それに合わせて更新が必要な開発者向けドキュメント、README、運用手順書、使用例、移行時の注意事項
- 技術製品のドキュメントを保守するチーム
Contents
ドキュメントを最新に保つ方法
コードやその他の情報源を使って、ドキュメントの更新を自動化します。
Codex でソースコードの変更内容、公開ドキュメント、リリースノート、PR の背景情報を照合します。そのうえで、必要な箇所に絞ってドキュメントの更新案を作成し、公開前の検証手順をまとめます。
Codex でソースコードの変更内容、公開ドキュメント、リリースノート、PR の背景情報を照合します。そのうえで、必要な箇所に絞ってドキュメントの更新案を作成し、公開前の検証手順をまとめます。
Related links
Best for
- 製品の動作が頻繁に変わり、それに合わせて更新が必要な開発者向けドキュメント、README、運用手順書、使用例、移行時の注意事項
- 技術製品のドキュメントを保守するチーム
Skills & Plugins
- GitHub でバグ報告を受け付けている場合は、イシュー、Pull Request、コメント、レビュースレッド、失敗したチェックの内容を確認します。
| Skill | Why use it |
|---|---|
| GitHub | GitHub でバグ報告を受け付けている場合は、イシュー、Pull Request、コメント、レビュースレッド、失敗したチェックの内容を確認します。 |
Starter prompt
はじめに
ドキュメントを最新の状態に保つには、更新を何週間も先送りせず、ソースコードの変更に合わせて更新するのが最も簡単です。Codex は、変更されたコードやテスト、リリースノート、リンク先のイシュー、pull request の背景を確認し、既存の構成に沿って必要な箇所の更新案を作成できます。
このワークフローは、開発者向けドキュメント、README の更新、変更履歴の下書き、移行時の注意事項、運用手順書など、頻繁に変わる挙動を反映する必要がある文書に利用できます。
利用手順
-
ドキュメントに反映する変更を Codex に伝えます。
対象のブランチ、pull request、コミット、イシュー、またはファイルを共有します。公開ドキュメントの場合は、未公開のロードマップ、非公開の顧客情報、社内限定の背景情報を含めないよう明示してください。
-
変更の影響を受けるドキュメントを Codex に特定してもらいます。
下書きを始める前に、機能名、設定キー、コマンド、使用例、関連用語を手がかりに既存のドキュメントを検索するよう依頼します。
-
更新範囲を必要最小限に絞ります。
既存のページ構成、用語、ページ間のリンク、フロントマターを維持するよう Codex に指示します。的確な補足や例の追加、該当するセクションの更新で十分なら、大幅な書き直しは避けるよう伝えます。
-
変更内容を検証します。
リポジトリに合ったフォーマットチェックとドキュメントチェックを実行し、その後、ユーザー向けの各記述にどのような根拠があるかをまとめるよう Codex に依頼します。
Codex に渡す情報
| 情報源 | 用途 |
|---|---|
| 変更されたコードとテスト | Codex が実際の挙動を分析し、必要な箇所に絞って更新案を作成できます。 |
| 公開済みのリリースノートや製品ドキュメント | 公開情報に合わせて用語を統一し、機能の提供範囲や現在の状態を正確に記述できます。 |
| Pull request やイシューの背景情報 | 変更の理由と、ユーザーにとって重要な挙動がわかります。 |
| ローカルで実行するドキュメントチェック | 公開前に満たすべき完了条件を Codex に具体的に示せます。 |
公開済みのリリースノートなどで背景情報を補うと、Codex が非公開の事情や未発表の変更内容をドキュメントに含めずに済みます。
ワークフローの再利用
リポジトリ全体で共通のルールにするには、ドキュメント更新時の要件を AGENTS.md に記載します。たとえば、次のように記述できます。
## ドキュメント
- ユーザーから見た挙動が変わる場合は、ドキュメント、使用例、変更履歴の更新が必要か確認してください。
- 公開ドキュメントに記載する内容は、公開情報またはこのリポジトリで確認できる挙動に限ってください。
- 既存の用語とフロントマターを維持してください。
- 成果物を引き渡す前に、ドキュメントのフォーマットチェックとビルドチェックを実行してください。手順がさらに多い場合は、スキルとしてまとめると、以降のタスクでも Codex が同じ手順で情報源の確認、下書き、検証を行えます。詳しくは「ワークフローをスキルとして保存」を参照してください。
現在のチャットから、このワークフローを実行するタスクをスケジュールすることもできます。たとえば、毎週 GitHub から最近の pull requests を取得し、ドキュメントを最新の状態に保つよう Codex に依頼できます。
