Reinvent Notes Blog https://notes.rewheel.dev/blog 個人的な技術発信ブログのフィード Sun, 14 Jun 2026 00:00:00 GMT https://validator.w3.org/feed/docs/rss2.html https://github.com/jpmonette/feed ja © 2026 rasshii <![CDATA[日本語 Web フォントと Core Web Vitals — LCP と CLS を実測で直す]]> https://notes.rewheel.dev/blog/core-web-vitals-japanese-fonts https://notes.rewheel.dev/blog/core-web-vitals-japanese-fonts Sun, 14 Jun 2026 00:00:00 GMT このサイト (notes.rewheel.dev) の SEO を点検したとき、技術的な項目はほぼ満点でした。sitemap も robots.txt も canonical も OGP も JSON-LD も揃っていて、Lighthouse の SEO スコアは全ページ 100。それなのに Performance だけが 58〜63 で止まっていました。

調べていくと、足を引っ張っていたのは Core Web Vitals の 2 つ — LCP (読み込みの速さ) と CLS (レイアウトのずれ) でした。そして犯人は、最初に疑った場所とは違うところにいました。LCP は日本語 Web フォントの読み込み方、CLS は本文の画像ではなくヘッダーのロゴ。この記事は、その犯人を実測で特定し、効かない対策を入れずに直すまでの記録です。

対象読者

Web フロントエンドの基本 (HTML/CSS、ブラウザの読み込み) が分かる方を想定しています。Docusaurus 固有の話も出ますが、render-blocking や CLS の考え方は静的サイト全般に通用します。

なぜ Core Web Vitals を直すのか​

Core Web Vitals は Google が定義したユーザー体験の指標で、検索ランキングのシグナルにもなっています。3 つの指標があり、2026 年時点の「良好 (good)」のしきい値は次のとおりです (web.dev より)。

指標測るものgoodpoor
LCP (Largest Contentful Paint)主要コンテンツが描画されるまでの時間≤ 2.5s> 4.0s
CLS (Cumulative Layout Shift)読み込み中の累積レイアウトずれ< 0.1> 0.25
INP (Interaction to Next Paint)操作への応答の速さ< 200ms> 500ms

「技術的 SEO が満点なら十分では」とも思えますが、SEO スコアはあくまで 機械可読性 の点検です。タイトルや構造化データが正しくても、ページが遅かったり読み込み中にガクッとずれたりすれば、ユーザーは離脱しランキングも伸びません。CWV は、その 体感 の側を数値化したものです。

このサイトの前提

Docusaurus v3.10 で構築した静的サイトで、本文フォントに日本語の Klee One を使っています。日本語 Web フォントはグリフ数が多くファイルが大きいため、CWV では英語サイトと違うクセが出ます。そこが今回の肝でした。

ベースライン何が「未達」だったのか​

まず本番 (notes.rewheel.dev) を Lighthouse のモバイル設定 (CPU 4x スロットリング) で計測しました。

ページPerformanceLCPCLSSEO
トップ (/)589.3s0100
ブログ記事624.4s0.287100
ドキュメント634.1s0.305100

LCP は全ページが poor (4 秒超)、CLS はブログとドキュメントが poor (0.25 超)。SEO は満点。問題の所在がはっきりしました。Performance、それも LCP と CLS です。

ここから 2 つの犯人を別々に追いました。

犯人 1LCP を遅らせていた render-blocking なフォント​

Lighthouse の render-blocking-insight が指していたのは、<head> で同期読み込みしている CSS でした。中でも重かったのが Google Fonts の CSS です。

当時の指定はこの 4 ファミリを 1 つの URL でまとめて読み込んでいました。

https://fonts.googleapis.com/css2?family=Klee+One&family=Noto+Sans+JP&family=Inter&family=JetBrains+Mono

問題は日本語フォント (Klee One / Noto Sans JP) です。日本語は常用漢字だけで 2,000 字を超え、フォントは数百のサブセットファイルに分割して配信されます。CSS 本体だけで約 150KB あり、しかもこれが render-blocking — つまりブラウザはこの CSS を取得し終えるまで本文を描画できません。CPU とネットワークが絞られたモバイルでは、ここで数秒が溶けていました。

ブラウザの読み込みを図にするとこうなります。同期読み込みでは、フォント CSS が First Paint の手前に割り込んでいます。

さらに 2 つの無駄がありました。

  • Inter は読み込んでいるのに使っていなかった。font-family のどこにも Inter は登場せず、純粋に転送量を増やすだけのファミリでした。
  • KaTeX の CSS も全ページで同期読み込みしていました。数式は一部の記事にしか出ないのに、トップページでも render-blocking になっていました。

犯人 2CLS を起こしていたのは画像ではなくロゴ​

CLS の方は、最初フォントを疑いました。Web フォントは読み込み完了時にフォールバックから切り替わる (swap) ので、字幅が変わって行が組み直され、レイアウトがずれる — というのは典型的な CLS 要因です。

ところが数字が合いません。CLS が高いのはブログ (0.287) とドキュメント (0.305) で、ほぼ同じ値。もしフォント swap が主犯なら本文量に応じて差が出るはずですが、そうなっていない。そして決定的だったのが、hero 画像を持たないドキュメントページでも CLS 0.305 だったことです。本文中の画像が犯人なら、画像の無いページでは下がるはず。下がっていない。

つまり犯人は 全ページに共通する要素。それは <head> の次に来る navbar、その中のロゴでした。

navbar のロゴ <img> に width/height が無いと、ブラウザは読み込み前にロゴの占める領域を確保できません。いったん高さ 0 で本文を上に詰めて描画し、ロゴ画像が届いた瞬間に領域を確保して本文を下へ押し下げる。これが累積されて CLS になっていました。

教訓

CLS の調査は「本文の派手な要素」から疑いがちですが、まず 全ページ共通のヘッダー/フッターに寸法未指定の画像が無いかを見るほうが早いことが多いです。共通要素は全ページの CLS を底上げします。

フォント swap については、この時点では「副次的に効いているかもしれない」と保留にしました。後で実測して決着をつけます (伏線)。

対策の実装​

特定できた原因に対して、5 つ手を入れました。前半 3 つが CWV へ直接効く本丸です。

1. 未使用の Inter を削除​

font-family に存在しない Inter を Google Fonts の URL から外しました。見た目はまったく変わらず、転送量だけが減ります。リスクゼロの純利益です。

2. navbar ロゴに width/height を付与​

CLS の主犯への直接の対処です。Docusaurus の navbar.logo は width/height を受け付けます。

docusaurus.config.ts
navbar: {
  logo: {
    alt: 'Reinvent Notes Logo',
    src: 'img/logo.svg',
    // CLS 対策: 読み込み前に領域を確保する (実測した CLS の主因)
    width: 32,
    height: 32,
  },
  // ...
}

これでブラウザは読み込み前にロゴ領域を予約でき、画像到着時の押し下げが起きなくなります。

3. フォントと KaTeX の CSS を非同期化​

LCP の主犯への対処です。render-blocking を解消するため、preload で取得しておき、読み込み完了時に rel="stylesheet" へ差し替える定番パターンに移しました。Docusaurus では headTags で <head> にタグを注入できます。

docusaurus.config.ts
headTags: [
  {
    tagName: 'link',
    attributes: {
      rel: 'preload',
      as: 'style',
      href: 'https://fonts.googleapis.com/css2?family=Klee+One:wght@400;600&family=Noto+Sans+JP:wght@400;500;700&family=JetBrains+Mono:wght@400;500&display=swap',
      // 読み込み完了時に stylesheet へ昇格させ、render-blocking を回避する
      onload: "this.onload=null;this.rel='stylesheet'",
    },
  },
  // KaTeX CSS も同じ要領で非同期化（数式の無いページの render-blocking を解消）
  // JS 無効環境向けに <noscript> で同期版のフォールバックも併記する
],

読み込みのタイムラインは、同期から非同期へこう変わります。

修正後はフォールバックの system-ui でまず描画し、フォントが届いてから差し替えます。display=swap を付けているので、フォント取得中もテキストは見えたままです (FOIT を避けられます。詳しくは MDN: font-display)。

あわせて、これまで custom.css の @import で読んでいたフォントも headTags 側へ寄せ、CSS 内 @import による直列読み込みを解消しました。

4. 画像を WebP 化​

トップの hero 画像と OGP の social-card を PNG から WebP へ差し替え、旧 PNG は削除しました。hero は約 90% の軽量化です。LCP 候補になりうる大きな画像の転送量を下げる効果があります。

5. llms.txt の生成（おまけ）​

CWV とは別軸ですが、AI クローラ向けに /llms.txt をビルド時生成するプラグインも足しました。生成 AI 経由の流入 (GEO/AEO) を意識した対応です。

検証スロットリングなしでは CLS は測れない​

修正の効果は、測り方を間違えると見えません。最初、ローカルのビルドを制限なしで計測したら CLS は 0.01。これでは元の 0.3 がどこへ行ったのか分かりません。

種明かしは CLS はネットワーク/CPU の遅さに強く依存する点にあります。回線が速いとフォントもロゴも一瞬で届き、シフトが起きる前に描画が固まってしまう。本番のモバイル相当の遅さを再現しないと、そもそも問題が再現しないのです。

そこで Chrome DevTools (MCP 経由) の performance trace で、本番相当のスロットリングをかけて計測しました。

CPU:      4x スロットリング
Network:  Slow 4G
Viewport: 360 x 640 @2x（モバイル・タッチ）

この条件で、ロゴに寸法を付けたあとのドキュメントページを再計測した結果がこれです。

ページ修正前 CLS修正後 CLS
ドキュメント (カテゴリ)0.3050.00
ドキュメント (本文 250KB)—0.00

本文量の多いページでも 0.00。DevTools の CLSCulprits インサイトも「該当するレイアウトシフトなし」で、シフトそのものが消えました。

LCP の本番値について

LCP もローカルでは大きく改善しましたが、localhost には CDN までの往復遅延が無いため、この数値を本番の LCP と直接比べることはできません。本番 after の LCP は別途あらためて計測する必要があります (この記事では断定しません)。確実に言えるのは「render-blocking だったフォント/KaTeX CSS を critical path から外した」という構造の変化までです。

size-adjust を入れなかった理由​

ここで、保留にしていたフォント swap の話に戻ります。

日本語フォントの CLS 対策としてよく挙がるのが、フォールバックフォントに size-adjust を効かせて Web フォントとメトリクスを揃える手法です。swap の瞬間に字幅・行高が変わらないようにして、組み直しによるシフトを防ぐものです。「日本語フォント + CLS」と来れば、これを入れるのが定石にも見えます。

しかし今回は 入れませんでした。理由は、実測でフォント swap が CLS にほぼ寄与していないと分かったからです。ロゴに寸法を付けただけで、本文量の多いページでも CLS は 0.00。swap で組み直しが起きているなら、ここに値が残るはずですが、残っていません。

構造的にも説明がつきます。本文の行の高さは、custom.css でこう決めています。

:root {
  --ifm-font-size-base: 16px;
  --ifm-line-height-base: 1.8; /* 単位なし */
}

line-height が 単位なし (1.8) で、font-size が固定 (16px)。すると 1 行の高さは常に 16px × 1.8 = 28.8px で、どのフォントに swap しても行ボックスの高さは変わりません。縦方向の組み直しが起きにくい構造になっていたわけです。

計測してから決める

size-adjust は正しい手法ですが、それが効くのは「フォント swap が実際に CLS を起こしている」ときだけです。今回はその前提が成立していませんでした。効くか分からない対策を「念のため」入れると、検証されないコードが残り、メンテナンスの負債になります。 目的の指標 (CLS) を計測し、達成済みなら追加の防御は入れない — そう判断しました。

ひとつ正直に補足すると、今回の after 計測はフォントがキャッシュ済みの状態 (warm cache) での swap を見ています。完全な初回訪問 (cold) では、字幅の差で行が再ワラップして微小な CLS が出る理論的な余地は残ります。ただし以前 cold に近い高速条件で測ったときも CLS は 0.01 で、good のしきい値 0.1 の 1/10。実害が出る水準ではないと判断しています。気になる場合は cold cache を分離した計測でさらに詰められます。

まとめ​

このサイトの Core Web Vitals を直して分かったことは、突き詰めると 3 点です。

  • LCP の主犯は日本語 Web フォントの render-blocking だった。150KB の同期 CSS を preload → swap で非同期化し、未使用の Inter を外して critical path から退けた。
  • CLS の主犯はフォントではなく、寸法未指定の navbar ロゴ だった。画像の無いページでも CLS が高いことが決め手で、width/height を付けるだけでシフトが消えた。
  • size-adjust は計測の結果として入れなかった。単位なし line-height のおかげで swap による組み直しが小さく、CLS は既に 0。効かない対策を足さないことも最適化のうち。

「日本語フォントが重い → とにかくフォント対策」と短絡せず、LCP と CLS をそれぞれ計測して別々の犯人を特定したのが効きました。次にやるなら、本番 after の LCP 再計測と、cold cache を分離した CLS の詰めです。

関連リソース
]]> performance core-web-vitals docusaurus web-font seo <![CDATA[hero に車が走るアニメーションを実装した]]> https://notes.rewheel.dev/blog/hero-car-animation https://notes.rewheel.dev/blog/hero-car-animation Tue, 02 Jun 2026 00:00:00 GMT このサイト「Reinvent Notes」のトップページを開くと、車が走り抜けていくアニメーションが目に入ります。Docusaurus の hero に自前で実装したメインビジュアルで、SVG の線画を React コンポーネント化し、タイヤの回転と背景のパララックスをすべて CSS で動かしています。

派手なアニメーションライブラリは使わず、svgr (Docusaurus 同梱) と純粋な CSS だけで作りました。テーマのライト / ダーク切り替えにも追従し、prefers-reduced-motion を有効にしている人には静止画として見せています。

この記事は、Web 開発を始めたばかりの人でも最後まで追えること を目標に書きました。そのため「SVG とは何か」「viewBox とは」「CSS の mask とは」といった基礎から順番に説明し、その土台の上で実装を読み解いていきます。長くなりますが、一つひとつの仕組みが分かるように噛み砕いたので、気になる章から拾い読みしても構いません。

2026-06-13 改訂

公開後にデザインを調整したため、現行の実装に合わせて本文を更新しました。主な変更は 3 つです。ビルを 2 層にして窓を抜いたこと、街路の標識・街灯などを車と同じ線画にしたこと、ループの境目で背景がカクッとずれる問題を直したこと。とくに 3 つ目は「無限ループの章」をまるごと書き直しています。

なぜ車なのかReinvent Notes とロゴの必然性​

このブログのテーマは、サイト名そのままに 「車輪の再発明 (reinventing the wheel)」 です。タグラインも「車輪を再発明して学ぶ」。既存のツールや概念をあえて自分で作り直すことで仕組みを深く理解する——そういう学びを記録する場所として運営しています (この名前に至った経緯は ブログのドメインを notes.rewheel.dev に変更しました に書きました)。

このサイトのロゴは、文字通り 車輪 です。外周のリムと中心のハブ、そして 4 本のスポークだけのシンプルな図形で、favicon にも同じものを使っています。

ある日ふと、「ロゴの車輪が止まったままなのはもったいない」と思いました。トップページくらいは、この車輪を実際に回してみたい。車輪が回るなら、いっそ車体に乗せて走らせてしまおう——というわけで、hero に「車が走るアニメーション」を置くことにしました。サイトの世界観を一目で伝える装飾であり、同時に「車輪の再発明」というコンセプトを動きで表現する小さな試みです。

完成形何が動いているのか​

まず、画面で何が起きているのかを大づかみに把握しておきましょう。細かい数値はあとの章で扱うので、ここでは 「どんな部品が、どう重なって、どう動くか」 だけを押さえます。

中央に線画の車があり、前輪と後輪が回転しています。車体は左を向いていて、背景の雲・ビル・街路の標識や街灯・路面の破線が右へ流れていきます。背景が右に流れると、相対的に車が左へ進んでいるように見える——という仕掛けです。

色はテーマに追従します。ライトモードでは落ち着いた sage green、ダークモードでは明るい緑。背景のビルや街路、雲もすべて同じ色なので、テーマを切り替えると全体の色がまとめて変わります。

ライトテーマのトップページ hero。sage green で車と背景が統一されている

同じ hero をダークテーマで開いたところ。currentColor が明るい緑に切り替わる

画面には、奥から手前へ次の部品が重なっています。いちばん奥に雲、その手前に遠景のビル、中景のビル (窓付き)、街路 (標識・街灯・街路樹・信号機)、路面、そしていちばん手前に車。これを図にすると、こうなります。

ここで 1 つ大事なポイントがあります。この重なり順は、CSS で重なりを指定する z-index ではなく、HTML に書いた順番 で決まっています。後に書いた要素ほど手前に重なる、というブラウザの基本ルールをそのまま使っているだけです。だから雲を最初に、車を最後に書いています。

「なぜ HTML の順番で重なるのか」「なぜ部品が縦に積まれず同じ場所に重なるのか」は、次の章の CSS の基礎で説明します。

CSS レイアウトの基礎​

この章では、背景や車を「同じ場所に重ねて配置する」ために使っている CSS の道具を 3 つ押さえます。実装で何度も出てくる前提知識なので、先に固めておきましょう。

position と要素の重なり​

ふつう、HTML の要素は上から下へ順番に「積まれて」並びます。段落を 2 つ書けば、2 段に並びますよね。

ところが、この hero では雲もビルも車も 同じ場所に重ねたい。それを実現するのが position: absolute です。

  • position: relative を付けた要素は「基準点」になります。この hero では親要素 .scene がこれにあたります。
  • position: absolute を付けた子要素は、通常の「積み上げ」の流れから外れて、基準点 (.scene) を原点として自由な位置に浮かびます。

.scene の中の雲・ビル・街路・路面・車は、すべて position: absolute で浮いています。だから縦に積まれず、同じ .scene の上に重なって配置されるのです。そして重なったときの前後関係が、前章で触れた「HTML に書いた順番」で決まります。

.scene {
  position: relative;   /* 子要素の配置の基準点になる */
  overflow: hidden;     /* はみ出した背景を枠の外に見せない */
}
.clouds {
  position: absolute;   /* .scene を基準に浮く */
}

overflow: hidden は、枠 (.scene) からはみ出した部分を切り取って見せなくする指定です。背景は枠より広く作って流すので、これがないと横にはみ出してしまいます。

% は何に対する割合か​

この実装では、位置やサイズの多くを % (パーセント) で指定しています。left: 78%、top: 80%、height: 38% のように。

CSS の % は、原則として 親要素のサイズに対する割合 です。雲レイヤの height: 38% は「親 .scene の高さの 38%」、タイヤの left: 78% は「親 .car の幅の 78% の位置」という意味になります。

% を使う利点は、画面幅が変わっても比率が保たれる ことです。スマホでも PC でも、タイヤは車体の同じ位置に付いてきます。ピクセル固定だと画面サイズごとに調整が必要ですが、% なら 1 つの値で追従してくれます。

ただし例外もあります。この実装では、ビルと街路のレイヤの高さだけは あえてピクセル固定 にしています。なぜ % にしないのかは、無限ループの章で説明します。

::after 疑似要素と background​

最後に 3 つ、背景描画でよく使う道具を紹介します。

::after 疑似要素 は、HTML を増やさずに「その要素の後ろに、もう 1 つ仮想の子要素を生やす」CSS の機能です。この hero では、路面 .road に .road::after を生やして「流れる破線」を作っています。content: '' を書くと中身が空の要素が現れ、そこに自由な見た目を与えられます。

