Communitygithub.com

kktbur/VibeCoding-Start

一个“氛围编码”治理技能,通过从一开始就建立清晰的文档、可复用的项目知识、质量关卡、独立审查、测试、可观测性和可回滚工作流,防止项目沦为难以维护的AI生成烂摊子。

VibeCoding-Start 是什么?

VibeCoding-Start 技能为 Codex 项目提供了一个轻量级的工程治理系统,旨在解决 AI 生成代码的维护性难题——它从项目的首次会话到发布与观测阶段,强制推行一套严格的结构和流程。该技能要求项目必须包含 AGENTS.md 和六个核心文档(INDEX、CURRENT、PRODUCT、PRD、ACCEPTANCE、CODEMAP),并定义了从 G0(范围)到 G9(观测)的十个工程关卡,每个关卡都设定了明确的检查点(如意图一致性、复用决策、对抗性评审和可观测性)。通过强制使用“USE → ADAPT → COMPOSE → BUILD → STOP”等复用决策顺序,以及要求所有变更在重现性证据和人工确认通过后才能发布,它显著降低了项目失控风险。该技能适用于任何希望保持项目可维护性的 AI 辅助开发环境,尤其适合需要长期迭代、多人协作或严格质量要求的项目。

兼容平台~Claude Code✓Codex CLI~Cursor
npx skills add kktbur/VibeCoding-Start

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

VibeCoding Start

使用这个技能让 Codex 从一开始就拥有一个轻量级工程系统,贯穿项目从首次会话到发布与观测的整个过程。其目标是一个后续会话能够理解、审查、验证、接受,并安全地继续开发,而无需重播整个聊天记录。

第一步操作

阅读项目的 AGENTS.md,然后按照以下热上下文顺序执行:

  1. docs/INDEX.md
  2. docs/CURRENT.md
  3. docs/PRODUCT.md
  4. docs/PRD.md
  5. docs/ACCEPTANCE.md

仅在任务需要时才读取 docs/CODEMAP.md、活跃的 ADR、计划、工作日志、标准以及本地原始证据。如果这六个文档的骨架缺失,请在实现之前先用配套的 vibecoding-project-knowledge 技能的 INIT 模式。

不可妥协的项目边界

  • 每个项目都必须拥有相同的最小骨架:AGENTS.md、docs/INDEX.md、PRODUCT.md、PRD.md、ACCEPTANCE.md、CURRENT.md 和 CODEMAP.md。
  • 复杂性的变化只会改变文档的深度和关卡强度,但不会移除骨架。
  • PRODUCT.md 解释“为什么”,PRD.md 解释“是什么”,ACCEPTANCE.md 解释“如何证明”。不要将这些职责合并而不加区分。
  • 当会话改变了需求、功能、非目标、约束或有意义的用户场景时,更新 PRD.md。
  • 默认将原始会话、日志、失败的尝试、调查和证据保存在本地的 .project-memory/ 目录下。只将经过筛选和刻意策划的示例提升到 docs/examples/。
  • 优先使用现有的项目能力、标准库、官方 SDK/API/工具、成熟的开源项目、包、适配器或组合,然后再考虑自定义基础设施。
  • 不要在本工作流中构建内存数据库、向量数据库、搜索引擎、测试框架、部署框架、CI 服务或可观测性后端。

工程关卡

对每个项目使用相同的词汇表,同时根据风险调整深度:

G0 范围
→ G1 意图
→ G2 复用
→ G3 计划
→ G4 构建
→ G5 对抗性评审
→ G6 验证
→ G7 人工验收
→ G8 发布
→ G9 观测

G0 范围

将工作分类为应用程序/产品、集成/适配器或基础设施/安全/运行时。越接近基础设施,复用、审查和恢复证据就必须越强。

G1 意图

使链条变得明确:

PRODUCT(为什么)→ PRD(是什么)→ ACCEPTANCE(如何证明)

在实现之前记录问题、用户、当前和期望状态、功能需求、非目标、约束、验收标准和风险。

G2 复用

对于任何非平凡的一般性能力,在构建之前先搜索,并按以下顺序做出决定:

使用 → 适配 → 组合 → 构建 → 停止

如果选择了“构建”,则在 ADR 中记录已搜索的替代方案、被拒绝的复用路径、维护责任以及所有者的验收方法。模型能编写代码并不能证明自定义代码是正确的选择。

G3 计划

将复杂工作分解为小的里程碑,每个里程碑后都有一个验证点。当范围、架构或风险发生实质性变化时,停下来重新计划。

G4 构建

保持实现小而可逆。使用现有工具链,避免投机性的抽象、依赖和基础设施。

G5 对抗性评审

由独立的评审者检查 PRODUCT.md、PRD.md、ACCEPTANCE.md、活跃决策、相关结构、差异以及测试。查找遗漏、错误假设、回归、重复的能力、过度设计、安全/数据风险、测试空白和回滚失败。重要变更的作者不能是最终评审者。

G6 验证

根据风险比例覆盖正常路径、错误路径、边界路径、无效输入路径、回归路径和恢复路径。提供机器证据和所有者可读的解释;绿色勾号只能证明它实际检查的不变量。

G7 人工验收

所有者确认结果是预期的产品,且其可观察的行为是可理解的。自动化检查和独立评审不能替代此步骤。

G8 发布

在真正使用之前记录版本、最后已知的良好状态、发布说明、备份、回滚方法、迁移风险以及精确的发布目标。

G9 观测

发布后,观察健康状况和用户证据。仅在健康时继续;当证据显示存在问题则停止并回滚或向前推进。根据情况将结果反馈到测试、工作日志、ADR、产品意图、验收或事后分析中。

知识收尾

在每个实质性会话结束时,使用配套的 vibecoding-project-knowledge 技能的 UPDATE 模式:

  1. 将原始会话细节和大输出保留在本地的 .project-memory/ 目录中。
  2. 整理 CURRENT.md 和相关的活跃文档。
  3. 当结构变化时更新 CODEMAP.md。
  4. 当需求、功能、非目标、约束或用户场景发生变化时更新 PRD.md。
  5. 在 ADR 中记录重要的选择。
  6. 更新索引和工作日志。
  7. 运行相关的确定性审计。

在没有机器证据、人类可读的解释以及所有者的验收方法之前,不要声称完成。

参考资料

  • 阅读 标准 v1.3 了解规范规则和发布边界。
  • 阅读配套的 vibecoding-project-knowledge 技能了解 INIT、UPDATE 或 AUDIT 流程。

相关技能