エージェントにページの修正を頼むと、シンプルなプロジェクトによくわからない名前のファイルが現れます：index.html、style.css、script.js。あるいはファイルは前からあって、エージェントのレポートには"スタイルを変更しました"とだけ書かれている。この一文からは、エージェントが具体的に何を触ったのかわかりません。

ブラウザが受け取る3つの基本技術、HTML、CSS、JavaScriptを見ていきましょう。わかりやすくするために、ビルドなしのシンプルな静的ページを例にします。実際のリポジトリではファイルの名前や置き場所が違うこともあるので、編集の前にエージェントにプロジェクトの構造を見せてもらい、目的の要素を担当しているファイルを探してもらうとよいでしょう。この記事ではマークアップを手で書く方法は扱いません。そのためにエージェントがいます。

Webページはブラウザが読むテキストです

シンプルな静的ページから始めましょう。そのソースはごく普通のテキストファイルです。メモ帳で開いて、そのまま目で読めます。追加のビルドは要りません。ブラウザがHTMLを読み、そこからリンクされたリソースを読み込み、それをもとに画面にページを描画します。

このようなプロジェクトの出発点は、たいていindex.htmlファイルです。ブラウザはこれを開いてマークアップを解析し、リンクをたどってスタイル、スクリプト、画像、フォントを読み込みます。

ブラウザがシンプルな静的プロジェクトの3つのファイルを読み込み、完成したページを表示しますindex.htmlstyle.cssscript.jsブラウザ完成したページ
シンプルな静的プロジェクトは、たとえばこんな構成です。ブラウザが関連する3つのファイルを読み込み、ページを表示します

ビルドのあるプロジェクトでは、ソースがコンポーネントに分かれていることがあり、最終的なHTML、CSS、JavaScriptは専用のツールが生成します。以下で説明する役割分担は地図として役に立ちますが、そうしたプロジェクトでこの名前の3つのファイルをそのまま探す必要はありません。

今回のシンプルな例では、役割の違う3つのファイルを使います：

  • HTML - ページに何があるか：見出し、段落、ボタン、画像
  • CSS - どう見えるか：色、フォント、余白、角の丸み、動きのなめらかさ
  • JavaScript - 何が起こるか：クリックしたとき、テキストを入力したとき、タイマーで

ここから1つずつ見ていきます。

HTML: マークアップの構成要素

HTMLはマークアップであって、絵を描くものではありません。ボタンがどう見えるかを記述するわけではないのです。"ここにボタン"と書けば、あとはブラウザが自分なりのやり方で描いてくれます。

マークアップの基本単位はタグです。ほとんどの場合、タグは開きタグと閉じタグの2つで1組になり、その間に中身が入ります。

button プレイという行を開きタグ、中身、閉じタグの3つの部分に分解し、全体をHTML要素と表示した図<button>プレイ</button>HTML要素開きタグ閉じタグ中身
この例では、3つの部分が合わさってページの1つの要素になります

それぞれの部分に名前がありますが、全体をまとめて要素と呼びます。この言葉は覚えておくと便利です。ページの話では、タグとその中身をひっくるめて"要素"と言うことが多いからです。

タグの名前は英単語の略です：pはparagraph、aはanchor、imgはimageから来ています。暗記する必要はありませんが、知らないタグが何を担当しているのか見当をつけるのに役立ちます。

閉じタグはスラッシュが付いている点で見分けられます。閉じタグのない要素もあります。たとえば<img>はテキストや入れ子のタグを中に持てず、画像のアドレスはsrc属性で受け取ります。

タグは箱の中の箱のように入れ子になり、閉じるときは逆の順番、つまり内側が先で外側が後です。順番を間違えてもブラウザは止まりません。推測で補おうとします。ただ、その推測はたいてい外れます。

2つ目の概念は属性です。開きタグの中に書く補足情報で、その要素について何かを伝えます。リンクの行き先、画像の取得元、その要素を何と呼ぶか、といったことです。

<a href="https://example.com">サイトを開く</a>
<img src="cover.png" alt="表紙">
<button id="play" class="btn">プレイ</button>
Kotlin

最後の行のclass属性は、この後すぐに出てきます。これを手がかりにボタンにスタイルが適用されます。id="play"属性はボタンに一意の名前を付け、スクリプトはこの名前でボタンを見つけます。

次はページ全体です。思っているより短いですよ：

<!doctype html>
<html>
<head>
  <title>私のページ</title>
