记忆与知识沉淀

Spec-First 当前的重点不是维护某个固定的"四层记忆目录"，而是让项目级 runtime 能把需求、计划、实现、评审和经验沉淀在可追溯的文件与 workflow 里。

为什么需要"记忆"

AI Coding 失败的常见原因不在 prompt 或 model 能力，而在上下文跨会话蒸发：

• 新会话不知道上次的需求是什么
• 评审者看到 diff，但看不到 "为什么这样改"
• 团队解决过的问题，下次 AI 还要从零重新调查
• 个人形成的经验，只活在某个人的记忆里

Spec-First 的解法不是更长 context window 或更聪明的 RAG，而是把关键决策与经验落地为项目内的工程文件，让下一次会话天然可读。

记忆来自哪里

来源	写入 workflow	作用
候选想法	/spec:ideate / $spec-ideate	记录候选方向、批判、排序、被拒原因
需求 brief	/spec:brainstorm / $spec-brainstorm	记录 actors、flows、scope 边界、验收标准
实施计划	/spec:plan / $spec-plan	记录实施单元、文件范围、风险、验证方式
Task pack	standalone spec-write-tasks	派生执行任务、依赖、waves、停止条件
Code 改动	/spec:work / $spec-work 等	记录 commit、测试结果、验证证据
评审结论	/spec:code-review / /spec:doc-review	结构化 findings、residual risks、learning signals
复用经验	/spec:compound / $spec-compound	写入 docs/solutions/ 长期知识
Runtime state	init / update 等	记录 host-specific managed state、developer profile
Control-plane facts	mcp-setup / graph-bootstrap 等	当前机器的 readiness 事实，可重建

三类记忆与三种 Git 策略

类型	路径	是否提交	生命周期
Durable 工程文档	docs/ideation/ docs/brainstorms/ docs/plans/ docs/tasks/ docs/solutions/	通常提交	跨会话、跨成员、跨版本
Control-plane facts	.spec-first/config/ .spec-first/graph/ .spec-first/impact/ .spec-first/providers/	不提交，本机重建	当前机器、当前 ready 状态
Generated runtime	.claude/ .codex/ .agents/skills/	不提交（init 自动 .gitignore）	当前 spec-first 版本下的副本

.spec-first/standards/ 是混合的：confirmed baseline 可提交，scratch/raw/cache 不提交。

跨会话工作的实际机制

新会话进入项目后，仓库内已经存在的文件就是它的"记忆"：

新会话开始
  │
  ▼
读取 docs/brainstorms/*-requirements.md      ← 上次的需求脉络
读取 docs/plans/*-plan.md                    ← 上次的方案选择
读取 docs/solutions/**/*.md                  ← 已沉淀的复用经验
读取 .spec-first/standards/                  ← 项目规范基线
读取 .spec-first/graph/*                     ← 本机 graph readiness
  │
  ▼
基于上述事实做新一轮判断（不必从零开始）

无需"上传上下文"或"导入会话"，文件就是上下文。

Compound 与 learnings-researcher 的协同

/spec:compound 写入 docs/solutions/ 后，下一次 AI Coding 不必显式查找。spec-code-review 等评审 workflow 会自动调度 spec-learnings-researcher agent，按当前 PR 的语义去检索相关 solution，作为评审证据带入：

新 PR 进入 code-review
  │
  ▼
spec-learnings-researcher
  │  检索 docs/solutions/ 里的根因、模式、过往坑
  ▼
把命中知识作为 reviewer 的证据输入
  │
  ▼
PR review 自动复用过往团队经验

这意味着团队解决过的同一类问题，下次新成员（或新会话）写出有同类风险的代码时，会自动收到相关警告——不用任何人记得去查文档。

Runtime state 边界

Claude Code 与 Codex 的 runtime state 分别由宿主管理：

• Claude：.claude/spec-first/state.json、.claude/spec-first/.developer
• Codex：.codex/spec-first/state.json、.codex/spec-first/.developer

这些文件服务于已安装 runtime（command/skill/agent/agent-support-files manifest 状态、developer profile），不应被当作手写业务文档，也不应该手改。runtime drift 的修复方式是 spec-first init，不是手改 state.json。

与 Graph Readiness 的关系

setup workflow 会写 readiness ledger、provider 配置和 runtime capabilities；graph bootstrap workflow 会消费这些事实并写 canonical graph、provider status 和 impact capabilities。下游 plan/work/review workflow 可以读取这些 artifacts，并在不可用时明确降级。

父 workspace 的 .spec-first/workspace/ 只保存 advisory summaries，不能替代 child repo 内的 canonical .spec-first/config/、.spec-first/graph/、.spec-first/impact/ 或 .spec-first/providers/。详见 三种开发模式。

知识如何回流：典型场景

场景	工作流	产物
刚解决一个非平凡 bug	/spec:compound	docs/solutions/<category>/bug-X-YYYY-MM-DD.md
找到一个值得复用的架构模式	/spec:compound	docs/solutions/<category>/pattern-X.md
旧 solution 因代码变化过期	/spec:compound-refresh	更新、合并、替换或删除条目
接手别人或自己的旧任务	/spec:sessions	检索历史会话、给出尝试过的路线
想了解 spec-first 自身近期 release	/spec:release-notes	版本依据摘要

沉淀内容应来自真实任务、真实 diff、真实测试和真实决策；不要为了填充目录而编造知识——spec-compound-refresh 会按证据淘汰编造内容。

相邻概念

• 想理解资产分类与 Git 边界细节：运行模型
• 想看 compound 实操：Compound 指南
• 想看跨会话调用历史：Sessions 指南