ARCHITECTURE.md を索引型に再構成する

[YusukeHirao]

概要

ARCHITECTURE.md が 837 行の詳細保存庫になっており、「実装把握の入口」として機能していません。索引に絞り、詳細はそれぞれ適切な置き場に移したいです。

CLAUDE.md は AI エージェントに対して「コードを読み始める前に ARCHITECTURE.md を読むこと」と指示しています。しかし現状の分量では入口として読み切れず、また実装詳細を含むため実装との乖離が起きやすい状態です。

現状の内訳

セクション	行数	性質
パッケージ構成と依存関係（mermaid）	約 75	全体地図
各パッケージの責任（5 レイヤー）	約 180	実装詳細
アーキテクチャ原則（レイヤー分離・機能配置の判断基準・headless core・コマンドバス）	約 70	境界・不変条件
テストアーキテクチャ	約 12	索引
モノレポ構成の利点	約 17	背景説明
実験的機能（設計原則・設定構造・実装例）	約 57	実装詳細
Tiptap 拡張機能の追加方法	約 405	コントリビュータ向け手順書
未確認事項	約 12	未解決事項

Tiptap 拡張の追加手順が単独で全体の約半分を占めています。実装パターン A/B の全文、8 ステップの実装チェックリスト、落とし穴 6 件、デバッグ方法が含まれており、これは「アーキテクチャ」ではなく手順書です。

目指す姿

ARCHITECTURE.md を 100〜200 行程度の索引にします。含めるのは以下に限定します。

• 全体地図（パッケージ構成と依存グラフ）
• 境界と所有権、依存方向
• 不変条件と負の知識（やってはいけないこと、意図的にやっていないこと）
• 変更種別ごとの Reading paths（何を変えるときどのファイルをどの順で読むか）

実装詳細の正はソースの JSDoc に置きます。

移動先の案

現在の内容	移動先
各パッケージの責任	各パッケージの README.md または公開 API の JSDoc。ARCHITECTURE.md 側は依存グラフと 1 行説明のみ残す
Tiptap 拡張機能の追加方法	CONTRIBUTING.md（未作成）または docs/ 配下の独立ファイル
実験的機能の設定構造・実装例	設定型の JSDoc（@example 付き）。ARCHITECTURE.md 側は設計原則のみ残す
モノレポ構成の利点	削除、または数行に圧縮
アーキテクチャ原則	維持（境界・不変条件そのもの）
未確認事項	維持（負の知識として有用）

docs/ には既に proposal-features.md と style-extension.md があるため、Tiptap 手順書もここに置くのが自然かもしれません。

補足

「未確認事項」に挙がっている 3 項目（モノレポ構成の選択理由、将来のプラットフォーム拡張計画、レイヤー間の厳密な境界定義）のうち、レイヤー間の境界定義は索引の中核にあたります。この整理と同時に埋められると索引としての価値が上がります。

参考

• 索引型の実例: nitpicker の ARCHITECTURE.md
• ドキュメント原則は CLAUDE.md の「ドキュメント原則」節を参照（コードには How、テストコードには What、コミットログには Why、コードコメントには Why not）