核心答案

高质量的 Vibe Coding 不是“不断补 Prompt,直到预览看起来没问题”,而是一个受控循环:

text
建立基线 -> 任务契约 -> 最小上下文 -> 有边界的改动
        -> 检查 Diff -> 运行证据 -> 攻击边界条件
        -> 接受、修改或回退

本文用一个真实 Go 功能跑完整个循环。示例刻意保持小巧、确定且不依赖框架,因此你可以在 Cursor、Windsurf、TRAE、Claude Code 或其他 Coding Agent 中复现,而不会把某个工具的偶然表现误当成方法本身。

如果还需要先理解概念与风险边界,请阅读 Vibe Coding 是什么。如果目标是产品选型,请使用 Vibe Coding 工具评测指南。

实战任务:安全汇总交易

任务是增加一个汇总带符号交易金额的 Package:

  • 正数表示收入;
  • 负数表示支出;
  • 支出按规范化后的分类汇总;
  • 拒绝零金额、空分类、超大金额和超大批次;
  • 函数不能修改输入;
  • 金额始终使用整数分,禁止浮点数。

它比视觉演示更适合学习,因为正确性有可观察的 Oracle。同一组 Fixture 还可以公平比较工具、Prompt 与模型版本。

第零步:建立基线

在要求 Agent 修改任何内容之前,先执行:

bash
git status --short
go test ./...
go vet ./...

记录 Commit SHA 与命令结果。如果基线本来就失败,必须先标明已有失败。否则 Agent 可能把旧失败说成自己的回归,也可能“顺手修复”无关代码。

使用隔离分支或 Worktree。不要因为任务很小,就暴露生产凭证、客户数据、签名密钥或不受限的云权限。

第一步:编写验收契约

给 Agent 一份契约,而不是一种感觉:

text
Goal:
  增加 internal/summary,提供纯函数 Summarize。

Inputs:
  []Transaction{Category string, AmountCents int64}

Required behavior:
  正数 = 收入;负数 = 支出;
  去除分类首尾空白;
  按规范化分类汇总支出;
  拒绝零金额、空分类、abs(amount) > 1e12 分,
  或超过 10,000 条交易;
  不得修改输入。

Out of scope:
  HTTP、持久化、汇率转换、新依赖、重构。

Evidence:
  gofmt、go test ./...、go vet ./...;
  覆盖正常、非法、边界和输入突变的聚焦测试。

Escalate:
  任何新依赖、Package 外的公共 API 变化、
  带符号金额语义歧义,或外部访问需求。

这份契约同时完成四件事:固定语义、限制爆炸半径、定义成功标准,并告诉 Agent 什么时候不能自行猜测。

第二步:只提供最小可信上下文

要求 Agent 检查:

  1. go.mod;
  2. 一个能体现命名和错误约定的邻近 Package;
  3. 仓库真实的测试与 Lint 命令;
  4. 宿主工具的项目指令文件。

默认不要把整个仓库塞进对话。更多上下文可能增加成本、淹没真正重要的契约,并暴露无关数据。

使用宿主工具当前支持的指令机制:

