三层工程模型

Spec-First 的产品定位建立在一个清晰的分层视角上：AI 软件工程不只是写更好的 prompt，也不仅是给模型更多 context。当把 AI 引入真实的研发协作和长期项目时，最难的部分发生在第三层——整个系统如何被组织、约束和反馈。

三层概览

层级	关注问题	典型工具/做法
Prompt Engineering	如何发出更清晰的指令？	提示词模板、role play、CoT、few-shot 示例
Context Engineering	模型能看到什么信息？信息如何组织？	RAG、长上下文、文件嵌入、tool descriptions、memory
Harness Engineering	整个系统如何运行？约束、反馈回路、工作流控制和持续改进	Workflow 治理、产物契约、entry surfaces、agent 编排、长期知识沉淀

每一层都不可替代。但只在前两层做工作，AI Coding 的产出仍会因为以下原因不稳定：

上一次会话的需求和方案在新会话里消失
Prompt 模板和 Cursor Rules 越加越多，散落在飞书 / Notion / 私人收藏
评审看到 diff，但看不到 "为什么这样改"
团队解决过的同一类问题，下次还要从头走一遍

Spec-First 在哪一层

Spec-First 把自己定位在 Harness Engineering 层：

它不替代 Claude Code 或 Codex —— 这两个宿主仍然提供 Prompt 与 Context 层的体验
它不替代 RAG 或 MCP —— 这些是 Context Engineering 的工具
它提供一套 repo-local 的 runtime，把工程治理（需求、计划、任务、评审、学习）变成可被 LLM 与人协作的工程资产

text

你的项目 / IDE
   │
   ├── Prompt Engineering ──── 由 Claude Code / Codex 提供
   │
   ├── Context Engineering ─── 由 MCP servers / RAG / 文件附件提供
   │
   └── Harness Engineering ─── 由 spec-first 提供
        │
        ├── 入口治理（哪个 workflow？什么时候用？）
        ├── 产物契约（requirements / plan / tasks / solutions）
        ├── 边界控制（脚本 vs LLM、source vs runtime、单仓 vs 多仓）
        └── 反馈回路（review、debug、compound、skill-audit）

为什么是这一层最难

Prompt 和 Context 主要影响单次对话的质量。Harness 影响项目长期演进的质量：

上下文是否能跨会话存活（不是只活在当次聊天）
需求和方案是否能被审查（不是只在脑子里）
AI 工程经验是否能被复用（不是每次重新发明）
团队规范是否能被治理（不是 prompt 模板四散）

这些问题用 prompt 技巧或更长 context window 都解决不了。它们需要一个项目内的工作流系统——这就是 spec-first 的工作。

设计原则

1. 脚本准备事实，LLM 做判断

spec-first CLI 负责确定性部分：安装、检查、生成、校验、清理。LLM 负责语义部分：scope 取舍、方案设计、实现细节、评审结论。两者职责清楚，互不越界。

应当由 CLI 做	应当由 LLM 做
检查 Node 版本、宿主可用性	决定这个需求要不要做
安装/初始化/清理 runtime assets	设计实现方案
编译 graph readiness facts	判断方案是否合理
校验 task pack hash 与结构	拆分实施单元
写入 `.spec-first/` control-plane	评审找问题、给建议

2. 一份源码，两个宿主

同一份 source skills + agents + templates，CLI 在 init 时按宿主治理过滤生成 host-specific runtime：

Claude Code 得到 /spec:* commands + .claude/skills/ + .claude/agents/
Codex 得到 $spec-* skills + .agents/skills/ + .codex/agents/

无需手工维护两套副本，runtime 漂移由 spec-first update 治理。

3. 长期协作文档 vs 临时运行时事实

类型	位置	Git 边界
长期协作文档	`docs/brainstorms/`、`docs/plans/`、`docs/tasks/`、`docs/solutions/`	通常提交，团队复用
运行时事实	`.spec-first/config/`、`.spec-first/graph/`、`.spec-first/impact/`	通常不提交，本机重建
生成 runtime	`.claude/`、`.codex/`、`.agents/skills/`	不提交（init 自动维护 `.gitignore` managed block）

阅读顺序

想看 spec-first 怎么落地：安装指南 → 首次工作流走查
想理解运行模型：运行模型
想看完整端到端：完整示例
想了解工程闭环：工作流总览

三层工程模型 ​

三层概览 ​

Spec-First 在哪一层 ​

为什么是这一层最难 ​

设计原则 ​

1. 脚本准备事实，LLM 做判断 ​

2. 一份源码，两个宿主 ​

3. 长期协作文档 vs 临时运行时事实 ​

阅读顺序 ​