Hotdry.
归档
ai-engineering

Everything as Code：如何在单一代码库中管理整个公司

探索Kasava如何将公司所有资产编码化，从代码到文档再到营销材料，全部纳入单一代码库，实现AI原生开发与原子化变更。

在传统的软件开发中，我们习惯于将代码、文档、营销材料和运营流程分开管理。代码放在 Git 仓库，文档放在 Confluence 或 Notion，营销内容在 Contentful 或 WordPress，而运营流程则分散在各种工具和电子表格中。这种碎片化管理在 AI 时代正变得越来越低效。

Kasava，一家专注于 AI 辅助产品开发的初创公司，提出了一个激进但实用的解决方案：Everything as Code。他们将整个公司 —— 不仅仅是产品代码，还包括文档、营销网站、投资者演示文稿、电子邮件模板，甚至内部架构文档 —— 全部放入一个单一的代码库中。

为什么需要 Everything as Code？

AI 原生开发的必然选择

AI 工具的核心价值在于上下文理解。当 AI 助手（如 Claude、GitHub Copilot）能够访问完整的上下文时，它们的工作效率会呈指数级提升。Kasava 的创始人 Ben Gregory 在博客中写道：

"AI is all about context. And this monorepo is our company—not just the product."

想象这样一个场景：你需要更新定价页面。在传统的工作流中，你需要：

  1. 更新后端服务的定价逻辑
  2. 修改前端界面的显示
  3. 同步营销网站的定价信息
  4. 确保文档反映最新变化
  5. 检查博客文章是否有过时信息

这通常涉及 4-5 个不同的系统，需要多个团队的协调。而在 Everything as Code 的模型中，你只需要修改一个 JSON 文件：

// billing-plans.json
{
  "plans": {
    "free": { "limits": { "repositories": 1, "aiChatMessagesPerDay": 10 } },
    "starter": { "limits": { "repositories": 10, "aiChatMessagesPerDay": 100 } },
    "professional": { "limits": { "repositories": 50, "aiChatMessagesPerDay": 1000 } }
  }
}

这个文件同时被后端（强制执行限制）、前端（显示限制）、营销网站（展示定价）和文档（说明功能）引用。一次提交，所有地方同步更新。

原子化变更的力量

在单一代码库中，跨边界的变更可以原子化完成。当添加 Asana 集成时，Kasava 的提交结构是这样的：

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，一次代码审查，一次合并。所有相关组件一起发布，没有版本不匹配的风险。

代码库的实际结构

Kasava 的代码库包含 5,470 多个 TypeScript 文件，结构清晰而全面：

核心应用层

frontend/                        # 面向客户的Next.js应用
├── src/
│   ├── app/                    # 25+路由目录
│   └── components/             # 45+组件目录

backend/                         # Cloudflare Workers API
├── src/
│   ├── services/               # 55+业务逻辑服务
│   └── workflows/              # Mastra AI工作流

营销资产

website/                        # 营销网站 (kasava.ai)
marketing/
├── blogs/                      # 博客管道（草稿→审查→发布）
├── investor-deck/              # Next.js投资者演示（非PowerPoint！）
└── email/                      # MJML邮件模板

是的，你没看错 —— 他们的投资者演示文稿也是代码。这是一个包含 17 个 React 幻灯片组件的 Next.js 静态站点，支持键盘导航和 PDF 导出。没有 PowerPoint，没有 Google Slides。当需要更新指标或信息时，这是一个带有完整 Git 历史的代码变更。

文档系统

docs/                           # 公开文档（Mintlify）
docs-internal/                  # 12+架构文档和规范

外部服务

external/
├── chrome-extension/           # WXT + React错误捕获工具
├── google-docs-addon/          # @helper AI助手（Apps Script）
└── google-cloud-functions/
    ├── tree-sitter-service/    # 支持10+语言的AST解析
    └── mobbin-research-service/

技术实现：如何让这一切工作

选择性 CI/CD

一个常见的担忧是："如果所有东西都在一个仓库里，每次提交都要运行所有测试吗？" Kasava 的解决方案是基于路径的选择性 CI/CD。

他们配置了 5 个独立的 GitHub Actions 工作流，每个只对特定路径的变更做出响应：

