Vibe coding in style.md

创始人、设计师、产品经理、营销人员——他们在不同程度上具备技术能力，但并非工程师——现在都在大量使用代码生成工具。这感觉非常自由，同时也极其令人上瘾。但是，当工程师打开你的代码仓库，并（尽管他们尽了最大努力让一切正常运行）不得不扔掉你“氛围编码”出来的所有东西并从头重写时，现实就来了个当头棒喝。如果你想避免这种情况，这篇文章就是为你准备的。以下是我们如何将“氛围代码清理”转变为一项可复用资产，将“火星人”（Evil Martians）的工程精髓浓缩进一个小文件：AGENTS.md。

AGENTS.md 是火星人工程师的精华浓缩。在你的下一个AI辅助项目中试试看！

Cloud Cards 的故事

一些背景故事。在思考如何更智能地推广旧金山Ruby大会时，Victoria Melnikova 想出了一个主意：让现有参会者基于他们的照片生成带有卡通角色的有趣个人邀请函。

接下来我记得的是：燃烧着深夜的算力，用 Ruby on Rails、Avo、RubyLLM 和 Nano Banana 构建这个应用。生成的“Cloud Cards”有时会拼错大会名称，但它们看起来很可爱，并且与我们的品牌风格匹配得几乎过于完美。

茶歇时刻：用 Bolt.new 构建 sfruby.com （2025年6月9日）

我尝试将应用部署到 Railway，遇到了一些问题，并与 Vladimir Dementyev 共享了代码库和项目的访问权限（方便的是，他是我在 Evil Martians 的同事，也是世界上最杰出的Web工程师之一）。

Vladimir 的反馈通常不适合心脏脆弱的人，但这次尤其极端：他埋头苦干，从头重写了整个应用。

当我再次查看这个应用时，它让我想起阅读代码也可以是一种享受。它感觉像是奢侈品——确实如此，考虑到投入了多少技能和关注。

在我意识到之前，我有了一个新的瘾好：“生成”看起来像是 Vladimir 写的代码。极致优雅且不言自明。

问题在于：不是每个人都有 Vladimir

有一个难题：没有世界级的工程师会永久值班，花费一生来重写我氛围编码的应用。

我们不能拥有这么好的东西！

我们确实拥有的是同一个应用的两个版本，即原始的 Cloud Cards 和重构后的 Cloud Cards。因此，问题变成了：我们能否用它们来教一个模型模仿 Vladimir 的风格？

值得一试。

我们的三步流程

以下是我们使用的流程：

1. 请求一个“思考模型”对比两个版本，并生成一份文档，解释关键差异和 Vladimir 的“风格”。将其视为未来工作的设计文档：这样我们在构建下一个应用时，可以将其交给模型，使结果更接近 Vladimir 自己会写的样子。
2. 将这个大文件 style.md，总结成一个更短、更聚焦的文件，名为 AGENTS.md：
   • AGENTS.md 重述了应用上下文和用例。
   • 它将关键的风格和结构决策编码为规则和模式。
3. 再次使用“思考模型” 来发现任何技术上的不一致之处，并提高文档质量。人工通读也很重要。

结果文件是：AGENTS.md。

接下来，我在构建一个新项目时使用了 AGENTS.md——这次是一个关于文本编辑和 AnyCable 的实验。几天后，Vladimir 审查了新的代码库。他分享了直接、详细的反馈，但这次，他说他可以在现有代码基础上工作，而不是把它扔掉。

这是成功吗？至少，这是一个有希望的开始！我们已经在向不同类别的反馈迈进，而且这是第一次，代码也让我感觉可以读懂。

AGENTS.md 内部揭秘

免责声明：需要明确的是，这些并非“官方”的 Evil Martians Rails 指南。它们设计上就不完美，产生自一个非常简单的过程，且仅基于单一重构案例。但这是一个好的开始，并且已经具备实用性。

那么，AGENTS.md 里到底有什么？出乎意料，内容相当丰富。以下是其中一些规则。

使用领域语言

命名时，使用你在自然语言中会使用的相同“正常”词汇，而不是通用的技术术语。结果是代码不需要图例：名称本身就已经不言自明。

• 不佳：User, Image
• 良好：Participant, Cloud, Invitation

对状态使用枚举

使用 enum 来定义状态，可以免费获得谓词方法、bang 方法和作用域：

1
2
3
4
5
6
7
8

class Cloud < ApplicationRecord
  enum :state, %w[uploaded analyzing analyzed generating generated failed].index_by(&:itself)
end

# 用法：
cloud.uploaded?          # 谓词方法
cloud.generating!        # Bang 方法（更新并保存）
Cloud.generated.count    # 作用域

将代码从模型提取到命名空间的类中

一个简单的组织技巧，避免模型过于臃肿：让模型专注于数据、关系、验证和简单逻辑。将复杂行为移动到命名空间的类中。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

class Cloud < ApplicationRecord
  # 模型：仅包含数据和简单方法
  def ready_to_generate?
    analyzed?
  end
end

# app/models/cloud/card_generator.rb
class Cloud::CardGenerator
  private attr_reader :cloud, :api_key

  def initialize(cloud, api_key: GeminiConfig.api_key)
    @cloud = cloud
    @api_key = api_key
  end

  def generate
    # 复杂的 API 逻辑放在这里，返回 IO 对象
  end
end

何时提取：

• 任何超过约 15 行的方法
• 任何调用外部 API 的方法
• 任何复杂的计算
• 任何在多个地方复用的内容

使用 anyway_config 进行类型安全的配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# config/configs/application_config.rb
class ApplicationConfig < Anyway::Config
  class << self
    delegate_missing_to :instance

    private

    def instance
      @instance ||= new
    end
  end
end

# config/configs/gemini_config.rb
class GeminiConfig < ApplicationConfig
  attr_config :api_key
end

api_key = GeminiConfig.api_key

为什么？

• 类型安全（加载时验证）
• 单例风格访问
• 组织在 config/configs/ 目录下
• 易于用辅助方法扩展（ssl?, configured? 等）
• 环境特定（开发、测试、生产）

绝不直接使用 Rails credentials 或 ENV。

推荐（及避免）的模式

文件中鼓励的其他示例：

• Form Object
• Query Object
• ViewComponent

它反对的一些东西：

• Service Object
• Result Object

这些并非普遍真理，只是针对这种特定风格和代码库的规则。文件的其余部分会更详细地阐述。

手动编辑

我们也发现 AGENTS.md 文件中存在一些“幻觉”（错误推断），所以我们手动进行了清理。

一个例子是它错误地得出结论，认为 ActiveJob::Continuable 需要 bundlebun gem。

将清理工作转化为资产

我们将一项非常昂贵且不可扩展的服务——“Vladimir 清理我的氛围代码”——转化为了一项可复用的资产，使我生成的代码更易于管理。

我们接下来的计划：

• 在其他氛围编码项目上尝试这个 AGENTS.md（Vladimir 风味）。
• 使用相同流程，在更多“氛围清理”案例上扩展它（或创建新的指南）。
• 继续试验更好的风格指南格式和代码生成的护栏。
• 分享结果并继续公开学习。

你觉得这个小实验怎么样？如果你决定尝试类似的事情——或者已经在做了——分享你的结果吧！