background 系のプロパティ は背景の塗り方を決めます。よく使うのは次の 4 つです。

  • background-color: 背景を単色で塗る。
  • background-image: 背景に画像やグラデーションを敷く。
  • background-size: 敷いた背景 1 枚分の大きさ。
  • background-repeat: 背景を繰り返すかどうか (repeat-x なら横方向に繰り返す)。

そして opacity は要素全体の 透明度 です。1 で不透明、0 で完全に透明。0.2 のように小さくすると、その要素がうっすら透けます。この hero では、奥のレイヤほど薄くして奥行きを強めるのに使っています。

これらを組み合わせると、画像ファイルを用意しなくても CSS だけで雲や破線を描けます。詳しくは背景の章で見ていきます。

まずは基礎からSVG とは何か​

車体とタイヤの素材は SVG という形式の画像です。アニメーションの主役なので、まず SVG が何者なのかを理解しておきましょう。

ベクター画像とラスター画像​

画像には大きく 2 種類あります。

  • ラスター画像 (JPEG / PNG など): 写真のように、小さな点 (ピクセル) の集まり で絵を表します。拡大すると点が大きくなり、ぼやけたりギザギザになったりします。
  • ベクター画像 (SVG): 「ここからここへ線を引く」「半径◯◯の円を描く」という 図形の指示 (座標と数式) で絵を表します。拡大しても指示を計算し直して描くだけなので、どれだけ大きくしても劣化しません。

SVG は Scalable Vector Graphics の略で、まさに「拡大縮小できるベクター画像」という意味です。車のロゴやアイコンのような線画は、SVG にぴったりの題材です。

SVG の中身はテキスト (XML) で、こんな図形要素を組み合わせて絵を作ります。

  • <rect>: 長方形
  • <circle>: 円
  • <polygon>: 多角形
  • <path>: 自由な曲線・輪郭 (いちばん表現力が高い)

viewBox は「座標を切り取る窓」​

SVG を理解するうえで最重要なのが viewBox です。SVG は座標で図形を描きますが、その**「どの座標範囲を表示枠に映すか」を決める窓** が viewBox です。

viewBox は 4 つの数値で指定します。

viewBox="min-x min-y width height"
  • min-x / min-y: 映し始める左上の座標。
  • width / height: そこから右・下に向かって、どれだけの範囲を映すか。

つまり「座標 (min-x, min-y) を左上として、幅 width・高さ height の長方形を切り取り、それを画面の枠いっぱいに引き伸ばして表示する」という指示です。下の図で確認してください。

説明用の図です（実装の car.svg そのものではありません）
(min-x, min-y)映し始める左上の座標width（映す幅）height

実際の車体 car.svg は viewBox="83 349 2650 747" です。座標 (83, 349) を左上として、幅 2650・高さ 747 の横長の範囲を切り取っています。横長なのは、横向きの車のシルエットを過不足なく収めるためです。

<g> グループと path・fill・stroke​

もう少しだけ SVG の部品を知っておきましょう。あとの章で「色が変わらなかった事件」を読み解くのに必要になります。

  • <g>: 複数の図形を 1 つに グループ化 するタグです (group の g)。まとめて移動・拡大したり、まとめて色を指定したりできます。
  • <path>: 前述の「自由な輪郭」を描く要素。車の線画は、いくつもの <path> でできています。
  • fill: 図形の 内側の塗り色。
  • stroke: 図形の 輪郭線の色。

ここで覚えておいてほしい性質が 1 つあります。fill 属性が指定されていない図形は、デフォルトで黒で塗られます。逆に言えば、fill 属性が無いということは、あとから CSS で色を上書きできる余地がある、ということです。この伏線は最後の「ハマりどころ」の章で回収します。

currentColor と CSS の色の借り方​

この実装の 色まわりの心臓部 が currentColor です。一度理解すれば、テーマ追従の仕組みが一気に腑に落ちます。

currentColor は CSS のキーワードで、「いま効いている color プロパティの値を借りてくる」 という意味です。color は本来「文字の色」を決めるプロパティですが、currentColor と書くと、文字以外のプロパティ (fill や background-color やグラデーション) でも同じ色を使い回せます。

たとえばこう書くと：

.box {
  color: green;              /* この要素の「現在の色」は緑 */
  border: 2px solid currentColor;  /* 枠線も緑（color を借りる） */
  fill: currentColor;        /* SVG の塗りも緑 */
}

color を 1 か所変えるだけで、currentColor を使っているすべての場所の色がまとめて変わります。

この hero では、.scene (アニメーション全体の親) に color を 1 つ置き、車・タイヤ・雲・ビル・標識・路面の塗りをすべて currentColor で参照しています。だから テーマを切り替えて .scene の color が変わると、画面全体の色が一斉に追従する のです。「色の指示は 1 か所、あとはみんなそれを借りる」という設計になっています。

CSS アニメーションの基礎​

動きの部分に入る前に、CSS で物を動かす道具を 4 つ押さえます。

@keyframes と animation​

CSS アニメーションは 2 つの部品でできています。

  • @keyframes: アニメーションの 振り付け。「開始 (from) はこの状態、終了 (to) はこの状態」と書きます。
  • animation: その振り付けを どう再生するか。かける時間・繰り返し回数・速度の変化のしかたを指定します。

最小の例はこうです。

/* 振り付け: 左から右へ動く */
@keyframes slide {
  from { transform: translateX(0); }
  to   { transform: translateX(100px); }
}

/* 再生: slide を 2 秒かけて・無限に・一定速度で */
.box {
  animation: slide 2s linear infinite;
}
  • 2s は 1 回の再生にかける時間。短いほど速く動きます。
  • linear は速度変化のしかた。linear は「最初から最後まで一定速度」という意味で、車や背景のように一定で流れ続けるものに向いています。
  • infinite は「ずっと繰り返す」。

transform移動と回転​

transform は要素を 変形 させるプロパティです。この hero では主に 2 つを使います。

  • translate(x, y): 平行移動 (ずらす)。translateX は横だけ、translate3d(x, y, z) は 3 次元版 (後述)。
  • rotate(角度): 回転。rotate(360deg) で 1 回転、マイナスを付けると逆回りになります。

回転には どこを軸に回すか という基準点があり、それが transform-origin です。transform-origin: center なら要素の中心を軸に回ります。タイヤをきれいに回すには、この軸が重要になります (次章)。

そしてもう 1 つ、必ず覚えておきたい落とし穴があります。transform は後勝ちで、まるごと上書きされる という性質です。translate と rotate の両方を効かせたいなら、transform: translate(...) rotate(...) のように 1 つの transform にまとめて書く 必要があります。片方だけ書くと、もう片方は消えます。これがタイヤ実装でハマるポイントです。

translate3d と GPU 合成​

translate3d(x, y, 0) は translate の 3 次元版ですが、見た目の動きは translate(x, y) と同じです。ではなぜ 3d を使うのか。

ブラウザは、translate3d のような変形を GPU (画像処理専用の装置) に任せる ことができます。GPU に任せると、ページの再計算 (どこに何を並べ直すか、という重い処理) を起こさずに、要素だけをスッと動かせます。結果として 動きが滑らかになり、カクつきにくくなる のです。

さらに will-change: transform を添えると、「この要素はこれから transform で動きますよ」とブラウザに事前予告でき、最適化を促せます。この hero では、流れる背景と回るタイヤすべてに translate3d + will-change を使っています。

prefers-reduced-motion動きを減らす配慮​

最後に、見落としがちですが大切な配慮です。OS には 「視差効果を減らす」「動きを減らす」 という設定があります (めまいを起こしやすい人などのための機能)。

CSS はこの設定を @media (prefers-reduced-motion: reduce) というメディアクエリで読み取れます。この設定が ON の人には、アニメーションを止めて静止画として見せる——という出し分けができます。実装の最後でこれを使います。

パララックスの仕組み​

背景に奥行きを出しているのが パララックス (parallax) です。電車の窓から外を見ると、近くの電柱はビュンと速く流れ、遠くの山はゆっくり動いて見えますよね。あの 「近いものほど速く、遠いものほど遅く動く」 効果がパララックスです。

この hero でも、奥のビルはゆっくり、手前の路面の破線は速く流すことで、平面なのに奥行きを感じさせています。レイヤごとの速さは「1 周で動く距離 ÷ 1 周にかける時間」で決まります (距離と時間の具体値は実装の章で見ます)。

                流れる速さ         イメージ
 奥   遠景ビル   毎秒 約 24px      ──→            （いちばんゆっくり）
      中景ビル   毎秒 約 40px      ────→
      雲         毎秒 約 60px      ──────→
      街路       毎秒 約 93px      ──────────→
 手前 路面の破線  毎秒 約 233px     ──────────────→（いちばん速い）
      タイヤ     1.1 秒で 1 回転    ◯ くるくる回転

(これは静的な図です。実際の動きはトップページで確認してください。)

奥ほど遅く、手前ほど速い。これだけで奥行きが生まれます。なお、これらの速さに理論的な正解はなく、実際の画面を見ながら「それらしく」調整した値です。

継ぎ目なく無限ループさせる仕掛け​

もう 1 つの工夫が、途切れずに延々と流れ続ける ループです。

背景の各レイヤは、同じ絵 (タイル) を横に繰り返し敷き詰めたものです。これを一定距離だけ横に動かし、動き終わったら開始位置に瞬間的に戻す——を繰り返すと無限ループになります。問題は、開始位置に戻った瞬間、絵がズレて見えないか です。

ここには明確な条件があります。動かす距離が「タイル 1 枚の幅」のちょうど整数倍 なら、戻った後の見た目は戻る前と完全に一致します。同じ絵がタイル幅ごとに繰り返されているので、タイル何枚ぶんズレても見分けがつかないからです。逆に、整数倍からずれた距離で戻すと、その瞬間に背景がカクッと飛びます。

タイル幅 600px の絵を敷き詰め、ちょうど 2 枚ぶん (1200px) 動かして戻す。

  開始        │[タイル][タイル][タイル][タイル]…
              └── 表示窓 ──┘

  1200px 移動 │        [タイル][タイル][タイル]…
              └── 表示窓 ──┘
                 ↑ どのタイルも同じ絵なので、2 枚ぶんズレても見た目は同一。
                   ここで開始位置に瞬間的に戻しても、見分けがつかない。

実は、この hero の最初の実装は「画面幅の 100% ぶん動かして戻す」方式でした。一見問題なさそうですが、画面幅はタイル幅の整数倍とは限りません。たとえば画面幅 1440px・タイル幅 600px なら 1440 ÷ 600 = 2.4 枚ぶん。ループのたびに 0.4 枚ぶん絵が飛び、「背景が一定のタイミングでカクッと動く」バグになっていました。

そこで現在の実装では、動かす距離を タイル幅のちょうど 2 倍の px 値 に固定しています。距離を px で確定させるには、タイル幅も px で確定している必要があります。ビルと街路のタイル (後述する mask) は「レイヤの高さに合わせて拡大縮小」されるため、レイヤの高さを px 固定 にすることでタイル幅を確定させました。% の章で予告した例外がこれです。具体的なコードは実装の章で見ます。

実装SVG をコンポーネント化する​

ここからは実際のコードです。まず素材の SVG を React で使えるようにします。

素材は車体の car.svg とタイヤの tire.svg の 2 枚です。Docusaurus の classic preset には svgr という仕組みが同梱されていて、SVG を import するだけ で React コンポーネントとして扱えます。

import React from 'react';
import clsx from 'clsx';
import Car from '@site/static/img/car.svg';
import Tire from '@site/static/img/tire.svg';
import styles from './HeroCarAnimation.module.css';

あとは普通のコンポーネントとして配置します。car.svg は車輪まで描かれた完成車なので、その前後輪の位置に tire.svg を 2 枚重ねて、タイヤだけを回転させる構成にしました。コンポーネント全体はこうです (clsx は複数のクラス名を 1 つにまとめるユーティリティで、ここでは共通の tire と個別の tireRear / tireFront を合成しています)。

export default function HeroCarAnimation(): React.ReactElement {
  return (
    <div className={styles.scene} aria-hidden="true">
      <div className={styles.clouds} />
      <div className={styles.buildingsFar} />
      <div className={styles.buildingsMid} />
      <div className={styles.street} />
      <div className={styles.road} />
      <div className={styles.car}>
        <Car className={styles.carBody} />
        <Tire className={clsx(styles.tire, styles.tireRear)} />
        <Tire className={clsx(styles.tire, styles.tireFront)} />
      </div>
    </div>
  );
}

返り値の型 React.ReactElement を明示し、<div> 1 つを頂点に、背景レイヤ → 車の順で子要素を並べているだけのシンプルなコンポーネントです。

完成形の章で見た「奥から手前へ」の重なり順が、そのまま HTML の記述順 (clouds → buildingsFar → buildingsMid → street → road → car) になっているのが分かります。ビルが buildingsFar (遠景) と buildingsMid (中景) の 2 層に分かれているのは、流す速さと濃さを変えて奥行きを強めるためです。

*.svg 用の型定義ファイル (svg.d.ts) を自分で書く必要はありませんでした。Docusaurus の型設定にコンポーネント宣言が含まれているため、yarn typecheck もそのまま通ります。

実装テーマ色への追従​

currentColor の章で学んだ仕組みを、ここで実際に使います。色の制御は CSS の color 1 か所に集約できるので、.scene (アニメーション全体の親) に color を与えるだけで、配下の車・タイヤ・背景すべてに伝わります。

.scene {
  position: relative;                      /* 背景・車（子要素）の配置基準になる */
  width: 100%;
  margin: 2.5rem auto 0;
  height: clamp(220px, 30vw, 300px);       /* 高さを先に予約してレイアウトのガタつきを防ぐ */
  color: var(--ifm-color-primary-darker);  /* この色を配下の currentColor が借りる */
  overflow: hidden;                        /* 枠からはみ出した背景を隠す */
}

[data-theme='dark'] .scene {
  color: var(--ifm-color-primary-light);
}

.scene は色だけでなく、子要素の配置基準 (position: relative)、高さの予約 (height: clamp(...)：読み込み時のガタつき防止)、はみ出した背景を隠す overflow: hidden もまとめて担う、このアニメーションの土台です。色について言うと、ライトでは少し濃い sage green (--ifm-color-primary-darker)、ダークでは明るい緑 (--ifm-color-primary-light) を使っています。[data-theme='dark'] は「ダークモードのとき」を表す Docusaurus の指定で、テーマを切り替えると color が差し替わります。どちらも Docusaurus が用意しているテーマ変数をそのまま参照しているだけで、この機能のために新しい色を定義してはいません。

そして車体とタイヤの線画は、CSS でこう塗っています。

.carBody path,
.tire path {
  fill: currentColor;
}

SVG の path の塗り (fill) を currentColor にしているので、.scene の color がそのまま線画の色になります。

なぜ CSS で塗る必要があるのか

「SVG の色は SVG ファイル側で決まっているのでは？」と思った人もいるかもしれません。実はここに、この実装でいちばんハマったポイントが隠れています。なぜ fill: currentColor をわざわざ CSS で書くのか の種明かしは、最後の「ハマりどころ」の章で詳しく語ります。いまは「色は .scene の color 1 つで決まる」とだけ覚えておいてください。

実装タイヤを軸ブレなく回す​

タイヤを回すときに気をつけたのは、回転軸がブレないこと です。回転の軸 (中心) がホイールの中心からずれていると、回したときにガタガタ揺れて見えてしまいます。

SVG 基礎の章で学んだ viewBox が、ここで効いてきます。tire.svg の viewBox は 正方形 にクロップしてあります。

static/img/tire.svg
<svg viewBox="682 41 1450 1450" fill-rule="evenodd">

幅も高さも 1450 で正方形です。viewBox が正方形なら、その枠の中心がそのままホイールの中心になります。あとは CSS で「要素の中心を軸に回す」だけで、軸ブレなく回転します。横長の枠だと中心がずれてしまうので、ここは正方形であることが重要です。

説明用の図です
正方形の viewBox（幅 = 高さ）枠の中心 ＝ ホイールの中心 ＝ 回転軸

CSS 側はこうです。

.tire {
  position: absolute;
  width: 17%;
  aspect-ratio: 1 / 1;               /* 縦横比を 1:1（正方形）に保つ */
  top: 80%;
  transform: translate(-50%, -50%);  /* 自分の中心を配置基準に合わせる */
  transform-origin: center;          /* 回転の軸 = 要素の中心 */
  animation: hero-tire-spin 1.1s linear infinite;
}

@keyframes hero-tire-spin {
  from { transform: translate(-50%, -50%) rotate(0deg); }
  to   { transform: translate(-50%, -50%) rotate(-360deg); }
}

aspect-ratio: 1 / 1 は「縦と横の比を 1:1 に保つ」指定で、要素自体も正方形に保ちます。transform: translate(-50%, -50%) は、要素の左上ではなく 中心 を配置の基準点に合わせるための定番テクニックです。

そしてここで、CSS アニメーション基礎の章で予告した 「transform は後勝ち」 の落とし穴に気をつけます。@keyframes の中で rotate() だけを書くと、中心合わせの translate(-50%, -50%) が上書きで消えてしまい、タイヤが画面外へ飛んでいきます。だから 回転のキーフレームでも translate を併記 しています。

回転量は -360deg (マイナスの 1 回転) で、車の進行方向に合う向きにしています (符号を逆にすると逆回りになります)。

前後輪の位置は left の % で指定します。

.tireFront { left: 78%; }
.tireRear  { left: 17.5%; }

車体側を width: min(88%, 680px) で可変にしているので (min() は「2 つのうち小さい方を採用」する関数で、画面が広いときは 680px で頭打ち、狭いときは 88% に縮みます)、タイヤも % で配置しておけば、画面幅が変わっても車輪の位置に追従します。

実装背景のパララックス​

パララックスの仕組みは基礎の章で見たとおりです。ここでは実際のコードに落とし込みます。

まず「タイル幅の整数倍だけ動かして戻す」ループの振り付けです。

@keyframes hero-scroll {
  from { transform: translate3d(calc(-1 * var(--loop)), 0, 0); }
  to   { transform: translate3d(0, 0, 0); }
}

ここで var(--loop) という書き方が出てきました。--loop は CSS カスタムプロパティ (CSS 変数) です。--名前: 値; の形で好きな値に名前を付けて宣言し、var(--名前) でその値を参照できます。ポイントは、同じ @keyframes を使い回しながら、--loop の値だけを各レイヤで変えられる ことです。振り付けは 1 つ、動く距離はレイヤごと、という構成になります。

各レイヤは「自分のタイル幅 × 2」を --loop に設定し、左にその距離だけずらした状態から元の位置へ動かします。ループの章で見たとおり、移動距離がタイル幅の整数倍なので、先頭に戻る瞬間も絵は飛びません。translate3d を使っているのは、基礎の章で説明したとおり GPU 合成に乗せて滑らかに動かすためです (各レイヤに will-change: transform も添えています)。

あとは、この hero-scroll を 各レイヤで違う距離・違う秒数 で再生するだけです。

レイヤ1 周の距離 (--loop)周期速さ
遠景ビル (.buildingsFar)1200px (タイル 600px × 2)50s24px/s
中景ビル (.buildingsMid)1320px (タイル 660px × 2)33s40px/s
雲 (.clouds)1440px (タイル 720px × 2)24s60px/s
街路 (.street)2688px (タイル 1344px × 2)29s約 93px/s
路面の破線 (.road::after)1400px (破線 70px × 20)6s約 233px/s
タイヤ (.tire)—1.1s最前面で回転