# .github/workflows/frontend-tests.yml
name: Frontend Tests
on:
  push:
    paths:
      - "frontend/**"
      - ".github/workflows/frontend-tests.yml"
# 运行：类型检查、lint、演示数据验证、测试覆盖率

# .github/workflows/backend-tests.yml
name: Backend Tests
on:
  push:
    paths:
      - "backend/**"
      - ".github/workflows/backend-tests.yml"
# 运行：单元测试、集成测试、端到端测试

这种设计确保了：

  • 修改 Chrome 扩展时，只运行相关测试
  • 更新后端时，运行后端测试加上任何依赖的集成测试
  • 营销内容变更不会触发代码测试

CLAUDE.md 约定

为了帮助开发者和 AI 助手理解代码库的不同部分，Kasava 引入了 CLAUDE.md 文件约定。每个主要目录都包含一个 CLAUDE.md 文件，记录：

  1. 这个代码做什么
  2. 技术栈和版本
  3. 快速启动命令
  4. 架构决策
  5. 常见模式
CLAUDE.md                          # 根级概述
├── frontend/CLAUDE.md            # Next.js 15, React 19, Tailwind v4
├── backend/CLAUDE.md             # Cloudflare Workers, Hono, Mastra
├── external/chrome-extension/CLAUDE.md
└── marketing/email/CLAUDE.md     # MJML邮件指南

当 AI 编码助手处理前端代码时，它会读取frontend/CLAUDE.md，了解使用的是 Next.js 15、React 19、npm（不是 pnpm）以及特定的代码模式。

独立项目结构

Kasava 故意不使用npm/yarn 工作区。每个目录都是独立的 npm 项目：

cd frontend && npm install    # 前端依赖
cd backend && npm install     # 后端依赖
cd external/chrome-extension && npm install  # 扩展依赖

这种设计的优势在于简单性和可预测性。没有提升（hoisting）的混淆，没有 "我实际得到的是哪个 React 版本？" 的问题。每个项目都是隔离且可预测的。

面临的挑战与解决方案

挑战 1：代码库大小

现状：克隆时间约 20 秒，Git 操作仍然迅速。他们目前不需要稀疏检出、LFS 或浅克隆。

未来规划：

  • 大型二进制资产会存储在 R2/S3，而不是 Git 中
  • 如果达到 1GB+，考虑在 CI 中使用浅克隆
  • 真正独立的服务可能会被提取出来

挑战 2：构建时间

误解：如果所有东西都连接在一起，是不是所有东西都要重新构建？

现实：不。每个项目独立构建：

# 前端构建（只重新构建前端）
cd frontend && npm run build

# 后端构建（只重新构建后端）
cd backend && npm run build

# 扩展构建（只重新构建扩展）
cd external/chrome-extension && npm run build

他们使用 Turbopack 进行前端开发（快速 HMR）、Wrangler 进行后端开发（快速重载）、WXT 进行扩展开发（快速重建）。

挑战 3：权限边界

当前情况：小团队，每个人都能看到所有东西。这是一个特性，而不是缺陷 —— 它促进了交叉学习。

如果团队扩大：

  • 使用 GitHub CODEOWNERS 进行代码审查要求
  • 分支保护规则
  • 可能拆分真正敏感的代码库（但会尽量避免）

挑战 4：上下文切换

问题：在 TypeScript（前端）、TypeScript（后端）、Apps Script（Google 插件）和 MJML（邮件）之间切换可能让人迷失方向。

解决方案：

  • 跨项目的一致模式（相同的 linting、相同的格式化）
  • CLAUDE.md 文件立即解释上下文
  • IDE 工作区配置

部署架构

组件 技术栈 部署到
前端 Next.js 15, React 19, Tailwind v4 Vercel
后端 Cloudflare Workers, Hono, Mastra Cloudflare
网站 Next.js, 自定义组件 Vercel
投资者演示 Next.js, 自定义组件 Vercel
文档 Mintlify MDX Mintlify
Chrome 扩展 WXT, React, Tailwind Chrome Web Store
Google Docs 插件 Apps Script, HTML Google Workspace Marketplace
Tree-sitter 服务 Node.js, GCP Functions Google Cloud
邮件模板 MJML Loops.so

