すべてをコードとして: 1 つのモノレポで会社を管理する方法

導入

先週、価格制限を更新しました。 1 つの JSON ファイル。バックエンドが新しい上限の適用を開始し、フロントエンドが新しい上限を正しく表示し、マーケティング サイトが価格設定ページに表示し、ドキュメントに変更が反映されました。これらすべてが 1 つのコミットから行われます。

同期の問題はありません。 「待って、現在の価格設定はどのリポジトリですか?」ということはありません。 3 つのチーム間でのデプロイ調整は行われません。たった 1 つの変更が、どこでも、瞬時に行われます。

Kasava では、プラットフォーム全体が単一のリポジトリに存在します。コードだけでなく—すべて:

kasava/                              # 5,470+ files TypeScript files
├── frontend/                       # Next.js 16 + React 19 application
│   └── src/
│       ├── app/                   # 25+ route directories
│       └── components/            # 45+ component directories
├── backend/                        # Cloudflare Workers API
│   └── src/
│       ├── services/              # 55+ business logic services
│       └── workflows/             # Mastra AI workflows
├── website/                        # Marketing site (kasava.ai)
├── docs/                           # Public documentation (Mintlify)
├── docs-internal/                  # 12+ architecture docs & specs
├── marketing/
│   ├── blogs/                     # Blog pipeline (drafts → review → published)
│   ├── investor-deck/             # Next.js site showing investment proposal
│   └── email/                     # MJML templates for Loops.so campaigns
├── external/
│   ├── chrome-extension/          # WXT + React bug capture tool
│   ├── google-docs-addon/         # @helper AI assistant (Apps Script)
│   └── google-cloud-functions/
│       ├── tree-sitter-service/   # AST parsing for 10+ languages
│       └── mobbin-research-service/
├── scripts/                        # Deployment & integration testing
├── infra-tester/                   # Integration test harness
└── github-simulator/               # Mock GitHub API for local dev

---

これが重要な理由: AI ネイティブ開発

これは「どのように働くべきか」のデザインパターンに関する抽象的な哲学の話ではありません。製品が急速に変化し、コンテキストが重要となる時代では、速度が重要です。

AI はコンテキストがすべてです。そしてこのモノレポ は 製品だけではありません。

AI ツールがドキュメントの作成を支援すると、ドキュメント化されている実際のコードにすぐにアクセスできるようになります。マーケティング Web サイトを更新すると、AI が主張を実際の実装と照合して検証できます。私たちがこのようなブログ記事を書くとき、AI はすべてのコード例、すべての数値、すべてのアーキテクチャ上の主張を真実の情報源と照らし合わせてファクトチェックできます。

これは、より速く移動できることを意味します:

• ドキュメントの更新が速くなります AI がコードの変更を認識し、同じコンテキストでドキュメントの更新を提案するため
• ウェブサイトの更新が早くなる 価格、機能、および機能は、アプリを強化するのと同じ構成ファイルから取得されるためです。
• ブログ投稿の発送が早くなります AI は自己参照チェックを実行できるため、「5,470 以上の TypeScript ファイル」という主張が実際に数えることによって正確であることを検証します。
• 何も同期が崩れることはありません なぜなら、真実の情報源は 1 つだけであり、AI はそのすべてにアクセスできるからです。

クロードに「新しい制限を反映するように価格ページを更新する」ように依頼すると、次のことが可能になります。

1. 制限を適用するバックエンド サービスを読み取る
2. それらを表示するフロントエンドを確認してください
3. マーケティング サイトを更新する
4. ドキュメントに一貫性があることを確認する
5. 古い数値について言及している可能性のあるブログ投稿にフラグを立てます

すべてを 1 つの会話で。すべてが 1 つのリポジトリにあります。

これが「AI ネイティブ開発」の実際の意味です。断片化と戦うのではなく、AI が最大限に役立つように作業を構造化することです。

