AI 駆動開発の技術選定: moonrepo/moon によるモノレポにおける GIt Worktree の並列稼働と Everything as Code な仕組みづくり

はじめに

この記事は人間が書いた駄文を元に、生成 AI で誤字脱字や表記ゆれの校正を行っています。 #Human-Authored!

おはこんばんにちは！
株式会社ライトカフェ AI駆動開発G Group Manager の 仙波（@semba_yui）です。
今回は社内プロジェクトで 0 → 1 の AI 駆動開発を技術選定をほぼ独断で実施したので、そこで採用した技術スタックと選定理由をつらつらと記載していきます。

TL;DR

• AI 駆動開発では、Everything as Code（= コンテキストエンジニアリングの仕組み化）がとても重要。結果としてモノレポとの相性が良い（💯）
• ボトルネックは「指示を出す人間側」と「AI が前提になっていない周辺環境」。ここを解消しなければ、AI を使ったとしても開発効率は思ったほど上がらない（= Theory of Constraints）
• 人間によるレビューの速度・精度を上げるには、「レビューしなくてよい範囲」を広げる仕組みを徹底整備する

この記事の対象読者

• AI 駆動開発をしている、もしくは興味があるエンジニア
• AI 駆動開発の導入を進めている、もしくは検討している開発チーム

採用した技術スタックまとめ

今回採用した技術一覧は以下です。太字部分は特に採用して良かったと感じているスタックです。
moonrepo/moon 等、主要なアーキテクチャに関しての細かい解説記事は別途作成予定です。

（再掲）文章中に絵文字があっても手動執筆です。最近 AI 文章を読みすぎて文体が若干引っ張られている自覚はあります。。

全体アーキ

並列開発 × 静的解析による AI への高速フィードバック & 品質の最低ライン向上をメインテーマに、人力中心の現場では後回しにしがちな仕組みを最初から導入しました。開発する作業員（= AI Agent）が理論上無限にスケールする前提のため、品質保証の仕組み化の費用対効果は高いと考えています。

そして AI コーディングは品質にかなりのバラつきがあり、これまだレビューできるアウトプットじゃないでしょ、、の回数を減らすのがコツです。静的解析にも限度はありますが、コード品質の下振れを抑えることで、AI の低品質アウトプットが AI 自身のコンテキストを再汚染していく悪循環も防げます。

モノレポ管理

moon

• 公式に Git Worktree をサポートしているモノレポ管理ツール
• Nx / Turborepo は Worktree 利用時にビルドキャッシュで課題が出やすく、現時点での正式サポートはない
• 地味に Git hooks 対応で lefthook や Husky が不要なのも良い

moon と Nx, Turborepo を moon 側有利に 比較した表が以下です。

注意点として、Git Worktree へ対応させるには、設定ファイルへ以下のように gitV2: true を追加して上げる必要があります。

workspace.yml

experiments:
  fasterGlobWalk: true
  gitV2: true # Git Worktree 対応のための設定値

とはいえ、Nx は対応言語が広く、Nx Cloud 連携（moon には Depot がある）、Nx Agents の分散ビルドなど、必ずしも moon が常に優れているわけではありません。
今回のプロジェクトでは、まずはローカル環境の最適化を優先し、CI の最適化までは踏み込みませんでした。

pnpm workspace

• シンプルにビルドが早い
• Worktree が増えても依存関係でストレージが無駄に圧迫されない
• pnpm catalogs で各モジュールでバージョンを中央管理できるのが便利

特に以下の設定は便利なのでプロジェクトルートに入れておきましょう。

pnpm-workspace.yaml

catalogMode: strict
cleanupUnusedCatalogs: true
engineStrict: true
sharedWorkspaceLockfile: true

Lint / Format

Biome

• ESLint × Prettier よりも圧倒的に速く、設定の作り込みがいらない
• 最近 v2 でモノレポ対応した
• ESLint のほうが細かいチェックはできるので、Lint の強度を取るか、ビルドのスピードを取るか若干迷っている

moon × biome を採用した際に1点だけ、必ず変更しておくべき moon の設定があります。

.moon/toolcain.yml

node:
  packageManager: 'pnpm'
  syncPackageManagerField: false // 必須！

これは package.json に以下のようなフィールドを設定してくれる設定です。
デフォルトでは true になっており、モノレポで管理しているモジュールの package.json には自動で反映されます。

package.json

{
  // ...
  "packageManager": "pnpm@10.15.0"
}

この packageManager のフィールドが反映されるタイミングが、biome による JSON のソートの formatter とイマイチ噛み合わないのです。

pnpm の場合、packageManager ではなく、engines, devEngines フィールドで対応しましょう。

package.json

  "devEngines": {
    "runtime": {
      "name": "node",
      "onFail": "download",
      "version": "^24.6.0"
    }
  },
  "engines": {
    "node": "24.7.0",
    "pnpm": ">=10.15.0"
  },

https://moonrepo.dev/docs/config/toolchain#syncpackagemanagerfield

textlint × AI Preset など

• AI が書く不自然な日本語を事前に強制・是正
  • https://github.com/textlint-ja/textlint-rule-preset-ai-writing