</head>
<body>
  <h1>最初のページ</h1>
  <p>通常のテキスト段落です。</p>
  <button id="play" class="btn">プレイ</button>
</body>
</html>

部分は2つです。<head>は管理用の部分で、タブのタイトルやスタイルへのリンクが入ります。<body>は、読む人が画面で目にするものすべてです。1行目は、これがモダンなHTMLだとブラウザに伝えているだけです。

ページの入れ子構造：htmlの中に、タブのタイトルを持つheadと、画面に見えるものすべてを持つbodyがあります<html></html><head></head><body></body><title>私のページ</title><h1>, <p>, <button>, <img>
箱の中の箱：headとbodyはhtmlの中にあり、それ以外はすべてその2つの中にあります

この図はマークアップのいちばん大事な性質を示しています。ページ上のものは、すべて何かの中に入っているということです。<body>は<html>の中、ボタンは<body>の中、テキストはボタンの中。ファイルの字下げが階段状になっているのもこのためです。見た目のためではなく、何が何の中にあるかを示しています。

実務上の結論はシンプルです。ブラウザのタブのタイトルとスタイルの読み込みは<head>にあり、画面にはまったく表示されません。それ以外はすべて<body>です。エージェントがレポートに"bodyにブロックを追加しました"と書いていたら、それはまさに2つ目の箱の話です。新しいものは管理用の部分ではなく、ページ上に追加されたということです。

HTMLのタグは100種類以上ありますが、実際のページで使われるのはほぼいつも同じ顔ぶれです：

タグ役割
<h1> ... <h6>見出し。いちばん大きいものから最も小さいものまで
<p>テキストの段落
<a>リンク。アドレスはhref属性に入る
<img>画像。ファイルへのパスはsrc属性に入る
<button>ボタン
<ul> と <li>リストとその項目
<div>ブロック単位のコンテナ。ほかの要素を入れる箱
<span>行の中のテキストの一部。そこだけ別扱いにするために使う

最後の2つは、それ自体では何の意味も持たず、何も描画しません。スタイルやスクリプトが手がかりにしやすい空の箱です。だからこそ、どのページでもいちばん数が多いのです。

CSS: ページの見た目はどう決まるか

素のマークアップは地味です。白地に黒い文字、灰色のシステム標準ボタン、すべてが左端に寄っています。これとデザインされたページとの差の大部分をつくっているのがCSSです。

CSSはルールの集まりです。ルールは2つの問いに答えます：何に適用するか、何を変えるか。

.btn {
  background: #6c5ce7;    /* 背景色 */
  color: #ffffff;         /* 文字色 */
  padding: 12px 24px;     /* 内側の余白 */
  border-radius: 12px;    /* 角の丸み */
}

1行目はセレクターで、このルールがどの要素に適用されるかを示します。続く波括弧の中に"プロパティ: 値"のペアが並び、それぞれセミコロンで終わります。

btnの前のドットはクラスを表します。ボタンのclass="btn"属性を覚えていますか。それがここで効いてきます。マークアップで要素に目印を付け、スタイルではその目印を指定するわけです。同じ目印を10個のボタンに付ければ、1つのルールで10個すべてが同じ見た目になります。

CSSのプロパティは何百もありますが、他人が書いたファイルを読んで何が起きているか理解するなら、いくつか知っていれば足ります：

  • color - 文字色、background - 背景の色または画像
  • font-size と font-family - フォントのサイズと書体
  • padding - 要素の内側の余白、margin - 外側の余白、つまり隣の要素との間隔
  • border-radius - 角の丸み。"高級感"の半分はこれでできています
  • transition - なめらかさ。パッと切り替わるのではなく、0.2秒かけて変わる

ルールはたいてい別のファイルに書かれていて、ページは管理用の部分にある1行でそのファイルの存在を知ります：

<head>
  <link rel="stylesheet" href="style.css">
</head>

この行を消すと、スタイルのファイルは読み込まれません。テキストや要素はマークアップに残りますが、見慣れた配置や装飾は消えるかもしれず、ページが使いにくくなることもあります。

同じマークアップを2回表示：左はスタイルなしでテキストと灰色の四角いボタン、右は同じ要素に余白、色、角の丸みが付いたものHTMLのみHTML + CSS
要素はまったく同じで、並び順も同じです。変わったのは色、余白、形だけです

図の左右は同じページです：見出し、2行のテキスト、ボタン。要素は1つも増えても減ってもいません。この例で編集したのはスタイルのファイルだけです。