そしてそれは配送文化を強化します。

Everything-as-code とは、すべてが同じ方法で出荷されることを意味します。 git push。 Web サイトの価格ページを更新したいですか? git push。新しいブログ投稿を公開する準備はできていますか? git push。ドキュメントのタイプミスを修正しますか? git push。バックエンド機能を導入しますか? git push。

個別の CMS にログインする必要はありません。 WordPress 管理パネルはありません。マーケティング ツールの同期を待つ必要はありません。いいえ、「コンテンツフル アクセス権を持つユーザーがこれを更新できますか?」コードを配布する同じ Git ワークフローによって、コンテンツ、ドキュメント、マーケティングも配布されます。チームの全員が何でも出荷でき、すべてが同じレビュー プロセス、同じ CI/CD、同じ監査証跡を通過します。

この均一性により摩擦がなくなり、言い訳がなくなります。送料はマッスルメモリーとなります。

---

なぜ 1 つのリポジトリにすべてが含まれるのでしょうか?

1. 境界を越えた原子的変化（AIが理解できる）

バックエンド API が変更されると、同じコミット内でフロントエンドのタイプ定義が更新されます。新しい機能を追加すると、ドキュメントも一緒に出荷されます。バージョンの不一致はありません。 「このフロントエンドにはどのバージョンの API が必要ですか?」という質問はありません。

AI はコンテキスト内の変化全体を確認して検証できます。

Claude に機能の追加を依頼すると、単にバックエンド コードを記述するだけではありません。それを使用するフロントエンド、更新が必要なドキュメント、およびそれを参照する可能性のあるマーケティング サイトが表示されます。すべてを 1 つのビューで確認できます。すべてを 1 つの会話で。

コードベースからの実例 – Asana 統合を追加:

commit: "feat: add Asana integration"
├── backend/src/services/AsanaService.ts
├── backend/src/routes/api/integrations/asana.ts
├── frontend/src/components/integrations/asana/
├── frontend/src/app/integrations/asana/
├── docs/integrations/asana.mdx
└── website/src/app/integrations/page.tsx

PRを1つ。レビューが 1 つあります。 1 つのマージ。すべて一緒に発送されます。

別の例として、価格の同期を維持します。

シングルがあります billing-plans.json すべてのプランの制限と機能を定義します。

{
  "plans": {
    "free": { "limits": { "repositories": 1, "aiChatMessagesPerDay": 10 } },
    "starter": {
      "limits": { "repositories": 10, "aiChatMessagesPerDay": 100 }
    },
    "professional": {
      "limits": { "repositories": 50, "aiChatMessagesPerDay": 1000 }
    }
  }
}

バックエンドはこれらの制限を強制します。フロントエンドは設定にそれらを表示します。マーケティング Web サイトの価格ページにそれらが表示されます。制限を変更すると、1 つの JSON 更新があらゆる場所に伝播します。「Web サイトには 50 リポジトリと記載されているが、アプリには 25 のバグが表示される」ということはありません。

そしてAIはそれをすべて検証します。 更新するとき billing-plans.json、バックエンド、フロントエンド、Web サイトがすべて一貫していることを確認するようにクロードに依頼できます。 3 つの実装をすべて読み取り、それらが一致していることを確認し、修正が必要なものを教えてくれます。

2. プロジェクト間のリファクタリング

関数の名前を変更しますか? IDE は、フロントエンド、バックエンド、ドキュメントのサンプル、ブログのコード スニペットにわたるすべての使用法を検索します。検索と置換は 1 回です。 1 つのコミット。

3. 単一の真実の情報源

• 依存関係: 一度構成された共有ツール
• CI/CD: 理解すべき 1 つのパイプライン
• 検索: これ1つで何でも見つかる grep

---

構造: 何がどこに存在するか

コアアプリケーション

