Portfolio logo
Notes に戻る
🤝

AIエージェントとMonorepoが共進化する理由

#ai-agent #monorepo #workflow #documentation

AIコーディングエージェントを戦力化するうえで、モノレポに蓄えられた設計資産と運用のパターンは精度向上のエンジンになります。このリポジトリではAGENTS.mdやdocs/agent/配下のテンプレートを通じて、エージェントが最初に読むべき共通語を明示的に整備しています。その結果、開発が進むほどエージェントの提案がチームの期待値へと収束し、サービス横断で再利用できる知見が加速度的に増えていきます。

When executing tasks, please refer to docs/agent/template/ai_driven.md — 全AGENTS.mdに掲げたこのリマインダーが、AI-Driven Development Common Guidelinesを常に参照させる道標になっています

MonorepoがAIに渡す初期コンテキスト

  • ルート階層のAGENTS.mdはサービス構成、ガイドライン索引、更新ワークフローを一覧化し、エージェントに最短距離で必要情報を届けます。
  • 各サービス・プロジェクト配下のAGENTS.mdはCompletion Gateやディレクトリ構成をASCIIアートで示し、迷わず作業フローに入れるよう設計されています。
  • docs/agent/template/のテンプレート群（APIレイヤード設計、フロントエンドSEO、MCP運用など）とSerenaメモリを組み合わせることで、AIは作業開始時点から統一された用語と手順を読み込めます。

この多層的なドキュメント構造により、エージェントは新しいコンポーネントやサービスに着手しても、初日から「何を守れば良いか」を明確に理解した状態でアウトプットを生成できます。

パターンが積み上がるほどアウトプットは滑らかになる

開発序盤は、エージェントの提案と人間の期待にズレが生まれやすく、「違和感のあるコード」や「抜けているチェックリスト」が散見されます。しかし、リポジトリ内で以下のサイクルを繰り返すと違和感は急速に減っていきます。

  1. 実際の修正方針やベストプラクティスをAGENTS.mdやノートに反映する
  2. 変更内容をSerenaメモリへ同期し、次回以降の会話で即参照できるようにする
  3. 生成コードをレビューし、必要なテンプレートやガイドラインをさらに磨く

このサイクルが回り始めると、エージェントは過去の修正例・命名・テスト観点を踏まえた提案を出すようになり、「手直し前提だったアウトプット」が「少ない修正で受け入れられるアウトプット」へと変化します。

新規サービスでも「初日から熟練チーム」感を得る

モノレポで蓄積されたパターンは、新規サービス着手時に特に威力を発揮します。

  • 既存サービスのAGENTS.mdから共通セクションをコピーし、テンプレートリンクを張り替えるだけで初期ドキュメントを短時間で整備可能。
  • packages/typescript/配下の共有パッケージやdocs/agent/guideline/service_design.mdに沿ったアーキテクチャが整っているため、エージェントは適切な依存関係やテスト構造をすぐに提案できます。
  • モノレポ横断で実装済みのパターン（APIのハンドラ構成、AstroレイアウトのSEO設定、Cloudflare Pages向けのデプロイフローなど）が再利用され、初日から高品質なプロトタイプを構築できます。

個人開発者にとっても、モノレポへの集約は大きな武器です。複数サービスのコードとAGENTS.mdを同じリポジトリに置くことで、AIエージェントが過去の成功パターンを瞬時に再利用し、1人でも多面的なアウトプットを安定した品質で量産できます。「次は何をどう作ればいいか」を都度説明する必要がなくなり、設計の一貫性と作業速度が同時に向上します。

結果として、「ゼロから新サービスを立ち上げるフェーズ」でも、AIが提示するコード品質が既存プロダクトと同じリズムに乗りやすくなります。

精度を伸ばし続けるための運用ループ

  • ドキュメント更新: 開発で得た新知見は必ずAGENTS.mdと関連テンプレートへ反映し、リンク切れや相対パスの正確さを保つ
  • メモリ同期: 重要なルール変更や注意点はSerenaメモリに記録し、次回セッションでの初期読み込みに備える
  • 差分モニタリング: 週次ワークフロー（.github/workflows/__weekly_coding_agent_docs_update.yml）からのIssueを確認し、抜け漏れなく反映する
  • レビューの可視化: エージェント提案へのフィードバックをノートやテンプレートに落とし込み、同じ指摘が繰り返されない仕組みを作る

このループが機能している限り、リポジトリのコード資産とAIの出力品質は同じ歩幅で成長し続けます。

まとめ

AIエージェントとMonorepoは二人三脚で成熟していく存在です。序盤は違和感を伴うアウトプットも、AGENTS.md・テンプレート・Serenaメモリを磨き上げることで、短期間のうちに期待値へ寄り添う提案へと変化します。そして、その積み重ねは新規サービス開発のスタートラインに直接的な速度と品質をもたらします。このリポジトリでは、グローバルルールを共有し続けることで「初日から熟練したチームのスピード」を保つ仕組みを育てています。開発が進めば進むほどAIの精度が上がる――その実感を、モノレポという巨大なコード資産と共に体験していきましょう。