これはどこを探すかの地図であって、技術的な壁ではありません。新しい配置のために、エージェントがHTMLのクラスやコンテナを変える必要が出ることもありますし、まずいCSSルールがボタンに覆いかぶさってクリックを妨げることもあります。だから見た目を編集した後は、diffを確認し、ページを開いて、影響を受けた操作を試します。

JavaScript: 操作したときに何が起こるか

HTMLとCSSだけでも、ページを表示し、なめらかな切り替えやアニメーションを付けることはできます。でも、この例のボタンにはまだ独自の動作がありません。押してもスコアは変わりません。

ページに自由なロジックを加えるのは、たいていJavaScriptです。ボタンにはすでにHTMLでid="play"という一意の名前が付いています。あとの流れはシンプルです：要素を見つけ、イベントを待ち、何かを変える。

// idでボタンを見つける
const button = document.getElementById("play");
let score = 0;

// イベントを登録する：クリックされたら何をするか
button.addEventListener("click", function () {
  score = score + 1;
  button.textContent = "スコア: " + score;
});

1回目のクリックで表示が"スコア: 1"に、2回目で"スコア: 2"に変わります。何も起きない場合は、まずHTMLにid="play"と書かれていて、スクリプトでも同じ名前playが使われているかを確認してください。

ポイントは3つです。constとletは変数、つまり値を入れておく名前付きの箱を作ります。addEventListenerは、クリック、テキスト入力、マウスオーバーといったイベントにページが反応するよう登録します。そして波括弧の中にあるのが関数、つまりイベントが起きたときに実行されるコードのまとまりです。

最後の行に注目してください。スクリプトがボタンのテキストを変えています。ここは大事なところです：JavaScriptは、ページが動いている最中にマークアップもスタイルも変えられます。段落を追加したり、ブロックを隠したり、ボタンの色を変えたりできます。つまり層どうしの境界は壁ではなく、役割分担です。

実際には、要素がデータに反応する、クリックを処理する、何かを計算する、といった場合はJavaScriptから探し始めましょう。ふわっと現れる表示、色の変化、ちょっとした動きはCSSで作られていることがよくあります。これは出発点であって、最終的な診断ではありません。編集の後はページを開き、見た目と動作を自分で確かめてください。スクリーンショット1枚では足りません。

1つのボタン、3つのファイル

ここまでの話を1つの要素でまとめましょう。"プレイ"ボタンは3つのファイルにまたがって存在していて、それぞれのファイルが自分の担当部分を受け持っています。

<button id="play" class="btn">プレイ</button>
.btn {
  background: #6c5ce7;
  border-radius: 12px;
}
const playButton = document.getElementById("play");

playButton.addEventListener("click", function () {
  playButton.textContent = "ゲーム開始";
});

ファイルがつながっていれば、クリックで表示が"プレイ"から"ゲーム開始"に変わります。これで、存在しない関数をでっち上げなくても例を試せます。

そして、ここからがいちばん役に立つところです。1つずつ取り除くと何が起きるでしょうか：

  • HTMLを取り除く - すべて消えます。スタイルを当てる対象も、動きを付ける対象もなくなります
  • CSSを取り除く - ボタンはそこにあって動きますが、見た目は90年代の灰色のシステムボタンです
  • JSを取り除く - ボタンはきれいなのに、中身は死んでいます。押せるけれど、何も起こりません

ここから、タスクを出すときのシンプルな地図が手に入ります。見た目が気に入らないならスタイルから、動作が気に入らないならスクリプトから探し始めてください。要素そのものがないなら、マークアップからです。あくまで"探し始める"場所です：実際の編集は隣の層に及ぶこともあるので、エージェントの結論はdiffとブラウザで確かめます。

プロジェクトフォルダーには何があるか

シンプルなページでいちばんよくある構成はこうです：

index.html    マークアップ、エントリーポイント
style.css     スタイル
script.js     動作

これらはマークアップの中の2行でつながっています。スタイルは管理用の部分で読み込み、スクリプトはいちばん最後、</body>で閉じる直前に読み込みます。スクリプトが動き出す時点で、すべての要素がもう存在しているようにするためです：

<head>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <!-- ページのマークアップ -->
  <script src="script.js"></script>
</body>

そうでない場合もあります。大きなプロジェクトではファイルが何十もあり、css/やjs/といったフォルダーに分けられ、そばに画像やフォントも置かれています。逆に、ファイルが1つしかないこともあります。このケースはすぐ下で扱います。マークアップ、スタイル、ロジックという役割は変わりませんが、ファイル名や読み込み方は違うことがあります。