frontend/                        # Customer-facing Next.js app
├── src/
│   ├── app/                    # Next.js 15 App Router
│   │   ├── analytics/         # Semantic commit analysis
│   │   ├── bug-reports/       # AI-powered bug tracking
│   │   ├── chat/              # AI assistant interface
│   │   ├── code-search/       # Semantic code search
│   │   ├── dashboard/         # Main dashboard
│   │   ├── google-docs-assistant/
│   │   ├── integrations/      # GitHub, Linear, Jira, Asana
│   │   ├── prd/               # PRD management
│   │   └── ...                # 25+ route directories total
│   ├── components/            # 45+ component directories
│   │   ├── ai-elements/      # AI-specific UI
│   │   ├── bug-reports/      # Bug tracking UI
│   │   ├── dashboard/        # Dashboard widgets
│   │   ├── google-docs/      # Google Docs integration
│   │   ├── onboarding/       # User onboarding flow
│   │   └── ui/               # shadcn/ui base components
│   ├── mastra/               # Frontend Mastra integration
│   └── lib/                  # SDK, utilities, hooks

backend/                        # Cloudflare Workers API
├── src/
│   ├── routes/               # Hono API endpoints
│   ├── services/             # 55+ business logic services
│   ├── workflows/            # Mastra AI workflows
│   │   ├── steps/           # Reusable workflow steps
│   │   └── RepositoryIndexingWorkflow.ts
│   ├── db/                   # Drizzle ORM schema
│   ├── durable-objects/      # Stateful edge computing
│   ├── workers/              # Queue consumers
│   └── mastra/               # AI agents and tools

この二人はいつもお互いに話し合っています。これらを同じリポジトリに置くということは、次のことを意味します。

• API の変更にはフロントエンドの更新が含まれます
• 境界を越えたタイプセーフティ
• 共有テストユーティリティ

マーケティングプロパティ

website/                        # kasava.ai marketing site
├── src/
│   ├── app/                   # Landing pages, blog
│   ├── components/            # Shared marketing components
│   └── lib/                   # Utilities

marketing/
├── blogs/
│   ├── queue/
│   │   └── drafts/           # Ideas and drafts
│   ├── review/               # Ready for editing
│   └── published/            # Live on the site
├── investor-deck/            # Next.js presentation (not PowerPoint!)
└── email/
    ├── CLAUDE.md             # Email writing guidelines
    └── mjml/                 # 7+ email campaign loops
        ├── loop-1-welcome/
        ├── loop-2-github-connected/
        ├── loop-3-trial-conversion/
        └── ...

はい、ブログ投稿もコードです。これらは、フロントマターを含む Markdown ファイルで、Git でバージョン管理され、PR でレビューされます。電子メール テンプレートは、顧客通信システム全体をバージョン管理する MJML です。

私たちの投資家資料もコードです。これは、17 の React スライド コンポーネント、キーボード ナビゲーション、PDF エクスポートを備えた Next.js 16 静的サイトです。 PowerPoint も Google スライドもありません。メトリクスやメッセージングを更新すると、それは完全な Git 履歴を含むコード変更となり、PR でレビューされ、デプロイされます。 git push。

なぜこれが重要なのか:

• マーケティングはエンジニアリングなしでコピーを更新できる
• 変更はレビューされ、追跡されます
• ロールバックは 1 つです git revert 離れて
• 電子メールキャンペーンはテスト可能で検証可能です

ドキュメント

docs/                           # Public docs (Mintlify)
├── index.mdx                  # Landing page
├── quickstart.mdx             # Getting started
├── demo-mode.mdx              # Demo mode guide
├── features/                  # Product features
│   ├── ai-chat.mdx
│   ├── code-intelligence.mdx
│   ├── code-search.mdx
│   └── prds.mdx
├── integrations/              # Integration guides
│   ├── github.mdx
│   ├── linear.mdx
│   ├── jira.mdx
│   └── asana.mdx
└── bug-tracking/              # Bug tracking docs