• AWS サービス名の表記ゆれなども自動で矯正
  • https://www.npmjs.com/package/textlint-rule-aws-service-name

remark CLI

• Markdown の目次自動生成に利用
• 目次があると、AI が先頭から読み込む際のコンテキスト圧縮に効く
• AI でも生成可能だが、ここはツールに任せたほうが安定

secretlint

• AI が環境変数を勝手に commit する可能性をちょっとでも減らす
• GitHub の Advanced Security のほうが精度は良さそうだが、そもそも GitHub に上がった時点で変更必須なのでローカル時点で強制する
• ただ、AI は .env をあの手この手で読みに来るので AI 側にキーの流出はあり得る

commitlint

• コミットメッセージを Conventional Commits に強制
• どこでどんな変更が入ったかわかりやすくすることもコンテキストエンジニアリングの一つ

バージョン管理

各種ツールや言語のバージョン管理も moonrepo 製のツールを採用しました。
ただし Proto だけでは賄えないツールもあるため、補助的に mise も併用しています。

Proto

• moon と同じ moonrepo 製のバージョン管理ツール
• もちろん moon と相性良し。.prototool ファイルを moon が参照してくれる
• WASM Plugin 対応でこれからのプラグイン開発が期待できる

mise

• Proto が非対応なツール（PlantUML をビルドするための JRE 等）を補完

フロントエンド（TypeScript）

なるべく一般的かつシンプルな構成を選定しました。下手にNext.js や Redux のように高度な機能があるものを採用してしまうと、AI に余計な選択肢を与えることになってしまいます。
また、OpenAPI Generator 等、ツールで自動生成できるものは自動生成に任せます。AI の出力は非決定的なので、ツールで作れるところはツールに頼ることでハルシネーションや出力の揺れを防ぎます。

• 言語
  • TypeScript
• ライブラリ
  • React 19 (SPA)
• CSS
  • Tailwind CSS
• ビルド
  • Vite 7
• ルーティング
  • React Router v7
• 状態管理
  • Zustand
• バリデーション
  • Zod
• OpenAPI Generator
  • Orval
• モック
  • MSW
• Lint / Format
  • Biome
• テスト
  • Vitest
  • React Testing Library
• Visual Regression Test
  • Storybook v9
  • Chromatic
  • レビュー支援系のツールは AI 実装と相性が良い
  • ローカルでの動作確認手間が減り、レビューの初動が速くなる
  • 面倒だった Story の更新も AI に任せられる
  • モノレポにも対応しているのが地味に嬉しいポイント
  • https://www.chromatic.com/docs/monorepos/

バックエンドその1（TypeScript）

Lambda ベースで動き、DynamoDB から情報を取得して返すだけの簡単なものなので、サクッと作れるものを選定。

• 言語
  • TypeScript
• FW
  • Hono
• バリデーション
  • Zod
• Lint / Format
  • Biome
• テスト
  • Vitest

バックエンドその2（Python）

このモジュールだけは別チームがアーキテクチャを選定しました。
FastAPI / FastMCP を使うために Python となったのですが、私の方で Lint / Format / Test 等 AI 駆動するための仕組みは導入しています。特に Python は動的型付け言語なので、AI の読み取る情報量が減ることに加え、型によるテストができないことになります。mypy, Pyright を導入することで型付けを強制させましょう。

とはいえ、mypy での型の強制は人間サイドには不評でした。
そりゃそうですよね。Python 書いてるのでそこまで型意識したくないよね。。

このあたりはチーム間での落としどころを引き続き議論したいところです。

• 言語
  • Python 3.12
• FW
  • FastAPI
  • FastMCP
• 型
  • mypy
  • Pyright
• Lint / Format
  • Ruff
• テスト
  • pytest

インフラ（AWS）

インフラ環境は AWS です。Terraform State が現状どうなっているのかを AI のコンテキストへ含めることに苦労しました。
MCP が充実していて、設計の壁打ちの際は AWS MCP をつなげながらベストプラクティスを探るのにも役立ちます。

• IaC
  • Terraform
  • AWS SAM
• コンテナ
  • Docker
• Lint
  • tflint
  • terraform validate
• ドキュメント生成
  • terraform-docs
  • terraform graph
• 脆弱性スキャン
  • Trivy
  • Checkov

CI/CD

CI はキャッシュをうまく活用できておらず、moon の Remote Cache として S3 を整備するか、Depot を採用して Docker のビルドも含めた高速化を検討中です。

PR の数が増えて CI の回数が爆増すると Docker ビルドが高くて辛い。。。
Docker Bake による高速化も試しているところですが、まだそこまで大規模なビルドを組めていません。
https://www.docker.com/ja-jp/blog/ga-launch-docker-bake/

• パイプライン
  • GitHub Actions
• Runner
  • AWS CodeBuild
• 依存バージョン管理
  • Dependabot

設計書管理

AsyncAPI は少しマイナーですが、メッセージブローカーや、WebSocket 等、OpenAPI で表しきれない I/F 仕様をドキュメンテーションすることができます。OpenAPI 同様、yaml から HTML 設計書を作成したり、各種言語で Schema モデルの自動生成も可能です。

