Spec-First

Project Standards 与 Glue Baseline ​

spec-standards 是 Spec-First 的 Project Standards and Glue Compiler。它把项目事实、graph evidence、团队共享规范、已有代码约定和可复用能力编译成可审阅的项目基线，供后续 brainstorm、plan、work 和 review 使用。

它不是规则引擎，也不是通用最佳实践生成器。脚本负责准备 facts，LLM 负责判断哪些规范是 confirmed、imported、observed、suggested、conflict 或 unknown。

什么时候使用 ​

场景推荐入口
首次接入 brownfield 项目，需要建立项目形态和约定基线/spec:standards --baseline 或 $spec-standards --baseline
已有 standards artifacts，只想快速判断是否仍可用/spec:standards --quick 或 $spec-standards --quick
某个 domain、module 或 child repo 发生变化，需要局部刷新/spec:standards --refresh --domain <name> 或 $spec-standards --refresh --module <path>
大项目需要更深的 graph-backed evidence 和候选规范分析/spec:standards --deep 或 $spec-standards --deep
要把团队共享规范仓库导入当前项目上下文/spec:standards --import-source <git-or-path> 或 $spec-standards --import-source <git-or-path>

常见顺序是先运行 setup 和 graph bootstrap，再建立 standards baseline：

text
doctor → init → mcp-setup → graph-bootstrap → standards → brainstorm / plan / work / review

如果 graph facts 缺失、stale 或 degraded，spec-standards 可以降级使用直接仓库事实，但输出应明确降低的证据置信度。

执行逻辑图 ​

text
用户运行 /spec:standards 或 $spec-standards
  |
  v
读取 repo facts、graph readiness、shared standards、现有 .spec-first/standards/*
  |
  v
识别 project shape、domains、modules、可复用 glue capabilities
  |
  v
生成 standards-plan.json 和 glue-map.json
  |
  v
LLM 基于证据合成 standards-candidates.json
  |
  +-- confirmed
  |     |
  |     v
  |   可作为下游 plan / work / review 的硬约束
  |
  +-- imported / observed / suggested / unknown / conflict
        |
        v
      只能作为软上下文或待确认事项
        |
        v
      输出 standards-preview.md 给维护者确认

输出产物 ​

spec-standards 的主要输出位于 .spec-first/standards/：

产物作用
project-shape.json记录项目形态、语言、package manager、目录信号和 runtime hints
standards-plan.json描述本次 baseline 或 refresh 的 scope、domain、预算和 artifact plan
glue-map.json记录下游应复用的项目能力、入口和 glue capability
standards-update-decision.json--quick / --refresh 的 freshness 判断和刷新建议
graph-query-index.json--deep 模式下的 bounded graph query plan
standards-sources.json / import-lock.jsonshared standards source 与锁定来源
imported-standards.json导入的团队规范条目，默认不是 confirmed project policy
standards-candidates.jsonLLM 合成的候选规范，必须带状态和证据来源
standards-preview.md给维护者确认的可读 preview，说明是否建议写回 durable baseline

work/、tmp/、cache/、raw/、graph-query-raw/ 和 *.log 是 scratch/runtime evidence，不应提交。

写回边界 ​

  • 默认只生成 preview 和候选规范，不直接改 repo-profile.yaml。
  • 只有人工确认后的 confirmed standards 才能作为硬约束。
  • observed、suggested、imported 和 unknown 只能作为软上下文或待确认事项。
  • 共享团队规范导入后仍要与当前项目事实对齐，不能直接变成项目政策。
  • 下游 plan、work、review 可以读取 confirmed standards 和 glue map，但仍要针对当前任务做语义判断。

和其它入口的关系 ​

入口关系
spec-graph-bootstrap提供 graph/provider readiness facts，spec-standards 消费这些 facts
spec-brainstorm / spec-plan读取项目形态、confirmed standards 和 glue capability，减少重复探查
spec-work执行时复用已确认的项目约定和能力，不把候选规范当硬规则
spec-code-review评审 diff 时可引用 confirmed standards；未确认候选只能作为风险提示
spec-compound-refresh刷新长期知识时可参考 standards baseline 是否过期

当项目还很小、没有跨模块约定，也没有团队共享规范时，可以跳过 spec-standards，直接进入 brainstorm、plan 或 work。

阅读下一步 ​