# タスク設計書: README をライブラリ本体向け内容へ再構成

最終更新: 2026-02-14
- ステータス: 完了(done)
- 作成者: Codex
- レビュー: shogohasegawa
- 対象コンポーネント: docs
- 関連: `README.md`, `pyproject.toml`, `examples/`, `src/graphyml/__init__.py`
- チケット/リンク: 該当なし
- 関連ゴールID: G-01, G-03
- 関連マイルストーンID: M-01, M-03

## 0. TL;DR
- 現在の `README.md` はテンプレート由来の運用説明が多く、ライブラリ利用者に必要な情報が埋もれている。
- README を Graphyml の配布・利用観点に絞って再構成する。
- API 利用方法、YAML スキーマ、examples、インストール/開発手順を優先表示する。
- エージェント運用規約は README から削減し、必要箇所のみ `AGENTS.md` 参照へ整理する。

## 1. 背景 / 課題
- README が「リポジトリ運用テンプレート」の説明を多く含み、Graphyml ライブラリとしての入口になっていない。
- 新規利用者にとって必要な情報（何ができるか、どう動かすか、どの YAML を書くか）が先頭で分かりづらい。
- 既に `examples/` と `Graphyml.from_workflow(...)` が整っているため、README を製品説明へ合わせる価値が高い。

## 2. ゴール / 非ゴール
### 2.1 ゴール
- README を「Graphyml ライブラリ利用ガイド」として再構成する。
- 次の項目を明確に記載する。
  - 概要・特徴
  - インストールと最小実行例
  - YAML 仕様の要点
  - examples 一覧
  - 開発者向け検証コマンド
- テンプレート由来の過剰な運用説明を削減する。

### 2.2 非ゴール
- ライブラリ実装（Python コード）の仕様変更は行わない。
- AGENTS や Playbook の内容変更は行わない。
- プロダクト進捗ドキュメントの状態更新は行わない（README再構成に限定）。

## 3. スコープ / 影響範囲
- 変更対象: `README.md`。
- 影響範囲: リポジトリ訪問者の初回理解、利用導線。
- 互換性: ドキュメントのみ変更のため実行互換性への影響なし。
- 依存関係: 既存公開 API（`Graphyml`, `InMemoryNodeRegistry`）、`examples/` 配下の YAML 構成。

## 4. 要件
### 4.1 機能要件
- README 先頭に Graphyml の目的と価値を簡潔に記述する。
- `uv` 前提のセットアップ手順を明記する。
- `Graphyml.from_workflow(...)` / `invoke(...)` の実行例を掲載する。
- YAML 主要キー（`start_at`, `end_at`, `nodes`, `edges`, `params`）を説明する。
- `examples/workflows/branch-inline.yaml` と `examples/workflows/loop-split.yaml` の用途を明記する。
- `LICENSE` と `CHANGELOG.md` への導線を残す。

### 4.2 非機能要件 / 制約
- README は人間向け説明に限定し、エージェント運用詳細は `AGENTS.md` へ誘導する。
- 内容は現実装と整合させる（存在しない API/コマンドを記載しない）。
- 冗長な背景説明より、最短で使える情報を優先する。

## 5. 仕様 / 設計
### 5.1 全体方針
- セクション順を「概要 → 使い方 → 仕様 → examples → 開発」に再編する。
- テンプレート起源の運用説明（AI context 同期手順や役割分担など）は README から外す。
- 運用規約が必要な場合は `AGENTS.md` への短い参照だけ残す。

### 5.2 変更点一覧
| 対象 | 変更内容 | 影響 | 備考 |
| --- | --- | --- | --- |
| `README.md` | テンプレ由来の運用説明を削減し、ライブラリ利用中心に全面再構成 | 利用者の理解性向上 | 更新 |

### 5.3 詳細
#### API
- `Graphyml.from_workflow(workflow_path, registry, bundle_root=None)`
- `Graphyml.invoke(state)`
- `InMemoryNodeRegistry`

#### UI
- 該当なし。

#### データモデル / 永続化
- README 内で `GraphSpec` 相当の YAML キー構造を説明する。

#### 設定 / 環境変数
- 追加なし。

### 5.4 代替案と不採用理由
- 代替案A: 現READMEに追記のみ行う。
  - 不採用理由: テンプレ情報が多く、主目的が埋もれた状態が解消しない。
- 代替案B: README を極小化して詳細を docs へ分割する。
  - 不採用理由: 初見ユーザーが最初に得るべき情報が不足する。

## 6. 移行 / ロールアウト
- README を1回で差し替え、既存 API/examples との整合を目視確認する。
- ロールバック条件: 記載 API/パスに不整合が見つかった場合。
- ロールバック手順: 直前コミットとの差分で不整合箇所のみ再修正する。

## 7. テスト計画
- 単体: 該当なし。
- 結合: 該当なし。
- 手動: README 内のコード/パスを `src`・`examples` と突合する。
- LLM/外部依存: 該当なし。
- 合格条件: README の記述が現行ファイル構成と一致し、利用導線が明確である。

## 8. 受け入れ基準
- README からテンプレート説明が大幅に削減されている。
- ライブラリ利用に必要な情報（概要、インストール、実行例、YAML仕様、examples）が揃っている。
- 記載された API 名・ファイルパスが実在する。
- `LICENSE`/`CHANGELOG.md` への案内が残っている。

## 9. リスク / 対策
- リスク: 運用関連情報を削りすぎて保守導線が失われる。
  - 対策: 運用規約は `AGENTS.md` 参照として最小限を残す。
- リスク: README のコード例が実装から乖離する。
  - 対策: 公開 API 実装（`src/graphyml/__init__.py`）に合わせて記述する。

## 10. オープン事項 / 要確認
- 該当なし。

## 11. 実装タスクリスト
- [x] README の章構成をライブラリ利用中心へ再編する。
- [x] `Graphyml.from_workflow` ベースの最小実行例を明記する。
- [x] YAML 仕様と examples の使い分けを追記する。
- [x] 不要なテンプレ運用説明を削減し、必要箇所を `AGENTS.md` 参照へ整理する。

## 12. ドキュメント更新
- [x] `README.md`（全面再構成）
- [ ] `AGENTS.md`（必要に応じて）
- [x] `docs/`（`docs/task-designs/*.md`）

## 13. 承認ログ
- 承認者: shogohasegawa
- 承認日時: 2026-02-14 00:03
- 承認コメント: 「OK」にて承認

## 実装開始条件
- [x] ステータスが `承認済み(approved)` である
- [x] 10. オープン事項が空である
- [x] 受け入れ基準とテスト計画に合意済み