スタイルやスクリプトがページの中にある場合

3ファイル構成はいちばんよくある形ですが、唯一の形ではありません。同じCSSでも置ける場所は3つあり、遅かれ早かれそのすべてに出会うことになります。

1つ目はもう見ました：別ファイルと<link>の1行です。2つ目は、別ファイルを作らずマークアップの中に直接書く<style>ブロックです：

<head>
  <style>
    .btn {
      background: #6c5ce7;
      border-radius: 12px;
    }
  </style>
</head>

中身はまったく同じです：セレクター、波括弧、"プロパティ: 値"のペア。変わったのは置き場所だけです。ページが1つしかなく、そのためにわざわざ別ファイルを作るまでもないときに、こう書きます。

3つ目の場所はインラインスタイルです。プロパティを要素に直接、style属性として書きます：

<button class="btn" style="background: #e17055; font-size: 20px">プレイ</button>

ここではセレクターは要りません。ルールがどれに適用されるかは明らかで、それが書かれている要素そのものです。だから波括弧もクラスの前のドットもなく、"プロパティ: 値"のペアをセミコロンで区切って1行に並べるだけです。

C++

便利なのは、その場1回きりのときだけです。その先は欠点が出てきます。ルールはたった1つの要素にしか効きません。ボタンが10個なら10個分のコピーが必要で、後から変えるときも10か所すべて直すことになります。さらに、通常のインラインスタイルは、ファイルに書いた通常のルールより基本的に優先されます。styleでボタンに色を付け、後でstyle.cssの同じプロパティを編集しても、なぜか色が変わらない、ということになります。だからstyle属性は真っ先に確認する場所の1つです。優先順位の細かいルールは、今はまだ知らなくて大丈夫です。

スクリプトも同じ話ですが、置き場所は2つです。別ファイルは<script src="...">で読み込みます。タグの間に直接コードを書くこともできます：

<script>
  document.getElementById("play").addEventListener("click", function () {
    alert("ゲーム開始");
  });
</script>

あとで見返せるように、表にまとめておきます：

何をどこに置くかHTMLでの書き方
スタイル別ファイル<link rel="stylesheet" href="style.css">
スタイルページ内のブロック<style> ... </style>
スタイル要素に直接style="color: red"
スクリプト別ファイル<script src="script.js"></script>
スクリプトページ内のブロック<script> ... </script>

極端なのは、全部が1つにまとまっている場合です：マークアップも<style>ブロックも<script>ブロックも、1つのindex.htmlに入っています。これは別に悪いことではありません。小さなページならむしろ手軽で、ファイルは1つ、ブラウザで開けば動き、途中で何かがはぐれる心配もありません。不便になるのはもっと後、ページが大きくなって、この長いファイルの中から何かを探す必要が出てきたときです。そうなると中身をファイルに分けるのが普通で、そこで例の3ファイル構成ができあがります。

エージェントに"スタイルを変えて"と頼む前に、スタイルがどこにあるかを確かめてください。プロジェクトにindex.htmlが1つだけなら、style.cssはないかもしれず、編集はマークアップの中で行われることになります。要素が変わらないときは、エージェントに3つの点を確認してもらいましょう：必要なスタイルファイルが読み込まれているか、セレクターが合っているか、インラインのstyleやもっと強いルールがないか。こうすれば、原因を当て推量せずに探す範囲を絞れます。

Claude Codeと組み合わせるとどうなるか

これで、エージェントがページに取りかかったときに何が起きているかがわかります：

  • シンプルな静的プロジェクトなら、エージェントがHTML、CSS、JavaScriptを自分で書いてつなげることもできます。別のプロジェクトでは、まず構造を見せてもらい、目的の要素を担当しているファイルを挙げてもらいましょう
  • 書き込みの前に何が見えるかは、設定と動作モードによって違います。エージェントが変更案を先に見せてくれるなら、目を通してください。書き込みの後は、いずれにしてもdiffと最終的なファイルを確認します。style.cssという名前はファイルの役割のヒントにはなりますが、それだけでは何も保証しません
  • 見た目の編集は、目で見て、影響を受けた要素をクリックして確認します。動作の編集は、実際に操作して確認します。スコアが数えられなくなったことは、スクリーンショットには写りません
  • 何かが壊れたら、当て推量した層ではなく、目に見える症状を伝えてください："編集後、ボタンは表示されるが、クリックしても何も起こらない"。そうすればエージェントがHTML、CSS、JavaScriptのつながりを確認してくれます