从 Harness 到 Loop：Vibe Coding 如何进入大型代码库

当 Vibe Coding 从个人原型走进大型代码库，真正的难点就不再是“让模型写出一段代码”，而是让它持续理解上下文、遵守工程约束，并在可验证的循环中交付变更。

“从 Harness 到 Loop”可以理解为一次工作方式的升级：Harness 负责搭建代码生成与验证的运行边界，Loop 负责让需求、实现、测试和反馈形成闭环。10 月 16 至 17 日，第 30 届 GOPS 全球运维大会暨研运数智化技术峰会上海站将讨论相关的研运实践。下面用一个可落地的工程流程，拆解大型代码库接入 Vibe Coding 时需要解决的问题。

大型代码库的三个现实约束

在小项目中，开发者可以把整个目录交给模型，再根据结果手动修正。但大型代码库通常同时存在多个约束：

• 代码上下文很大，模型无法一次性读取所有模块。
• 模块之间存在隐含契约，例如错误码、日志字段、数据库迁移规则和 API 兼容性。
• 一次看似局部的修改，可能影响构建、测试、部署或线上观测。

因此，Vibe Coding 不应被设计成“输入一句话，生成一份补丁”的单次动作，而应被设计成一个有边界的执行循环：

需求澄清 -> 定位影响范围 -> 生成小步变更 -> 自动检查 -> 反馈修正 -> 人工审阅

这里的关键不是让模型拥有更多权限，而是让它每次只处理清晰、可验证、可回滚的任务。

Harness：先把模型放进工程边界

Harness 可以理解为围绕编码代理建立的工程控制层。它不一定是某个特定产品，也可以是团队自己维护的一组脚本、配置和检查规则。一个合格的 Harness 至少应该回答四个问题：

1. 模型可以读取哪些目录？
2. 模型可以修改哪些文件？
3. 修改后必须运行哪些检查？
4. 检查失败时，如何把结构化反馈交回下一轮？

例如，一个 Python 服务可以为编码代理准备如下项目级约束文件。下面的内容是可按团队实际情况改造的示例，并不代表某个会议的官方配置：

# .vibe/workflow.yaml
project:
  language: python
  source_dirs:
    - src
  test_dirs:
    - tests
  protected_paths:
    - migrations
    - infra/production
    - .github/workflows

workflow:
  max_files_per_change: 8
  require_plan: true
  require_tests: true
  require_human_review: true

checks:
  - name: format
    command: python -m ruff format --check src tests
  - name: lint
    command: python -m ruff check src tests
  - name: unit-tests
    command: python -m pytest -q

这类配置的价值在于把“请谨慎修改”变成可执行的规则。protected_paths 限制高风险区域，max_files_per_change 防止一个需求扩散成大范围重构，检查命令则把代码质量从主观判断变成机器可重复执行的结果。

在实际接入时，还可以要求代理先输出计划，再开始编辑。例如：

你正在修改一个 Python 服务。

任务：为订单查询接口增加按 customer_id 过滤的能力。

执行规则：
1. 先读取 src/orders、src/api 和 tests/orders 中与订单查询相关的文件。
2. 先输出影响范围、拟修改文件和测试计划，不要立即编辑。
3. 不修改数据库迁移、生产部署和认证模块。
4. 每次最多修改 8 个文件。
5. 修改后运行 ruff 和 pytest，并报告完整命令及结果。
6. 如果测试失败，只修复与当前任务直接相关的问题。

Loop：让交付变成可观察的反馈循环

有了边界，下一步是建立 Loop。一个实用的 Loop 不需要很复杂，但必须让每一轮都有输入、产物和判定结果。

可以用一个简单的 Bash 脚本把本地验证流程固定下来。运行前，将 ruff 和 pytest 加入项目依赖，并根据仓库实际情况调整路径：

#!/usr/bin/env bash
set -Eeuo pipefail

changed_files="$(git diff --name-only -- '*.py')"
if [[ -z "$changed_files" ]]; then
  echo "No Python files changed."
  exit 0