AsyncAPI の PlayGround はこちら: https://studio.asyncapi.com

設計書を作るときは Excel のようなバイナリデータを扱うより、テキスト形式でいかに AI にも、人間にも読みやすい・取り扱いやすいドキュメンテーションをするかが鍵 になります。

REST API 設計書

• OpenAPI 3.0.4（3.1 系はエコシステムが未だに少ない）

WebSocket API 設計書

• AsyncAPI 3.0（OpenAPI 同様型の自動生成が可能）

図

• PlantUML, Mermaid 等
• Draw.io も使いますが、AI にはまだ複雑な図が無理なのでこっちは人力での作成を行い、Git 管理。

テスト

Playwright × Cucumber で Gherkin記法の E2E テストを整備するところがキモです。QA チームはプログラミングが得意ではないことも多く、AI を使ってこのあたりの橋渡しができるような仕組み化を目指しています。

E2Eテスト

• Playwright / Playwright MCP
  • Playwright MCP を使って Playwright コードを書かせる
• Cucumber（Gherkin記法）
  • 自然言語でシナリオを記載することでレビュー負荷を下げる、かつテストの仕様書化

Mutation テスト

• Stryker
  • テスト対象のコードをあえて変更し、該当のテストケースで正しく検証できるかどうかを確かめるテスト
    • いわゆるテストのテスト
  • AI が書くテストコード、assertTrue(true) のような、たまにとんでもないものが混ざる問題があります。（ Claude 3.7 sonnet には死ぬほど苦しめられた）
    • これは報酬ハッキングによる問題で、ある意味仕方が無い挙動とも言える
  • 見逃しているエッジケースのようなテストケースを見つけることも可能

レビュー

AI 駆動開発では大量の PR が押し寄せて来るので、レビューがボトルネックになります。一次レビューや、それに対する指摘対応は AI にまかせますが、モデルを変えることで様々な視点からレビューしてくれるようにしています。
ただし、PR の数が多ければ、修正の数も多く PR の CI がガンガン回るのでなるべくコスパ重視なモデルが良さそうです。

• GitHub Copilot Code Review: GPT 4.1 モデルを採用
• Claude Code GitHub Actions: Sonnet 4 モデルを採用
• Gemini CLI GitHub Actions: Gemini 2.5 Flash モデルを採用

開発ツール

AI 駆動開発が便利になるツール系。使い方覚えるのが大変なのでスラッシュコマンドにすると楽できます。

• aku11i/phantom
  • tmux × Git Worktree 管理
• mizchi/similarity
  • AI の書き散らす重複コードの発見

MCP サーバー

AI が持っていない／参照しづらい情報をうまく渡してあげられるような仕組みとして MCP サーバーが便利です。

• Serena MCP
  • Claude Code に LSP を
• context7 MCP
  • 各種ライブラリなどの最新ドキュメントを参照
• awslabs/mcp
  • インフラ設計の壁打ち時の公式ドキュメントを参照
• Terraform MCP
  • 同上
• codex CLI MCP
  • Claude Code に Codex CLI を操作させる（主に壁打ち用）
• Gemini CLI MCP
  • Claude Code に Gemini CLI を操作させる（主に検索用）
• Playwright MCP
  • ブラウザ操作をさせ、実際の挙動のフィードバックをする
• Figma MCP
  • UI 実装時にデザインを参照させる
• Phantom MCP
  • Git Worktree 管理

今後導入したいが現状未対応

AI の差分を素早く反映させ、そのフィードバックを受けさせるためにはこのあたりのテスト・テスト環境の最適化も充実させたいと思っています。ですが、現状は 0 → 1 で開発スピードも早めないと行けないタイミングだったのですべてを整備することは間に合わず、取りこぼしてしまっているのが以下です。

• CI / CD
  • Depot: moon のキャッシュサーバー（Nx Cloud 的な立ち位置）
• a11y テスト
  • Storybook の Accessibility Tests
• パフォーマンステスト
  • Lighthouse CLI
• 負荷テスト
  • k6
• 静的解析
  • SonarQube

つぶやき

AI 導入における開発生産性の計測と費用対効果の説明、難しすぎ問題。
上長や取締役が推進している弊社はかなりありがたいなと感謝しながら AI を怒鳴りつける と共に開発する日々を過ごしています。

それでは。

AI 駆動開発の関連記事

問い合わせ先

案件のご依頼・ご相談は、以下までご連絡ください。
[e-mail]

We are hiring!

ライトカフェはエンジニアを積極採用中です。

常にお客様に寄り添い課題を認識し、解決の手助けをさせていただく。業務SIerにとって当たり前の事ですが、わたしたちはそれを一番大切にしています。
この会社コンセプトに共感して頂ける方、世の中のWEBサービス開発に関わりたい方をお待ちしています。

#イツモトナリニライトカフェ

ライトカフェ採用ページはこちら

ライトカフェクリエイション採用ページはこちら

note はこちら: 社内の雰囲気や制度など、ライトカフェの魅力を発信しています。

X（旧Twitter）はこちら: 会社のニュースや日々の出来事、採用情報などを発信しています。