サイト全体を一度に変えるより、小さく検証できる増分が確実な理由

「サイト全体を整える」という依頼は、完了を判断しにくいものです。配色、コンテンツ、コンポーネント、ルート、操作をまとめて含んでいるかもしれません。どれか一つが期待と違うだけでも、原因を探す前に、今回何をまとめて変更したのかを確認する必要があります。

私はこうした仕事を、それぞれ独立して確認できる増分に分けます。ただし、小さくするとは、一つのファイルだけを変更することでも、ページにつながっていない空の枠を先に渡すことでもありません。一回の作業には、完結した用途、見分けられる境界、実際に確認できる結果が必要です。

このサイトでの Button の基礎導入と、記事の英日翻訳は、異なる種類の増分でした。前者では、新しいコンポーネントが既存のサイトに適合するかを確かめました。後者では、選んだ記事を原文から読める多言語ルートまでつなげました。どちらも「すべてを終える」だけを完了の単位にはしていません。

最小の単位は、ファイルではなく結果にします

記事ページで読者が英語版に切り替えられるようにする場合を考えます。完了条件には、少なくとも訳文、同じ記事としての識別、有効なルート、その版へのリンクが必要です。英語のファイルを一つ作っても、記事がまだ草稿だったり、リンクがなかったりすれば、公開ページの読者にとってその用途は成立していません。

これは説明のための要件例であり、特定の翻訳トラブルの記録ではありません。ファイル数だけで仕事を分けてはいけないことを示しています。

反対に、一つの結果のために複数の場所を変更することもあります。Button の導入では、コンポーネント、class のマージ、tokens、依存関係が関わります。翻訳を一括で完了するには、言語ファイルの追加、追跡ドキュメントの更新、関連する一覧の再ビルドが必要になる場合があります。ファイルが多いだけで、範囲が制御できていないとは限りません。すべての変更が同じ用途につながっていることが大切です。

私はまず二つの文を書きます。今回、誰が何をできるようになるのか。そして、一緒には変えないものは何かです。この二つを明確に書けないうちは、実装手順への分解を急ぎません。

Button の試験導入では、まず互換性を確かめました

このサイトに bejamas/ui を追加したときは、最初の範囲を一つの Button に限定しました。ライブラリにほかのコントロールがあるからといって、サイト全体をデモのスタイルへ置き換えませんでした。

その回で確かめたのは、コンポーネントをどうプロジェクトに入れるか、どの依存関係が必要か、既存の色につなげられるか、リンクとして使うと実際に anchor が出力されるかでした。いずれも、実際の変更と生成された HTML から追えることです。

当時、既存のページはまだ新しい Button を使っていませんでした。そのため、サイト全体のビルドが通っても、そのコンポーネントがレンダリングされた証拠にはなりません。同じコンポーネントと CSS を参照する独立したテスト用テンプレートを別途用意し、サイズ、バリアント、type、無効状態、リンク、class のマージを確認しました。

正式なページをすべて置き換えていなくても、この増分には完結した結果がありました。完了したのは基礎導入の互換性確認であって、サイト全体での採用ではありません。正式な使用箇所につなげることや、フォーカス管理が必要な操作コントロールを追加することは、別の回の作業です。

Button の導入記録には、依存関係の復元に関する制限も含め、当時の条件を残しています。そのテンプレートが通ったことを、後のすべてのコンポーネント更新への保証にはできません。

翻訳の増分は、原文からサイトの出力までつなげます

原文が 2026 年 10 月 12 日に記録した、その後の英日翻訳作業では、先に対象記事を限りました。翻訳待ちのすべての記事を、その回の作業として扱ったわけではありません。

各記事は言語間で同じ stableId を保ちますが、タイトル、概要、本文は各言語で自然に表現します。版の日付には、その訳文の完成と、公開可能なソースに入った時刻を記録し、繁体字中国語版の過去の日付をコピーしません。原稿に「英語の一覧にはまだ記事がない」と書かれていた場合は、原稿が記録した時点の状況だと訳文で説明する必要があります。すでに記事がある一覧を、今も空だと書いてはいけません。

この境界は、二つのものを同時に守ります。新しい版を完全に仕上げることと、サイト所有者が確認した繁体字中国語の原文を、翻訳のついでに書き直さないことです。既存の翻訳記録では、ファイルごとのハッシュで原文が変わっていないことを照合していました。これはファイル内容の一致を確認できますが、訳文の意味を読み返す代わりにはなりません。

内容が完成した後も、サイトにつながるところまで確認が必要です。公開対象の集合にその版が含まれるか、記事ページが生成されるか、言語リンクで各版を行き来できるか、一覧と sitemap が整合しているかを確かめます。本文を書いただけでは、こうした接続の結果まで完了したとは言えません。

