[4.4] コード近接の人間向け仕様ドキュメント（README.html）と静的サイト/PDF 化 — 実装設計

# [4.4] コード近接の人間向け仕様ドキュメント（README.html）と静的サイト/PDF 化 — 実装設計

> ソースコードの各機能ディレクトリに、**人間向けの読みやすい仕様書 `README.html`**（真の仕様書）を配置し、あわせて GitHub 上で読める**短い索引 `README.md`** を置くハイブリッド構成を導入します。さらに全 `README.html` を集約した**静的サイト**として常時公開し、`data-customer` フィルタと**ブラウザ印刷で顧客提出用 PDF** を派生させます（戦略資料 §8.1 + §8.2）。
>
> 個別実装ではなく、**構成・テンプレート・SKILL.md/AGENTS.md との棲み分け**をまず合意し、パイロット（PurchaseFlow）→ 段階展開 → 静的サイト基盤の順で進める土台とします。

| 項目 | 値 |
|------|-----|
| 対象バージョン | **EC-CUBE 4.4**（Symfony 7.4 / PHP 8.2+） |
| 主目的 | **人間向けの仕様ドキュメント**（読みやすさ・図表・顧客提出 PDF）。副次的に AI エージェントの導線 |
| 形式 | **`README.html`＝真の仕様書 / `README.md`＝短い索引** のハイブリッド（戦略資料 §8.1） |
| 公開 | 全 `README.html` を集約した**静的サイト**＋ PDF 派生（戦略資料 §8.2） |
| 受入基準 | [§8](#8-受入基準-acceptance-criteria) |

---

## 1. 概要

`src/Eccube/` の各機能ディレクトリに、コードと同じ場所へ 2 ファイルを配置します。

- **`README.html`** — 人間向けの**真の仕様書**。図表・レイアウトを使い「何を・なぜ・どう動くか」を記述。`data-section` / `data-customer` 属性で開発者向けフル版と顧客提出向けフィルタ版を 1 ファイルで出し分け（§8.1）。
- **`README.md`** — GitHub のディレクトリビューで自動表示される**短い索引**。要点＋ `README.html`（人間向け仕様）と該当 `.claude/skills//SKILL.md`（AI 向け規約）へのリンク。

さらに全 `README.html` を集約した**静的サイト**を常時公開し、顧客提出用 PDF はブラウザ印刷で派生させます（§8.2）。

まず `src/Eccube/Service/PurchaseFlow/` をパイロットに構成を固め、以降を段階展開します。

## 2. 背景と目的

- **背景 / 動機**：EC-CUBE には **人間（開発者・新規参加者・顧客）向けの、コードと一体化した読みやすい仕様書**が不足している。機能仕様がコードや散在する Wiki に埋もれ、顧客提出資料も都度手作りになりがち。
- **目的**：
1. **人間向けの仕様書をコード近接に置き**、コードと同時に更新される Single Source of Truth 化する。
2. HTML の表現力（図表・レイアウト）で読みやすくし、**静的サイトで常時公開**、**顧客提出 PDF をワンソースから派生**させる（§8.2）。
3. 副次的に、`README.md` 索引が **AI エージェントのコード → 仕様/規約への導線**も兼ねる。
- **なぜ HTML か**（戦略資料 §8.1 準拠）：Markdown を超える表現力と、`data-customer` による顧客向けフィルタ・PDF 派生を 1 ソースで実現するため。GitHub 非レンダリング等の弱点は **README.md 索引＋§8.2 静的サイト**で補う。

## 3. 全体構成（3 層の役割分担）

人間向け仕様（HTML）・GitHub/AI 向け索引（MD）・AI 向け実装規約（Skill）を**読者別に分離**し、二重化を避ける。

| 成果物 | 主読者 | 役割 | 置き場所 |
|---|---|---|---|
| `README.html` | **人間**（開発者・新規参加者・顧客） | 真の仕様書（挙動・なぜ・図表）。§8.2 で静的サイト／PDF に派生 | 各機能ディレクトリ |
| `README.md` | GitHub 閲覧者・**AI エージェント** | 短い索引。要点＋ `README.html` と `SKILL.md` へのリンク（AI の道標を兼ねる） | 各機能ディレクトリ（`README.html` と同居） |
| `.claude/skills//SKILL.md` | **AI エージェント** | 実装の書き方ルール（規約・DO/DON'T）。仕様説明は `README.html` に委ね相互リンク | `.claude/skills/`（既存） |

> **SKILL.md との棲み分け**：`README.html` は「機能の仕様（人間向け）」、`SKILL.md` は「コードの書き方（AI 向け）」。同じ事柄を二度書かず、相互にリンクする。読者と目的が異なるため両立する。
>
> **参照トポロジ**（既存の一方向ルールを維持）：`README.md`（索引）→ `README.html`（仕様）／`SKILL.md`（規約）→ `AGENTS.md`（正典）。上流（`AGENTS.md`）から個別 README への下向き内容参照は足さない。

## 4. Phase A: HTML コロケーション（規約・テンプレート・パイロット）

### 4.1 配置構成

```
src/Eccube/Service/PurchaseFlow/
├── README.html ← 人間向けの真の仕様書（主）
├── README.md ← 短い索引（GitHub 自動表示・AI 道標）
├── PurchaseFlow.php
└── Processor/ ...
```

### 4.2 テンプレート（README.md 索引）

```markdown
# <ディレクトリ名> — <一行の説明>

<何をする所か 1〜2 行>

- 📖 仕様（人間向け）: [README.html](./README.html)
- 🛠 実装規約（AI 向け）: [`.claude/skills//SKILL.md`](<相対パス>)

## 主要ファイル
- `.php` — <1行>
- ...（3〜5個）
```

### 4.3 テンプレート（README.html 仕様書）

- 自己完結 HTML（戦略資料本体と同様の構造）。`` で章立てし、顧客提出時は `data-customer="true"` のみ抽出。
- 章立て例：概要 / 用語 / 処理フロー（図） / 拡張ポイント / 注意点。
- スタイルは共通 CSS を将来 §8.2 の静的サイト側で当てられるよう、過度なインライン装飾は避ける。

### 4.4 パイロット：`src/Eccube/Service/PurchaseFlow/`

最も複雑で仕様説明の価値が高い PurchaseFlow で、README.html（処理フロー図・段階の実行順・拡張ポイント）と README.md（索引）の雛形を具体化し、分量・粒度の基準を作る。

### 4.5 段階展開（配置対象の全リスト）

配置対象は原則で機械的に決め、抜けを作らない。各対象に `README.html`（人間向け仕様）＋ `README.md`（索引）を置く。

#### 4.5.1 配置の原則と対象外

「**Skill が対象と宣言しているディレクトリ**」＋「**Skill は無いが仕様説明の価値が高い非自明ディレクトリ**」に配置する。以下は対象外：

- **対象ディレクトリを持たない Skill**：`contributing` / `capture-learning` / `docker-qa` / `review-responsibility`（プロセス・横断系）
- **自動生成ディレクトリ**：`app/proxy/entity/` 等
- **個別ファイルが対象の Skill**（`csv` = `CsvImportService.php`/`CsvExportService.php`、`mail` = `MailService.php`）：独立配置はせず、`src/Eccube/Service/` の README で 1 節言及
- **小さく定型的なディレクトリ**：`Util/` `Exception/` `Log/` `Common/` `Request/` `Session/` `DataCollector/` `Validator/`（仕様書化の価値が薄くノイズになる）

#### 4.5.2 レイヤ根（Skill が対象宣言するディレクトリ・12 箇所）

| No. | ディレクトリ | 対応 Skill（README.md からリンク） |
|---|---|---|
| 1 | `src/Eccube/Controller/` | controller |
| 2 | `src/Eccube/Service/` | service（csv・mail もここで言及） |
| 3 | `src/Eccube/Entity/` | entity |
| 4 | `src/Eccube/Repository/` | repository |
| 5 | `src/Eccube/Form/Type/` | formtype |
| 6 | `src/Eccube/Command/` | command |
| 7 | `src/Eccube/Twig/Extension/` | twig-template |
| 8 | `src/Eccube/Security/` | security |
| 9 | `src/Eccube/EventListener/`（＋ `Event/`・`Doctrine/EventSubscriber/`） | event-subscriber |
| 10 | `src/Eccube/Plugin/`（＋ `app/Plugin/`） | plugin |
| 11 | `app/Customize/` | customize |
| 12 | `app/DoctrineMigrations/` | migration |

> `e2e/`（TypeScript）・`tests/` は別ツリーのため本 Issue のリストからは除外し、必要になった時点で別途検討する（対象言語・読者が異なるため）。

#### 4.5.3 高複雑サブシステム（深い仕様書・3 箇所）

| No. | ディレクトリ | 記述内容 |
|---|---|---|
| 13 | `src/Eccube/Service/PurchaseFlow/` | **パイロット**。段階の実行順・拡張ポイント・処理フロー図 |
| 14 | `src/Eccube/Service/AgentCommerce/` | 8 サブドメイン（Catalog/CheckoutSession/Discovery/Fulfillment/Idempotency/Payment/Security/Exception）ごとに配置 |
| 15 | `src/Eccube/Controller/Admin/Order/` | 受注編集 `EditController`。管理操作から PurchaseFlow を呼ぶ二重副作用の仕様 |

#### 4.5.4 Skill が無い非自明ディレクトリ（自己完結の仕様書・3 箇所）

上流 Skill が無いため `README.md` 索引は `README.html`（自己完結の仕様）のみを指す。

| No. | ディレクトリ | 記述内容 |
|---|---|---|
| 16 | `src/Eccube/Doctrine/` | Query カスタマイズ・DBAL カスタム型・ORM Mapping・Filter・CsvDataFixtures（EC-CUBE 固有の Doctrine 拡張） |
| 17 | `src/Eccube/DependencyInjection/` | Compiler パス・`EccubeExtension.php`（`/mypage`・`/admin` の access_control を動的生成する等の非自明挙動）・Facade |
| 18 | `src/Eccube/Attribute/` | `CartFlow`/`ShoppingFlow`/`OrderFlow`（PurchaseFlow 登録）・`EntityExtension`/`FormAppend`（拡張機構） |

#### 4.5.5 着手順（全 18 箇所・仕様価値と事故りやすさ順）

1. No.13 `Service/PurchaseFlow/`（パイロット）
2. No.15 `Controller/Admin/Order/`
3. No.14 `Service/AgentCommerce/`
4. No.1 `Controller/`
5. No.2 `Service/`
6. No.3 `Entity/`
7. No.5 `Form/Type/`
8. No.4 `Repository/`
9. No.9 `EventListener/`（＋ `Event/`・`Doctrine/EventSubscriber/`）
10. No.16 `Doctrine/`
11. No.17 `DependencyInjection/`
12. No.8 `Security/`
13. No.7 `Twig/Extension/`
14. No.6 `Command/`
15. No.18 `Attribute/`
16. No.10 `Plugin/`（＋ `app/Plugin/`）
17. No.11 `app/Customize/`
18. No.12 `app/DoctrineMigrations/`

## 5. Phase B（§8.2）: 静的サイト / PDF 派生

- **静的サイトジェネレータ**を選定（Astro Starlight / VitePress / Antora いずれか。PoC で決定）。全 `README.html` を集約し **常時公開**（例：`docs.ec-cube.net/spec/`）。
- **顧客提出 HTML/PDF**：`bin/console eccube:docs:export --filter=customer` で `data-customer="true"` の章だけ抽出 → ブラウザ印刷で PDF 化。
- **鮮度維持**：PR テンプレートにドキュメント更新チェック項目、CI で生成検証（リンク切れ・ビルド可否）。

> Phase B は独立実装ボリュームが大きいため、**本 Issue では設計・方針まで**を合意し、実装は Phase A 合意後に着手（必要なら別 PR/サブ Issue に分割）。

## 6. AGENTS.md への追記

`AGENTS.md` に、本構成（`README.html`＝人間向け仕様 / `README.md`＝索引・AI 道標 / `SKILL.md`＝AI 規約）の役割分担と、README のテンプレート・参照トポロジを 1 節追記する（Skill 配置ルールと同格のメタ記述）。

## 7. 想定される懸念と対応

| 懸念 | 対応 |
|---|---|
| `README.html` は GitHub で生ソース表示 | `README.md` 索引が GitHub 側の入口。真の仕様は §8.2 静的サイトで読む |
| HTML は AI エージェントにとってトークンが重い | AI の一次入口は軽い `README.md`＋`SKILL.md`。`README.html` は人間向けと割り切る |
| `README.html` と `SKILL.md` の二重化 | 仕様＝HTML／書き方＝Skill と役割分離し相互リンク（§3） |
| HTML 更新の形骸化 | PR テンプレのチェック項目＋ §8.2 の CI 生成検証 |

## 8. 受入基準 (Acceptance Criteria)

- [ ] `README.html`（真の仕様書）／`README.md`（索引）の**テンプレートと書式規約**が合意される（`data-section`/`data-customer` の使い方含む）。
- [ ] **3 層の役割分担**（README.html＝人間向け仕様 / README.md＝索引・AI 道標 / SKILL.md＝AI 規約）と参照トポロジが合意される。
- [ ] **パイロット（PurchaseFlow）の README.html + README.md サンプル**が妥当と判断される。
- [ ] **段階展開の対象と優先順位**が合意される。
- [ ] **Phase B（§8.2）静的サイト／PDF の方針**（ジェネレータ候補・公開先・export コマンド・鮮度維持）が合意される。

## 9. スコープ外 / 依存

- Phase B の実装（静的サイト構築・`eccube:docs:export` 実装・ホスティング）は合意後の後続 PR。
- 戦略資料の他施策（`DESIGN.md`/`ARCHITECTURE.md`、`.cursor/`、Copilot instructions、MCP、ADR 等）は別 Issue。