Harness Dossier

Spec Playbook

Spec 是任务契约,不是漂亮文档

会议里对 Spec 的讨论非常务实:它不需要预测所有未来,但要覆盖足够多的安全、性能、资源、接口和业务边界,让 Agent 不靠猜来写系统。

Meta Spec85%-90% 完整度分层拆解资源感知检查点

Meta

先有 Meta Spec,再裁剪具体项目

Meta Spec 是可复用的通用规范底座。

通用维度

安全、性能、用户体验、数据边界、错误处理、测试策略、部署资源和监控口径都应先沉淀为默认规范。

项目裁剪

新项目不是从空白开始写 Spec,而是在 Meta Spec 上删减、补充和具体化。这样 Spec 周期可以从一个月压缩到数天。

合理完整度

会议建议 Spec 完整度控制在 85%-90%,为未来 3-6 个月变化留空间。追求 100% 往往会拖慢启动。

Layers

分层拆解:业务、表结构、API、组件

ToB 项目尤其需要把可复用子系统拆出来。

业务逻辑先行

先讨论产品需求和业务主流程,再确定表结构和接口。过早进入数据库设计会污染需求讨论。

子系统复用

权限管理、商户端、账户系统、资源管理等能力应被沉淀成可复用模块,而不是每个版本重做一次。

前后端契约

前端需要集中 mock 数据和接口结构,后端按数据层、算法层、业务逻辑层拆分,双方用契约而不是口头同步。

Checkpoints

检查点比口头偏好可靠

会议提到前端和后端都要设硬约束。

领域检查点作用
前端组件库优先、统一 ID 类型、长文本不撑破布局、多端一致性、关键流程截图验收。减少 AI 味和反复改坏旧逻辑。
后端数据层/算法层/业务层分离,脚手架约定目录,API 与数据结构分开封装。让不可见后端也能被逐层验收。
资源端口、CPU、GPU、外部服务、测试账号、线上线下差异写入 Markdown。防止多项目并发时互相抢资源。
质量KISS、DRY、复用公共类、自动测试、Review 后转 Skill。把治理从人工提醒变成制度。

Template

一份最小可用 Spec 应该回答什么

这是从会议观点抽象出的执行模板。

目标与非目标

这次要解决什么,不解决什么,什么情况算过度设计。

上下文入口

业务背景、现有架构、关键文件、术语表、禁止改动区。

接口与数据

输入输出、表结构、API shape、mock 数据、错误状态。

验收与测试

功能路径、回归风险、自动测试命令、人工检查点。

资源与环境

端口、服务依赖、CPU/GPU、外部凭证、部署差异。

沉淀方式

本次 Review 里哪些问题要转成 Skill、模板、脚手架或自动检查。