docs-internal/                  # Engineering knowledge base
├── GITHUB_CHAT_ARCHITECTURE.md
├── QUEUE_ARCHITECTURE_SUMMARY.md
├── UNIFIED_TASK_ANALYTICS_QUEUE.md
├── features/                  # Feature specs
├── migrations/                # Migration guides
├── plans/                     # Implementation plans
└── research/                  # Research notes

パブリックドキュメントはプッシュ時に自動的にデプロイされます。内部ドキュメントはコードと一緒に検索できます。「キューはどのように機能するのですか?」と尋ねると、古い Wiki ページではなく、実際のアーキテクチャ ドキュメントが見つかります。

外部サービス

external/
├── chrome-extension/          # WXT-based bug capture tool
│   ├── entrypoints/          # popup, content scripts, background
│   ├── lib/                  # Screen capture, console logging
│   ├── components/           # React UI components
│   └── wxt.config.ts         # WXT configuration
│
├── google-docs-addon/        # @helper mentions in Docs
│   ├── Code.gs              # Main Apps Script (18KB)
│   ├── Sidebar.html         # React-like UI (26KB)
│   ├── Settings.html        # Configuration UI
│   └── appsscript.json      # Manifest
│
└── google-cloud-functions/
    ├── tree-sitter-service/  # AST parsing
    │   └── Supports: JS, TS, Python, Go, Rust,
    │       Java, C, C++, Ruby, PHP, C#
    └── mobbin-research-service/  # UX research

これらはまったく異なるプラットフォーム (Chrome Web Store、Google Apps Script、GCP) にデプロイされますが、次の理由により共存します。

• API コントラクトをメインアプリと共有します
• 変更は境界をまたぐことが多い
• 1 つのチームがすべてを保守します

開発インフラ

github-simulator/              # Mock GitHub API for local dev
infra-tester/                  # Integration test harness
scripts/
├── google-cloud/             # GCP deployment scripts
├── test-credentials.ts       # Credential testing
└── test-webhook-integration.ts

ローカル開発には外部サービスは必要ありません。モック サーバーには、シミュレートされたコードが存在します。

---

何をどこに展開するか

成分	技術スタック	デプロイ先
フロントエンド	Next.js 15、React 19、Tailwind v4	ヴェルセル
バックエンド	Cloudflare Workers、ほの、マストラ	クラウドフレア
Webサイト	Next.js、カスタムコンポーネント	ヴェルセル
投資家デッキ	Next.js、カスタムコンポーネント	ヴェルセル
ドキュメント	ミントリファイMDX	ミントリファイ
Chrome拡張機能	WXT、リアクト、追い風	Chrome ウェブストア
Google ドキュメント アドオン	アプリスクリプト、HTML	Google Workspace マーケットプレイス
ツリーシッターサービス	Node.js、GCP 関数	グーグルクラウド
メールテンプレート	MJML	ループス.so

---

どうやって機能させるか

ワークスペースがない (それでも問題ありません)

私たちは意図的に npm/yarn ワークスペースを使用しません。 （そうですね、私たちはそうします 1つ 特定の使用例ですが、それは別の投稿にします。) 各ディレクトリは独自の独立した npm プロジェクトです。

cd frontend && npm install    
cd backend && npm install     
cd external/chrome-extension && npm install  

なぜ？シンプルさ。吊り上げの混乱はありません。 「実際に入手している React のバージョンは何ですか?」ということはありません。各プロジェクトは分離されており、予測可能です。

選択的 CI/CD

5 つの GitHub Actions ワークフローを実行し、それぞれが特定のパスによってトリガーされます。

name: Frontend Tests
on:
  push:
    paths:
      - "frontend/**"
      - ".github/workflows/frontend-tests.yml"

name: Backend Tests
on:
  push:
    paths:
      - "backend/**"
      - ".github/workflows/backend-tests.yml"