可落地的实施清单

如果你考虑在自己的组织中实施 Everything as Code，以下是具体的步骤和参数：

第一阶段：评估与规划（1-2 周）

  1. 代码库审计：列出所有当前分散的资产

    • 产品代码（前端、后端、移动端）
    • 文档（公开和内部）
    • 营销材料（网站、博客、邮件模板）
    • 运营流程（配置、脚本、部署定义）

  2. 依赖关系映射：识别资产之间的依赖关系

    • 哪些文档引用了特定 API？
    • 营销材料中的哪些声明需要代码验证？
    • 配置变更如何影响多个系统？

  3. 工具链统一：选择一致的技术栈

    • 格式化：Prettier 配置
    • Linting：ESLint 规则
    • 类型检查：TypeScript 配置
    • 测试框架：Jest/Vitest

第二阶段：迁移与整合（2-4 周）

  1. 创建单一代码库结构

    your-company/
├── frontend/
│   ├── package.json
│   └── CLAUDE.md
├── backend/
│   ├── package.json
│   └── CLAUDE.md
├── docs/
│   ├── public/
│   ├── internal/
│   └── CLAUDE.md
├── marketing/
│   ├── website/
│   ├── blogs/
│   └── CLAUDE.md
└── shared/
    ├── config/
    └── types/

  2. 实现选择性 CI/CD

    • 基于路径的 GitHub Actions/GitLab CI 触发
    • 每个目录独立的测试运行
    • 共享的 linting 和格式化检查

  3. 建立 CLAUDE.md 约定

    • 每个目录的标准化文档模板
    • AI 助手友好的格式
    • 包含技术栈、快速启动、架构决策

第三阶段：优化与扩展（持续）

  1. 监控指标

    • 代码库大小增长：目标 < 1GB
    • 克隆时间：目标 < 30 秒
    • 构建时间：各项目独立 < 5 分钟
    • CI/CD 运行时间：基于变更选择性运行

  2. AI 工具集成

    • 配置 AI 助手读取 CLAUDE.md
    • 建立代码审查的 AI 辅助流程
    • 实现自动化的文档同步

  3. 团队培训

    • Everything as Code 理念培训
    • 新工作流上手指导
    • 最佳实践分享会

关键成功因素

技术参数阈值

  • 代码库大小：保持 < 1GB，超过时考虑资产外部化
  • 克隆时间：目标 < 30 秒，超过时启用浅克隆
  • 构建时间：各项目独立构建 < 5 分钟
  • 测试覆盖率：核心业务逻辑 > 80%

组织文化要求

  • 透明文化：团队成员需要能够访问大部分代码
  • 文档习惯：强制 CLAUDE.md 更新作为 PR 要求
  • 原子提交：鼓励跨边界的单一提交
  • AI 友好：设计代码和文档时考虑 AI 可读性

风险管理策略

  1. 回滚计划：每个部署都有明确的回滚步骤
  2. 权限控制：CODEOWNERS 文件定义审查要求
  3. 监控告警：关键指标偏离时立即告警
  4. 定期审计：每季度审查代码库健康状况

结论

Everything as Code 不是关于遵循趋势，而是关于消除自然属于一起的事物之间的摩擦。在 AI 时代，相关上下文就是一切。当一个功能涉及后端 API、前端组件、文档和营销网站时，为什么这应该是四个仓库、四个 PR、四个合并协调会议？

Kasava 的经验表明，单一代码库不是约束，而是力量倍增器。它使 AI 工具能够发挥最大效用，确保一致性，并创建真正的原子化工作流。对于正在向 AI 原生开发转型的团队来说，Everything as Code 提供了一个切实可行的路径，将碎片化的资产整合为统一的、可操作的、AI 友好的系统。

正如 Ben Gregory 所说："The monorepo isn't a constraint. It's a force multiplier." 在上下文为王、AI 辅助成为标配的时代，将一切编码化可能是保持竞争力的关键策略。

资料来源：

  1. Kasava 博客文章：https://www.kasava.dev/blog/everything-as-code-monorepo
  2. Hacker News 讨论：https://news.ycombinator.com/item?id=46437381
查看归档