新闻详情

新闻详情

首页 / 资讯中心 / 详情

SpecCoding + Harness 实战:给 Vibe Coding 装上可交付的「验收骨架」

发布时间:2026/11/15 11:29:25来源:尧图网络
SpecCoding + Harness 实战:给 Vibe Coding 装上可交付的「验收骨架」
1. 为什么 Vibe Coding 需要一个「验收骨架」Vibe Coding 这个词这两年被聊得很多核心意思就是你不再一行行敲代码而是把意图丢给 Claude Code 或 Cursor让模型帮你把功能「生成」出来。它确实快快到很多人第一次用的时候会有点上头——半小时一个接口、一小时一个页面感觉生产力翻了好几倍。但问题也恰恰出在这里。生成快不代表交付稳。我见过太多这样的场景需求口头对一下Cursor 开干代码能跑联调一开边界条件全炸安全扫一眼密钥硬编码在配置里架构评审更狠直连数据库、绕过网关、分层被揉成一锅粥。这不是模型不够聪明而是缺少两样东西——规格Spec和护栏Harness。SpecCoding 解决的是「写什么、不写什么、怎么算通过」的问题它把模糊需求压成机器可读的约束面接口契约、验收用例、任务清单。Harness 解决的是「AI 能碰哪里、不能碰哪里」的问题它约束的是行为空间不是灵感本身。两者合起来就是给 Vibe Coding 装上一副可交付的「验收骨架」。这篇文章面向的是已经在用 Claude Code / Cursor 做开发、但被「能跑但不该合」的差分坑过的同学。我会给出可复制的config.toml与settings.json骨架、一份验收清单模板并完整演示一次从模糊需求到通过校验的动作。适合谁独立开发者、小团队 Tech Lead、以及任何想把 AI 编码从「灵感式」推进到「可审计」的人。2. TaoToken 前置把模型调用收进可控入口在讲 Spec 和 Harness 之前得先把模型调用这条链路理清楚。因为无论你的规格写得多好如果模型调用本身是散的、不可观测的那 Harness 就无从下手。TaoToken 在这里扮演的角色是统一的模型调用入口。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。它的价值不在于「多一个中转」而在于让你的 Claude Code、Cursor、以及后续的 CI 校验脚本都走同一个可配置、可审计的出口。为什么这对 SpecCoding Harness 很重要因为 Harness 的第一层约束就是「调用边界」。如果每个开发者本地各配一套 key、各走一条链路那你在 Rules 里写的「禁止越层调用」根本落不了地。统一入口之后你才能在config.toml里把模型、超时、重试、以及后续的审计字段集中管理。你需要先拿到 API Key入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。拿到之后不要硬编码进任何仓库文件而是走环境变量注入。这一步本身就是 Harness 的一部分——密钥不进仓库是第一条硬规则。如果你只是想先验证模型通不通可以用模型对话页面快速试一下 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。确认链路没问题之后再往下做 Spec 和 Harness 的配置。3. 可复制配置config.toml 与 settings.json 骨架这一节是全文的技术核心。我会给出两份可直接复制的骨架一份是config.toml用于统一模型调用与 Harness 参数一份是settings.json用于 Claude Code / Cursor 的项目级约束。3.1 config.toml模型调用与 Harness 参数# config.toml —— 放在仓库根目录供本地与 CI 共用 [model] provider taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY # 只读环境变量禁止写死 default_model claude-sonnet timeout_seconds 60 max_retries 2 [harness] # 目录边界AI 只能在这些目录内生成/改写 allowed_paths [src/, tests/, docs/specs/] # 禁止触碰的路径 denied_paths [infra/, secrets/, .env, migrations/] # 依赖白名单新增依赖必须在此列表内 dependency_whitelist [fastapi, pydantic, httpx, pytest] # 禁止模式命中即阻断 forbidden_patterns [ AKIA[0-9A-Z]{16}, # 硬编码密钥 jdbc:mysql://, # 直连数据库 0.0.0.0/0, # 全开放安全组 ] [review] # Review 三关开关 correctness true security true architecture true # 架构规则失败是否阻断合并 block_on_arch_fail true [ci] run_unit_tests true run_static_check true run_secret_scan true这份config.toml的关键设计点有三个。第一api_key_env只读环境变量任何把 key 写进文件的 PR 都会被 secret scan 拦下。第二allowed_paths和denied_paths构成目录边界AI 生成差分时如果越界Harness 直接红灯。第三forbidden_patterns是正则级别的禁止模式命中即阻断不给你「下个迭代再还」的机会。3.2 settings.jsonClaude Code / Cursor 项目级约束{ project: { name: speccoding-harness-demo, spec_dir: docs/specs, rules_file: .cursor/rules/architecture.mdc, claude_md: CLAUDE.md }, cursor: { rules: [.cursor/rules/architecture.mdc], skills_dir: .cursor/skills, require_spec_before_edit: true }, claude_code: { read_spec_first: true, forbid_cross_layer: true, run_min_verify_after_edit: true, compact_keep_spec: true }, review_gates: { correctness: [unit_test, boundary_case], security: [secret_scan, authz_check], architecture: [layer_check, gateway_check, dependency_whitelist] } }settings.json里最值得说的是require_spec_before_edit和read_spec_first。这两个开关强制 AI 在动手之前先读 Spec避免它凭「看起来像对」的直觉去改代码。compact_keep_spec则是针对 Claude Code 的/compact场景——上下文被压缩时Spec 里的验收点不能被压掉否则约束就丢了。3.3 验收清单模板把下面这份模板放进docs/specs/feature.md每个需求一份AI 和人共用同一份验收标准。# Spec: 功能名 ## 目标 - 一句话说明这个功能要解决什么问题 ## 非目标 - 明确列出这次不做什么防止 AI 顺手重构 ## 接口契约 - 输入 - 输出 - 失败态 ## 验收用例 | 用例 | 输入 | 期望输出 | 边界条件 | |------|------|----------|----------| | 正常 | ... | ... | 无 | | 边界 | ... | ... | 空值/超长/并发 | ## 验收命令 - pytest tests/test_feature.py -v - pre-commit run --all-files ## 架构约束 - 必须走网关禁止直连 DB - 新增依赖必须在白名单内这份模板的写法有个原则可判定。写「尽量高可用」等于没写写「p99 ≤ 500ms失败重试 2 次」才能进门禁。Spec 是契约不是说明书。4. 验证请求从模糊需求到通过校验的完整动作光有配置不够得跑一遍才知道骨架能不能用。这一节我演示一次完整动作从一句模糊需求开始到 Spec 落地、AI 生成、Harness 校验、CI 通过。4.1 模糊需求假设产品同学丢来一句话「给用户列表接口加个按注册时间筛选的功能要快。」这句话就是典型的 Vibe Coding 起点——信息量约等于零。如果直接丢给 Cursor它会给你生成一个能跑的版本但边界条件、分页、时区、索引全凭它猜。4.2 压成 Spec按第 3.3 的模板把它压成可判定的规格# Spec: 用户列表按注册时间筛选 ## 目标 - 支持按注册时间区间筛选用户列表 ## 非目标 - 不做排序切换 - 不做导出 ## 接口契约 - 输入start_time, end_timeISO8601含时区 - 输出分页用户列表 - 失败态start_time end_time 返回 400 ## 验收用例 | 用例 | 输入 | 期望输出 | 边界条件 | |------|------|----------|----------| | 正常 | 2024-01-01 ~ 2024-06-30 | 列表非空 | 无 | | 边界 | 空区间 | 空列表 | start end | | 异常 | start end | 400 | 参数校验 | ## 验收命令 - pytest tests/test_user_filter.py -v ## 架构约束 - 必须走网关禁止直连 DB - 新增依赖必须在白名单内4.3 让 AI 按 Spec 生成在 Claude Code 里先贴 Spec 路径再下指令# 在 Claude Code 会话中 先读 docs/specs/user_filter.md按验收用例生成实现与测试。 只改 src/user/ 和 tests/ 下的文件禁止动 infra/。这一步的关键是「先读 Spec」。settings.json里的read_spec_first会强制这个动作。生成完之后AI 会给出差分你过一遍 Review 三关。4.4 Harness 校验本地跑一遍校验脚本模拟 CI 门禁# 1. 单元测试 pytest tests/test_user_filter.py -v # 2. 静态检查 ruff check src/ tests/ # 3. secret 扫描 gitleaks detect --source . --no-git # 4. 架构规则校验读 config.toml 的 forbidden_patterns python scripts/harness_check.py --config config.tomlharness_check.py是个几十行的小脚本核心逻辑就是读config.toml遍历差分文件检查路径是否越界、是否命中禁止模式、新增依赖是否在白名单内。命中任意一条就返回非零退出码CI 直接红灯。4.5 成功结果全部通过时输出大概长这样[harness] allowed_paths check: PASS [harness] denied_paths check: PASS [harness] dependency whitelist: PASS [harness] forbidden patterns: PASS [harness] unit tests: 3 passed [harness] secret scan: no leaks [harness] architecture gate: PASS到这一步这个差分才算「可交付」。注意这里没有任何一步是「我觉得没问题」全是机械执行。CI 负责不信任任何人包括 AI 和你自己。5. 本篇常见错排查配置跑起来之后最容易踩的坑集中在下面几类。我按出现频率排一下。第一类Spec 写了但 AI 不读。症状是生成的代码和 Spec 对不上。原因通常是settings.json里的read_spec_first没开或者 Spec 路径没在会话里显式给出。排查方法在 Claude Code 里问一句「你读了哪个 Spec 文件」如果它答不上来就是没读。第二类Harness 误报。症状是明明没问题的代码被forbidden_patterns拦下。最常见的是正则写太宽比如jdbc:mysql://把测试里的 mock 字符串也命中了。排查方法把forbidden_patterns逐条单独跑定位是哪条规则误伤然后收窄正则。第三类密钥进了仓库。症状是 secret scan 红灯。原因多半是本地调试时图省事把 key 写进了config.toml。正确做法是永远走api_key_env本地用.env且.env在.gitignore里。如果已经提交了先轮换 key再清理历史。第四类CI 通过但架构漂移。症状是测试全绿但代码直连了 DB 或绕过了网关。原因是block_on_arch_fail被设成了false或者架构规则没进 CI。排查方法确认config.toml里block_on_arch_fail true且 CI 脚本真的调用了harness_check.py。第五类/compact之后约束丢失。症状是长会话里 AI 突然开始越层改代码。原因是上下文压缩把 Spec 里的验收点压掉了。排查方法确认compact_keep_spec true并且在/compact之前把关键验收点重新贴一遍。这几类坑有个共同点都不是模型的问题而是 Harness 配置没到位。修配置比换模型便宜得多。6. 把 Spec 和 Harness 接进你的日常链路写到这里方法论其实已经清楚了Vibe 负责速度Spec 负责方向Harness 负责边界Review 负责硬问题CI 负责不信任任何人。但要让这套东西真正跑起来还得把它接进你现有的工具链。如果你主要用 Claude Code 做长期编码和 Agent 编排建议把 Coding Plan 用起来它更适合这种需要持续上下文、多轮迭代的场景 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。配合本文的settings.jsonread_spec_first和compact_keep_spec能显著降低长会话里的约束漂移。如果你还在验证阶段想先确认模型输出质量再决定要不要接 CI可以用模型对话页面快速试几轮 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。确认没问题之后再回到config.toml把default_model固定下来。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的端点说明和参数列表。API Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 记得定期轮换别让一个 key 用到底。最后给一个我自己的习惯下一个需求先写半页 Spec再开 Claude Code / Cursor把三条架构禁止项写进 Rules让 CI 替你挡掉「能跑但不该合」的差分。速度会回来翻车会少。工具可以换方法不散。
网站建设高端定制企业官网
RELATED