name: Tree-sitter Tests
on:
  push:
    paths:
      - "external/google-cloud-functions/tree-sitter-service/**"

Chrome拡張機能を変更しますか？関連するテストのみが実行されます。バックエンドを更新しますか?バックエンド テストとそれに依存する統合テスト。

CLAUDE.md 条約

すべての主要なディレクトリには、次の内容が記載された CLAUDE.md ファイルがあります。

• このコードが行うこと
• 技術スタックとバージョン
• クイックスタートコマンド
• アーキテクチャに関する決定
• よくあるパターン

CLAUDE.md                          # Root-level overview
├── frontend/CLAUDE.md            # Next.js 15, React 19, Tailwind v4
├── backend/CLAUDE.md             # Cloudflare Workers, Hono, Mastra
├── external/chrome-extension/CLAUDE.md
├── external/google-cloud-functions/CLAUDE.md
└── marketing/email/CLAUDE.md     # MJML email guidelines

これは人間だけのものではありません。AI コーディング アシスタントがこれらのファイルを読み取ります。クロード コードがフロントエンドで動作すると、次のようになります。 frontend/CLAUDE.md Next.js 15 を React 19、npm (pnpm ではない)、および特定のパターンとともに使用していることを知っています。

一貫したツール

1 つの構成でどこでも:

.prettierrc              # Formatting (all JS/TS)
.eslintrc               # Linting (shared rules)
tsconfig.json           # TypeScript base config

新しい開発者? npm install 作業中のディレクトリ内にあります。すべてが機能します。

---

課題 (およびその対処方法)

課題: リポジトリのサイズ

それが（まだ）問題にならない理由:

• クローン時間: ~20 秒
• Git 操作: 依然としてキビキビ
• スパース チェックアウト、LFS、シャロー クローンは必要ありませんでした

次のことが必要な場合:

• 大規模なバイナリ アセットは git ではなく R2/S3 に移動します。
• 1GB 以上に達したら、CI のシャロー クローンを検討します。
• 真に独立したサービスを抽出できる

課題: ビルド時間

問題: すべてが接続されている場合、すべてが再構築されますか?

現実: いいえ。各プロジェクトは独立してビルドされます。

cd frontend && npm run build


cd backend && npm run build


cd external/chrome-extension && npm run build

フロントエンド開発 (高速 HMR) には Turbopack、バックエンド開発 (高速リロード) には Wrangler、拡張機能開発 (高速リビルド) には WXT を使用します。

課題: 権限の境界

問題: 誰もがすべてを見る必要があるわけではありません。

私たちの状況: 私たちは小さなチームです。誰もがすべてを見ることができます。これはバグではなく機能であり、他家受粉が可能になります。

私たちが成長して境界線が必要になった場合:

• レビュー要件については GitHub CODEOWNERS
• ブランチ保護ルール
• 本当に機密性の高いコードベースを分割する可能性があります (ただし、これには抵抗します)

課題: コンテキストの切り替え

問題: TypeScript (フロントエンド)、TypeScript (バックエンド)、Apps Script (Google アドオン)、MJML (電子メール) の間を行き来すると、方向感覚が失われます。

解決策:

• プロジェクト全体で一貫したパターン (同じ lint、同じフォーマット)
• CLAUDE.mdファイルはコンテキストを即座に説明します
• IDE ワークスペース構成

---

結論

私たちのモノレポはトレンドを追うことではありません。それは、自然に一緒に属するもの間の摩擦を取り除くことであり、関連するコンテキストがすべてである場合に重要なことです。

機能がバックエンド API、フロントエンド コンポーネント、ドキュメント、マーケティング サイトに関わる場合、なぜ 4 つのリポジトリ、4 つの PR、4 つのマージ調整会議が必要になるのでしょうか?

モノリポジトリは制約ではありません。それは力の乗算器です。

---

Kasava は統合プラットフォームとして構築されています。 私たちが構築したものを見てください