ADR-0029: リポジトリの構成を buddy に合わせ、文書を docs/ に、E2E を packages/e2e に置く¶
Status¶
承認
Context¶
運営者は、このリポジトリのほかに buddy を保守している。
ディレクトリ、文書の配置先、検証の仕組みが 2 つのリポジトリで違うと、手順とスキルを共有できない。
buddy の構成は次のとおり。
出典: buddy
- 文書を
docs/に集める。docs/PRD.md、docs/design/DesignDoc.md、docs/adr/が実体である。 - 機能ごとの Design Doc は、コードの隣に置く。
docs/design/から、シンボリックリンクで指す。 - context は、ルートの
context/に置く。 - E2E は、workspace の package の
packages/e2e/に置く。tests/の下に、specs、evidence、screens、selectors、fixtures、setup、widgetsを持つ。ESLint は、packages/e2eだけに入れている。 - lint と format は、Vite+ の
vp checkで実行する。
このリポジトリの今の構成は次のとおり。
- 文書は、ルートの
PRD.md、design/、adr/にある。 - ルートの
e2e/は、ページの見た目を改修の前後で比べるスクリプトである。E2E のテストは無い。 apps/webは、記事、ハンズオン、playground を持つ Astro のサイトである。このサイトのコードと原稿は引き継がない。packages/design-systemは、古いトークン、レイアウトのユーティリティ、サイト全体の動きの規則の文書、挿絵の文書を持つ。トークンとコンポーネントはpackages/uiに、挿絵の生成の出力はpackages/ui/src/art/に移っている。- package を切り出す条件は、ADR-0003 にある。
- Content Model は、Astro に依存しない package である。
- lint と format は Oxlint と Oxfmt を直接実行する。
Decision¶
1. workspace の構成¶
- 古い
apps/webとpackages/design-systemを消し、apps/webを新しく作る。古いコードを直しながら移すより、引き継がないコードが残らないためである。 packages/content-modelとpackages/configは残す。Astro なしでテストできる境界を保つためである。packages/e2eは、テストだけを持つ package として、package を切り出す条件の例外にする。- TypeScript は 6.0.2 にする。buddy と同じバージョンである。
2. 文書の配置先¶
PRD.md、design/、adr/を、docs/PRD.md、docs/design/、docs/adr/に移す。古いapps/webを消す変更と同じ変更で移す。- 機能ごとの Design Doc は、コードの隣に置いたままにする。
docs/design/apps/とdocs/design/packages/から、シンボリックリンクで指す。ドキュメントサイトがdocs/だけを読めば済むためである。 context/は、ルートに置いたままにする。- 全てのページを
packages/uiのトークンとコンポーネントで構築する。 - サイト全体の動きの規則は、全体の Design Doc の Cross-Cutting Concerns に移す。挿絵の Design Doc は、
packages/ui/src/art/に移す。
3. E2E の配置先¶
- E2E を
packages/e2e/（@fukuemon/e2e）に置く。ディレクトリの分け方は buddy と同じにする。 - E2E は、Playwright の録画と字幕でエビデンスを撮れる形で書く。
- ESLint は
packages/e2eだけに入れ、E2E の書き方の規則だけを実行する。 - ルートの
e2e/を消す。改修の前後の見た目は、E2E のエビデンスの静止画を並べて比べる。
4. buddy に合わせないもの¶
lint と format のコマンドは、buddy の vp check に合わせない。
Oxlint と Oxfmt を直接実行する今の形を変える理由が、コマンドの名前がそろうことのほかに無いためである。
Considered Options¶
| 選択肢 | 強み | 弱み |
|---|---|---|
採用: 文書を docs/ に、E2E を packages/e2e に置く |
buddy と同じ配置先になり、手順とスキルを共有できる。E2E の依存を package に閉じる | 文書のパスが変わり、文書の間のリンクとスクリプトのパスを直す |
文書をルートに置いたままにし、E2E をルートの e2e/ に置く |
パスを変えない | buddy と配置先が違う。E2E の依存をルートに追加する。ドキュメントサイトが、ルートの複数の場所を読む |
packages/content-model を消し、schema を apps/web に書く |
package が 1 つ減り、buddy の packages/ に近づく |
Astro なしでテストできる境界が無くなる。contentId と関連を捨てるかを、別に決めることになる |
lint と format も buddy の vp check に寄せる |
2 つのリポジトリで、コマンドと設定の形がそろう | Oxlint の依存の規則と、Vite+ の使い方の決定を書き直す |
Consequences¶
Positive¶
- 2 つのリポジトリで、文書の配置先と E2E の配置先がそろう。
- 引き継がないコードと原稿が、リポジトリに残らない。
- 古いトークンと新しいトークンが並ぶ状態が終わる。
Negative¶
- 文書を移す変更で、文書の間の相対リンク、
context/project.ymlのdocs、文書のチェックのスクリプトが読むパスを直す。 - シンボリックリンクは、Windows の checkout で、設定によってはリンクにならない。
- lint と format のコマンドは、buddy と違うままである。