相关资讯

更多精彩内容,欢迎继续阅读

较早相关资讯

最新相关资讯

【外设】之大彩串口显示屏 2026/11/15 4:54:16

【外设】之大彩串口显示屏

大彩串口屏初步使用 1 .官网下载 STM32 屏幕 GUI 设计资料 http://www.gz-dc.com/category/typeid/4112 找到 STM32 Keil 工程,移植相关代码因项目而异进行移植,由于项目简单,本人只对用到的指令接口进行修改。 比如:注意事项&…

阅读更多 →
无法下载Windows系统iso文件 2026/11/15 2:04:12

无法下载Windows系统iso文件

当我遇到这个问题的时候,我打开了一个网站: 登录 然后我打算下载的时候: 突然那个官方的连接就可以下载了:

阅读更多 →
【清华代码熊】DeepSeek V4.1 Flash 后训练详解 2026/11/14 10:11:15

【清华代码熊】DeepSeek V4.1 Flash 后训练详解

📌 上期解析了 DeepSeek V4.1 Flash 模型架构改进,本期解析 DeepSeek V4.1 Flash 预训练/后训练技术: 🌟 预训练:45T 文本 多模态混合语料、直接训练 sparse attention(取消 DeepSeek V4 的 dense 冷启动&…

阅读更多 →
Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ... 2026/11/16 6:47:19

Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ...

文章主要内容和创新点 主要内容 本文聚焦于多模态大语言模型(MLLM)强化学习(RL)训练中的效率问题,提出了一个名为Shuffle-R1的框架。研究发现,当前RL训练存在两个关键缺陷: 优势值坍缩(Advantage Collapsing):批次中大多数优势值集中在零附近,导致有效梯度信号被淹…

阅读更多 →
PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction 2026/11/14 16:35:50

PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction

一、文章主要内容总结 本文聚焦于利用大型语言模型(LLMs)实现个人身份信息(PII)脱敏的研究,旨在解决传统脱敏方法(如基于规则的系统、领域特定命名实体识别(NER)模型)泛化能力差、跨格式/跨语境适应性弱的问题。 研究通过全面评估多种LLM架构(包括密集型LLM(D-LLM…

阅读更多 →
LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model 2026/11/15 4:06:36

LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model

文章主要内容和创新点 主要内容 本文聚焦于二进制图像-文本相关性评估任务(判断图像与文本“相关”或“不相关”),针对该任务中文本格式多样、相关性定义随场景变化等挑战,提出了基于多模态大语言模型(MLLM)的解决方案LLaVA-RE。 模型设计:LLaVA-RE基于LLaVA 1.5架构,…

阅读更多 →

今日资讯

本周资讯

本月资讯

看完文章仍有疑问?

联系尧图顾问,获取一对一建站咨询

立即免费咨询 📞 400-888-8888
📞 ✉