Vibe Coding 规范

Posted on Edited on In Views:

我的 Vibe Coding 项目规范，这个文章会在我每次Vibe Code 前被喂给 Agent。

Vibe Coding 规范

  1. 项目应做成完整、成熟的 GitHub 仓库：

    • 有英文文档，特别的，有 README 文档，并且符合下文定义的规范

    • 在 README 开头放一句

      1
      2
      3
      You can use AI to translate or explain this document and the rest of the project's documentation in your preferred language.

      你可以使用 AI 将本文档和本项目的其他文档翻译成你偏好的语言，或为你解读其中的内容。

      因此项目中不用放别的语言的文档。

    • 目录结构整洁，源码放在 src/ 等目录下，README 之外的文档放在docs/下，避免仓库根目录杂乱

    • 建议在 docs/ 下至少有 cli / design / workflows 三个文档

    • 项目 / 文档 中不硬编码绝对路径

    • 有 MIT License

    • 有 .gitignore

  2. 项目应有测试与自动化：
    • 有单元测试
    • 有 GitHub Actions，在 push / pull request 时自动运行测试
  3. 项目应有清晰文档：
    • 说明项目用途、安装方式、使用方法
    • 给出必要的示例
  4. 如果提供命令行工具：
    • 命令结构简洁
    • 有文档说明
    • 也有 -h / --help 说明
  5. 总体要求：
    • 项目应像真正可发布、可维护、可被他人使用的 GitHub 项目，而不是临时脚本堆砌

README 规范

  1. 用英文写。
  2. 语言要偏技术说明文，不要像宣传文案。 直接、克制、具体。
  3. 先说“这是什么”，再说“怎么用”。最理想的 opening 通常是三段：
    1. 一句话定义项目
    2. 一两句话说明核心行为
    3. 一句话说明边界和非目标
  4. 术语要先定义，再使用。如果开头解释术语会挤占 opening，就单独列一个简短的 Terminology 小节，并在正文首次使用时链接过去。
  5. 第一次出现的专业术语，要给读者落脚点。如果一个词在项目里有特定含义，就先定义。如果是较专业、较小圈子的术语，首次出现时最好用超链接包裹，用斜体标出，必要时补一个简短解释
  6. 可以使用“心智模型级别”图示和伪代码来帮助说明。
  7. README 结尾注明：本项目由 AI 和人类共同编写

设计文档规范

采取自顶而下的方式。