Loop Engineering（ループエンジニアリング）って？
Xなどで広まりつつあるキーワード「Loop Engineering（ループエンジニアリング）」
ついこの前「HarnessEngineering（ハーネスエンジニアリング）」って単語で？？？？でしたが、またトレンドが変化しているようですね
AI関連は進化や変化が非常に激しい発散期ともいえるのでしょうか
トップランナーが次々と新たなキーワードや手法を考え出し、世間に広まる頃には既に別のキーワードがわいてくる
正直、この「Loop Engineering（ループエンジニアリング）」
追いかける価値があるのか、ないのか！？
それを見極めるためにもどのような特徴でどう動くのかは理解したほうが、AI駆動開発やAIと仲良く開発するためには必要となりますよね。
前置きが長くなりましたが、そんなわけで個人のClaude Proプラン（予算都合で）で「Loop Engineering（ループエンジニアリング）」の体験をしようと思い立ちチャレンジを開始しました。
なお、本記事は思いを徒然と昔ながらの手書きで書いていたりします。
世の中どこを見ても、会社の上司のドキュメントもそろって「あっAI使っているんですね」な資料があふれちょっと飽きてきたのであえての手書きです。
- この記事を書いているわたくし 「効率だけではない栄養素がある」と信じています。
- GitHub Copilotを利用していたが6月の課金体系変更に伴い、CluadeCodeに移行したClaudeCode初心者
です。
「Loop Engineering（ループエンジニアリング）」として動作するワークスペースを構築する
Loop Engineering向けのワークスペースを用意しました。
LoopEngineeringWS/
単純すぎるフォルダ名ｗ
VisualStudioCodeを利用しているのでLoopEngineeringWS/を開き作業開始
superpowersに助けられながら要求をまとめる
ClaudeCodeにはあらかじめプラグインを追加しています。
- superpowers@claude-plugins-official
わたし
ループエンジニアリングによるPHPのWeb開発のためのワークスペースのベースを作成したい。
なんて情報の薄いペラペラの要求でしょうかw
これを受けてClaudeCodeはsuperpowers:brainstorming skillを召喚
いやこのプラグインは本当にすばらしいと感じています。
ClaudeCode
ブレインストーミングのスキルに従って進めます。まずチェックリストをタスク化します。
- [x] プロジェクトのコンテキストを調査する
- [ ] 明確化のための質問をする(1つずつ)
- [ ] 2〜3個のアプローチを提案する
- [ ] 設計を提示して承認を得る
- [ ] 設計ドキュメントを書いてコミットする
- [ ] スペックのセルフレビュー
- [ ] ユーザーによるスペックレビュー
writing-plansスキルで実装計画へ移行
タスクを整理しました。ディレクトリが空であることは確認済みなので、
まず一番重要な点から1つずつ質問させてください。
あんなダウンの様なふわふわなオーダーにもかかわらずsuperpowers:brainstorming skillがインタビューをスタートしてくれます。
以下、ClaudeCodeがヒアリングしてくれている回答に対する私の選択は「☆」としています。
ClaudeCode
「ループエンジニアリング」とは、このワークスペースにおいて具体的にどのような開発手法を指しますか?
1. AIエージェント駆動の開発ループ
2. TDD/CIのフィードバックループ中心
3. 独自の方法論がある
☆ 4. Other
わたし
4. ループエンジニアリングによるPHPのWeb開発のためのワークスペースのベースを作成したい。
ClaudeCode
PHPのWeb開発で使うフレームワーク・スタックは何を想定していますか?
1. Laravel
2. Symfony
☆ 3. まだ決めていない/案件次第
ClaudeCode
この loopEngineering ディレクトリはどのような役割を持ちますか?
☆ 1. 複数プロジェクトの親ワークスペース
2. テンプレート/ベースリポジトリ
3. 単一プロジェクトの器
4. Other
これらの問いに答えて行くとこで要件を整理しspecをmarkdownでまとめてくれます。
まとめてもらったspecを確認し要望があれば追加オーダー
Claude: 全体像とディレクトリ構成はこれで良いですか?
わたし: ループ内で設計やコーディングを行うエージェントに対しレビュアーは2つのエージェントでレビューおよびすり合わせを実施する構成であること。
ClaudeCode
2つのレビュアーエージェントの役割分担はどうしますか?
☆視点分担: 設計 × 品質 (推奨)
レビュアーA=設計・アーキテクチャ担当(構造・境界・シンプルさ・仕様適合)、レビュアーB=品質担当(正しさ・テスト・セキュリティ・エッジケース)。異なる角度からの指摘をすり合わせる。
同役割の独立2名
同じレビュー観点を持つ2エージェントが独立にレビューし、両者の指摘を照合。見落としの検出率重視(N-version型)。
数回の調整の結果出来上がったspecを承認するとplanが作成され
planを承認すると実装を自律的に行ってくれます。
生成された
「php-loop-workspace-design.md」
php-loop-workspace-design.md
# PHP ループエンジニアリング・ワークスペース 設計書
日付: YYY-MM-DD
ステータス: 承認済み
## 目的
AIエージェント(Claude Code)が「計画 → 実装 → テスト → レビュー → 修正」のループを自律的かつ安全に回すための、PHP Web開発用テンプレートリポジトリを作る。新しい案件を始めるたびにこのリポジトリをコピーして使う。
## 要件(確定事項)
| 項目 | 決定 |
|---|---|
| 手法 | AIエージェント駆動の開発ループ。品質ゲートをフックで機械的に強制 |
| リポジトリの役割 | テンプレート/ベースリポジトリ(案件ごとにコピーして利用) |
| フレームワーク | 非依存。案件開始時に `/bootstrap` で選択(Laravel / Symfony / Slim / 素PHP) |
| 実行環境 | Dockerのみ。ホスト(Windows)にPHP/Composerは入れない。イメージはUBI10 / PHP 8.4(本番環境に合わせる) |
| リリース | `src/` 配下一式(vendor含む)を手作業で商用環境と同期する。`src/` だけでリリース物が完結する |
| レビュー体制 | 同役割の独立レビュアーエージェント2体によるレビューと「すり合わせ」 |
| 基本方針 | 余計なことをしない(karpathy CLAUDE.md の4原則ベース)。案件固有情報は PROJECT-SPEC.md に分離。常にコンテキスト/トークン効率を意識 |
## アーキテクチャ
### 核となる原則
ループの全参加者(フック・スキル・レビュアー・人間)は常に同じ入口を使う:
```
scripts/ → docker compose exec php composer <test|lint|analyse>
```
フレームワークが何であれ、`src/composer.json` がこの3スクリプトを提供する限りループは回る。これがテンプレート(不変)とアプリ(可変)の間の安定インターフェースである。
### ディレクトリ構成
```
loopEngineeringWS/
├── CLAUDE.md # AIへの掟。karpathy 4原則 + ワークスペースの掟。60行以内
├── PROJECT-SPEC.md # 案件固有情報(テンプレート時点では雛形。bootstrapが記入)
├── README.md # 人間向け: テンプレートから新案件を始める手順
├── compose.yaml # php サービス + db(profile "db" でオプトイン)
├── docker/
│ └── php/Dockerfile # UBI10 / PHP 8.4 ベース + Composer
├── scripts/
│ ├── test.ps1 # → composer test(コンテナ内)
│ ├── lint.ps1 # → composer lint(PHP-CS-Fixer)
│ ├── analyse.ps1 # → composer analyse(PHPStan)
│ ├── gate-file.ps1 # フック用: 編集1ファイルの php -l + 整形 + PHPStan
│ └── gate-stop.ps1 # フック用: ターン終了前の全テスト実行
├── .claude/
│ ├── settings.json # フック定義 + docker/scripts の許可リスト
│ ├── agents/
│ │ └── reviewer.md # レビュアー定義(1定義を2インスタンス並列起動)
│ └── skills/
│ ├── bootstrap/SKILL.md # 案件開始: FW選択 → scaffold → 配線 → PROJECT-SPEC生成
│ └── dev-loop/SKILL.md # 開発ループの手順書(TDD + 2レビュアー + すり合わせ)
├── src/ # アプリのプロジェクトルート = リリース単位(bootstrapでFWがここに入る)
│ ├── composer.json # ループの安定インターフェース(test|lint|analyse)
│ ├── vendor/ # 依存もsrc/配下に置き、src/一式でリリース物が完結する
│ └── (app/ public/ 等、FWの流儀に従う)
├── config-templates/
│ ├── phpstan.neon.dist # レベル8(bootstrap が src/ へコピーして配線する雛形)
│ ├── .php-cs-fixer.dist.php # PER-CS 2.0(同上)
│ └── phpunit.xml.dist # 素PHP案件用デフォルト(同上)
└── docs/superpowers/specs/ # 設計ドキュメント
```
テンプレートのインフラ(docker/ scripts/ .claude/)とアプリコード(src/)を分離する。Laravel等を scaffold してもテンプレート側ファイルと衝突しない。
## Docker環境
- `docker/php/Dockerfile`: **UBI10 / PHP 8.4**(`registry.access.redhat.com/ubi10/php-84`)ベース + Composer。本番環境(RHEL系)に合わせる。イメージにComposerが含まれない場合はDockerfileで追加する
- `compose.yaml`:
- `php`: `./src` をコンテナへマウント(マウント先はUBIイメージの規約 `/opt/app-root/src`)、ポート8000公開。開発サーバーはFWのserveコマンドまたは `php -S`
- `db`: MariaDB。`--profile db` 指定時のみ起動
- ホストにPHP/Composerはインストールしない(現状: PHP未導入、Docker Desktop導入済み)
## リリース
- リリースは**手作業**: `src/` 配下一式(vendor/ を含む)を本番環境の`/opt/app-root/src`へ同期する
- そのため `vendor/` も `src/` 配下に置き、`src/` の外に実行時依存を置かない
- CI/CDによる自動デプロイはスコープ外(要件どおり)
## 品質ゲート(3層)
| 層 | タイミング | 内容 | 失敗時 |
|---|---|---|---|
| ゲート1 | PHPファイル編集直後(PostToolUseフック) | `php -l` → PHP-CS-Fixer整形 → PHPStan(該当ファイルのみ) | 指摘をClaudeに即フィードバック、その場で修正 |
| ゲート2 | ターン終了前(Stopフック) | `composer test`(全テスト) | ターン終了をブロック。通るまで完了不可 |
| ゲート3 | タスク完了前(dev-loopスキル) | 独立2レビュアーによるレビュー + すり合わせ | 指摘解消まで完了不可 |
フックの動作規則:
- ゲート2は「このターンで `src/` のPHPファイルが編集された場合のみ」発火する。ゲート1がマーカーファイル(`.claude/.gate-dirty`)を置き、テスト成功時に消す
- **Docker未起動時はフェイルオープン**: ゲートをスキップし「⚠ Docker未起動・ゲート未実行」と警告を出す。CLAUDE.mdで「この警告を見たら `docker compose up -d` を実行しゲートを再実行せよ」と義務付ける
- フック出力は失敗時のみ詳細を返す(トークン効率)
- 品質ツールの設定は `config-templates/` の雛形を bootstrap が `src/` へコピーする(コンテナは `./src` しかマウントしないため、設定はアプリ側に置く)。PHPStanレベル8・PER-CS 2.0 は案件ごとに調整可能
## レビューループ(ゲート3)
N-version型: `.claude/agents/reviewer.md` の**同一定義を2インスタンス並列起動**し、独立にレビューさせる。
1. 実装完了(ゲート1・2通過)後、両レビュアーに同じ入力を渡す: タスク内容 + 差分 + PROJECT-SPEC.md。リポジトリ全体は渡さない(トークン効率)。互いの出力は見えない
2. 指摘を構造化(重要度 / 箇所 / 問題 / 根拠)して突き合わせる:
- 両者が指摘 → 確定。必ず修正
- 片方のみ指摘 → もう一方に同意可否を確認(すり合わせ)。合意なら修正、不一致なら実装者がコードで裏取りして判断
3. 修正後は修正箇所のみ再レビュー。最大3ラウンドで収束しなければユーザーにエスカレーション
4. レビュアー起動失敗時は1回リトライ。それでも失敗なら単独レビューで続行し警告を出す(レビューゼロにはしない)
5. 対象は `src/` のコード変更。ドキュメントのみの変更はレビュー省略可
レビュアーの観点: 正しさ、仕様適合(PROJECT-SPEC.md照合)、シンプルさ(余計なコード・不要な抽象の検出)、テストの妥当性。
## ドキュメント分離とコンテキスト効率
- **CLAUDE.md**(テンプレート共通・不変・60行以内): karpathyの4原則(Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven Execution)+ ワークスペースの掟(ゲート遵守、`scripts/` 経由の実行、Docker必須、完了前レビュー必須、PROJECT-SPEC.md参照指示)
- **PROJECT-SPEC.md**(案件固有・可変): 案件名 / 目的 / FW / PHPバージョン / DB / ドメイン用語 / 案件固有ルール。`/bootstrap` がユーザーへのヒアリングから生成
- トークン意識: フック出力は失敗時のみ詳細、レビュアーには差分+関連ファイルのみ、スキルは必要時のみロード
## スキル(2つのみ)
- **`/bootstrap`**(案件開始、テンプレートコピー後に1回だけ実行):
1. FW選択(Laravel / Symfony / Slim / 素PHP)
2. コンテナ内で `composer create-project`(src/ に scaffold)
3. `config-templates/` の品質ツール設定を `src/` へコピーし、`composer test|lint|analyse` スクリプトを配線(FWごとの流儀に合わせる。例: LaravelならPint/Pestへの置換も選択肢)
4. ユーザーにヒアリングして PROJECT-SPEC.md の雛形に記入
5. 初期コミット
- **`/dev-loop`**(日常の開発ループ手順書。名称は組み込み `/loop` スキル(定期実行)との衝突回避のため `dev-loop` とした):
タスク受領 → 成功基準の明文化(Goal-Driven)→ TDDで実装(ゲート1・2は自動)→ 2レビュアー並列 → すり合わせ → 修正 → 完了報告
## エラーハンドリング
| 状況 | 挙動 |
|---|---|
| Docker未起動 | ゲートはフェイルオープン + 大きな警告。Claudeは起動して再実行する義務 |
| テスト失敗が解消しない | ゲート2がターン終了をブロックし続ける。Claudeは修正を継続 |
| レビュー3ラウンドで収束せず | ユーザーにエスカレーション |
| レビュアー起動失敗 | 1回リトライ → 単独レビュー + 警告 |
## 検証計画(テンプレート完成の定義)
素PHP構成でサンプルタスクを1つ流し、以下を実際に観察して確認する:
1. スタイル違反のあるPHPファイルを編集すると、ゲート1が自動整形・指摘を返す
2. テストが失敗している状態ではターンを終了できない(ゲート2)
3. 2レビュアーが並列起動し、指摘が突き合わされ、すり合わせが機能する
4. `/bootstrap` で素PHPプロジェクトが scaffold され PROJECT-SPEC.md が生成される
## スコープ外(YAGNI)
- CI設定(GitHub Actions等)— 案件のリモート先が決まってから
- Dev Container構成
- DB以外のミドルウェア(mailpit, redis等)— 必要になった案件で追加
- 複数PHPバージョンの同時サポート(ターゲットはUBI10 / PHP 8.4に固定。変える場合はベースイメージのタグを差し替える)
次のステップに向かって
改めて記事に起こしている最中に気が付きましたが
## レビューループ(ゲート3)
5. 対象は `src/` のコード変更。ドキュメントのみの変更はレビュー省略可
ここは修正しないsrc/以外が野放しになってしまいますね
「人は特に見落とす生き物である、AIもまたしかり」
複数の視点や十分なレビューを必要なタイミングで行う。
これ本当に大切ですよね。（今回はわたしのレビュー指摘洩れです
）
spec->planを立ててもらったあたりで
Claude Proプランの5hリミットに引っ掛かったので残りは後日
つづく