ここで「周期が短い = 速い」ではないことに注意してください。速さは距離 ÷ 時間です。たとえば街路 (29s) は雲 (24s) より周期が長いのに、1 周で進む距離が約 2 倍あるので、流れは速くなります。

たとえば雲のレイヤは、こう書いています。

.clouds {
  --loop: 1440px;                   /* 1 周で動く距離 = タイル幅 720px × 2 */
  position: absolute;
  left: 0;
  top: 2%;
  width: calc(100% + var(--loop));  /* 動いている間も画面を覆い続ける幅 */
  height: 38%;
  opacity: 0.22;
  background-size: 720px 100%;      /* タイル 1 枚の幅を 720px に固定 */
  /* 雲の形（radial-gradient）の描き方は次章 */
  animation: hero-scroll 24s linear infinite;
  will-change: transform;
}

幅の calc(100% + var(--loop)) は「画面幅 + 移動距離」です。最大で --loop ぶん左にずれても背景が途切れないように、あらかじめ移動距離のぶんだけレイヤの幅を広げています。

ビル・街路・路面も骨組みは同じで、違うのは --loop の距離、animation の秒数、背景の描き方だけです。なお、雲は background-size でタイル幅を直接 px 指定できるので高さは % のままですが、ビルと街路は次章の mask で描くため「タイルがレイヤの高さに合わせて拡縮」されます。この 2 種類のレイヤだけ高さを px 固定 (遠景ビル 120px、中景ビル 102px、街路 84px) にして、タイル幅を確定させています。

1 つ細かい注意点があります。流れているのは路面の「破線」だけで、地平線そのものは固定 です。地平線は .road 本体 (width: 100% の固定要素) で描き、その上を流れる破線は .road::after (hero-scroll で流れる) で描いています。地面の線まで一緒に流れると不自然なので、線は止めて破線だけ流しているわけです。破線の --loop は 1400px で、これは破線 1 周期 (塗り + すき間 = 70px) のちょうど 20 個ぶん。ここでも「パターンの整数倍」のルールを守っています。

実装背景を描き分ける（mask / gradient）​

背景の雲・ビル・街路・破線は、画像ファイルを 1 枚も使わず、すべて CSS だけで描いています。形の性質に合わせて 3 通りの方法 (mask / radial-gradient / repeating-linear-gradient) を使い分けました。いずれも塗りは currentColor なので、まとめてテーマ色に追従します。

加えて、各レイヤには opacity (透明度) を与えています。いちばん遠いビルを最も薄く (0.15)、中景のビルはやや濃く (0.25)、上空の雲はうっすら (0.22)、線の細い街路はしっかりめ (0.5)、手前の路面はくっきり (0.4〜0.7)。奥ほど薄く・手前ほど濃くすることで、パララックスの速度差と合わせて奥行きを強めています。

下の図が 3 つの方法のイメージです。

説明用の図です
① mask：黒いシルエットの形だけ下地を残す下地（currentColor）+シルエット（mask）=ビルの形だけ残る② radial-gradient：楕円を重ねて雲にする楕円のグラデーションを 3 つ重ねる③ repeating-linear-gradient：等間隔の破線塗り 26px・透明 44px を繰り返す

ビルCSS mask​

mask (マスク) は、「シルエット (型抜きの形) を使って、下地の見える部分を切り抜く」 CSS の機能です。不透明に描かれた形の部分だけ下地が残り、それ以外は透明になります。クッキーの型でクッキー生地を抜くイメージです。

ビルは、シルエットを data URI の SVG にして mask に渡し、下地を currentColor で塗っています。

遠景ビルのシルエットは矩形の組み合わせです。ビル本体に加えて、アンテナや給水タンクといった屋上のディテールも細い矩形で添えて、単調な箱の並びにならないようにしています。

遠景ビルのシルエット（mask 用の SVG・抜粋）
<svg viewBox="0 0 1000 200">
  <rect x="40"  y="96"  width="80"  height="104" fill="#000"/>       <!-- ビル本体 -->
  <rect x="78"  y="62"  width="4"   height="34"  fill="#000"/>       <!-- アンテナ -->
  <rect x="64"  y="74"  width="32"  height="4"   fill="#000"/>       <!-- アンテナの横棒 -->
  <rect x="310" y="116" width="110" height="84"  fill="#000"/>       <!-- ビル本体 -->
  <rect x="330" y="68"  width="70"  height="28" rx="4" fill="#000"/> <!-- 給水タンク -->
  <!-- 以下、計 3 棟ぶん続く -->
</svg>

この SVG を data URI の文字列にエンコードして、CSS の mask に渡します。

.buildingsFar {
  height: 120px;                   /* px 固定 → タイル幅が 600px に確定する */
  background-color: currentColor;  /* 下地をテーマ色で塗る */
  /* ↑ のビル SVG を data:image/svg+xml,... の形にエンコードしたもの */
  --bg-mask: url("data:image/svg+xml,%3Csvg ... %3C/svg%3E");
  -webkit-mask: var(--bg-mask) repeat-x left bottom / auto 100%;
  mask: var(--bg-mask) repeat-x left bottom / auto 100%;
}

ここで data URI という言葉が出てきました。これは「画像ファイルを外部に置く代わりに、画像の中身を直接 URL の文字列として埋め込む」方法だと思ってください (data:image/svg+xml,... の部分がそれです)。おかげで .svg ファイルを別途用意しなくても、CSS の中にシルエットを書けます。

repeat-x はシルエットを横に繰り返し敷き詰める指定です。末尾の auto 100% はタイルのサイズ指定で、「高さはレイヤに合わせ、幅は元の縦横比なりに」という意味です。viewBox が 1000×200 のタイルを高さ 120px に合わせると、幅は 1000 × (120 ÷ 200) = 600px。レイヤの高さを px で固定したからこそ、ループの章で使った「タイル幅 600px」が確定します。-webkit-mask を併記しているのは Safari 対応のためです (Safari は -webkit- という接頭辞付きの書き方を必要とする場合があります)。

中景ビルの窓fill-rule: evenodd で穴を抜く​

中景のビルには窓があります。といっても窓を描き足したのではなく、シルエットに窓の形の穴を空けています。mask は「不透明な部分だけ下地が残る」仕組みなので、穴の部分は下地が消え、向こう側の背景が抜けて見えます。これが窓になります。

穴空けに使うのが SVG の fill-rule="evenodd" です。1 つの <path> の中に「外形」と「窓」を重ねて描くと、evenodd ルールでは 図形に偶数回囲まれた部分が塗られなくなる ため、外形の内側に重ねた窓の長方形だけが穴になります。

中景ビルのシルエット（窓抜き・抜粋）
<path fill-rule="evenodd" d="
  M60 60H220V170H60Z    ← ビルの外形（大きな長方形）
  M84 78h24v20H84Z      ← 窓（外形の内側の小さな長方形 → 穴になる）
  M134 78h24v20H134Z    ← 窓
  ...
"/>

街路の線画stroke も mask になる​

街路の標識・街灯・街路樹・信号機は、ビルと違って 線画 で描いています。車体 (car.svg) が線画なので、車に近い位置に並ぶオブジェクトはテイストを揃えたかったからです。

mask は「不透明な部分を残す」仕組みなので、塗り (fill) だけでなく 輪郭線 (stroke) でも機能します。線そのものが不透明な部分になり、線画がそのまま型になります。

街路の線画（mask 用の SVG・抜粋）
<svg viewBox="0 0 2400 150">
  <g fill="none" stroke="#000" stroke-width="3.5"
     stroke-linecap="round" stroke-linejoin="round">
    <path d="M180 150V78"/>                    <!-- 標識のポール -->
    <circle cx="180" cy="56" r="22"/>          <!-- 丸標識 -->
    <path d="M760 150V44Q760 26 782 26H796"/>  <!-- 街灯のポールとアーム -->
    <circle cx="803" cy="26" r="7"/>           <!-- 街灯のランプ -->
    <!-- 街路樹・信号機と続く -->
  </g>
</svg>

fill="none" で塗りを消し、stroke で線だけを描いています。stroke-linecap="round" と stroke-linejoin="round" は線の端や角を丸める指定で、車の線画の柔らかい質感に寄せるためのものです。オブジェクト同士の間隔は広めに取っています。最初はもっと密に並べていたのですが、主役の車が背景に埋もれてしまったため、数を減らして間隔を空けました。

雲radial-gradient​

radial-gradient (放射状グラデーション) は、中心から外へ向かって色が変化する円・楕円のグラデーションです。雲は、この楕円のグラデーションを currentColor でいくつか重ねて表現しています。

.clouds {
  background-image:
    radial-gradient(ellipse 20% 26% at 22% 40%, currentColor 0 60%, transparent 62%),
    radial-gradient(ellipse 15% 20% at 42% 52%, currentColor 0 60%, transparent 62%),
    radial-gradient(ellipse 12% 16% at 9% 55%, currentColor 0 60%, transparent 62%);
}

ellipse 20% 26% at 22% 40% は「幅 20%・高さ 26% の楕円を、位置 (22%, 40%) に置く」という意味。currentColor 0 60%, transparent 62% は「中心から 60% までは色を塗り、62% で透明にする」指定で、この境目がふわっとした雲の輪郭になります。これらを background-size: 720px 100% で幅 720px のタイルにし、background-repeat: repeat-x で横に繰り返しています (タイル幅を px で固定する理由は、ループの章で説明したとおりです)。

路面の破線repeating-linear-gradient​

repeating-linear-gradient (繰り返し直線グラデーション) は、一定のパターンを繰り返す直線グラデーションです。路面の破線はこれ 1 つで作っています。

.road::after {
  background: repeating-linear-gradient(to right, currentColor 0 26px, transparent 26px 70px);
}

to right は左から右への向き。currentColor 0 26px で「0 から 26px までは色」、transparent 26px 70px で「26px から 70px まで (＝ 44px ぶん) は透明」。これが延々と繰り返され、塗り 26px・すき間 44px の破線になります。

シルエットや線画には mask (ベタ塗りは fill、窓抜きは fill-rule: evenodd、線画は stroke)、ふんわりした塊や規則的な線には gradient、と使い分けると、画像ファイルを 1 枚も足さずに背景が組めます。

実装アクセシビリティとレスポンシブ​

最後に、いろいろな人・いろいろな画面で気持ちよく見えるための配慮です。

このアニメーションは純粋な装飾なので、スクリーンリーダー (画面の内容を読み上げる支援技術) からは隠しています。

<div className={styles.scene} aria-hidden="true">

aria-hidden="true" は「この要素は支援技術に伝えなくてよい」という印です。hero の見出し (サイト名の <h1>) が内容を担保しているので、装飾の車まで読み上げる必要はありません。

そして CSS アニメーション基礎の章で触れた prefers-reduced-motion を、ここで使います。動きを減らす設定をしている人には、すべてのアニメーションを止めます。

@media (prefers-reduced-motion: reduce) {
  .clouds,
  .buildingsFar,
  .buildingsMid,
  .street,
  .road::after,
  .tire {
    animation: none;
  }
}

ここで効いてくるのが、「止まっていても 1 枚の絵として成立する」ようにレイアウトを先に組んでおく という設計です。このアニメーションは、まず静止状態 (車が道に佇んでいる絵) を作り、そこに動きを後付けしました。だから動きを止めても、ちゃんと成立した静止画になります。

レスポンシブ (画面幅への対応) も同じ考え方です。背景は画面幅いっぱいに広げ、車は中央でサイズの上限を持たせています。

.car {
  position: absolute;
  left: 50%;
  bottom: 18%;
  width: min(88%, 680px);      /* 画面が広いときは 680px で頭打ち、狭いときは 88% */
  transform: translateX(-50%); /* 中央寄せ */
}

.carBody {
  display: block;
  width: 100%;                 /* 車体 SVG を .car の幅いっぱいに広げる */
  height: auto;
}

タイヤ位置は % 指定なので車のサイズ変化に追従します。モバイルでは、上の余白を少し詰めるだけでそのまま表示しています。

@media (max-width: 720px) {
  .scene {
    margin-top: 1.5rem;
  }
}

ハマりどころreplaceAttrValues はなぜ効かなかったか​

ここからは、この実装でいちばん時間を取られた 色の問題 の種明かしです。テーマ追従の章で「fill: currentColor をなぜ CSS で書くのか、あとで説明する」と予告した、その回収です。

素材の SVG は黒一色の線画 (#000000) でした。これをテーマ色に追従させたい。svgr には属性値を置換する機能があると知っていたので、まず docusaurus.config.ts でこう設定しました。

svgr: {
  svgrConfig: {
    replaceAttrValues: {'#000000': 'currentColor', '#000': 'currentColor'},
  },
},

#000000 という色の指定を currentColor に置き換えれば、あとは CSS の color で色を制御できる——はずでした。ところが、これが効きませんでした。 ビルドしても車は黒いまま。

原因を追うために、ソースの SVG と、ビルドされた後の HTML を見比べてみました。

まずソース (static/img/car.svg)。色は <g> (グループ) の fill="#000000" に 1 か所だけ あり、その中の <path> には fill 属性がありません。SVG 基礎の章で「fill が無い図形はデフォルトで黒」と説明した、まさにその状態です。(<path> の d 属性は実際には数千文字におよぶ 1 本の長大な座標列なので、ここでは先頭だけ示して ... で省略しています。完全な中身は static/img/car.svg で見られます。)

static/img/car.svg (ソース)
<svg viewBox="83 349 2650 747">
  <title>car-line-art</title>
  <g transform="translate(0,1536) scale(0.05,-0.05)" fill="#000000" stroke="none">
    <path d="M31820 23734 c-1590 -37 -2289 -76 ..."/>
    <!-- path が続くが、いずれも fill 属性を持たない -->
  </g>
</svg>

次にビルド後の HTML。<g> が丸ごと消え、<path> が <svg> の直下に並んでいます。座標は <g> の transform が各 path に計算し直されて畳み込まれ、肝心の fill 属性は付いていません。

ビルド後の DOM (build/index.html)
<svg viewBox="83 349 2650 747" class="carBody_DE43">
  <title>car-line-art</title>
  <path d="M1591 349.3c-79.5 1.85-114.45 3.8 ..."/>
  <!-- g が消滅 / path に fill 属性なし -->
</svg>

何が起きたのか。svgr は内部で svgo という「SVG 最適化ツール」を通してから React コンポーネントに変換します。その最適化の過程で、<g> が畳まれて消え (transform は各 path の座標に適用され)、fill="#000000" の情報は最終的な <path> に残りませんでした。

replaceAttrValues は「#000000 という文字列を探して置換する」機能です。ところが、置換すべき #000000 が最適化後の HTML に存在しないので、置換のしようがなく、何も起きなかったのです。下の図が、その流れです。

最終的に効いたのは、CSS のたった数行でした。

/* path に fill 属性が無い（svgo が除去）ので、CSS の fill が SVG デフォルトの黒を上書きできる */
.carBody path,
.tire path {
  fill: currentColor;
}

ポイントは、SVG 基礎の章で伏線を張った性質——<path> に fill 属性が無いとき、CSS の fill が SVG デフォルトの黒を上書きできる ——です。属性が無いからこそ、CSS で素直に塗れる。皮肉にも、replaceAttrValues が効かなかった理由 (path に fill 属性が残らなかったこと) が、そのまま CSS で解決できる理由になっていました。

config の設定はなぜ残してあるか

上記の経緯で replaceAttrValues は実質的に効いていませんが、docusaurus.config.ts には今も残してあります。理由は 2 つで、(1)「この SVG はテーマ色化したい」という意図を設定として残す価値があること、(2) svgo の最適化結果は素材次第なので、別の SVG を足したときには効く可能性があること。実際の色制御は CSS が担っている、という整理です。

その他のつまずき​

色の問題ほどではありませんが、他にもいくつか引っかかった点を、本文で説明した内容のおさらいとして並べておきます。

  • タイヤの軸ブレ: viewBox がいびつだと回転中心がずれてガタつく。viewBox を 正方形 にクロップして中心を揃えると解決 (「タイヤを軸ブレなく回す」の章)。
  • transform の上書き: @keyframes で rotate() だけを書くと、中心合わせの translate(-50%, -50%) が消えてタイヤが飛ぶ。回転キーフレームでも translate を 併記 する (「CSS アニメーションの基礎」の章)。
  • ループの境目で背景が飛ぶ: 初版は移動距離を「画面幅の 100%」にしていたため、画面幅がタイル幅の整数倍にならず、ループのたびに背景がカクッとずれていた。移動距離をタイル幅の整数倍 (px) に固定して解決 (「継ぎ目なく無限ループさせる仕掛け」の章)。
  • 背景の密度は控えめに: ビルや標識を増やすほど街は賑やかになるが、主役の車が埋もれる。実際に初版は密度が高すぎて、ビルの棟数と街路オブジェクトを減らし、間隔を広げる調整をした。
  • 速度・位置・向きは実測で: パララックスの距離・秒数やタイヤの座標 (%) に理論値はなく、画面を見ながら調整した。回転や流れの向きも符号 1 つで逆転するので、最後は目で見て決めるのが早い。

まとめ・再利用のヒント​

画像ファイルを 1 枚も足さず、svgr と純 CSS だけで「車が走る」hero を作りました。同じ構成は他の SVG メインビジュアルにも応用できます。要点を再利用しやすい形でまとめます。

  1. SVG はコンポーネント化: Docusaurus なら svgr が同梱なので import X from './x.svg' で済む。型定義も不要。
  2. 色は currentColor に寄せる: path に fill 属性が無ければ CSS の fill で塗れる。.scene に color を置き、テーマで切り替える。色の指示は 1 か所に集約する。
  3. 背景は mask / gradient で: シルエットは CSS mask (窓抜きは fill-rule: evenodd、線画は stroke)、ふんわりした塊は radial-gradient、規則的な線は repeating-linear-gradient。画像を増やさずに済む。
  4. 動きは transform だけで: translate3d と rotate を GPU 合成に乗せ、will-change を添える。レイアウトを揺らさない。transform は後勝ちなので、効かせたい変形は 1 つにまとめて書く。
  5. ループの移動距離はタイル幅の整数倍に: 繰り返し背景は「パターンの整数倍だけ動かして戻す」と境目が見えない。タイル幅と移動距離を px で固定するのが確実。
  6. 止まった状態を先に作る: prefers-reduced-motion で止めても 1 枚の絵になるよう、静止レイアウトを出発点にする。

ロゴの車輪を動かしたいという思いつきから始めましたが、SVG と CSS の素直な性質を組み合わせるだけで、ライブラリなしでここまで作れました。車輪の再発明、なかなか楽しいものです。

]]> docusaurus react css svg animation <![CDATA[Claude Code ベストプラクティス集 shanraisshan/claude-code-best-practice の歩き方]]> https://notes.rewheel.dev/blog/claude-code-best-practice-guide https://notes.rewheel.dev/blog/claude-code-best-practice-guide Mon, 25 May 2026 00:00:00 GMT Claude Code を業務に取り入れ始めると、公式ドキュメントを読んでも「次に何を導入すべきか」「自分のレベルに合うのはどれか」が見えにくくなる段階があります。Anthropic 自身が出している機能だけでも 30 種類を超え、コミュニティが公開しているワークフローも 12 件以上、Boris Cherny や Thariq といった Claude Code 開発陣の Tips も 80 件以上が散らばっている状態です。

その整理に役立つのが、2026 年 3 月の GitHub Trending #1 を獲得した shanraisshan/claude-code-best-practice です。Shayan Raisshan 氏 (Claude Pakistan community 主宰、Claude Community Ambassador) が MIT ライセンスで公開・継続更新しているリポジトリです。執筆時点 (2026 年 5 月 25 日) で 445 ファイル、585 行の README を持つキュレーション集です。

