この記事は 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=改善提案)
- ゲート:先へ進む前に必ず通す確認ポイント。機械チェック(typecheck やテスト)と人間の承認の両方がある
- retrospective(レトロスペクティブ):タスク後の振り返り。学んだことを環境に反映するステップ
- コンテキスト: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つのループが乗っています。ここが本体ですが、この記事では見取り図までにして、詳細は各回に譲ります。
(色分け: 青=フローの工程 / 青緑=サブエージェントの作業 / 紫=学習系の仕組み。ループ3の視覚一致は第4回の図で描きます)
ループ1は開発フローのループです(第2回)。設計書1枚を入力に、実装 → 6観点レビュー(BE3観点+FE3観点、計6体) → 修正 → テスト → 最終ゲート → PR を、メインセッション(指揮者)がサブエージェントに任せながら回します。メインは実装コードを書きません。人間が出てくるのは5つの確認ゲートだけ。ループには「止まり方」(修正は3周まで、進んでいない・堂々巡りの検知、人間への引き継ぎ)まで定義してあります。
ループ2は環境の自己学習ループです(第3回)。タスク完了ごとの retrospective で、レビュー指摘を追記専用ログに貯めていきます。1指摘=1行で、並行ブランチをマージしてもカウントが消えない形にしてあります。ログが一定量を超えたら集計し直し、各レビューエージェントの頻出違反ランキングを更新。次のレビューはよく出るミスから重点的にチェックします。実装前に防げた指摘は予防DoD(提出前のセルフチェックリスト)に書き戻し、実装エージェントが提出前に自己チェック。冒頭の「AIが同じミスを二度としない」の実体はこのループです。
ループ3は視覚一致ループです(第4回)。Figma → 実装 → Storybook 撮影 → ピクセル単位の計測(画素計測)による比較 → 修正を、差分ゼロまで回します。「目視でだいたい合ってる」を「一致」と報告することを禁止し、判定には実際に測った数値(px / カラーコード)を要求します。ここにも失敗頻度ランキングという学習の仕組みが入っていて、過去に見た目のミスが多かった項目ほど細かく測る作りです。
対象はバラバラですが、3つとも「閉じる、測る、学びを書き戻す」という同じ形をしています。
効いているかを感覚で語らずに済むよう、メトリクスを取っています。タスクごとに初回レビューの P0/P1 指摘数、予防可能違反数(既知ミスの再発数)、修正周回数などを決まった書式の1行で記録し、grep で集計できるようにしてあります。数字の詳細は第3回で。
5. まとめ
環境が学習する、の中身は地味です。ミスの記録場所を決め、反映のタイミングをフローに固定し、効果を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でハーネスエンジニアリングを実践する(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)。なお本人は「業界に定着した用語があるかは分からないが、自分はこう呼んでいる」という断りつきで名付けています。 ↩