本記事は Zenn にも掲載しています。
AI コーディングエージェントに、同じ指摘を何度もしていませんか?
「日付は dayjs を使ってと言ったのに」「そのボタン、また二重送信できるよ」「その色、トークンにあるのにハードコードしてる」。モデルは賢いのに、あなたのチームの過去の失敗を知らない。だから同じミスを繰り返します。
筆者のチームでは、AI レビューの指摘のうち「過去に出たものと同種の指摘」を予防可能違反と呼んで毎タスク数えています。直近数タスクの実測では、これが初回の P0/P1 指摘の約4割（22/53件）を占めていました。これらはレビューと修正のループが検出して自動で直せてはいます。ただ、既知のミスなら検出して直すより、そもそも出る前に消したい。検出→修正の往復には、毎回コストがかかるからです。
そこで発想を変えました。モデルが賢くなるのを待つのではなく、環境が学習するようにする。 本シリーズは、実運用中の Claude Code Skills 群（スキル18個・サブエージェント12体）を素材に、その作り方を全4回で紹介します。
- 全体像（本記事） — 4つの「〇〇エンジニアリング」の流れと、環境全体の設計
- 設計書1枚から実装・レビュー・PRまで — 開発フローを回すオーケストレーター Skill
- AIレビューの指摘を資産化する — 追記専用ログと予防DoDで作る自己学習ループ
- Figma to Code を閉ループにする — 測定ファーストの視覚一致ループ
用語メモ（本シリーズ共通）
- エージェント: 指示を受けて、コードの読み書きやコマンド実行まで自律的にこなす AI のこと
- サブエージェント: メインの AI が子タスク用に別途起動する、独立した作業用 AI
- CLAUDE.md: Claude Code が毎回必ず読み込む、プロジェクトのルールを書いたファイル
- Skill: 特定の作業の手順や知識をまとめたファイル群。必要なときだけ読み込まれる
- P0 / P1 / P2: レビュー指摘の重要度ラベル（P0=必ず直す / P1=直すべき / P2=改善提案）
- コンテキスト: AI が一度に読み込める情報の器。上限があり、使うほど劣化やコスト増につながる
- トークン: AI が文章を処理する単位。API 利用料や処理量の基準になる
-
frontmatter: Markdown ファイル冒頭に
---で囲んで書く設定欄（名前・説明文など） - モノレポ: 複数のアプリ・パッケージを1つのリポジトリで管理する構成
1. 4つの「〇〇エンジニアリング」— プロンプトの先に何があるか
まず、本シリーズの立ち位置を整理します。AI コーディングの設計手法は、この数年で段階的に積み上がってきました。
| 層 | 誰が定着させたか | 一言でいうと |
|---|---|---|
| Prompt Engineering | — | 「何を言うか」の設計 |
| Context Engineering | Tobias Lütke（Shopify CEO）のツイート（2025年6月）を Andrej Karpathy（著名なAI研究者）が支持して定着 | LLM に渡す情報環境全体の設計 |
| Harness Engineering | Mitchell Hashimoto（HashiCorp 共同創業者）が2026年に用語を定着させた。ハーネス設計の議論自体は Anthropic が2025年末から公式記事で先行 | モデルを取り囲む足場（ツール・検証・フィードバック）の設計 |
| Loop Engineering | Peter Steinberger らの議論を受け、Addy Osmani（Google のエンジニア）が2026年6月のエッセイで命名。Claude Code 開発責任者 Boris Cherny の「my job is to write loops」も同じ思想 | 足場を「いつ・誰が・どの頻度で」回すかまで含めた、自走するループの設計 |
誤解されがちですが、この4層は置き換えの関係ではなく積み上げです。CLAUDE.md や Skills を整えるのは Context の仕事。レビューエージェントや品質ゲートを組むのは Harness の仕事。そしてそれらが自動で回り、回るたびに環境自体が更新されていくところまで設計するのが Loop の仕事です。
なお、この層の切り方は論者によって揺れがあります。Loop Engineering を命名した Addy Osmani 自身、Loop を「ハーネスの一階上」と位置づける一方で、両者を「従兄弟（cousin）」とも呼んでいます1。ハーネス側にフィードバックループまで含める広い整理も存在し、境界線は確定していません。本記事の4層は「関心が、1回の応答の中身から、回り続ける仕組みへと外側に広がっていく」順序を示す見取り図として使います。
Harness Engineering を定着させた Mitchell Hashimoto は、その定義をこう書いています2。
エージェントがミスするたび、同じミスが起きないよう環境側に恒久的な修正を入れる。
ただ、この「恒久修正を入れる」を人の心がけに任せておくと、忙しい週から順に守られなくなっていきます。本シリーズで紹介するのは、これをデータ構造と定型フローに落として、忘れようがない形にした実例です。新しい概念の発明ではなく、この流れの上にある実践報告として読んでもらえればと思います。
2. 前提: どんな環境で運用しているか
筆者のチームでは、管理画面・ユーザー向けフロントエンド2つ（Next.js）・バックエンド API（NestJS）・Playwright E2E を含むモノレポを運用しており、
.claude/skillsに18個のスキル、.claude/agentsに12個のサブエージェント定義を置いています。
.claude/ ディレクトリの全体像はこうです。
.claude/
├── skills/ # 18スキル
│ ├── workspace-plan/ # ★開発フロー全体のオーケストレーター（第2回の主役）
│ ├── figma-to-code/ # ★Figma視覚一致ループ（第4回の主役）
│ ├── frontend/ # FE共通規約（各アプリ固有スキルが枝としてぶら下がる）
│ ├── backend/ # BE規約・API作成手順・テスト戦略
│ ├── e2e/ # 日本語シナリオ→Playwrightテスト生成
│ ├── git/ # コミット・PR作成（ユーザーの明示指示時のみ）
│ ├── add-env/ # 環境変数追加で連動する全ファイルの一括更新
│ └── ... # mail / gcp / storybook / sentry など
├── agents/ # サブエージェント定義
│ ├── frontend-implementer.md / backend-implementer.md / test-implementer.md
│ ├── fe-review-*.md # FEレビュー3観点（規約/品質/UX）
│ ├── be-review-*.md # BEレビュー3観点（規約/セキュリティ/品質）
│ └── figma-fetch.md / storybook-shoot.md / figma-compare.md # Figma取得/撮影/視覚比較
└── workspace/ # ブランチごとの作業プランドキュメント（進捗を残す場所）
3. 土台の設計: 「常時ロード」と「取りに行く知識」を分ける
ループの話に入る前に、土台となる情報設計（Context 層）を押さえます。ここが雑だと、上に何を積んでも崩れます。
振り分け基準は一行
Claude のコンテキストは有限です。そこで、ルールを物理的に2種類へ分離しています。判断基準はこの一行だけです。
「このルールを知らない状態でコードを書かれたら困るか?」
- 困る →
CLAUDE.md（常時ロード）- 困らない（タスク発生時に取りに行けばいい）→ Skill
「日付生成は new Date() 禁止、必ず dayjs」「any 禁止」のような、知らずに書かれると毎回直すハメになるルールは CLAUDE.md へ。「メールテンプレートの追加手順」のような、そのとき初めて要る知識は Skill へ追い出します。
実物の CLAUDE.md は、たとえばこんな粒度で書いています（抜粋・マスキング済み）。
- any型はなるべく使わず、できるだけはっきりした型を使用してください
- **日付の生成にはnew Date()ではなく必ずdayJsを使用してください**
- バックエンド: `import { dayJs } from 'src/utils/dayJs'`
- 例: `dayJs('2024-01-15').toDate()` または `dayJs().toDate()`
- Propsの型の命名規則は、〇〇(コンポーネント名)Propsという名前で統一してください
## Git操作ルール
**git add、git commit、git push、PR作成などのgit操作は、ユーザーが明示的に
/git skill を実行した場合にのみ行ってください。** コード変更後に自動的に
commitやpushを行うことは禁止です。
地味ですが、import パスや実例まで書くのがポイントです（dayJs は日付ライブラリ dayjs をチーム設定でラップした自作ユーティリティです）。「日付ライブラリを使うこと」とだけ書くと、エージェントは毎回少しずつ違う書き方をしてきます。
Skill は「目次 + 実体」の4層構造
各 Skill も、全部を一度に読ませない構造にしています。
- SKILL.md は「どのタスクならどのファイルを開け」のルーティング表に徹する（目安30〜50行。オーケストレーターのような大きいスキルでも100行以内に収め、詳細は下層へ逃がす）
- operations/ はそのまま上から実行できる番号付きの台本
- reference/ は守るべき規約と、過去に踏んだ地雷。抽象論ではなく NG/OK の実コード付きで書く
- examples/ は完結した動くサンプル
常時ロードされるのは frontmatter の description だけです。ここにサブ操作のキーワードを過不足なく並べておくと、Claude がタスクに応じて該当 Skill を自動で引きに行き、SKILL.md を読んで必要なファイルだけ開きます。「必要になったときだけ読み込む」目次の仕組み（遅延ロード）を手作りしているイメージです。
---
name: workspace-plan
description: プランニング用ワークスペースの初期化と管理＋開発フロー全体の
オーケストレーション。ブランチごとに設計->実装->レビュー->テスト->PRまでを
サブエージェントに委譲しながら指揮者として一気通貫管理する。
初期化、orchestrate(一気通貫)、実装、更新、ステータス確認。
---
「唯一の正」原則とスキル自身の lint
スキルが十数個規模になって効いてきた運用ルールが2つあります。
唯一の正（single source of truth）: 同じ情報を2つのファイルに書かない。書きたくなったら片方を参照リンクにする。たとえば各サブエージェントが使うモデル名は agent 定義の frontmatter にだけ書き、スキル側には書きません。二重に書いた情報は、必ず片方だけ更新されて矛盾します（ドリフト）。
スキル自身を lint する: 必須セクションの欠落・ポート定義の不整合・未集計ログの行数など、スキル構成の健全性を検査するスクリプトを用意し、スキルや agent 定義を編集したら必ず回します。スキル群も立派な「コード」です。コードと同じように、壊れたことに気づける仕組みを添えます。
4. 自己学習型開発環境の全体像 — 3つのループ
この土台の上に、3つのループが乗っています。ここからが本シリーズの本体です。といっても本記事では見取り図を描くところまでで、詳細は各回に譲ります。
（色分け: 青=フローの工程 / 青緑=サブエージェントの作業 / 紫=学習系の仕組み）
ループ1: 開発フローのループ（第2回）。 設計書1枚を入力に、実装 → 6観点レビュー（BE3観点+FE3観点、計6体） → 修正 → テスト → 最終ゲート → PR をメインセッション（指揮者）がサブエージェントに任せながら回します。メインは実装コードを書きません。人間が登場するのは5つの確認ゲートだけ。ループには「止まり方」（修正は3周まで・進んでいない/堂々巡りの検知・人間への引き継ぎ）まで定義してあります。
ループ2: 環境の自己学習ループ（第3回）。 タスク完了ごとの retrospective で、レビュー指摘を追記専用ログ（1指摘=1行。並行ブランチをマージしてもカウントが消えない設計）に貯めていきます。ログが一定量を超えたら集計し直し、各レビューエージェントの頻出違反ランキングを更新。次のレビューはよく出るミスから重点的にチェックします。実装前に防げた指摘は予防DoD（提出前のセルフチェックリスト）に書き戻し、実装エージェントが提出前に自己チェック。冒頭の「AIが同じミスを二度としない」の実体はこのループです。
ループ3: 視覚一致ループ（第4回）。 Figma → 実装 → Storybook 撮影 → ピクセル単位の計測（画素計測）による比較 → 修正を、差分ゼロまで回します。「目視でだいたい合ってる」を「一致」と報告することを禁止し、判定には実際に測った数値（px / カラーコード）を要求します。そしてここにも「失敗頻度ランキング」という学習の仕組みが入っており、過去に見た目のミスが多かった項目ほど細かく計測されます。
3つのループは対象こそ違いますが、「閉じる・測る・学びを書き戻す」という3点で同じ形をしています。
なお「効いているか」は感覚ではなくメトリクスで確認しています。タスクごとに初回レビューの P0/P1 指摘数（P0=必ず直す / P1=直すべき、の重要度ラベル）・予防可能違反数（既知ミスの再発数）・修正周回数などを決まった書式の1行で記録し、grep で集計できるようにしてあります。数字の詳細は第3回で。
5. まとめ — 「Skills を書く」から「Skills が育つ仕組みを書く」へ
環境が学習するとは、大げさな ML の話ではありません。ミスの記録場所を決め、反映のタイミングをフローに固定し、効果を1つの数字で測る。それだけのことを、人力の心がけではなく構造にする、ということです。
導入チェックリストを置いておきます。
- CLAUDE.md と Skill を「知らずに書かれたら困るか?」で振り分けたか
- Skill は目次（SKILL.md）+ 実体（operations / reference）の遅延ロード構造か
- 同じルールを2箇所に書いていないか（唯一の正）
- エージェントのミスを「環境側への恒久修正」に変換する置き場（ログ・DoD）があるか
- その効果を測る数字（メトリクス）を1つでも取っているか
プロンプトを磨く時代から、コンテキストを設計する時代へ。そしていま、足場を組み、その足場が自走して育つループを設計する時代に入っています。「Skills を書く」で止まらず、「Skills が育つ仕組みを書く」ところまで進むこと — それがループエンジニアリングの入口だと考えています。
次回は、開発フロー全体を回すオーケストレーター Skill の実装を詳しく見ていきます。
参考リンク
- Loop Engineering入門：AIコーディングエージェントを動かすシステムを設計する（suwash）
- Loop Engineering（ループエンジニアリング）とは（Qiita, y-morimatsu）
- Claude Codeでハーネスエンジニアリングを実践する — 5層の設計パターン（sasadango28）
- Claude Codeでハーネスエンジニアリングを実践する 〜狩りから稲作へ（ignission）
- コンテキスト・エンジニアリング入門（shunsuke_stack）
- Claude Code Skillの作り方｜21個運用して分かった設計と育て方（yamato_snow）
-
Addy Osmani「Loop Engineering」より。"Loop engineering sits one floor above the harness." / "the cousin of this, agent harness engineering"（https://addyo.substack.com/p/loop-engineering） ↩
-
Mitchell Hashimoto「My AI Adoption Journey」（2026年2月）の一節の訳。原文: "It is the idea that anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again."（https://mitchellh.com/writing/my-ai-adoption-journey）。なお本人は「業界に定着した用語があるかは分からないが、自分はこう呼んでいる」という断りつきで名付けています。 ↩