本記事はこのリポジトリを 自分のレベルと用途に合った要素だけ拾い出せる ように整理した見取り図です。長めの 1 本ですが通読は前提にしておらず、目次から拾い読みできる構成にしてあります。気になった箇所はそのまま GitHub 上のファイルへ飛べるよう、本文中の重要リンクはリポジトリ内の具体ファイルへの直リンクで張っています。

加えて、各章末には :::info 筆者の実装例 ブロックを設けて、筆者自身の ~/.claude/ (agents 7 件 / skills 38 件 / rules 31 件 / hooks 3 script / teams 1 件 / ADR 16 件) でどう実践しているかを併載しました。「他人の整理 (キュレーション)」と「自分の harness (実装)」の橋渡しとして使えるようにしてあります。実装例が不要な方は :::info ブロックを読み飛ばし、:::note 採用判断 ブロックだけを拾って章をまたいでも、本筋は崩れない構成にしています。

本記事の読み方

このリポジトリは作者自身が「コードリポではなくリファレンス・コース」と位置づけています (README の How to Use セクション)。本記事もそれに倣い、まず全体像を提示してから、章末ごとに 採用判断 ミニまとめを置いて「自分は何を試すか」を整理する形で進めます。最後の第 9 章にレベル別ロードマップをまとめてあるので、急ぐ方はそちらから読んでも構いません。

第 1 章: リポジトリの正体13 ディレクトリの役割​

最初に全体像を把握します。リポジトリ直下には 13 の主要ディレクトリと 2 つの基幹ファイルがあります。

shanraisshan/claude-code-best-practice/
├── README.md                    ハブ。585 行に全分類表が集約
├── CLAUDE.md                    このリポ自身の Claude Code 設定 (自己言及)
├── best-practice/    (8 件)     概念ごとの仕様カタログ
├── implementation/   (6 件)     実際に動く実装例
├── orchestration-workflow/      ショーケース (Command → Agent → Skill)
├── agent-teams/                 Agent Teams 実装例
├── development-workflows/       cross-model + RPI ワークフロー
├── reports/         (12 件)     深掘り解析レポート
├── tips/            (10 件)     Boris / Thariq 等の発言集
├── videos/           (8 件)     ポッドキャスト / 動画解説
├── tutorial/                    day0 / day1 セットアップ手順
├── changelog/                   更新追跡
├── presentation/                GDG Kolachi 等の登壇資料
└── .claude/                     このリポ自身が使う agents/commands/skills/hooks

このリポジトリの特徴は 4 つの情報軸が役割分担している 点にあります。

軸配置用途読者にとっての価値
Conceptsbest-practice/各機能の仕様カタログ「この機能は何か」を 5 分で把握
Workflowsdevelopment-workflows/, orchestration-workflow/, ECC/Superpowers 等の外部リポへのリンク機能を組み合わせた方法論他人がどう組み合わせているかを学ぶ
Tipstips/ + README の 83 件開発者発言の集約自分が次に試すべきことを発見
Reportsreports/ (12 件)比較分析・深掘り論考「なぜそうするか」の理屈を理解

どこから読み始めるかは、自分の Claude Code 経験レベルで決まります。インストールが終わったばかりなら tutorial/ から始めて Tips の入門カテゴリへ。基本機能は動かしたことがあるなら best-practice/ の 8 ファイルを順に読みつつ Workflows を 1 つ試す。すでに自前で .claude/ を育てている人は Reports と Workflows の比較で次の改善ヒントを探す、という具合です。

採用判断

ディレクトリ図を「目次」としてブックマーク。1 セッションで全部読もうとせず、章別に拾い読みする方が頭に残ります。第 9 章のロードマップを先に眺めてから戻るのも1つの読み方。

第 2 章: 30+ の Claude Code 概念カタログ​

リポジトリの中心になるのが、README 冒頭の 🧠 CONCEPTS 表と 🔥 Hot 表です。Anthropic が Claude Code に追加した機能を網羅し、各機能について「公式ドキュメント」「リポ内の best-practice 解説」「実装例」「コミュニティの実装例」へのリンクを付けています。

ここでは機能を 役割で再グルーピング して紹介します。各機能に 採用 difficulty ラベル を付けてあります: ★ は設定 1 ファイル / 学習 30 分以内で導入可能、★★ は数ファイル + 1-2 時間の学習が必要、★★★ は複数機能の組み合わせ / 半日以上の理解が必要です。

2.1 中核プリミティブ (4)​

Claude Code を「ただのチャットボット以上」にする 4 つの基本機能です。

Subagents ★★：best-practice/claude-subagents.md には 16 個の frontmatter (= ファイル冒頭に書く YAML メタデータ) フィールドが表形式で解説されています。フィールドは name / description / tools / model / permissionMode / skills / mcpServers / hooks / memory / effort / isolation / initialPrompt / color などです。Anthropic 公式ビルトインも 5 種類用意されていて、general-purpose (汎用), Explore (haiku でコードベース探索), Plan (read-only な実装計画), statusline-setup, claude-code-guide という構成です。実装例は implementation/claude-subagents-implementation.md にまとまっています。

設計の中核にあるのは Generator-Evaluator 分離 という原則です。これは「作る側 (Generator)」と「評価する側 (Evaluator)」を別 subagent に分けて、self-evaluation bias (= 自分が作ったものを自分で評価すると品質を過大評価しやすい認知バイアス) を回避する考え方です。Boris Cherny も繰り返し言及しています。

Commands ★：slash コマンドの作り方は best-practice/claude-commands.md に解説があります。.claude/commands/<name>.md に Markdown を置くだけで /<name> として呼び出せるようになる、もっとも導入コストが低い拡張ポイントです。Boris Cherny の Tip でも「1 日 1 回以上やる作業は command か skill にする」と繰り返し強調されています。

Skills ★★：best-practice/claude-skills.md では 15 個の frontmatter フィールドに加え、9 個の公式 bundled skill が表になっています。まず simplify (重複削除リファクタ), batch (一括コマンド), debug (失敗調査), loop (定期実行), claude-api (Anthropic SDK 補助) の 5 つです。残る 4 つは fewer-permission-prompts (allowlist 自動生成), run (実アプリ起動), verify (動作検証), run-skill-generator (起動レシピ作成) です。v2.1.145 で /run, /verify, /run-skill-generator の 3 つが追加された点が特に新しいです。

Skill 設計の重要概念に Progressive disclosure (段階的開示) があります。1 つの SKILL.md ファイルに全情報を詰め込むのではなく、フォルダ内に references/ scripts/ examples/ を配置し、必要になった時だけ Claude が読み込む構造にします。こうすることで context window (一度に処理できるトークン枠) を圧迫しないという設計指針です。

Hooks ★★★：PreToolUse / PostToolUse / Stop / SessionStart などライフサイクルイベントで shell コマンドを実行できる機構。リポ内では別リポ shanraisshan/claude-code-hooks として独立しており、サウンド通知 / 自動フォーマット / 危険コマンドのブロック等の実装例が揃っています。Boris の発言「PostToolUse hook で auto-format を入れると Claude が生成するコードの最後 10% を仕上げてくれて CI failure を防げる」が代表的な活用例です。

Hook の役割を整理する枠組みとして Computational Sensor / Inferential Guide の二分法 があります。Computational Sensor は「コードで自動検出する deterministic (決定的) な仕組み」です (lint / CI / hook の suppression 検出など)。Inferential Guide は「LLM 自身に判断させる確率的な仕組み」です (CLAUDE.md / rules / skills の指示文)。Hook は前者を担当し、rules や CLAUDE.md だけでは LLM が確率的に違反してしまう規範を deterministic に強制する役割を持ちます。

ここまでで Subagent / Command / Skill / Hook の 4 つを見てきましたが、初学者が最も混乱しやすい Subagent vs Skill vs Command の境界 を 1 つの表に集約しておきます (Hook はライフサイクル機構のため別軸として整理)。

機能役割起動方法
Commandエントリポイント / ワークフロー指揮/<name> をユーザーが打鍵
Agent (Subagent)ドメイン作業の主役 (別 context window で動く)Command または上位 agent から呼出
Skill成果物生成 / 参照知識の単位trigger 発話で自動起動、または Skill tool から呼出
筆者の実装例 (~/.claude/)

筆者は ~/.claude/agents/ に 7 件の subagent を配置し、Generator-Evaluator 分離 を意図的に組んでいます。内訳は architect / code-reviewer / debugger / implementer / refactorer / test-strategist / infra-reviewer の 7 つです。

  • Generator (作る側): implementer (実装専任) / refactorer (リファクタ専任) / debugger (バグ調査 + 修正)
  • Evaluator (評価する側): architect (設計レビュー) / code-reviewer (コードレビュー) / test-strategist (テスト戦略) / infra-reviewer (TF/IaC レビュー)

Evaluator 側の 4 件は disallowedTools: Write, Edit で read-only を強制 しており、評価担当が誤って実装に手を出すことを構造的に防いでいます。命名も general qa のような汎用名ではなく、Boris 推奨の feature 特化 (具体的な役割名) に統一しています。

具体的には、subagent 定義ファイルの frontmatter は以下のような YAML 形式で書きます (筆者の code-reviewer.md 抜粋)。

---
name: code-reviewer
description: ペアプログラミング用コードレビュアー。コード変更後のレビューとガイダンスを提供
model: opus
effort: max
tools: Read, Grep, Glob, Bash, WebSearch, mcp__context7__query-docs
disallowedTools: Write, Edit
isolation: worktree
---

# Instruction 本文...

tools で許可ツール、disallowedTools で禁止ツールを明示することで、評価専任エージェントが誤って実装に手を出すリスクを deterministic に排除できます。

Commands は 0 件で運用 しており、用途は全て skill に統合しています。理由は、skill は frontmatter に書いた trigger 発話 (例: 「レビュー」「バグ」) で自動起動できるため、/command-name を毎回打つ手間が省けるからです。Boris の「1 日 1 回以上やる作業は command か skill にせよ」は、筆者環境では「全部 skill にせよ」に翻訳されています。

Skills は 38 フォルダ (propose / debug / review / explain / compare / learn / next / checkpoint / spec-driven-development / verify ほか) を運用。代表的な trigger 発話の対応は以下のとおりです。

Skilltrigger 発話役割
/propose"提案して", "設計案"敵対的自己批判付きで実装方針を提案 (最大 2 反復)
/debug"バグ", "動かない"Investigate → Fix → Verify を最大 3 反復で自律解決
/review"レビュー", "チェック"7 観点 (正確性 / 可読性 / パフォーマンス / セキュリティ / 保守性 / 規約 / デグレ) でコードレビュー
/explain"説明して", "なぜ"コード・概念を段階的に説明
/checkpoint"checkpoint", "区切って"現セッション整理 + 次セッション用 prompt 生成

Progressive disclosure 構造 (references/ scripts/ examples/ を持つフォルダ型) は 2 件のみ (skill-creator / react-view-transitions)。他の 36 件は SKILL.md 単体 + metadata で済ませており、必要に応じて段階導入する方針です。

Hooks は実体スクリプト 3 件 を運用しています。

  • ~/.claude/hooks/check-protected-files.sh (PreToolUse)：Write/Edit 実行前に .env 等の保護ファイルへの書き込みを block
  • ~/.claude/hooks/check-suppression.sh (PostToolUse)：Write/Edit の出力に suppression が新規追加されていないか deterministic に検証。対象は // eslint-disable-next-line や // @ts-ignore 等
  • ~/.claude/hooks/check-plain-question.sh (Stop)：応答終了時にテキスト出力を grep し、「〜ましょうか」「〜ですか」等の平文質問パターンを検出。exit 2 で Claude に自己修正を促す (AskUserQuestion ツール使用を強制する Sensor)

Boris の「PostToolUse hook で auto-format」を、筆者は 「format」ではなく「suppression 検出」 に転用しているのが意図的な差分です。format は CI で十分カバーできますが、suppression は LLM が確率的に挿入する anti-pattern で、CI 通過後に永続化されると harness が空洞化するため、PostToolUse hook で実行直後に即時 block します。

2.2 統合機構 (5)​

外部世界やプロジェクト設定とつなぐためのレイヤです。

機能難易度リポ内リファレンス
MCP Servers★★best-practice/claude-mcp.md：context7 / aws-knowledge / playwright 等を Claude Code から呼べるプロトコル
Plugins★★公式 docs：配布可能パッケージ。marketplace を立てる方法もリンクあり
Settings★best-practice/claude-settings.md：.claude/settings.json の全フィールド網羅、permission / model / output style 等
Status Line★shanraisshan/claude-code-status-line：context 使用量 / cost の可視化
Memory★★best-practice/claude-memory.md + 深掘り reports/claude-agent-memory.md：CLAUDE.md / .claude/rules / auto-memory の階層

ここで MCP (Model Context Protocol) について少し補足しておきます。これは Anthropic が策定した「外部のツールやデータソースを Claude に呼び出させるための標準プロトコル」です。対応する MCP server を導入すれば、Claude が外部機能を tool として呼べるようになります。例えばライブラリドキュメント取得 (context7) / AWS 公式 docs 取得 (aws-knowledge) / ブラウザ自動化 (playwright / chrome-devtools) / コードベース symbol 検索 (serena) などです。WebSearch だけでは取りこぼす一次情報を確実に取得できるため、技術的判断の精度が上がります。

2.3 セッション制御 (3)​

長時間セッションや複雑タスクで Claude Code が「賢く動き続ける」ための機構です。

  • Checkpointing ★：ファイル編集を自動追跡し、/rewind で過去状態に戻れる。失敗した試行で context を汚すより rewind した方が良い、という Thariq の Tip と組み合わせると価値が出ます。
  • CLI Startup Flags ★：best-practice/claude-cli-startup-flags.md に主要フラグの一覧。--permission-mode, --agent, --bg, --worktree 等。
  • Auto Mode / Plan Mode ★★：Shift+Tab で Ask → Plan → Auto のモードを循環。Auto Mode はモデルベース classifier (= 小型モデルでコマンドの安全性を自動分類する分類器) が各コマンドの安全性を判定して自動承認する仕組みで、Boris は「dangerously-skip-permissions の代わりにこれを使え」と推奨しています。

2.4 🔥 Hot 機能群 (新機能、優先度高)​

2026 年に入って急速に追加された機能群です。一部は beta 表記がついていて仕様変更の可能性がありますが、業務での活用余地が大きいものを中心に紹介します。

機能難易度用途
Ultrareview ★★beta/ultrareview で multi-agent な PR レビュー。GitHub PR# を指定して走らせると複数視点でレビューが並列実行される
Ultraplan ★★beta/ultraplan で大規模な計画立案。Plan mode の上位版
Auto Mode ★beta上記 §2.3 参照。classifier が安全なコマンドを自動承認
Power-ups ★—/powerup (best-practice/claude-power-ups.md)
Fast Mode ★beta/fast で出力高速化 (モデルはダウングレードしない、Opus 4.6/4.7 で利用可)
Chrome ★★beta--chrome で Claude 専用 Chrome 拡張連携。Payload admin 等のログイン状態を共有して操作
Code Review ★betaGitHub App として managed 提供。Boris は「Greptile / CodeRabbit / Cursor BugBot を置き換える」と言及
GitHub Actions ★★—.github/workflows/ で claude を呼び出し。GitLab CI/CD も対応
Remote Control ★★—/remote-control / /rc で headless (= GUI なしで実行する) 操作
Agent Teams ★★★betaenv var で起動、複数 agent を並列実行 (implementation/claude-agent-teams-implementation.md)
Scheduled Tasks ★★—/loop (local 最大 7 日) と /schedule (cloud cron) (implementation/claude-scheduled-tasks-implementation.md)
Routines ★★betacloud で動く scheduled agent。マシンがオフでも実行される
Goal ★★—/goal <condition> で「条件達成までターン自動反復」 (implementation/claude-goal-implementation.md)
Voice Dictation ★beta/voice で音声プロンプト
Computer Use ★★★betacomputer-use MCP server。デスクトップ操作の自動化
Git Worktrees ★★—--worktree / -w で並列開発。Boris は 5 通りの使い方を 紹介
Simplify & Batch ★—/simplify / /batch の bundled skill
Ralph Wiggum Loop ★★★—プラグイン。長時間自律ループ。実装は 別リポ で公開

なお、表中の Git Worktrees は git 標準機能で「同じリポジトリを別ディレクトリにチェックアウトして並列作業できる仕組み」のことです (git worktree add ../feature-x feature-x のように使います)。Claude Code の --worktree フラグや subagent の isolation: worktree 設定は、この機能を使って main workspace から作業を隔離します。

筆者の実装例 (~/.claude/)

筆者は --worktree フラグそのものは多用していませんが、subagent (debugger / refactorer / code-reviewer) を isolation: worktree で起動するパターン1 を採用しています。長時間 / 破壊的になりやすいレビューやリファクタを main workspace から隔離し、失敗時の巻き戻しを安全にしています。

Auto Mode は permission prompt 削減効果を活用しています。Plan mode 承認後の自動実装で classifier が block するケースには、AskUserQuestion ツールで筆者に明示認可を求める動線を組んでいます (Phase 13 W1-1 ratchet)。この動線は ~/.claude/rules/ask-user-question.md の規範によるものです。Auto Mode の便利さと破壊的操作の認可ギャップを harness で吸収する設計です。

採用判断

迷ったらまず ★ から導入します。Plan Mode、Commands、Settings あたりは初日から効きます。★★ の Subagents / Skills / Hooks は次の週末で 1 つ作ってみると進歩が大きい領域。★★★ (Agent Teams / Computer Use / Hooks 自作 / Ralph Wiggum) は基本機能を組み合わせて手応えを得てから挑む順番が安全です。

第 3 章: Orchestration Workflow ショーケース​

このリポの中央に置かれているのが Command → Agent → Skill という 3 層オーケストレーションです。作者はこれを /weather-orchestrator という気象データ取得ワークフローで実演しています (orchestration-workflow.md)。

この showcase が伝える設計の要点は 2 つあります。

1 つ目は 2 つの Skill パターン の使い分けです。weather-fetcher は weather-agent の frontmatter に skills: フィールドで指定され、agent が起動した瞬間に context へ全文 inject されます (Agent Skills パターン)。一方 weather-svg-creator は preload されておらず、command が Skill tool を呼び出した時点で初めて発火します (Skill パターン)。前者は agent に「ドメイン知識を骨格として持たせる」用途、後者は「成果物を作る」用途、と覚えれば整理がつきます。

2 つ目は 役割分担の徹底 です。Command がワークフローを指揮し、Agent がデータ取得などのドメイン作業を担い、Skill が成果物を出力する。3 層がそれぞれ単一責任で並んでいるため、後から「fetcher を OpenWeather に差し替える」「SVG ではなく PNG を出す」といった変更が局所化されます。実装ファイルは .claude/commands/weather-orchestrator.md と .claude/agents/weather-agent.md で直接参照できます。skill 側は .claude/skills/weather-fetcher/SKILL.md と .claude/skills/weather-svg-creator/SKILL.md です。

リポを clone して /weather-orchestrator を実行すれば、上記の流れがそのまま手元で再現できます。3 層構造を学ぶ題材としては、このリポで一番手を動かしやすい素材です。

筆者の実装例 (~/.claude/)

筆者は weather example と同じ「3 層オーケストレーション」の発想で、~/.claude/teams/multi-perspective-review/ という team 構成を組んでいます。違いは weather example が「Command → Agent → Skill」の 異種役割の直列実行 であるのに対し、こちらは 同種 Evaluator agent の並列実行 という点です。

  • Team 構成: code-reviewer + architect + test-strategist の 3 つの Evaluator subagent を並列起動
  • trigger 発話: 「複数視点でレビュー」「総合レビュー」「3 視点」(10 ファイル以上の変更時に推奨)
  • 統合: 各 agent が独立に出した judgment を main agent が統合し、重複指摘を整理した上で筆者に提示