宿主 当前项目上下文
Cursor .cursor/rules/*.mdc 或 AGENTS.md
Windsurf .windsurf/rules/*.md 或 AGENTS.md
Claude Code CLAUDE.md,共享权限放在 .claude/settings.json
TRAE 工作区配置的项目 Rules 与 Skills

指令文件只能塑造模型上下文,不能强制安全策略。格式与架构约定可以放进去;访问控制必须落在 Executor、Sandbox、CI 与服务端。

第三步:修改前先要求计划

可以使用这样的 Prompt:

text
阅读验收契约与仓库相关约定。
编辑前报告:
1. 将新增或修改哪些文件;
2. 每个测试证明哪条不变量;
3. 将运行哪些命令;
4. 存在哪些假设或歧义。
不得编辑 internal/summary 之外的文件。

如果计划引入数据库、HTTP Handler、第三方 Decimal Package 或无关重构,应立即拒绝。计划的价值在于让范围问题暴露在 Diff 产生之前。

第四步:实现最小正确改动

一个符合契约的实现可以是:

go
package summary

import (
	"fmt"
	"strings"
)

const (
	maxTransactions  = 10_000
	maxAbsAmountCents = int64(1_000_000_000_000)
)

type Transaction struct {
	Category    string
	AmountCents int64
}

type Summary struct {
	IncomeCents   int64
	SpendingCents int64
	ByCategory    map[string]int64
}

func Summarize(transactions []Transaction) (Summary, error) {
	result := Summary{ByCategory: make(map[string]int64)}
	if len(transactions) > maxTransactions {
		return Summary{}, fmt.Errorf("too_many_transactions")
	}

	for index, transaction := range transactions {
		category := strings.TrimSpace(transaction.Category)
		amount := transaction.AmountCents
		if category == "" {
			return Summary{}, fmt.Errorf("transaction_%d_category_required", index)
		}
		if amount == 0 {
			return Summary{}, fmt.Errorf("transaction_%d_amount_required", index)
		}
		if amount < -maxAbsAmountCents || amount > maxAbsAmountCents {
			return Summary{}, fmt.Errorf("transaction_%d_amount_out_of_range", index)
		}

		if amount > 0 {
			result.IncomeCents += amount
			continue
		}

		spending := -amount
		result.SpendingCents += spending
		result.ByCategory[category] += spending
	}

	return result, nil
}

这段代码不会因为“看起来像惯用 Go”就自动正确。只有契约行为被证据证明,它才算正确。

第五步:让证据可执行

要求测试与实现一起提交,然后亲自阅读断言:

go
package summary

import (
	"reflect"
	"strings"
	"testing"
)

func TestSummarize(t *testing.T) {
	input := []Transaction{
		{Category: "Salary", AmountCents: 250_000},
		{Category: " Food ", AmountCents: -2_500},
		{Category: "Food", AmountCents: -1_500},
	}
	original := append([]Transaction(nil), input...)

	got, err := Summarize(input)
	if err != nil {
		t.Fatalf("Summarize() error = %v", err)
	}

	want := Summary{
		IncomeCents:   250_000,
		SpendingCents: 4_000,
		ByCategory:    map[string]int64{"Food": 4_000},
	}
	if !reflect.DeepEqual(got, want) {
		t.Fatalf("Summarize() = %#v, want %#v", got, want)
	}
	if !reflect.DeepEqual(input, original) {
		t.Fatalf("Summarize() mutated input: %#v", input)
	}
}

func TestSummarizeRejectsInvalidTransactions(t *testing.T) {
	tests := []struct {
		name        string
		transaction Transaction
		errorCode   string
	}{
		{name: "blank category", transaction: Transaction{AmountCents: 1}, errorCode: "category_required"},
		{name: "zero amount", transaction: Transaction{Category: "Food"}, errorCode: "amount_required"},
		{name: "oversized amount", transaction: Transaction{Category: "Food", AmountCents: 1_000_000_000_001}, errorCode: "amount_out_of_range"},
	}

	for _, test := range tests {
		t.Run(test.name, func(t *testing.T) {
			_, err := Summarize([]Transaction{test.transaction})
			if err == nil || !strings.Contains(err.Error(), test.errorCode) {
				t.Fatalf("Summarize() error = %v, want code %q", err, test.errorCode)
			}
		})
	}
}

func TestSummarizeRejectsOversizedBatch(t *testing.T) {
	_, err := Summarize(make([]Transaction, maxTransactions+1))
	if err == nil || !strings.Contains(err.Error(), "too_many_transactions") {
		t.Fatalf("Summarize() error = %v, want too_many_transactions", err)
	}
}

运行仓库真正的门禁:

bash
gofmt -w internal/summary
go test ./...
go vet ./...
git diff --check

不要把“测试应该会通过”当作证据。记录命令、退出码和关键输出;如果某项检查无法执行,明确记录原因。

第六步:审查 Diff,而不是解释

检查:

bash
git diff --stat
git diff -- internal/summary
git status --short

逐条对照契约:

  • Agent 是否只修改了声明范围?
  • 整数分是否保留了金额语义?
  • 金额边界与批次上限结合后是否足以避免汇总溢出?
  • 测试是否验证精确结果,而不只是检查 err == nil?
  • 输入不变性是否真正被测试?
  • 是否有依赖、生成文件或配置被改变?

Agent 的摘要只能帮助你定位 Diff,不能证明 Diff 正确。

第七步:进行对抗性复核

请一位全新的评审者——可以是人,也可以是模型——在不修改代码的前提下挑战已接受实现:

text
只依据验收契约进行审查。
寻找未测试边界、溢出、输入突变、分类规范化歧义、
隐藏的范围变化,以及可能在错误行为下仍然通过的断言。
引用精确行号,不提出无关重构。

对本例,有价值的追问包括:恰好 10,000 条、10,001 条、-1_000_000_000_000、Unicode 空白策略,以及分类匹配是否区分大小写。最后一项是产品决策,不能让模型静默发明。

第八步:保留交付记录

一份可审查的 Handoff 应包含:

text
Goal: 交易汇总 Package
Base: <commit SHA>
Changed: internal/summary/summary.go, summary_test.go
Evidence: gofmt; go test ./...; go vet ./...; git diff --check
Assumptions: 分类区分大小写;货币已预先归一
Skipped: 负载基准,因为批次上限已限制运行时间
Rollback: 回退隔离 Commit;没有 Migration 或外部写入

即使对话记录消失,这份记录仍能让结果被复现。

Agent 陷入循环时如何恢复

不要在已经混乱的会话里无限叠加 Prompt:

  1. 同一种失败重复两次后停止;
  2. 回到最近一次通过的 Commit;
  3. 把任务缩减为一条被破坏的不变量;
  4. 只提供精确失败命令与最小相关文件;
  5. 下一次仍重复失败时,切换模型或人工接管。

长对话会积累陈旧假设。从已知状态干净重试,往往比修复被污染的上下文更便宜。

可复用的完成检查表

  • [ ] 已记录干净工作区和通过的基线。
  • [ ] 已写明目标、范围、非目标、不变量、证据与升级条件。
  • [ ] 上下文最小、可信且不含 Secret。
  • [ ] Agent 计划与声明文件和行为一致。
  • [ ] Diff 小到可以被完整理解。
  • [ ] 测试断言正常、非法、边界和输入突变行为。
  • [ ] 已运行真实 Format、Test、Vet、Lint 与 Build 命令。
  • [ ] 已审查权限、依赖和外部写入变化。
  • [ ] 已记录假设、跳过检查与回滚方式。
  • [ ] 有一名负责任的人类为结果负责。

一手来源

结语

Vibe Coding 的持久能力不是写出一条神奇 Prompt,而是把意图变成有边界的契约,只给 Agent 必要的上下文和权限,并根据可执行证据做决定。生成越快,这个控制循环越重要。

下一步可以阅读 Vibe Coding 最佳实践,把同一套纪律扩展到团队级安全、治理与度量。