01 · INITIALIZATION
一条命令建立工程基线
spec-first init 把 workflow runtime 装进任何 repo。不接管现有工具链，不依赖外部 SaaS，不需要新账号。CLI 生成并管理 runtime assets；你只需运行命令。
AI CODING WORKFLOW · CLI
把 AI Coding
从临时对话升级为工程化工作流
规范驱动 · 计划可追踪 · 代码有证据 · 评审可治理 · 知识可沉淀
用 AI 写代码容易——但每次会话相互割裂，需求只在聊天里，方案没有记录，评审看不到决策依据，团队经验无法复用。spec-first 不是另一套 prompt 模板，而是把整个 AI Coding 过程纳入工程化闭环的工作流系统。
install
npm install -g spec-firstClaude Code
spec-first init --claudeCodex
spec-first init --codex- Repo-local
- Session-agnostic
- Claude + Codex
- No SaaS
- Traceable
- Open Source
- Node ≥20
CORE FEATURES
为团队工程文化而设计的能力，
不是另一个 prompt 收藏夹。
02 · SPEC CHAIN
从想法到代码的可追溯链路
一个特性从 brainstorm 到上线会留下：requirements.md → plan.md → tasks.md → commits → review findings → solution.md。任何 PR 都有完整的决策证据链。
03 · CODE REVIEW
最多 12 个 reviewer agent 并行
6 个 always-on personas（correctness / testing / maintainability / project-standards / agent-native / learnings-researcher）+ 按 diff 触发的 security / performance / API / migration / reliability / stack reviewer。小改动 6 个 reviewers，大改动最多 12 个——按代码变化自动缩放。
04 · KNOWLEDGE
团队经验进入下次循环
每个被解决的问题的根因、排查顺序和稳定解法，沉淀到 docs/solutions/。下次 AI coding 时 spec-learnings-researcher 会自动检索相关历史经验。
05 · DUAL HOST
21 个 workflow，Claude 与 Codex 同时支持
同一套 source skills，CLI 自动生成 Claude Code 的 /spec:* 入口和 Codex 的 $spec-* 入口。不需要手工维护副本，两个宿主始终同步。
06 · POSTURE
脚本准备事实，LLM 做判断
spec-first 不让 LLM 跑 npm install，也不让脚本替代设计决策。CLI 采集 graph facts、impact capabilities、项目规范；LLM 决定 scope、取舍和评审结论。
07 · GRAPH
老项目照样跑——Codebase 前置
spec-graph-bootstrap 在写 Spec 之前先编译代码库结构：依赖图谱、模块边界、影响范围、provider 状态，全部落到 .spec-first/graph/。AI 理解存量代码，不凭空规划。
08 · STANDARDS
候选规范 ≠ 已确认规范
spec-standards 扫描项目后，区分 confirmed / observed / suggested 三级规范。未经 review 的观察不会被固化成长期约束——防止 AI 把"偶然代码风格"误认成团队规范。
THE WORKFLOW
Spec → Plan → Code → Review → Knowledge
五个阶段，一条可审查的工程闭环
01Spec
SpecRequirements become explicit
需求不再只在聊天里
把模糊想法收敛成可审查的工程契约——actors、key flows、scope 边界与验收样例。所有 scope 决策都留在文件里，而不是当次会话的记忆中。
→docs/brainstorms/YYYY-MM-DD-NNN-topic-requirements.md
02Plan
PlanPlans become traceable
方案落到可执行的实现单元
把目标拆成实施单元（U1/U2…）、文件范围、风险点和验证方式。方案变更被记录、被审查、被交接——reviewer 能看到"为什么这样改"。
→docs/plans/YYYY-MM-DD-NNN-feat-topic-plan.md
03Code
CodeImplementation stays grounded
每个 commit 可追溯到原始需求
按计划执行，ad-hoc 的临时改动留下证据链。工作循环里不存在"从零开始"——上下文、验证标准和前置决策始终在 repo 里。
→git commits ← spec_id: YYYY-MM-DD-NNN-*
04Review
ReviewReview becomes structured
评审基于事实，而不是直觉
按代码变化自动派遣 reviewer agents（最多 12 个并行）：correctness、security、performance、learnings-researcher…。review 结论本身也是工程资产。
→P0–P3 findings · residual risks · learning signals
05Knowledge
KnowledgeKnowledge becomes reusable
团队经验进入下一次循环
解决过的问题沉淀到 docs/solutions/，自动被下一次 AI coding 检索。团队每次解决一个新问题，下次就少走一段弯路。
→docs/solutions/<category>/description-YYYY-MM-DD.md
USE CASES
团队级 AI 编码治理，
已经在这些场景里跑通。
TEAM STANDARDS
团队 AI 编码标准化
用一套可演进的 workflow 替代四散的 prompt 模板和 Cursor Rules。新成员 `spec-first init` 即获得完整的工程基线；老成员的经验通过 `docs/solutions/` 自动传递。
FEATURE DELIVERY
Spec-driven 特性交付
从 brainstorm 到 PR，全程有迹可查。每个 PR 都带着它的 requirements.md 和 plan.md 进代码库，reviewer 看到完整的"为什么"，而不只是"改了什么"。
AGENT ORCHESTRATION
AI Builder 的工程脚手架
spec-first 的 plan 是天然的编排契约，task pack 是结构化的执行输入，`docs/solutions/` 是持久记忆。在 agent 之上加工程治理层，让自动化可信、可审查、可回溯。
TEAM ONBOARDING
知识传承不依赖个人
历史 brainstorm、plan 和 solution 是最具体的工程文化教材——比 README 更有上下文，比文档站更接近真实决策现场。新成员上手即有完整的工程记忆可查。
WHY IT FEELS DIFFERENT
不是更多的 prompt 模板，
而是把工程闭环搬进 AI 编码现场。
没有 spec-first
用了 spec-first
会话结束，需求和方案就消失在聊天窗口里
每次会话留下 requirements.md / plan.md，跨会话存活，可被下一次直接引用
Prompt 模板、Cursor Rules 越加越乱，散落在飞书 / Notion / 私人收藏
一套 repo-local workflow 替代数十条规则；新加的规则进入 docs/solutions，自动被检索
LLM 也要写 init 脚本、跑构建命令，结果越来越不可预测
脚本准备事实和 runtime assets，LLM 只做 scope 决策、方案取舍和评审判断
Code review 靠直觉，看不到"方案为何这样设计"
审查基于 brainstorm → plan → code 的完整证据链，reviewer 看到决策背景
每次解决一个问题，下次还要从头走一遍
解法沉淀到 docs/solutions/，下次 AI coding 自动命中已验证的根因与稳定解法
GET STARTED
让团队 AI Coding 进入工程化轨道
spec-first 是开源的、repo-local 的、无 SaaS 依赖的。一次安装，把 21 个工程 workflow 带进任何项目。
install
npm install -g spec-firstClaude Code
spec-first init --claudeCodex
spec-first init --codex