設計目的は「単一 Evaluator では観点漏れが発生する大規模変更を、独立した 3 視点で冗長検証する」ことです。weather example の「定型タスクを直列で組み立てる」用途とは対照的に、こちらは「重要判断を並列で冗長化する」用途で、3 層構造の応用範囲の広さを示す事例として参考にできます。

なお Agent Teams 機能が無効な環境でも、Task tool での fallback 経路 (main agent が 3 subagent を逐次呼ぶ) を team.md に記載しており、機能変動に対する耐性も組み込んでいます。

採用判断

このパターンを理解するには、weather example をそのまま clone して動かすのが手っ取り早いです。自分の業務でも「定型レポート生成」「データ取得 + 可視化」のような 3 ステップで終わる作業を 1 つだけ、この 3 層構造で書き直してみると pattern が身につきます。

第 4 章: 12 の開発ワークフローを比較する​

README の ⚙️ DEVELOPMENT WORKFLOWS セクションは、コミュニティで公開されている主要ワークフロー 12 件を star 数順に並べて比較しています。各ワークフローは「複数の slash command やスキルを連鎖させて開発を進める方法論」で、それぞれ思想と粒度が異なります。

ワークフロー★流れの特徴構成数 (A / C / S)向き
Superpowers200kbrainstorming → worktrees → writing-plans → subagent-driven → TDD → code-review → verification → finishing0 / 0 / 14TDD + 並列開発を重視する人
Everything Claude Code (ECC)188k/ecc:plan → /tdd → /code-review → /security-scan → /e2e → merge48 / 143 / 230商用プロダクトでフルセット導入
Spec Kit104k/speckit.constitution → .specify → .clarify → .plan → .tasks → .implement0 / 9 / 0仕様駆動の最小構成を体験
gstack100k/office-hours → 3 種類の /plan-*-review → /design-shotgun → /review → /ship → /retro0 / 0 / 48CEO/Eng/Design の多角レビューを回したい
Matt Pocock Skills97k/grill-with-docs → /to-prd → /to-issues → /triage → TDD → /diagnose → /improve-codebase-architecture0 / 0 / 28要件詰めから PRD 化までを丁寧に
Get Shit Done63k/gsd-new-project → discuss → plan → execute → verify → ship → complete-milestone33 / 67 / 0個人開発で速度を求める
OpenSpec50k/opsx:propose → :apply → :archive の 3 段0 / 11 / 03 段だけのミニマル仕様駆動
BMAD-METHOD48kproduct-brief → PRD → architecture → epics-and-stories → sprint-planning → story-by-story 実装0 / 0 / 42PdM/PM と協働するチーム
oh-my-claudecode34k/deep-interview → /team → 5 段 team フロー → /ralph → merge19 / 0 / 39Team モードと Ralph ループを使いたい
agent-skills27k/spec → /plan → /build → /test → /review → /ship3 / 7 / 21王道 6 段、迷ったらここから
Compound Engineering17k/ce-ideate → brainstorm → plan → work → code-review → debug → optimize → compound49 / 4 / 38アイデア発散段階から伴走させたい
HumanLayer11k/create_plan → /validate_plan → /implement_plan → /iterate_plan → /local_review → /commit6 / 27 / 0Plan 検証と iteration を厳密に分けたい

A = Agent / C = Command / S = Skill の数。表中の略語は以下のとおりです。TDD = Test-Driven Development (テスト駆動開発、テストを先に書いてから実装する手法)。PRD = Product Requirement Document (製品要件定義書)。RPI = Research-Plan-Implement (調査 → 計画 → 実装の 3 段階パターン)。

12 件の流れを並べて眺めると、構成要素の粒度や名前は違っても どれもほぼ同じパターンに収束している ことが分かります: Research → Plan → Execute → Review → Ship。これは作者本人が README で強調しているポイントで、ベテランほどこの 5 段に自然と寄っていく、という観察的事実とも一致します。

ワークフローを選ぶ際の見方をいくつか挙げます。Spec Kit は 6 個の slash command だけで完結する最小構成で、まず「仕様駆動の流れ」を体験するのに適します。Everything Claude Code (ECC) は 48 agents + 143 commands + 230 skills という超大規模で、商用プロダクトでフルセット導入したい人向け。BMAD-METHOD は PRD → architecture → sprint planning という「マネジメントの言葉」で構成されているので、PdM や PM と協働するチームに馴染みやすい。Matt Pocock Skills は /grill-with-docs で要件を詰めてから PRD 化する流れが特徴的で、Matt 氏自身の YouTube 解説と組み合わせれば理解が早いです (リポ内 videos/claude-matt-pocock-24-apr-26.md)。

リポ独自の方法論として、development-workflows/ ディレクトリには Cross-Model Workflow (cross-model-workflow.md) と RPI Workflow (rpi-workflow.md) が独自に整備されています。RPI は Plan agent と 8 種類の専門 agent を組み合わせた research-plan-implement パターンの実装です。専門 agent は constitutional-validator / requirement-parser / ux-designer / senior-software-engineer 等です。リポ内 .claude/agents/ に実体ファイルがあるため、そのまま参照できます。

筆者の実装例 (~/.claude/)

筆者は表中の 12 ワークフローのどれも 丸ごとは採用していません。代わりに、Plan-and-Solve (ACL 2023) / Plan-and-Act (ICML 2025) の論文エビデンスを根拠に、plan-then-execute Workflow Gate という規範を採用しています。これは ~/.claude/rules/plan-then-execute.md に harness 規範化したものです。「3 ファイル以上 / 不慣れ領域 / アーキテクチャ判断 / 不可逆変更を伴うタスクは、実装着手前に必ず Plan フェーズを分離する」というシンプルな gate です。

SPECIFY → PLAN → TASKS → IMPLEMENT の 4-phase 構造そのものは、表中 12 件には含まれていない addyosmani/agent-skills (MIT) の spec-driven-development skill で運用しています。この skill は ~/.claude/skills/spec-driven-development/ に取り込み済みです。Skill が trigger 発話 (「仕様駆動」「spec から進めて」) で自動起動するため、Spec Kit のように /specify.constitution から手動で打鍵する必要がありません。

ワークフローを「外部からまるごと導入する」のではなく 「個別 skill 単位で取り込んで自前 rule と組み合わせる」 のが筆者方針で、これは表中のどのワークフローとも違う独自スタイルです。BMAD-METHOD の PRD → architecture の流れや Get Shit Done の discuss → plan → execute 等は、参考にした部分があれば個別の skill description にコメントを残す運用にしています。

採用判断

1 つだけ採用するなら Spec Kit (シンプル、6 コマンドだけ) か ECC (網羅型、商用想定) を推奨。チームに導入するなら BMAD-METHOD、個人で速度を求めるなら Get Shit Done あたりも候補。複数試してみて、しっくり来るものを 1 つだけ残す方が定着します。

第 5 章: Skill / Agent コレクションライブラリを借りる​

ワークフローではなく、個別の SKILL.md / agent.md を「ライブラリ」として配布しているリポも多数あります。README の 🧰 SKILL COLLECTIONS と 🤖 AGENT COLLECTIONS セクションがこれを整理しています。

Skill コレクション (8 件、star 数順):

リポ★Skill 数
anthropics/skills138k17
mattpocock/skills97k24
wshobson/agents36k155
impeccable27k1 (デザイン 7 ドメイン参照)
addyosmani/agent-skills27k21
scientific-agent-skills25k138
awesome-agent-skills22k1,100+ (キュレーション一覧)
claude-skills15k246 (9 ドメイン横断)

Agent コレクション (2 件):

リポ★Agent 数
msitarzewski/agency-agents105k144
VoltAgent/awesome-claude-code-subagents20k151

選び方のポイントは 2 つあります。1 つは ドメイン特化か汎用か。デザイン業務なら impeccable、研究用途なら scientific-agent-skills が個別ドメインに最適化された SKILL.md を提供します。汎用なら Anthropic 公式の anthropics/skills と Matt Pocock 氏の mattpocock/skills を入れておけば日常作業はカバーできます。

もう 1 つは メンテナンス頻度。Claude Code 自体が頻繁にアップデートされるので、半年以上更新が止まっているリポは frontmatter フィールドが古い可能性があります。README の表は star 数だけでなく更新時期も把握できるよう作られているので、コレクションを選ぶ際は元リポの commit 履歴も合わせて確認すると安全です。

筆者の実装例 (~/.claude/)

筆者は外部コレクションを 丸ごとは採用せず、自前で 38 skills + 7 agents + 1 team を運用しています。理由は以下の 2 点です。

  • trigger 発話のカスタマイズが必要: 各 skill の自動起動条件 (「レビューして」「バグ」等の日本語発話) を自分のタイピング習慣に合わせて細かく設定したいため、外部 skill を入れると description 全件を再編集することになりがち
  • Generator-Evaluator 分離の意図的設計: 第 2.1 章で述べたとおり、agent 群は「作る側 3 / 評価する側 4」で role-based 分離を意図的に組んでいる。外部 agent コレクションは「全部 generalist」「全部 specialist」のどちらかに寄っているケースが多く、設計思想ごと取り込めない

ただし「自前 vs 外部」は二項対立ではなく 個別 skill 単位で取捨選択 しています。例えば前章で触れた spec-driven-development skill は addyosmani/agent-skills (MIT) から取り込んだもので、自前 rule (~/.claude/rules/plan-then-execute.md) と組み合わせて使っています。コレクション全体を導入するのではなく「気に入った skill だけ 1 つずつ取り込み、自前環境と整合させる」運用が現実的です。

採用判断

ドメイン特化が要るなら専用 collection (impeccable / scientific-agent-skills 等) を、そうでなければ anthropics/skills + mattpocock/skills の 2 つだけ で十分実用的。awesome-agent-skills は 1,100+ のキュレーション一覧なので「他に何があるか」を探す入口として使います。

第 6 章: Cross-Model WorkflowsClaude Code に他モデルを混ぜる​

README の 🔀 CROSS-MODEL WORKFLOWS セクションでは、Claude Code を Codex / Gemini / GPT / Kimi / DeepSeek / local モデル等と組み合わせる方法が 3 つの方式 に分類されています。

方式概念代表リポ
Plugin他モデルの CLI を Claude Code 内から呼び出す (/codex:review 等)openai/codex-plugin-cc (18k★)
MCPClaude Code が他モデルを「tool」として呼ぶBeehiveInnovations/pal-mcp-server (12k★、Gemini / OpenAI / Azure / Grok / Ollama / OpenRouter 50+ モデル対応)
RouterClaude Code の API endpoint を別 provider に振り替えmusistudio/claude-code-router (34k★)、router-for-me/CLIProxyAPI (32k★)

リポ独自の方法論 development-workflows/cross-model-workflow/cross-model-workflow.md は、Plan を Claude Code で、QA-Review を Codex で行う「手動 2-terminal フロー」を推奨しています。これは Plugin / MCP / Router いずれにも依存せず、すぐ試せる構成です。

筆者の実装例 (~/.claude/)

筆者は cross-model を 意図的に採用していません。Anthropic 内のモデル群 (Opus 4.7 / Sonnet 4.6 / Haiku 4.5) を subagent の model: フィールドと Fast Mode (/fast) で使い分けます。さらに adaptive thinking (effort level low/medium/high/xhigh/max) も併用すれば、必要な推論深さとコストのバランスは取れているという判断です。

cross-provider router (musistudio/claude-code-router 等) を導入すると、料金体系の二重管理 / Anthropic 公式機能との互換性のリグレッション追跡 / 用途別の品質差検証 / API key 管理の複雑化など、運用負荷が大きく上がります。これに見合うリターン (例: DeepSeek でコスト 1/10 化など) が筆者業務では明確でないため、現時点では Anthropic 単独運用を続けています。

将来採用するとしたら、第一候補は router 方式 (claude-code-router 経由で OpenRouter にバックアップを通す) です。Plugin 方式 (openai/codex-plugin-cc で Codex を /codex:review として呼ぶ) は cross-model QA レビューが必要な場面が増えれば検討、という温度感です。

なお Anthropic 内ルーティングについては、effortLevel: xhigh を default にしています。architect / debugger / propose 等 28 件の subagent / skill では frontmatter で effort: max を上書き指定する、という細かい使い分けを harness で組んでいます。詳細は第 7 章の Workflows Advanced カテゴリで触れます。

採用判断

主要モデルを Claude Code 内に統合したいなら Plugin (openai/codex-plugin-cc) です。コスト最適化したいなら Router (musistudio/claude-code-router で OpenRouter / DeepSeek / Ollama に振り分け)。Claude を主役のまま他モデルに QA レビューさせたいなら MCP (pal-mcp-server) という棲み分けで考えると選びやすいです。

第 7 章: 83 個の Tips を 15 カテゴリで概観する​

README の 💡 TIPS AND TRICKS (83) セクションは、開発陣やコミュニティから集められた Tips を 15 カテゴリ に分けて表化したものです。出典は Boris Cherny (Claude Code 開発者) / Thariq (Anthropic) / Cat Wu / Dex Horthy / Lydia Hallie / コミュニティ等です。各 Tip には元ツイートや元動画への直リンクが付いていて、文脈ごと辿れるようになっています。

カテゴリと件数、そして象徴的な Tip を 1-2 個ずつ取り上げます。

カテゴリ件数象徴的な Tip
Prompting3"grill me on these changes — PR を作る前に Claude にテストさせろ" (Boris)
Planning/Specs7"always start with plan mode" (Boris), "AskUserQuestion で Claude にインタビューさせて仕様を引き出す" (Thariq)
Context5"context rot は ~300-400k tokens 周辺で発生" / "dumb zone は ~40% context — 新人は 40%、ベテランは 30% 以下を死守" (Thariq / Dex)
Session Management6"new task = new session" / "/compact vs /clear はトレードオフ" (Thariq)
CLAUDE.md + rules8"CLAUDE.md は 200 行以下、humanlayer は 60 行" / "paths: frontmatter で lazy-load"
Agents4"feature 特化型 subagent を作れ、general qa とか general backend とかは作るな" (Boris)
Commands3"1 日 1 回以上やる作業は skill か command にせよ" (Boris)
Skills9"skills are folders, not files — references/, scripts/, examples/ で progressive disclosure" / "Gotchas section は最重要、Claude の失敗ポイントを蓄積せよ" (Thariq)
Hooks5"PostToolUse hook で auto-format — Claude が生成するコードの最後 10% を仕上げて CI failure を防ぐ" (Boris)
Workflows5"thinking mode true + Output Style Explanatory で意思決定が見える" (Boris)
Workflows Advanced9"/sandbox で permission prompt -84%" / "Opus 4.7 の effort level を low / medium / high / xhigh / max で動的調整" (Boris)
Git / PR5"PR の p50 は 118 行 — 141 PR / 45K 行/日 のうち中央値" / "always squash merge" (Boris)
Debugging6"screenshot を Claude に渡せ" / "agentic search (glob + grep) beats RAG — Claude Code は vector DB を試して破棄した" (Boris)
Utilities5"iTerm / Ghostty / tmux > IDE" (Boris)
Daily2"Claude Code を毎日アップデート" / "朝、CHANGELOG を読む"

各カテゴリの右側には Boris / Thariq の元投稿リンクが付いていて、原文の文脈を確認できます。特に tips/claude-boris-6-tips-16-apr-26.md (Opus 4.7 関連の最新 6 Tips) には、2026 年時点の Claude Code 運用に直結する内容がまとまっています。tips/claude-thariq-tips-16-apr-26.md (Session Management と 1M context の使いこなし) も同様です。

Tips の中には 🚫👶 (do-not-babysit) というマークが付いているものがあります。これは「Claude に細かく口出しせず任せろ」系の Tip を区別するためのアイコンです。grill me、fix だけ言う、use subagents to throw more compute at it、Code Review の自動化、@claude でレビュー lint rule を自動生成、等が代表例です。「Claude を信頼して手放す」段階に進む人向けの位置づけです。

CLI binary から抽出された hidden Tips は reports/claude-spinner-verbs-and-tips.md にまとめられています。こちらでは、公式 README には載っていないものの CLI 内部で使われているスピナー verb (Pondering, Cogitating, Synthesizing 等) と関連 Tips も拾えます。

筆者の実装例 (~/.claude/)

主要 5 カテゴリの Tips に対する筆者の実装を対比表にまとめます。

カテゴリshanraisshan の象徴的 Tip筆者の実装 (~/.claude/)
CLAUDE.md + rules"CLAUDE.md は 200 行以下"436 行 (推奨の 2 倍超だが意図的)。詳細は path-scoped rule 20 件 + references/ 30 件に分散。常時 load は 10 件 / 722 行に抑制
Skills"Gotchas section は最重要"doubt-driven-development / mcp-builder / grill-me 等の SKILL.md に "When to Use" / "Loading Constraints" セクションを実装
Hooks"PostToolUse hook で auto-format"format ではなく suppression 検出 (check-suppression.sh) + 平文質問検出 (check-plain-question.sh) に転用
Agents"feature 特化型 subagent を作れ"architect / code-reviewer / debugger 等 7 件すべて特化命名、generalist 系ゼロ
Workflows Advanced"effort level を低 / 中 / 高 / xhigh / max で動的調整"~/.claude/settings.json で effortLevel: xhigh を default 化、frontmatter で skill 別に effort: max (architect / debugger / propose 等 28 ファイル) で上書き

ここで補足を 4 つ追加します。

Gotchas / Loading Constraints セクション が Tips で「最重要」と言われている理由は、SKILL.md の本文で「この skill が失敗しやすい条件 / 使ってはいけない場面」を明示すると、Claude が起動判断を間違えなくなるからです。筆者の ~/.claude/skills/grill-me/SKILL.md から実例を抜粋すると、以下のような構成になっています。

---
name: grill-me
description: 要件・設計を厳しい質問で詰めて曖昧性を排除する skill...
---

## When to Use
- タスク着手前の要件解像度向上
- 仕様が曖昧な状態で実装すると手戻りが大きい場面

## Gotchas (使ってはいけない場面)
- 既に明示指示済みの作業継続中 → 過剰な質問になる
- 純粋な事実確認 (Read / Grep で解決可) → AskUserQuestion を 1 回だけで十分

## Loading Constraints
- context が 50k tokens 超のときは skip 推奨 (詰問が context を圧迫する)
- 他 skill が in_progress の場合は割り込まない

このように ## Gotchas と ## Loading Constraints をセクション化しておくと、Claude が「今この skill を起動すべきか」を構造的に判断できます。逆にこれが無いと、不適切な場面で skill が暴発しやすくなります。

Path-scoped rule (lazy-load) とは、rule ファイルの frontmatter に paths: ["**/*.ts"] のような glob を書いておく方式です。その glob にマッチするファイルを Claude が Read した時だけ、rule が自動 load されます。frontmatter は以下のような形になります。

---
paths: ["**/*.ts", "**/*.tsx"]
---

# TypeScript Strict Mode 規範
- `any` 型は禁止
- ...

常時 load にすると context window を圧迫しますが、path-scoped にすればフロントエンド作業中はフロントエンド rule だけ、infra 作業中は terraform rule だけ、と必要なものだけが context に注入されます。筆者は 31 件中 20 件 (64%) を path-scoped 化して 200 行制約を実質的に回避しています。

