| name | update-docs |
| description | 実装、仕様変更、スコープ調整の後に使う。pytest-stepfunctions の README、TODO、設計書、要件メモを最新状態にそろえ、実装と文書の食い違いをなくす。 |
ドキュメント一括最新化
pytest-stepfunctions の実装や仕様変更の後に、関連ドキュメントをまとめて更新する。
対象は主に以下:
README.mdTODO.mddocs/requirements.mddocs/design/*.md
Phase 1: 変更内容の把握
まず、最近の変更を把握する。
推奨コマンド:
git diff --name-only HEAD~5
git log --oneline -10
確認ポイント:
- どの機能が追加、変更、削除されたか
- 公開 API が変わったか
- 実装済みになった TODO があるか
- 新しい制約や既知の注意点が増えたか
Phase 2: 開発ドキュメントを更新
Step 2-1: 要件メモを更新する
docs/requirements.md がある場合:
を実装に合わせて更新する。
まだ存在しないが、README だけでは要件整理が足りない場合は新規作成する。
Step 2-2: 設計書を更新する
docs/design/*.md がある場合は以下を更新する:
- 実装ステータス
- 公開 API
- backend 設計
- 設定解決の優先順位
- テスト戦略
- エラー処理や制約
該当設計書がない場合でも、実装や仕様が README だけでは追えないなら新規作成を検討する。
Phase 3: README.md を更新
README.md は利用者向けの最新契約として扱う。
更新項目の例:
- プラグインの目的
- 使い方
- fixture / marker / dataclass の例
- backend の違い
- 制約事項
- インストール方法
ルール:
- 予定機能と実装済み機能を混同しない
- コード例は現在の公開 API に合わせる
- まだ未実装の例は、予定であることが分かる形にする
Phase 4: TODO.md を更新
TODO.md は実装バックログとして扱う。
更新内容:
- 完了した項目にチェックを付ける
- 仕様変更で不要になった項目を整理する
- 新しく見つかった作業を追加する
- 粒度が粗すぎるタスクは分割する
実装済み内容が TODO に残り続けないようにする。
Phase 5: 一貫性チェック
最後に以下を確認する:
- README の公開 API が設計書と一致している
- TODO の残課題が実装状況と一致している
- backend 名、fixture 名、marker 名、型名が全ファイルで一致している
- スコープ説明が README、requirements、design docs で矛盾していない
- 日付やステータス表記が最新である
記述ルール
- 既存の文体に合わせる
- 現在の repo では README も開発ドキュメントも日本語が基調なので、それを維持してよい
- 箇条書きだけで済ませず、判断理由や制約が必要なら本文に残す
- 実装より先にドキュメントを進める場合は、仮仕様であることを明記する
