update-design

name	update-design
description	pytest-stepfunctions の設計書や仕様メモを作成・更新した後に使う。README、TODO、既存 docs を照合し、厳しめに自己評価して不足を埋め、矛盾や収載漏れがない状態に整える。

設計書の評価と改善

pytest-stepfunctions の設計書や仕様メモを作成・更新した直後に使う。 対象ドキュメントを読み込み、自己評価し、不足点を修正し、README.md と TODO.md と矛盾しない状態まで仕上げる。

Phase 1: 対象と関連資料の特定

Step 1-1: 対象ドキュメントを決める

優先順は以下:

1. ユーザーが明示した設計書
2. 直近で変更された docs/design/*.md
3. まだ設計書がない場合は、新規に作るべき docs/design/<feature>.md

設計書がまだ存在しない場合は、必要に応じて docs/requirements.md も合わせて作成または更新対象に含める。

Step 1-2: 必須コンテキストを読む

最低限、以下を確認する:

• 対象の設計書
• README.md
• TODO.md
• docs/requirements.md があればその内容
• 関連する src/ や tests/ があれば実装状況

Phase 2: 100点満点で自己評価する

以下の 10 項目を各 10 点で採点する。

#	項目	観点
1	基本構造	概要、スコープ、設計、テスト、実装計画が揃っているか
2	目的と非スコープ	何を実装し、何をまだ実装しないかが明確か
3	公開 API 設計	fixture、marker、dataclass など利用者向け API が具体的か
4	backend 設計	local、teststate、aws の扱いと責務分離が明確か
5	設定と優先順位	marker、CLI、設定ファイル、引数の優先順位が定義されているか
6	異常系と制約	timeout、認証不足、Local 未起動、quota などが考慮されているか
7	テスト戦略	unit / integration の方針と具体ケースがあるか
8	実装計画	ファイル構成、段階分割、依存順が具体的か
9	ドキュメント整合性	README.md と TODO.md と矛盾しないか
10	実装着手可能性	実装者が追加質問なしで着手できるか

採点基準:

• 9-10: 実装開始に十分
• 7-8: 軽微な追記で十分
• 5-6: 重要情報が欠ける
• 3-4: 大幅な補強が必要
• 0-2: 骨格のみ

評価結果は表でまとめ、合計点を出す。

Phase 3: 不足点をタスク化して修正する

評価で 9 点以下の項目は、具体的な修正タスクに落とす。

タスク粒度の目安:

• 1 タスク = 1 セクションの追加または 1 つの論点の具体化
• 曖昧な表現ではなく、何を追記するかまで書く

修正ルール:

• 既存の記述は尊重し、矛盾する場合だけ修正する
• 抽象論だけで終わらせず、型、優先順位、入出力、失敗時挙動を具体化する
• 実装済みコードがある場合はコードに合わせる
• 未実装なら「予定」であることを明示する
• 日本語ドキュメントの文体は既存に合わせる

Phase 4: 最終検証

更新後に以下を確認する:

• README.md の API 説明と設計書の公開 API が一致している
• TODO.md の作業分解と設計書の実装計画が矛盾していない
• backend の責務境界が文書全体で一貫している
• planned と implemented の表現が混ざっていない
• ファイルパス、型名、fixture 名、marker 名が実装または計画と一致している

必要なら修正して再確認する。

Phase 5: 報告

最後に以下を簡潔に報告する:

• 初回評価点
• 改善後評価点
• 主な修正点
• 残るリスクや未確定事項

注意事項

• docs/design/ がまだない場合は、必要に応じて新規作成を提案または実施する
• README.md だけでは設計詳細が足りない場合、設計書へ詳細を逃がす
• 実装が未着手の段階では、設計書が TODO の粒度と噛み合っていることを重視する