Effort level は Opus 4.7 で推論の深さを動的に切り替えるパラメータ (low / medium / high / xhigh / max)。Anthropic 公式では coding/agentic タスクで xhigh が default 推奨です。max は overthinking (考えすぎ) + diminishing returns (= 投入量を増やしても得られる効果が頭打ちになる現象) リスクのため、日常 default にしないとされています。筆者は重要判断 (architect / debugger / propose 等) のみ frontmatter で max に上書きし、コスト効率を保ちつつ深い推論が必要な場面で精度を出しています。

Ratchet という用語が Tips に頻出します。これは「同じ失敗を 2 度起こしたら必ず rule / hook / learning のいずれかに永続化して、再発を構造的に不可能にする」原則のことで、筆者 harness では ~/.claude/rules/ratchet-workflow.md として規範化しています。Claude が同じミスを繰り返したら、その都度 prompt で叱るのではなく、deterministic な sensor (hook) や inferential guide (rule) に組み込んで「次は仕組みで防ぐ」という発想です。

なお ~/.claude/learnings/ には、core / frontend-vue / frontend-react / infra のカテゴリ別に 14 ファイル / 4,363 行の知見が蓄積されています。/learn skill の trigger 発話 (「追記して」「覚えといて」) で、1 件単位で即座に永続化する運用です。

採用判断

全 83 件を一度に読まず、直近で困っているカテゴリ だけ拾います。Context や Session Management で苦戦している人は Thariq の 16/Apr/26 まとめだけで方針が立ちます。Opus 4.7 や Auto Mode を試したい人は Boris の 16/Apr/26 まとめを優先。🚫👶 マークの Tips は中級者以上向けと捉えてください。

第 8 章: 12 本の Reports深掘り資料の地図​

reports/ ディレクトリには 12 本の深掘り解析が格納されています。Tips が「箇条書きで覚える知識」だとすれば、Reports は「文章で理屈を理解する読み物」です。

Report用途こんな読者に
why-harness-is-important「features は prompt と同じ」論への反論 (10 capability 表)harness の価値を疑っている人
claude-agent-memorymemory の 3 scope (user/project/local) を詳細解説セッション跨ぎ知識を永続化したい人
claude-global-vs-project-settings設定階層 6 段 + Tasks system個人 / チーム / 組織の設定境界を整理したい人
claude-agent-command-skill3 機能 (agent / command / skill) の境界線「どれを使うべきか」迷う人
claude-skills-for-larger-mono-reposmonorepo での skill 配置戦略複数 package を扱う人
claude-in-chrome-v-chrome-devtools-mcpブラウザ MCP (Claude in Chrome vs Chrome DevTools) の使い分けfrontend / E2E で Claude にブラウザ操作させたい人
llm-day-to-day-degradationモデル「劣化」現象の追跡と検証「最近 Claude が頭悪い気がする」と感じる人
claude-usage-and-rate-limitsrate limit の構造とプラン別上限業務利用でコスト管理する人
claude-advanced-tool-usetool use の高度パターンカスタム tool を実装する人
claude-agent-sdk-vs-cli-system-promptsAgent SDK vs CLI の system prompt 差分 (110+ fragments)SDK で独自 agent を組む人
claude-spinner-verbs-and-tipsCLI binary から抽出した hidden tipsClaude Code を deep dive したい人
learning-journey-weather-reporter-redesignweather example の設計再考過程orchestration pattern を学ぶ人

1 本だけ深掘り: why-harness-is-important.md​

12 本の中で最初に読むべき 1 本を選ぶなら why-harness-is-important.md です。これは「skills / commands / subagents / hooks も結局モデルに渡る prompt なんだから、強い prompt を 1 本書けば同じ結果になる」という reduction (還元論) への反論を、表形式で整理した論考です。

論旨の中核を要約すると次のようになります。

  • 単発タスク (例:「再帰版 flatten 関数を書け」) では確かに Output quality ≈ Prompt quality が成立する。これがチャットボットの世界。
  • だが本物のソフトウェア開発では Output quality = f(effective context, model capability, iteration loop) という関係になる。effective context (モデルが推論時に見るもの) はユーザーが打った prompt よりはるかに大きい。
  • harness の役割は、ユーザーが打った 6 トークンの prompt を、推論時には 5,000〜50,000 トークンの effective context に変換することにある。
  • harness にしかできない capability が 10 個ある。例えば context isolation (subagent が別 window で動く) や、harness-enforced tool restrictions (disallowedTools 等の deny 設定でモデルが tool を使う前にブロック)。lazy-loaded rules (paths: frontmatter)、hooks の deterministic な execution、model: による model routing、subagent の parallelism も挙がる。さらに memory による cross-session persistence、modular system prompt (CLI 内部で 110+ fragments を条件付き load) も該当する。最後が skill preloading と auto モードの permission classifier だ。これらは strong wording で代替できない。

ここで重要概念の Effective context について少し補足しておきます。これは「ユーザーが打鍵した prompt そのもの」ではなく、「harness が裏で注入する CLAUDE.md / rules / skills / agents 定義 / memory / MCP 出力をすべて合計した、推論時に実際にモデルが見る情報の総体」のことです。6 トークンの prompt が 5,000〜50,000 トークンの effective context に膨らむのが harness の役割です。これが「rules を強い文言で書けば済む」という reduction (還元論) では代替できない理由になっています。

このレポートを先に読んでおくと、第 2-4 章で紹介した機能群がなぜ存在するのかを理屈として捉えやすくなります。残り 11 本は自分の興味に応じて選ぶ形で問題ありません。memory に困っているなら claude-agent-memory、settings 階層を整理したいなら claude-global-vs-project-settings を選びます。ブラウザ自動化を考えているなら claude-in-chrome-v-chrome-devtools-mcp、という具合です。

筆者の実装例 (~/.claude/)

筆者は ~/.claude/ を Phase 0-13 の段階的進化として育ててきました。Phase は筆者固有の用語で、harness を一気に完成形にせず「節目ごとに rules / hooks / skills / agents を追加して必要性を検証する」運用の単位です。代表的な節目:

  • Phase 0: harness engineering 概念導入 (Guides × Sensors 二分法)
  • Phase 1: Computational Guards 実装 (check-suppression.sh / check-protected-files.sh 等の hook)
  • Phase 6: 4 指標 (Task Resolution Rate / Code Churn Rate / Verification Tax / Defect Escape Rate) による health check 計測
  • Phase 11: rules の path-scoped 化と token reduction (常時 load を 10 件 / 722 行に圧縮)
  • Phase 13: 持ち越し吸収 + Notification Sensor 整備 (最新の transitional)

各 Phase の意思決定は ADR (Architecture Decision Record) として ~/.claude/docs/adr/ に 16 件記録しています。ADR は「重要な設計判断を 1 件 1 ファイルで markdown 記録する慣習」で、「なぜそうしたか」を後から辿れます。代表的な ADR:

  • ADR-0001: harness self-review を月次 / 四半期 cron 化
  • ADR-0004: Phase 進化ロードマップ (Foundation 0-6 / Consolidation 7-9 / Next-Gen 10+)
  • ADR-0011: Opus 4.7 の effortLevel を env 撤去 + settings.json field に移行
  • ADR-0013: Plan-then-Execute を Workflow Gate として規範化

why-harness-is-important.md で紹介されている harness の 10 capability は、筆者環境では Phase 0-13 の追加ロードマップとほぼ対応しています。10 capability の内訳は context isolation / harness-enforced tool restrictions / lazy-loaded rules / hooks の deterministic execution / model routing です。残りが subagent parallelism / memory cross-session persistence / modular system prompt / skill preloading / Auto Mode classifier です。harness は「完成」ではなく「継続的に Ratchet を積み上げる」性質のもの、というのが Phase 運用から得た実感です。

なお Phase の詳細な背景理論や規範は別記事 harness-engineering でより深く扱っているので、harness の枠組み自体に興味がある方はそちらを参照してください。

採用判断

まず why-harness-is-important.md 1 本だけ読んで「features の価値」を腑に落とす。残り 11 本は「いま自分が困っているテーマ」のものだけ 1-2 本選んで読みます。全部読破しようとすると 30 分以上かかるので、必要な時に必要な分だけ。

第 9 章: 取捨選択ロードマップ自分のレベルで何を選ぶか​

ここまでで紹介してきた全要素から、自分のレベルに合うものだけ選ぶ ためのロードマップを 4 種類提示します。複数を中途半端に走らせるより、1 つを完走してから次に進む方が定着するため、まず自分の現在地に近いものを 1 つだけ選んでください。

9.1 初心者ロードマップまず Claude Code を動かせるようになる​

Claude Code をインストールしたばかり、または使い始めて 1 週間以内の段階を想定。

  1. セットアップ: tutorial/day0/README.md を読み、OS 別の手順 (linux / mac / windows) でインストール
  2. 初プロジェクト: tutorial/day1/README.md を辿って Claude Code を使った最初のコード生成を体験
  3. Tips 入門: Boris 13 Tips (03/Jan/26) を一読
  4. 実践: Tips の Prompting / Planning/Specs カテゴリだけ実践 (plan mode から始める / AskUserQuestion で仕様を引き出す / spec を書く)

この段階では subagent や hooks に手を出さず、まずは Claude Code 単体での会話と plan mode に慣れることに集中します。

9.2 中級者ロードマップ基本機能を組み合わせる​

Claude Code は使えているが、自分で .claude/ を育てるのはこれから、という段階を想定。

  1. 概念理解: best-practice/claude-subagents.md + claude-commands.md + claude-skills.md を順に通読
  2. showcase 実行: orchestration-workflow.md を clone して /weather-orchestrator を動かす
  3. Tips の応用: CLAUDE.md, Skills, Hooks カテゴリを実践 (CLAUDE.md を 200 行以下に整理、自分の skill を 1 個作る、PostToolUse hook で auto-format を仕込む)
  4. 自作: 自分の業務で 1 日 1 回以上やる作業を題材に、slash command を 1-2 個作る

この段階で自分の .claude/commands/ が 1 個でも増えれば、Claude Code との関係が変わってきます。

9.3 上級者ロードマップharness を設計する​

すでに自分の .claude/ を運用していて、次の改善方向を探している段階を想定。

  1. 理屈の整理: why-harness-is-important.md で harness の 10 capability を再確認
  2. 大規模ワークフローの精読: Superpowers (14 skills) と ECC (48 agents + 143 commands + 230 skills) のソースを読む
  3. cross-model 導入: cross-model-workflow.md を参考に Codex で QA レビューを 2-terminal で試す
  4. 並列化: agent teams / git worktrees / scheduled tasks の実装例を 1 つ試す
  5. 継続観察: Boris / Thariq の最新 tips を継続購読 (README の 🔔 SUBSCRIBE セクションに集約)
筆者の現在地

参考までに、筆者の ~/.claude/ は 2026 年 5 月時点で Phase 13 (持ち越し吸収 + Notification Sensor 整備) を完了しています。現在は Phase 14 (XML 全展開 + Six Sigma 統計手法 + Tree-of-Thoughts 推論パターン導入) に着手中です。第 8 章で書いたとおり Phase は筆者固有の節目単位で、ADR-0004 に進化ロードマップが残してあります。

実感としては、harness は 「完成して安定運用に入る」性質のものではなく、「四半期ごとに新しい Ratchet を積み上げる」性質のもの です。Claude Code 本体が頻繁にアップデートされる以上、当面はこの「継続的に harness を更新する」モードが続く見込みです。

並列化系 (agent teams / worktree / scheduled tasks) は導入済みですが、cross-model はまだ導入していません (第 6 章で書いた理由)。本格採用は claude-code-router 経由の router 方式から、というのが現時点の見立てです。

9.4 「3 つだけ」採用するなら時間がない人向け​

このリポを読む時間がなく、最も効くものを 3 つだけ採用したい場合の選び方。

  1. Plan Mode を必ず使う (Tips - Planning/Specs カテゴリ): 全ての複雑タスクで plan mode から入る。実装に飛びつかない。
  2. CLAUDE.md を 200 行以下に保つ (Tips - CLAUDE.md カテゴリ): プロジェクト指示書が肥大化すると Claude が無視し始める。簡潔に。
  3. feature 特化型 subagent を作る (best-practice/claude-subagents.md): general qa や backend engineer のような汎用名は避ける。payment-flow-verifier のような具体名の subagent を skill 付きで作る。

この 3 つだけでも Claude Code の出力の安定感は変わってきます。

採用判断

自分のレベルに最も近いロードマップを 1 つだけ選んで、それを完走してから次のレベルへ。並走させると認知負荷が上がって全部中途半端になるので、順序を守ることをおすすめします。

第 10 章: 注意点と Open Questions​

最後に、このリポを参考にする際の注意点と、作者が読者に投げかけている open question を確認します。

10.1 鵜呑みにしない 5 つの注意点​

  • 更新頻度の早さ: リポは Claude Code v2.1.145 (2026-05-19 リリース) ベース。Anthropic 側の機能名や仕様は頻繁に変わるため、重要な判断をする時は 公式 docs で必ず再確認してください。
  • 英語前提: 元 Tip の出典 (X tweet / YouTube / Reddit) は全て英語。リポ内の解説も英語のため、翻訳しながら読むか機械翻訳を併用する場面が出てきます。
  • コピペで動くわけではない: 多くは「実装ヒント」であり、.claude/agents/<name>.md の中身までは書かれていない場合があります。自分のプロジェクトに合わせた調整が前提です。
  • 業界トップの運用 ≠ 個人プロジェクトの最適解: Anthropic 社内や Boris 個人の workflow を、そのままチーム導入しても合わないことが多いです。「なぜそうしているのか」の理屈だけ抜き出して自分の状況に翻訳する姿勢が安全です。
  • コストへの注意: Cross-model workflow、Agent Teams の並列実行、Routines (cloud cron)、Computer Use 等の機能は API クレジット消費が大きく増えます。Anthropic Console で spending limit を必ず設定しておきましょう。

10.2 作者からの Open QuestionsBillion-Dollar Questions​

README 末尾には Billion-Dollar Questions というセクションがあり、作者自身が「自分にも答えがないが、解いた人がいたら教えてほしい」と公開している 13 個の未解決問題が並んでいます。代表的な 3 カテゴリを紹介します。

Memory & Instructions に関する問い (4 問):

  • CLAUDE.md に何を入れて何を入れないか
  • 既に CLAUDE.md がある状態で、別に constitution.md や rules.md は必要か
  • CLAUDE.md はどれくらいの頻度で更新すべきで、古くなったとどう判別するか
  • なぜ Claude は MUST と全大文字で書いても CLAUDE.md の指示を無視するのか (reddit 投稿: 80% 無視される事例)

Agents, Skills & Workflows に関する問い (6 問):

  • command vs agent vs skill はいつ使い分けるか — そして「vanilla な Claude Code」だけで十分なケースはどれか
  • agents / commands / workflows はモデル進化のたびに更新が必要か
  • generalist subagent vs feature/role 特化型 subagent はどちらが良いか
  • Claude Code 標準の plan mode を使うか、それともチームの workflow を強制する自前の plan command/agent を作るか
  • 個人 skill (例: 自分のコーディングスタイル付き /implement) とコミュニティ skill (例: /simplify) はどう共存させるか
  • 既存 codebase を spec markdown に変換 → コード削除 → AI に spec から再生成させて元と同じコードが復元できる時代は来るか

Specs & Documentation に関する問い (3 問):

  • 全 feature に spec markdown が必要か
  • spec の更新頻度はどう保つか
  • 新機能実装で他 spec への波及をどう管理するか

これらは「正解」を作者が知っているわけではなく、読者がそれぞれの現場で答えを見つける性質の問いです。本記事を読み終えた後の探求テーマとして覚えておくと、自分の運用が深まります。

採用判断

5 つの注意点を踏まえつつ、Open Questions は「自分の現場ではどう答えるか」を考えながら採用判断する。注意点 3 (コピペで動かない) と 4 (業界トップの運用が自分に合うとは限らない) は特に意識して、リポは「写経対象」ではなく「思考の材料」として扱うのがおすすめです。

第 11 章: まとめと関連リンク​

shanraisshan/claude-code-best-practice は、Claude Code をめぐる公式機能とコミュニティ実践を一次情報リンク付きで集約したキュレーション集です。本記事では 13 ディレクトリ構成、30+ の概念カタログ、12 の開発ワークフロー、8 + 2 のコレクション、3 種の cross-model 方式、83 個の Tips、12 本のレポートを概観し、レベル別の 4 ロードマップで取捨選択の道筋をまとめました。

このリポは「読んで終わり」というより、自分の .claude/ を育てる際の参照先として手元に置いておく類のものです。気になった概念があれば本記事のリンクから該当ファイルへ直接飛んで原文を読む、という使い方が向いています。

関連リンク​

最後に、このリポジトリは継続的にアップデートされています。本記事で紹介した数字 (445 ファイル / 83 Tips / 12 Workflows 等) は 2026 年 5 月 25 日時点のスナップショットです。最新の状態は元 README で確認してください。

Footnotes​

  1. isolation: worktree は subagent の frontmatter で指定する設定で、起動時に一時的な git worktree (作業用ディレクトリ) を自動生成し、変更を main workspace から隔離します。subagent が作業完了 (または失敗) すると、変更がなければ worktree は自動削除され、変更があれば path と branch が返ります。リファクタや大規模 debug など「失敗時に丸ごと破棄したい」作業で、main workspace を汚さずに済むのが利点です。 ↩

]]> ai-agent claude-code best-practice curation <![CDATA[ブログのドメインを notes.rewheel.dev に変更しました]]> https://notes.rewheel.dev/blog/rewheel-naming https://notes.rewheel.dev/blog/rewheel-naming Mon, 18 May 2026 00:00:00 GMT このブログのドメインを notes.rasshii.dev から notes.rewheel.dev に変更しました。あわせてサイト名も「Tech Notes」から 「Reinvent Notes」 に、タグラインを 「車輪を再発明して学ぶ」 に改名しています。

ドメインを変えるたびに「なんで変えたんだっけ」「なんでこの名前にしたんだっけ」を忘れてしまうので、決定までの経緯と検討プロセスを記録に残しておきます。同じように「個人ブログのドメインを変えたい」と思っている方のヒントになれば嬉しいです。

旧 notes.rasshii.dev の何が気に入らなかったか​

rasshii.dev は僕の GitHub / X ハンドル名から取った apex ドメインで、技術ブログ用にサブドメイン notes.rasshii.dev を切って運用していました。1 ヶ月ほど運用してみて、以下が引っかかりました。

  • 個人ハンドル名依存: ブログのコンセプトとハンドル名が結びつくと、サイトの方針を変えづらい
  • apex の用途が決まらない: rasshii.dev 自体をポートフォリオに使うつもりだったが、「個人ハンドル = ポートフォリオ」だと特徴が出にくい
  • 読者目線で意味が伝わらない: rasshii.dev を初見で見ても、サイトの内容が想像できない

要するに、ブログのアイデンティティをハンドル名から独立させたい と感じはじめました。

コンセプトから決める​

ドメイン名を考えるとき、いきなり候補を並べるよりも 「サイトの軸となるコンセプトは何か」 から決めたほうが筋がいいです。

このブログで僕がやりたいのは、要するに 「既存ツールや概念を、自分で作り直したり整理しなおしたりして理解を深める」 ことです。最近書いた ハーネスエンジニアリング入門 もまさにそれで、Anthropic / Hashimoto らが提唱する harness engineering の概念を、自分の ~/.claude/ 構成例とともに自分の言葉で再構築したものでした。

