记忆与知识沉淀

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

本页帮助你区分：哪些上下文值得沉淀成团队知识，哪些只是一次运行的 evidence，哪些不应该被长期保存。好的记忆系统不是保存更多，而是保存可验证、可复用、能回到下一次 workflow 的内容。

Memory Loop

Spec-First 的记忆不是私有聊天记录，而是下一次会话能直接读取的项目资产。

Durable Docs长期工程记忆docs/ideation、brainstorms、plans、tasks、solutions

Control Plane当前机器事实.spec-first/config、graph、impact、providers

Runtime State宿主受管状态.claude/spec-first/state.json 与 .codex/spec-first/state.json

Next Session新会话读取 repo不依赖上次聊天窗口，也不需要手动上传上下文。

→

Review / Compound经验自动回流learnings researcher 命中过往 solution，compound 写入新的复用知识。

为什么需要"记忆"

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

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

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

判断是否值得沉淀

内容	是否沉淀	推荐位置
已验证 root cause、稳定修复方式、复发预防	是	docs/solutions/**
一次 brainstorm 的 scope 决策和验收标准	是	docs/brainstorms/**
一次 plan 的文件边界、风险和验证策略	是	docs/plans/**
provider 当前 ready / degraded 状态	否，重建即可	.spec-first/config/**、.spec-first/providers/**、.codegraph/**、graphify-out/**、.graphify/**（legacy）
会话中的临时猜测或未验证观察	否，除非后续被证实	保留在当前会话或 open question 中

记忆来自哪里

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

三类记忆与三种 Git 策略

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

跨会话工作的实际机制

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

新会话开始
  │
  ▼
读取 docs/brainstorms/*-requirements.md      ← 上次的需求脉络
读取 docs/plans/*-plan.md                    ← 上次的方案选择
读取 docs/solutions/**/*.md                  ← 已沉淀的复用经验
读取 AGENTS.md / CLAUDE.md / docs/contracts  ← 项目说明和契约
读取 .spec-first/config/*                    ← 本机 runtime setup facts
  │
  ▼
基于上述事实做新一轮判断（不必从零开始）

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

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。

与 Provider Evidence 的关系

setup workflow 会写 readiness ledger、provider 配置和 runtime capabilities；完整 setup 会验证 CodeGraph / Graphify baseline，provider 输出仍只是候选证据。下游 plan/work/review workflow 可以读取这些 artifacts，并在不可用时明确降级到 bounded direct source reads。

父 workspace 的 .spec-first/workspace/ 只保存 advisory summaries，不能替代 child repo 内的 canonical .spec-first/config/、source files、测试和显式 opt-in provider evidence。详见 三种开发模式。

知识如何回流：典型场景

场景	工作流	产物
刚解决一个非平凡 bug	spec-compound	docs/solutions/<category>/bug-X-YYYY-MM-DD.md
找到一个值得复用的架构模式	spec-compound	docs/solutions/<category>/pattern-X.md
旧 solution 因代码变化过期	spec-compound-refresh	更新、合并、替换或删除条目

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

相邻概念

• 想理解资产分类与 Git 边界细节：运行模型
• 想看 compound 实操：Compound 指南