fi

file_count="$(printf '%s\n' "$changed_files" | sed '/^$/d' | wc -l | tr -d ' ')
if (( file_count > 8 )); then
  echo "Refusing to validate: more than 8 Python files changed ($file_count)." >&2
  exit 2
fi

python -m ruff format --check src tests
python -m ruff check src tests
python -m pytest -q

这个脚本并不能替代代码审查，但它能阻止最常见的失控情况：修改范围过大、格式检查遗漏，以及模型声称“已经测试”但实际没有运行测试。

如果团队使用 CI，可以把同样的规则放进 Pull Request 检查：

# .github/workflows/vibe-check.yml
name: Vibe Coding Checks

on:
  pull_request:
    paths:
      - "src/**"
      - "tests/**"
      - "pyproject.toml"

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python -m pip install -e ".[dev]"
      - run: python -m ruff format --check src tests
      - run: python -m ruff check src tests
      - run: python -m pytest -q

上下文管理比提示词技巧更重要

大型代码库中的模型效果，往往取决于上下文是否被正确切分。与其把整个仓库压缩成一段超长提示，不如按任务建立最小上下文包：

• 目标模块的实现文件。
• 直接调用方和被调用方。
• 相关接口或数据模型定义。
• 最近的测试用例。
• 与任务有关的错误日志或历史变更。
• 明确的非目标范围。

例如，修改订单查询功能时，不需要把支付、用户认证和生产基础设施全部加入上下文。可以先用代码搜索确定入口：

rg -n "class Order|def list_orders|/orders|customer_id" src tests

git log --oneline -- src/orders src/api tests/orders -20

git diff --stat origin/main...HEAD

这几条命令提供了结构、历史和当前变更范围。把结果交给代理后，再要求它只围绕这些文件工作，通常比反复调整一句“请写得更好”的提示更有效。

需要特别关注四类风险：

• 隐藏行为改变：模型修改了默认排序、分页边界或异常处理。
• 测试幻觉：测试文件被补充了，但断言只验证了实现本身，没有覆盖真实契约。
• 依赖扩散：为了完成一个小功能，引入了新的库或升级了基础依赖。
• 安全边界绕过：代理读取了不应暴露的密钥、生产配置或个人数据。

这些风险不能只依赖模型自律解决。仓库权限、密钥隔离、CI 门禁和人工批准仍然是必要的工程设施。

从小任务开始建立度量

团队落地 Vibe Coding 时，不建议一开始就追求“代理自动完成所有开发”。更可行的起点是选择边界清晰、回归成本低的任务，例如：

• 为已有接口补充单元测试。
• 根据明确的 API 契约生成 DTO 或校验逻辑。
• 修复静态检查发现的局部问题。
• 为日志和指标增加统一字段。
• 更新已有模块的文档和示例。

同时记录一些可比较的指标：任务从开始到合并的时间、人工修改行数、测试失败次数、回滚次数、审查发现的问题数量，以及变更涉及的文件数。指标的目的不是证明模型“替代了开发者”，而是判断这套 Loop 是否真的减少了重复劳动，是否让质量反馈更早出现。

落地检查清单

在大型代码库中推广前，可以逐项确认：

• 是否有明确的代码读取和写入边界？
• 是否把高风险目录设为保护路径？
• 是否要求先计划、后编辑？
• 是否限制单次变更的文件数和 diff 规模？
• 是否有可重复执行的格式、静态检查和测试命令？
• 是否能把失败日志结构化地交给下一轮？
• 是否保留人工审阅和合并权限？
• 是否记录了效率、质量和回滚相关指标？

Vibe Coding 进入大型代码库后，核心竞争力不只是模型本身，而是团队能否把模型嵌入一条可观察、可验证、可追责的工程流程。Harness 解决“在哪里、以什么权限工作”，Loop 解决“如何持续反馈并完成交付”。两者结合，才可能把一次性的代码生成变成稳定的研发能力。