このパターンを英語のフレーズで言うと、ぴったりなのが "reinventing the wheel" (車輪の再発明) です。本来は 「すでにあるものを無駄に作り直す」 という否定的なイディオムですが、AI エージェントが何でも作ってくれる時代に 「あえて自分で作り直して理解する」 こと自体が学習価値を持つ、と考えると、この皮肉なフレーズをポジティブに反転させて使えそうだと思いました。

ドメイン名の候補出し​

「車輪の再発明 = reinventing the wheel」をテーマに、候補を出してみました。

候補カテゴリコメント
reinventingthewheel.comフル元フレーズ忠実だが 24 文字、Slack で誤記しやすい
reinvent.dev短縮 (既存単語)強い、reinvent 単体で意味成立
rewheel.dev造語7 文字、短く印象的、re + wheel で意味推測可能
wheelnotes.dev合成造語tech-notes リポ名との親和性、ノート感
wheellab.dev合成造語「車輪の実験室」、試行錯誤のニュアンス
whyreinvent.com反転問いかけ「なぜ再発明するか」、攻めたトーン

SEO 観点での検討​

最初は「SEO は気にしないから何でもいい」と思っていましたが、念のため検討してみました。結論として 現代の SEO では造語が有利になりやすい です。

既存フレーズ系 (reinventingthewheel.com など) の問題​

  • Exact Match Domain ペナルティ: Google は 2012 年に「キーワードを丸ごとドメインに入れたサイト」の評価を下げる仕様変更を入れました。コンテンツの質が低いと、むしろ逆効果になります
  • 検索競合多数: 「reinventing the wheel」は一般的なイディオムなので、上位表示は難しい
  • 覚えにくい / 綴り間違いリスク: 長いフレーズはシェア時に誤記されやすい

造語 (rewheel.dev など) の強み​

  • ブランド検索に強い: 「rewheel」を検索したときに 上位を取りやすい
  • 競合が少ない: 同じドメイン名がなければ SEO 競争が起きにくい
  • 短くシェアしやすい: 7 文字なら口頭・Slack での誤記リスクが低い
  • 大手の前例: Google / Spotify / Vercel：すべて造語または独自綴り

「ブランド検索の独占」は思った以上に強い武器で、現代の SEO は「内容で勝負 + ブランドで集客」という構造になっています。造語ドメインはこの両方を加速させます。

結局 rewheel.dev に決めた​

候補の中から rewheel.dev を選びました。決め手は:

  1. 7 文字と短い: Slack や口頭で URL を伝えるときに最短
  2. 意味が推測できる造語: re + wheel で「車輪を再び」というコンセプトが伝わる
  3. SEO 競争がゼロ: ブランド検索の独占ができる
  4. .dev TLD: Google が運営する技術者向け TLD、HTTPS 必須でクリーン
  5. 発音しやすい: 「リホイール」とそのまま読める

サブドメイン構成にした理由​

rewheel.dev を Vercel Domains で取得した後、最初は apex (rewheel.dev) でこのブログを公開していました。が、すぐに サブドメイン (notes.rewheel.dev) に変更 しました。理由は:

  • apex を将来の用途に温存: ポートフォリオ / landing / 別のサイトに rewheel.dev apex を使いたくなったときに切り替えやすい
  • 過去パターンとの一貫性: 旧 notes.rasshii.dev と同じ「notes.<brand>.<tld>」の形なので、URL パターンとして読者にも自然
  • 拡張性: 将来 blog.rewheel.dev / lab.rewheel.dev / api.rewheel.dev のような形でサブサイトを増やせる

rasshii.dev を取得したときと同じ反省で、apex は気軽に他用途に切り替えられないので、明確な目的が決まるまで残しておく のが個人的な定石になりました。

サイト名・タグライン・トップページ説明文も刷新​

ドメインを変えるなら、ついでにサイト名やタグラインも揃えたほうが一貫性が出ます。

項目BeforeAfter
サイト名Tech NotesReinvent Notes
タグライン個人的な技術発信車輪を再発明して学ぶ
説明文フロントエンド・バックエンド・インフラ・AI・学習ログなどを記録する個人的な技術発信サイトです。車輪の再発明は無駄と言われますが、あえて作り直すことで仕組みを深く理解できます。フロントエンド・バックエンド・インフラ・AI などを再発明しながら学んだことを記録する個人技術ノートです。

当初はサイト名を URL そのもの (notes.rewheel.dev) にしようと考えました。ブランドと URL を一体化させる ことで覚えやすさを狙う、Vercel や Linear のようなプロダクト系サイトでよく見るパターンです。ただ、いざ navbar に置いてみると コンセプト (車輪の再発明から学ぶ) が初見の人に伝わらない ことに気付き、より直接的に意味が伝わる 「Reinvent Notes」 に落ち着きました。re- (再び) + invent (発明する) + notes (記録) の 3 要素を合わせた構造で、ドメインを知らない人にも一目でサイトの性質が伝わります。

旧ドメイン (notes.rasshii.dev) はどうする?​

しばらく 削除せずに残します (1-2 週間程度)。理由は:

  • ブックマークしてくれている方の URL が即死しない
  • Slack や Twitter でシェアした古い URL がしばらく動く
  • 万一新ドメインで問題が出たときに旧 URL に戻せる

SEO 観点では「旧 URL → 新 URL の 301 リダイレクト」を設定するのが王道ですが、このブログは SEO を主目的にしていないので、シンプルに 両方並列で配信 する運用にしました。新ドメインが安定したら旧ドメインを削除する予定です。

まとめ​

ドメイン変更は地味な作業ですが、サイトのアイデンティティを 1 つの単語に圧縮する プロセスとして面白い経験でした。技術選定と同じで、複数候補を並べてトレードオフを検討するクセを付けると、後から振り返って意思決定の理由を再現できます。

  • 旧 URL: https://notes.rasshii.dev (しばらく並列で動きます)
  • 新 URL: https://notes.rewheel.dev

ブックマークしてくださっている方は、お時間あるときに新 URL に切り替えていただければ嬉しいです。これからも「車輪の再発明から学ぶ」記録を続けていきます。

]]> meta branding <![CDATA[ハーネスエンジニアリング入門: AI エージェントの信頼性は周囲の設計で決まる]]> https://notes.rewheel.dev/blog/harness-engineering https://notes.rewheel.dev/blog/harness-engineering Tue, 12 May 2026 00:00:00 GMT 「モデルを最新版に上げたのに、結局同じ間違いを繰り返す」「プロンプトを工夫してもどこかで頭打ちになる」。AI エージェントを業務に組み込もうとすると、必ずこの壁に当たります。これは多くの場合モデル本体の問題ではなく、モデルを取り囲む環境 (= harness) の設計品質に起因します。本記事では 2026 年 2 月以降に急速に体系化された ハーネスエンジニアリング (Harness Engineering) という考え方を、自分の ~/.claude/ 配下の構成例とあわせて整理します。

なお、用語の語源について軽く触れておきます。「harness」は『装備・馬具・(動詞で) 力を制御し活用する』意味を持つ英単語で、AI 文脈では Mitchell Hashimoto (HashiCorp 共同創設者) が 2026 年 2 月に「モデルを支える環境一式」の意味で導入しました。中核にある等式はとてもシンプルです。

Agent = Model + Harness

この等式を出発点に、harness とは何か、どう設計するか、どう段階的に育てるかを見ていきます。

本記事の読み方

本記事は 公式 / 業界共通の概念 と 自分の運用例 が混在しています。後者は :::info 自分の運用例 ::: のブロックで囲んで明示しているので、「あなたの Claude Code にもそのまま当てはまるか」「rasshii さん独自の運用か」を判別しながら読み進めてください。コード雛形もすべて自分の運用例ブロック内に置いています。

ハーネスエンジニアリングとは​

ハーネスエンジニアリングとは、AI エージェント (Claude Code / Codex / Cursor などの coding agent) が動作する 全環境を設計する実践 を指します。Mitchell Hashimoto が 2026 年 2 月に個人ブログで概念を提唱し、数日後に OpenAI の Ryan Lopopolo がフィールドレポートで追従しました。Lopopolo のチームは 5 ヶ月で約 100 万行のコードベースを 手書き 0 行 / 1500 自動 PR で構築したと報告しており、これが業界の注目を集めるきっかけになりました。その後 Anthropic / Augment Code / Birgitta Böckeler (Martin Fowler のサイト掲載) / SIG など複数社がそれぞれの語彙で体系化し、2026 年 5 月現在は業界共通の用語として定着しつつあります。

ハーネスエンジニアリングは、これまでの「プロンプトエンジニアリング」「コンテキストエンジニアリング」と階層的に区別される概念です。

層問いスコープ
Prompt Engineering何を尋ねるか単一インタラクション
Context Engineering何を見せるか1 つの context window 内
Harness Engineering環境全体をどう設計するか複数セッション横断 / 環境設計 / phase gate

プロンプトエンジニアリングが「単発の指示文を磨く」のに対し、ハーネスエンジニアリングは エージェントが今後ずっと動く環境全体 を対象にします。同じモデルでも、harness の設計品質次第でエージェントの信頼性は大きく変わる、というのが主張です。

中核等式: Agent = Model + Harness​

もう一度等式を書きます。

Agent = Model + Harness

ここでいう Model は Claude Opus / Sonnet / Haiku、GPT、Gemini といった LLM 本体です。Harness はそれ以外のすべてを指します。具体的には次のようなものが含まれます。

  • システムプロンプト
  • 常時注入される指示書 (Claude Code でいう CLAUDE.md)
  • ルール / スキル / サブエージェントの定義
  • MCP (Model Context Protocol) サーバー / 各種 tool / permissions
  • フック (PreToolUse / PostToolUse / Stop など、ツール実行前後の特定タイミングで発火する shell 連携。詳細は後述)
  • メモリ (会話を跨いだ永続化)
  • コンテキスト管理 (compaction [会話履歴の圧縮] や reset の戦略)
  • 検証ループ (CI / lint / type-check / 自動レビュー)

つまり「エージェントが世界とやり取りする経路」と「エージェントが自分を律する仕組み」をまとめて harness と呼びます。モデル単体の精度より、これらが噛み合っているかどうかが、業務利用に耐える信頼性を左右します。

二分法フレームワーク: Guides × Sensors​

harness の設計を整理する上で最も実用的なフレームが、Birgitta Böckeler（Thoughtworks Distinguished Engineer、Martin Fowler のサイトで公開）による Guides + Sensors の二分法です。

  • Guides (feedforward): 行動「前」のステアリング。失敗が起きる前に方向付けする
  • Sensors (feedback): 行動「後」の自己修正。間違いを検出して直す

さらにそれぞれを、Computational か Inferential かで十字に分類します。Computational は deterministic、つまり機械的に毎回同じ結果が返る検証 (lint / 型チェック / テストなど) です。Inferential は LLM-based、すなわち LLM の推論に依存する確率的な検証 (レビュー agent / 提案 skill など) です。すると 4 象限になります。

このフレームの重要な含意は、どちらか片方だけでは harness は機能しない ことです。

  • Feedback だけ (Sensors のみ): エージェントは同じミスを何度も繰り返した後でしか修正できない
  • Feedforward だけ (Guides のみ): ルールを書いても LLM は確率的に違反するため、効果を検証する手段がない
  • Computational だけ: 機械的な lint や型は通っても、設計の妥当性や仕様適合は見抜けない
  • Inferential だけ: LLM のレビューは確率的で、// eslint-disable のような明確な違反すら見落とすことがある

良い harness は 4 象限すべてで何か手を打ってある 状態を目指します。

CLAUDE.md / MCP / memory: harness の入口​

~/.claude/ 配下の細かいディレクトリに入る前に、Claude Code 標準で用意されている harness の入口 にあたる 3 要素を押さえておきます。これらは Anthropic が公式に提供している機能で、誰の Claude Code でも同じように使えます。

  • CLAUDE.md: プロジェクトルートや ~/.claude/ 直下に置く Markdown 指示書。起動時に常時 context に注入されます。@path/to/file 構文で他ファイルを auto-load (自動読み込み) できるため、ハブ的な位置づけになります
  • MCP (Model Context Protocol): 外部ツール / データソースへのアクセス手段。Claude Code に対するプラグインのようなものです。例: context7 (ライブラリの最新 docs)、aws-knowledge (AWS 公式 docs)、terraform、sequential-thinking (構造化推論)、serena (LSP ベースのコード検索) など
  • auto-memory: 会話を跨いで ~/.claude/projects/<project>/memory/ に永続化される情報 (<project> は git リポジトリから派生)。ビルドコマンド、デバッグ知見、アーキテクチャメモ、コーディング規約の好み、ワークフロー習慣などが蓄積されます

これら 3 つは harness の「外周の入口」にあたります。CLAUDE.md がエージェントに「今回も守ってほしいこと」を毎回伝え、MCP が「最新の一次情報にアクセスする手段」を提供し、memory が「前回までに学んだことを思い出させる」役割を担います。

自分の運用例

僕は CLAUDE.md の Quality & Accuracy Policy セクションに「MCP 第一選択 → WebSearch fallback」と明記しています。これは、WebSearch だけに頼ると古い情報を引きやすいためで、ライブラリ仕様は context7 / AWS は aws-knowledge / Terraform は terraform MCP / 複雑判断は sequential-thinking、と用途別に MCP を割り当てています。さらに、特定キーワード (例: 「ultrathink」「アーキテクチャ設計」) が発話に含まれたら sequential-thinking を自動起動するように CLAUDE.md でトリガーを定義しています。

~/.claude/ 配下の構成 (全体マップ)​

ここから先は具体的なディレクトリ構成の例として、自分の ~/.claude/ 配下を題材に紹介します。Claude Code 標準の機能と自分の独自運用を 2 列で対比した表が以下です。

ディレクトリClaude Code 標準機能自分の運用
rules/✅ Memory システムの一部 (auto-load 対象)29 ファイルに分割、frontmatter paths: で path-scoped 化
skills/✅ Skill システム (発話 trigger で起動)23 個、Step 0 で MCP 起動を強制
agents/✅ Subagent システム (隔離 context で起動)7 個、Generator (implementer) と Evaluator (code-reviewer / architect / test-strategist) を意図的に分離
hooks/✅ PreToolUse / PostToolUse / Stop などの hook システム2 個、suppression 検出 / 保護ファイル防御
teams/⚠️ 公式機能ではなく自分で定義した meta orchestration パターンmulti-perspective-review 等、複数 agent を main agent から spawn (起動)
references/❌ 公式機能ではなく自分の命名progressive disclosure 用、on-demand Read で context 節約
scripts/❌ 公式機能ではなく自分の運用月次 cron で consistency check / self-test
commands/✅ Custom slash command システム軽量な汎用コマンド (init / review / security-review など)
output-styles/✅ Output style システムレスポンス調整用、最小限のみ

「✅」が付いているディレクトリは Claude Code 公式機能の格納先で、誰でも同じ位置に置けば同じように動きます。「⚠️ / ❌」は個人的に切り出した運用上の慣習で、別に notes/ でも meta/ でも構わない名前です。読者の Claude Code でこれをそのまま真似する必要はありませんが、なぜそういうディレクトリを切ったのか の理由を以降の章で紹介します。

全体のレイヤ構造は、入口 (CLAUDE.md / MCP / memory) から Inferential Guides (rules / skills)、Generator/Evaluator (agents) へと進みます。その先に Computational Sensors (hooks)、Orchestration (teams)、補助 (references / scripts) が続く構成です。

rules/: Inferential Guides の中核​

Claude Code には Memory システムという仕組みがあり、~/.claude/rules/*.md (および各リポジトリの CLAUDE.md) を起動時に context に取り込みます。常時ロードされる rule と、frontmatter (Markdown 冒頭の --- 区切りメタデータ部) に paths: を持つ path-scoped rule (特定パスのファイルを読んだときだけロード) の 2 種類が公式にサポートされています。

rule は「LLM に向けた規範指示」なので、二分法フレームでいう Inferential Guide に分類されます。コンパイラや lint と違って違反を機械的に止められるわけではありませんが、エージェントに「こうあってほしい」を伝える最も基本的な手段です。

自分の運用例

僕は ~/.claude/rules/ を 29 ファイルに分割して運用しています。1 ファイルに詰め込みすぎると context window (LLM が一度に扱える情報量) を圧迫し、かつ「いつでも全部読まれる」状態になるためです。

  • 常時ロード: コーディング規約 (code-style.md)、Git ワークフロー (git-workflow.md)、harness 概念 (harness-engineering.md) など、どのタスクでも参照したいもの
  • path-scoped: Terraform 規約 (terraform.md、paths: ["**/*.tf"])、Ratchet ワークフロー (ratchet-workflow.md、関連 path Read 時のみ) など、特定ドメインに入ったときだけ必要なもの

各 rule の構造はだいたい次のような Markdown です。

---
name: code-style
description: コード可読性 / 命名規則 / コメント / シークレット管理
---

# Code Style

- Priority: readability > maintainability > performance > brevity
- 変数・関数・クラス名: English / コメント: Japanese ("why" を説明)
- Documentation format: JSDoc
- Credentials via environment variables only, never hardcoded

## Example (Good)

```ts
const MAX_RETRY_COUNT = 3;
function groupUsersByRole(users: User[]): Map<Role, User[]> { /* ... */ }
const apiKey = process.env.MY_SERVICE_API_KEY;
```

## Example (Bad)

```ts
function f(u: any[]) { /* ... */ }                // 命名違反
const apiKey = "hardcoded-value-here";            // ハードコード禁止
```
一般的な TypeScript コード品質の話題 (上記 code-style.md の harness 版ではなく、コードそのものをどう書くか) は本サイトの Docs に Clean Code (TypeScript) として体系化しています。命名・関数設計・SOLID 等は そちらを参照してください。

一方、特定の拡張子やパスでのみ参照したい規約は、frontmatter に paths: (minimatch グロブ) を追加するだけで path-scoped rule になります。Terraform 規約ならこんな感じです:

---
name: terraform
description: Terraform のコーディング規約 (provider バージョン / リソース命名 / シークレット管理)
paths:
  - "**/*.tf"
  - "**/*.tfvars"
---

# Terraform

- Provider バージョンは `~> X.Y` 形式で固定する
- リソース命名: `<service>_<purpose>` のスネークケース
- シークレットは AWS Secrets Manager / SSM Parameter Store 経由 (ハードコード禁止)
- module は input/output を明示し、可能な限り公式 Verified module を優先する

## Example (Good)

```hcl
provider "aws" {
  region  = "ap-northeast-1"
  version = "~> 5.0"
}

resource "aws_s3_bucket" "app_logs" {
  bucket = "${var.project_name}-app-logs"
}
```

この rule は .tf / .tfvars ファイルを Read したときだけ context に追加されます。フロントエンドだけ触っている日はロードされず context window が空くので、ドメイン別に分割しておくと効きます。

どちらの形式でも、Good / Bad の Example を必ず添えるようにしています。LLM は説明文だけより、具体例から「型」を学ぶほうが安定するためです。

:::

skills/: 発話駆動スキル​

Skill は Claude Code が公式に提供する仕組みで、特定の発話 (たとえば「レビューして」「提案して」「デバッグして」) で起動するワークフローを ~/.claude/skills/<name>/SKILL.md に記述します。SKILL.md の frontmatter で発話トリガー / 利用可能ツール / effort などを宣言し、本文で実行手順を記述する形です。

二分法フレームでいうと、/review や /debug のように出力後に検査・修正するものは Inferential Sensor、/propose のように事前ステアリングするものは Inferential Guide として機能します。

自分の運用例