Button の試験導入とは異なり、この増分の成果物は、正式なソースに入る完全な言語版です。そのため、未検証のファイルで止めることはできません。本番ホストが更新されたかどうかは、引き続きデプロイの別の境界です。

変えてはいけないものを先に記録します

変更するときは、追加する範囲と同じくらい具体的に、保護する範囲を書きます。次は作業形式の例であり、すべての仕事でそのまま使うべき仕様ではありません。

問い	Button の試験導入の境界	選んだ記事を翻訳する際の境界
今回何を追加するか	テストできる基礎コンポーネント	指定した原文の完全な言語版
何を変えないか	既存の情報設計とサイト全体のデザイン	確認済みの繁体字中国語本文と公開用の項目
何で結果を判断するか	コンポーネントのテスト用テンプレートが出力する実際の HTML と関連チェック	訳文の読み返し、公開ページ、言語の入口、コンテンツの出力
一緒に何を主張してはいけないか	操作コンポーネント一式の受け入れが完了したこと	外部の母語編集者による認証や、本番ホストへのデプロイ

保護条件が「むやみに変更しない」だけでは、確認しにくくなります。原文ならバイトの一致を照合できます。コンポーネントの導入なら、グローバル CSS、依存関係、既存の使用箇所をレビューできます。守り方は対象によって異なり、同じ道具を無理に当てはめる必要はありません。

付随する問題が出たら、今回の用途を妨げるかを判断します

範囲を限定することは、見つけた問題をすべて放置することではありません。

新しく追加した有効なコンテンツを、既存の出力チェックが誤って失敗と判定する場合は、まず切り分けます。記事が本当に契約に違反しているのか、それとも検証器がその有効なデータを扱えていないのかです。ツールを通すために正当なコンテンツを削除してはいけません。検証器の修正が必要なら、既存の保護を残し、再現できるケースを追加してから、もう一度確認します。

これは付随する問題の判断方法であって、記事を書くたびにプログラムを変えるという意味ではありません。今回の用途を妨げないレイアウトの好みや、別のコンポーネントをリファクタリングする機会なら、別に記録し、サイト全体の整理へ広げません。

仕事を小さくする利点は、この判断に根拠を持てることです。その問題は、今約束している結果を成立しなくするでしょうか。そうであれば、成立するところまで対応します。そうでなければ、別の範囲として扱います。「最小の変更」で必要な修正を隠してはいけませんし、「ついでの改善」で許可された範囲を広げてもいけません。

同じ回の内容と確認を一緒に締めくくります

一度検証に通った後で本文、metadata、クエリの規則を変えたら、前の結果をそのまま最終版の証拠にはできません。引き渡すときには、どの内容に対する確認なのかを把握する必要があります。異なる段階の成功メッセージをつなぎ合わせてはいけません。

私は引き渡しの説明を、実際に追加した結果、完了した確認、未完了またはサイト所有者の判断が必要な部分に分けます。範囲外のことは黙って省くのではなく、境界を明示します。

例えば、英日翻訳の一括作業なら、次のように書けます。「指定した版は校正済みで、ローカルの正式な出力に入りました。原文は変えていません。デプロイはしておらず、スマートフォンでの読みやすい見た目は、サイト所有者の確認が必要です。」これは引き渡し形式の例であり、この記事が新たな翻訳一式のテスト通過を宣言しているわけではありません。

タスクリストにすべてチェックが付いたことも、必ずしも引き渡しの成立を意味しません。実際のルート、主要な使用箇所、必要な許可がリストから抜けていたなら、完了条件を修正するべきです。リストを結果の保証に使ってはいけません。

小さく分けても避けられない仕事があります

データ移行、権限の規則、層をまたぐ契約は、まとめて成立させなければならない場合があります。変更するファイルを減らすために、新旧の規則が同時に働く過渡的な状態を残してはいけません。この記事は、このサイトの静的コンテンツの経験をもとに、そうしたシステムも同じように分けられると証明しているわけではありません。

先に分離できない契約を見つけ、それ以外の作業を小さくする方が適切です。変更範囲が大きくても、対応する検証とロールバックの条件は必要です。部分的な版を安全に引き渡せないなら、中途半端な結果を完了済みの増分として扱ってはいけません。

この記録の範囲

この記事は、原文が 2026 年 10 月 12 日に記録した、このサイトでの Button の基礎導入と複数回の記事翻訳の記録をもとに、変更範囲と完了条件の判断を整理しています。表、仮定した要件、引き渡しの引用文は、方法を示す例です。作業時間、エラー率、性能、協働の効率を新たに測定したわけではなく、小分けの変更が一括変更より必ず短時間で済むとも主張していません。

私の選択は、一回の仕事を具体的な結果に戻せるようにすることです。何を変え、何を変えずに保ち、次の段階に新しい許可が必要かを分かるようにします。小さく分ける目的は、理解と照合をしやすくすることであり、引き渡しを途中で止めることではありません。