僕は 23 個の skill を運用しており、主なものは /propose / /review / /debug / /learn / /explain / /compare / /tec-doc / /grill-me / /next / /checkpoint などです。共通の運用ポイントとして:

  • Step 0 で MCP 起動を強制: 複雑判断は sequential-thinking、ライブラリ仕様は context7、AWS は aws-knowledge を必ずロードするよう SKILL.md に書く
  • 反復プロトコル: /review は最大 3 反復で Critical / Major を 0 に収束、/propose は敵対的自己批判で最大 2 反復、/debug は Investigate → Fix → Verify を最大 3 反復、というように skill ごとに反復回数を決める

SKILL.md の雛形例:

---
name: review
description: コード変更を 7 観点 (正確性 / 可読性 / パフォーマンス / セキュリティ / 保守性 / 規約 / デグレ) で重要度付きレビュー
when_to_use: 「レビュー」「review」「見て」「チェック」発話で起動
allowed-tools: Read, Grep, Glob, Bash, WebSearch
effort: max
---

## Step 0: MCP 起動

- sequential-thinking (複雑判断時に強制)
- context7 (FW 用法検証時)

## Step 1: 変更範囲の把握

git status / git diff で対象ファイルを取得。

## Step 2-3: 7 観点レビュー → 重要度付け

Critical / Major / Minor / Nit の 4 段階で指摘。

## 終了条件

Critical / Major が 0 になるか、最大 3 反復に到達したら終了。

agents/: Subagent (Generator-Evaluator 分離)​

Claude Code には Subagent (サブエージェント) という公式機能があり、隔離された context で独立した役割を持つエージェントを起動できます。~/.claude/agents/<name>.md に定義し、main agent から Agent ツール (subagent を起動するための main agent 側の tool) 経由で呼び出します。

ここで harness engineering の重要原則のひとつ、Generator-Evaluator 分離 が登場します。Anthropic や業界共通の知見として「実装した agent が自分で評価すると self-evaluation bias が働き、品質を過大評価する」ことが分かっています。実装役 (Generator) と評価役 (Evaluator) は別の agent にする、というのが要点です。

自分の運用例

自分の ~/.claude/agents/ には 7 個の subagent を定義しています。

  • Generator 系: implementer (TDD [テスト駆動開発] + 型安全)、refactorer (振る舞い保存のリファクタ)、debugger (バグ自律解決)
  • Evaluator 系: code-reviewer (7 観点レビュー、read-only [読み取り専用])、architect (設計レビュー + 敵対的検証)、test-strategist (テスト戦略)、infra-reviewer (TF / IaC レビュー)

Evaluator 系は disallowedTools: Write, Edit を設定して、編集権限を持たない read-only な役割に固定しています。これで「レビュアーが勝手にコードを書き換える」事故を構造的に防げます。

subagent 定義の雛形:

---
name: code-reviewer
description: ペアプログラミング用コードレビュアー。コード変更後のレビューとガイダンスを提供
tools: Read, Grep, Glob, Bash, WebSearch
disallowedTools: Write, Edit
---

## Step 0: MCP 起動 (必須)

- sequential-thinking (複数仮説の検証で強制)
- context7 (FW 用法検証時)

## レビュー観点

正確性 / 可読性 / パフォーマンス / セキュリティ / 保守性 / 規約 / デグレ

## 出力フォーマット

- Critical / Major / Minor / Nit で重要度付け
- ファイル名 + 行番号で指摘箇所を明示
- 修正案を提示 (具体的な diff か命令で)

hooks/: Computational Sensors​

Claude Code の Hook システムは、特定のイベント (PreToolUse: ツール実行前、PostToolUse: ツール実行後、Stop: 応答終了時、UserPromptSubmit: ユーザー入力受信時 など) で shell コマンドを実行できる公式機能です。~/.claude/settings.json で hooks フィールドに登録します。

二分法フレームでいうと、hook は典型的な Computational 層: deterministic な仕組みで、入力と出力が毎回同じ shell スクリプトに従います。Guide 用途 (実行前ブロック) と Sensor 用途 (実行後検出) の両方に使えます。

自分の運用例

僕は 2 個の hook を運用しています。

  • check-suppression.sh (PostToolUse): // eslint-disable / @ts-ignore / # type: ignore / # noqa などの lint 抑制コメントの新規追加を検出 します。検出時は exit 2 で Claude にフィードバックを返し、根本原因の修正を強制します (編集そのものを未然に止めたいなら PreToolUse を使います)
  • check-protected-files.sh (PreToolUse): .env / 秘密鍵 / 認証情報ファイルへの書き込みを未然にブロック

check-suppression.sh の最小実装例:

#!/bin/bash
# ~/.claude/hooks/check-suppression.sh
# PostToolUse hook: lint suppression コメントの新規追加をブロック

set -eu

# 緊急時の override (環境変数で skip 可能)
if [ "${CLAUDE_HOOK_SKIP_SUPPRESSION:-0}" = "1" ]; then
  exit 0
fi

# hook 入力 (JSON) から新規追加コンテンツを取り出す
INPUT=$(cat)
NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // empty')

# 抑制パターンの検出
if echo "$NEW_CONTENT" | grep -qE '(eslint-disable|@ts-ignore|# type: ignore|# noqa)'; then
  echo "ERROR: Suppression comment is not allowed. Fix the root cause instead." >&2
  exit 2   # PostToolUse の exit 2 は Claude に feedback として返る
fi

exit 0

settings.json への登録例 (matcher フィールドで発火対象のツール名を正規表現で絞れます):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/check-suppression.sh" }
        ]
      }
    ]
  }
}

ポイントは 「rules で『any 禁止』と書くだけでは LLM は確率的に違反する」 という前提です。重要規範ほど deterministic な hook で機械的に止める、というのが harness engineering の中核哲学のひとつになります。

補助ディレクトリ (teams / references / scripts)​

ここからは Claude Code 標準機能ではない、自分の運用上の慣習として切り出したディレクトリです。読者がそのまま真似する必要はありませんが、なぜこういう箱が欲しくなるのかを共有しておきます。

teams/: Multi-agent Orchestration​

複数の subagent を協調動作させたいケースがあります。たとえば「10 ファイル以上の変更を、code-reviewer (品質) + architect (設計) + test-strategist (テスト) の 3 視点で並列レビューしたい」など。

自分の運用例

~/.claude/teams/multi-perspective-review/team.md に、main agent が 3 subagent を並列 spawn して結果を統合する手順を Markdown で記述しています。発話に「複数視点」「総合レビュー」「3 視点」が含まれたら main agent が team.md を Read して実行する、という運用です。

これは Claude Code 公式機能ではなく、subagent 機能の上に乗せた meta orchestration (複数 agent を束ねる統制) パターンです。

references/: 詳細プロトコル (progressive disclosure)​

rules/ に詳細な手順 / テンプレート / 適用例まで書き込むと、auto-load されるたびに context を圧迫します。そこで rules には 規範ルール (要約) だけ書き、詳細プロトコルは別の場所に置いて、必要時のみ Read する、という形で分離します (これを progressive disclosure [段階的開示] と呼びます)。

自分の運用例

~/.claude/references/ に 25 ファイルの詳細プロトコルを置いています。rules 側から「詳細プロトコル: ~/.claude/references/xxx.md (必要時 Read)」と参照する形です。これで context window を節約しつつ、深掘りしたいときは詳細にアクセスできます。

これも公式機能ではなく、命名も任意です。docs/ でも manuals/ でも構いません。

scripts/: 計測・検証​

harness 自体の整合性を機械的にチェックする shell スクリプト置き場です。

自分の運用例

~/.claude/scripts/ に内部整合性チェック (check-internal-consistency.sh) と self-test (self-test.sh) を置き、月次 cron (定期実行ジョブ) で実行しています。「rules 内のクロスリンクが壊れていないか」「skill の発話トリガーが衝突していないか」など、harness そのものの drift を検出する Computational Sensor です。

Phase 0-6 段階的導入パス​

ここまで個別のディレクトリを紹介してきましたが、これらを どういう順番で導入していくか が次の論点になります。「29 個の rules / 23 個の skills / 7 個の agents / 2 個の hooks」を一気に書こうとすると、context window が溢れ、規範が形骸化し、違反が量産されて基準そのものが崩壊します。

Phase 番号は自分で付けた整理軸です

以下の Phase 0-6 という段階分けは僕が自分の harness を整理するために便宜的に付けたラベルで、公式・業界標準の区分ではありません。ただし、各 Phase で扱う 個別の概念 (Computational Guards / Architecture Fitness / Generator-Evaluator 分離 / Spec-First / Ratchet / Metrics) は僕のオリジナルではありません。Hashimoto / Anthropic / Neal Ford / Birgitta Böckeler などの公式・業界由来です。

Phase名称主な成果物概念の由来
0概念整理harness 規範 rule の文書化Hashimoto / Lopopolo / Böckeler
1Computational Guardshook (suppression 検出 / protected files) + pre-commitAnthropic / 業界共通
2Architecture Fitnessdependency-cruiser / Conftest / tflint で構造制約検証Neal Ford (Building Evolutionary Architectures)
3Generator-Evaluator 分離subagent (implementer / code-reviewer / architect ...)Anthropic
4Spec-First PipelineCONTEXT.md (用語) / docs/adr/ (決定) / docs/specs/ (仕様)Hashimoto
5Ratchet Workflow失敗 → 永続修正への昇格手順Hashimoto の原則 + 自分の運用整理
6Metrics & Health Check4 Quality metrics の月次集計スクリプトHashimoto / Lopopolo

進化の流れを図にすると以下です。

各 Phase の狙いは次のとおりです。

  • Phase 0: まず harness とは何かを文書化する。rules/harness-engineering.md のような規範文書を書き、その後の Phase で何を強制したいかの 語彙 を揃える
  • Phase 1: rule (Inferential Guide) で書いた規範のうち、機械化できるものを hook / lint / type-check で deterministic に止める。LLM の probabilistic compliance を補完する最初の砦
  • Phase 2: 単一ファイルではなくファイル間関係 (循環依存 / レイヤ違反 / cross-feature 依存 [feature 間の不要な依存関係]) を CI で検出する。具体的には dependency-cruiser (JS/TS の依存方向検証) / Conftest (OPA Rego ベースの policy 検証) / tflint (Terraform linter) などのツールを使う。Neal Ford の Architecture Fitness Functions が出典
  • Phase 3: 実装役と評価役を別 subagent に分ける。Generator (implementer) と Evaluator (code-reviewer / architect / test-strategist) を意図的に分離し、self-evaluation bias を排除する
  • Phase 4: 用語定義 (CONTEXT.md) / 重要設計決定 (ADR) / 機能仕様 (docs/specs) を harness の必須入力にする。Spec を読まずに実装させない
  • Phase 5: 失敗パターンを rule / hook / fitness function に永続化して再発を構造的に不可能にする (Hashimoto の原則がベース。詳細は後述)。僕は中間置き場として learnings/ を使い、繰り返した失敗だけを昇格させる運用
  • Phase 6: harness 自体の信頼性を 4 Quality metrics (後述) で計測し、月次 cron で health check する

要点は「いきなり Phase 6 から始めない」ことです。Phase 0 と Phase 1 だけでも、ほとんどのプロジェクトで効果が出ます。

Ratchet Workflow: 失敗を永続修正に変える​

Phase 5 で登場した Ratchet の考え方は、harness engineering の中でも特に「これだけ覚えて帰っていい」レベルの中核原則なので、独立した節として取り上げます。土台にあるのは Mitchell Hashimoto がブログで示した原則で、原文に沿って要約すると次のとおりです。

agent がミスをしたと気付いたら、その都度、同じミスが二度と起きないような解決を engineering する。

僕はこの原則を Ratchet (ラチェット) と呼び、「同じ失敗が 2 度 観測されたら、必ず rules / hooks / fitness function / learnings のいずれかに 永続的修正 を加え、再発を 構造的に不可能 にする」という形で運用に落とし込んでいます。「ratchet」という呼び名、「2 度」という閾値、修正先の 4 分類は、いずれも Hashimoto の記事そのものにはない僕自身の運用整理です。

ratchet (ラチェット) は工具用語で「一方向にしか回らない歯車」を指します。一度進んだら戻らない、という性質を harness の学習ループに重ねた比喩です。「もう気をつけます」「次から注意します」では同じ失敗を必ず繰り返すので、気をつけなくても発生しない仕組み に組み込む、というのが要点です。

自分の運用例

僕は /learn skill で会話中に得た知見をその場で ~/.claude/learnings/<category>/<topic>.md に追記し、セッション終了時には /record-learnings skill で一括抽出しています。さらに、同じ失敗が複数回観測されたら learnings から rule や hook に昇格させます。たとえば「型違反を見落としがち」という learnings が積み重なれば、rules/typescript-strict.md に項目を足したり、TypeScript 設定を strict 寄りに更新したりします。

8 つの規範ルール​

ハーネスエンジニアリングの実践で守りたい主な規範を 8 つにまとめます。出典は公式 / 業界共通のものと、自分の運用方針が混在しています。

  1. Anything not in context doesn't exist (Hashimoto / Lopopolo): agent に伝えたい情報は repository-local かつ versioned な artifact に置く。Slack や口頭、個人の頭の中は agent から見えない
  2. Probabilistic compliance を信用しない (業界共通): rule で「any 禁止」と書いても LLM は確率的に違反する。重要規範は computational sensor (lint / hook / CI) で deterministic に強制する
  3. Generator と Evaluator は分離する (Anthropic): 実装した agent に自己評価させない。別の subagent でレビューする
  4. Inline-disable suppression を許さない (業界共通): // eslint-disable-next-line / @ts-ignore で sensor を抑制するのは harness を空洞化させる最大の anti-pattern。修正で対応する
  5. Ratchet principle (Hashimoto の原則に基づく自分の運用整理): 同じ失敗を 2 度起こしたら永続的修正を加える。再発を構造的に不可能にする
  6. Volume metrics を主指標にしない (Hashimoto / Lopopolo): 「AI が書いた行数」「採用された提案数」は harness 信頼性を反映しない。後述の Quality metrics を使う
  7. Context Resets > Compaction (Anthropic / Hashimoto): 長期タスクを compaction で延命させず、構造化ハンドオフで完全リセットして新規 agent を起こす
  8. Spec drift を sensor で検出する (Hashimoto): CONTEXT.md / ADR / docs/specs と実装の乖離は下流テストでは捕捉できない。Evaluator agent が仕様準拠で判定する

アンチパターン​

harness を組むときによく起きる失敗パターンも併せて挙げておきます。

  • One-shot completion: 複雑タスクを一発完了させようとする。途中で hand-off (別 agent / 次セッションへの引き継ぎ) / 反復を入れない
  • Rules files alone: rule だけ書いて computational sensor を併設しない。Inferential Guide のみだと違反は確率的に発生する
  • Over-constraining: 厳しすぎる制約で legitimate な refactoring まで阻害する。「全部禁止」は誰も従わなくなる
  • 完了の早期宣言: verification なしで「完了」と言う。テスト・型・lint の確認なし
  • 部分実装の放置: 途中状態のままハンドオフ。次セッションが拾えない
  • Self-evaluation only: Generator agent に自己評価させる。code-reviewer / architect など別 agent を介さない

4 Quality metrics​

最後に、harness 自体の品質を測る指標を整理します。コードの「行数」「採用率」のような Volume metrics ではなく、信頼性に直結する Quality metrics を主指標にすべき、というのが Hashimoto / Lopopolo の主張です。

指標内容なぜ大事か
Task Resolution Rate自動テストで検証された正解率エージェントが「自称完了」したものの実際の合格率
Code Churn Rate2 週間以内に破棄されたコードの割合短期で書き直された量。harness が安定設計を導けたかの指標
Verification TaxAI 生成コード監査に費やした時間人間のレビュー負荷。これが下がるほど harness が信頼できる
Defect Escape Rate本番に到達した欠陥率最終的なユーザー影響。harness 全体の総合スコア

Volume metrics との対比は次のとおりです。

  • Volume metrics は「使用量」を測る (e.g. AI が書いた行数、受諾された提案数): エージェントがどれだけ働いたか
  • Quality metrics は「信頼性」を測る: エージェントがどれだけ役に立ったか

harness の良し悪しは Quality 側で評価しないと、「たくさん書いたけど 2 週間後に全部書き直し」が高得点になってしまいます。

はじめの一歩 (実践指南)​

ここまで読んで「全部一気にやるのは無理だ」と感じたら、それで正解です。ハーネスエンジニアリングは段階的に育てるものです。読者が今日から始められる最小ステップを 3 つ挙げておきます。

  1. CLAUDE.md を 1 ファイル書く: プロジェクトルートか ~/.claude/CLAUDE.md に「このプロジェクトで守ってほしいこと」を Markdown で 5-10 行。「型は any 禁止」「コメントは日本語」「テストを書いてから実装」など、自分が普段口頭で伝えていることを文字に起こすだけで十分です
  2. 失敗したら learnings に記録: 同じミスが 2 回出たら、CLAUDE.md か別の rule ファイルに永続化する (Ratchet Workflow)。「気をつける」ではなく「次から発生しない仕組み」に倒す
  3. 重要なものは Computational Sensor で deterministic 化: 型安全 (TypeScript strict) や lint (ESLint) は LLM の意思にかかわらず違反を弾けます。一番効くのは pre-commit hook (Git コミット前に走るチェック) と CI

「いきなり 29 個の rules / 23 個の skills を書かない」が最大の落とし穴回避策です。1 ファイルから始めて、必要が出るたびに増やすほうが、長期的には強い harness になります。

出典・参考リンク​

用語提唱・中核概念​

Anthropic 公式 (Long-Running Agents)​

二分法フレームワーク​

Architecture Fitness Functions​

Claude Code 公式 docs​

ツール公式​

語源​

まとめ​

最後にもう一度、中核等式を確認します。

Agent = Model + Harness

モデルを最新版に上げても精度が頭打ちなら、harness を疑う。harness は Guides (feedforward) と Sensors (feedback) の 2 軸、それぞれを Computational / Inferential で十字分類して設計する。一気に全部入れず、Phase 0 (概念整理) と Phase 1 (Computational Guards) から始める。失敗は気をつけるのではなく Ratchet で構造的に不可能にする。

本記事を読み終えたあなたが「自分のプロジェクトでも、まず CLAUDE.md を 1 ファイル書いてみよう」と感じたなら、この記事は十分に役目を果たしたと思います。

]]> ai-agent claude-code harness-engineering <![CDATA[Welcome to Reinvent Notes]]> https://notes.rewheel.dev/blog/welcome https://notes.rewheel.dev/blog/welcome Wed, 29 Apr 2026 00:00:00 GMT このブログを始めました。Docusaurus + Vercel で個人的な技術発信を続けていきます。

このサイトの方向性​

  • ブログ (このページ): 学んだこと・調査メモを時系列で発信
  • Docs: 体系的にまとめたリファレンスやガイドを蓄積
  • スコープ: フロントエンド・バックエンド・インフラ・AI・学習ログ等

なぜ Docusaurus か​

技術ノートを発信するうえで、ブログとドキュメントを 1 つのサイトに併設できるのが Docusaurus の強みです。 Markdown で書けて、タグ・RSS が標準で備わっているのも嬉しいところ (検索もプラグインで簡単に追加できます)。

// Sample code block
const greeting: string = 'Hello, Reinvent Notes!';
console.log(greeting);

数式テスト​

インラインで E=mc2E = mc^2、ブロックで:

∫0∞e−x2dx=π2\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}

図表テスト​

これから書きたいこと​

  • 開発環境のセットアップ手順
  • AWS/Terraform の運用 Tips
  • AI/LLM (Claude) を活用した開発フロー
  • 読書メモやカンファレンス参加記

よろしくお願いします。

]]> meta