1. 项目概述为软件交付构建缺失的“上下文层”如果你和我一样在过去两年里深度使用过 Claude Code、Cursor 或者 GitHub Copilot那你一定经历过这种时刻你刚加入一个新项目或者接手一个遗留代码库满怀期待地打开 AI 助手输入“帮我实现一个用户注册功能”结果它要么开始胡言乱语要么生成一套与项目现有技术栈、代码风格和业务逻辑完全脱节的代码。你不得不花上大量时间手动在聊天窗口里粘贴项目结构、解释业务规则、说明编码规范——这个过程本质上是在为 AI 重建项目上下文。这就是Project Spine要解决的核心痛点。它不是一个 AI 代码生成器而是一个“上下文编译器”。它的定位非常清晰成为软件项目中连接人类意图需求、设计与机器执行AI 助手、自动化工具之间那个缺失的、可版本化、可审计的中间层。简单来说它能把一份零散的需求文档brief.md、一个代码仓库repo/和一份设计规范design.md编译成一个机器可读的、结构化的“项目操作手册”spine.json并自动生成一系列可直接使用的交付物如AGENTS.md、CLAUDE.md、copilot-instructions.md以及架构摘要、组件规划、QA 检查清单和 Sprint 待办事项。为什么这很重要根据 Atlassian 2025 年的开发者体验报告开发者每周使用 AI 工具节省的约 10 小时几乎又被同样时长的“碎片化上下文管理”所消耗。更关键的是只有不到 5% 的代码仓库包含了 AI 配置文件如AGENTS.md而且这些文件往往在创建后很快就与实际项目状态脱节变得过时且不可信。Project Spine 通过将上下文“编译”并“锁定”到仓库中并提供漂移检测drift check功能旨在终结这种混乱让 AI 助手从一开始就站在正确的起跑线上。2. 核心设计理念与架构拆解2.1 核心理念确定性优先于魔法在接触了众多标榜“智能”但实际不可靠的工具后我对 Project Spine 的第一印象是它的“反魔法”设计哲学。它明确宣称自己是“有主见的而非神奇的”。这意味着它的核心价值不依赖于不可预测的大语言模型LLM调用。整个编译过程是确定性的基于规则、模板和静态分析。为什么这是关键在软件交付中尤其是涉及客户、团队协作和严格时间线的场景可重复性和可审计性比“智能”更重要。一个基于 LLM 的“魔法”生成器可能第一次能给出惊艳的结果但第二次、第三次呢当需求微调后它还能生成一致的结果吗当出现问题时你能追溯某条规则或决定的来源吗Project Spine 的确定性设计回答了这些问题。spine.json中的每一条规则都携带一个source指针例如brief.md#section0/item3或template:saas-marketing/contributes#2。这就像代码中的 Git Blame让你能精确知道某条架构决策或组件规范是来自客户需求文档的第几段还是来自某个预设模板的第几条贡献。2.2 架构总览从输入到输出的编译流水线Project Spine 的架构是一个清晰的、管道式的编译器模型我们可以将其分解为四个主要阶段输入解析阶段Brief Parser解析brief.md。它支持 Markdown 和 YAML frontmatter能够提取项目目标、用户故事、非功能性需求性能、安全、验收标准等结构化信息。它不只是做文本提取还会进行归一化处理生成brief.normalized.json。Repo Analyzer静态分析代码仓库。它会探测技术栈如 React TypeScript Tailwind CSS、识别代码结构和约定如路由结构是文件式还是配置式、组件是原子设计还是按功能划分、分析已有的package.json、配置文件等。输出为repo-profile.json。Design Parser这是一个可选但强大的输入。它可以导入符合 DTCGDesign Tokens Community Group标准或 Tokens Studio 导出的tokens.json文件。这意味着你可以将 Figma 中的设计变量颜色、间距、字体、阴影直接转化为项目中的设计规则和约束。规则编译与合并阶段 这是核心的“大脑”。编译器接收来自上述三个来源的规则并进行合并将不同来源的规则整合到一个统一的规则集中。去重识别并合并相同的规则。冲突检测这是关键步骤。例如如果brief.md要求“移动端优先”但repo-profile.json检测到项目使用的是桌面端优化的 UI 框架或者设计令牌中定义的断点与代码中的媒体查询不匹配编译器会识别这些冲突并将其记录到warnings.json中供人类审查决策而不是武断地覆盖。生成规范模型阶段 编译器的输出是spine.json。这个文件是整个项目的“单一事实来源”。它是一个结构化的 JSON 文件包含了项目的完整操作上下文代理指令告诉 AI 助手如 Claude Code这个项目的核心约束、代码风格、架构模式。架构摘要技术栈、关键依赖、部署环境。UX/设计规则源自设计令牌的视觉规范、可访问性要求。脚手架决策应该创建哪些路由、哪些组件它们的初始实现逻辑是什么。QA 护栏代码质量、性能、安全性的检查清单和“完成的定义”。Sprint 待办事项基于需求拆解出的、可执行的开发任务。导出阶段 最后一系列导出器会根据spine.json模型生成人类和机器都可读的交付物文件。这些文件被放置在项目根目录或.project-spine/文件夹下可以直接被版本控制系统管理并被相应的工具引用。2.3 漂移检测保持上下文鲜活的“守门员”这是 Project Spine 区别于其他一次性生成工具的核心“护城河”功能。通过spine drift check命令它可以对比当前仓库状态与上一次编译时生成的export-manifest.json一个记录了所有输出文件哈希值的清单。它能检测三种漂移输入漂移brief.md、源代码或tokens.json被修改了。输出漂移有人手动编辑了生成的AGENTS.md或CLAUDE.md这可能是必要的知识更新。文件缺失生成的某个文件被意外删除。实操价值你可以将此命令集成到 CI/CD 流水线中通过--fail-on any参数确保任何可能破坏上下文一致性的更改都会被及时发现并触发警报或阻断流程。这强制团队将项目上下文的维护视为一项持续性的、与代码变更同等重要的工程实践。3. 从零开始完整实操指南3.1 环境准备与安装Project Spine 是一个 Node.js CLI 工具要求 Node.js 版本 ≥ 20。安装非常简单。# 推荐从 npm 安装最新的 alpha 版本功能最全 npm install -g project-spinenext # 安装后验证 spine --version如果你希望贡献代码或体验最前沿的功能也可以从源码构建git clone https://github.com/PetriLahdelma/project-spine.git cd project-spine npm install npm run build # 此时可以使用本地构建的 CLI node dist/cli.js --help3.2 第一步初始化项目简报对于一个新项目最难的往往是开始。Project Spine 提供了init命令和预设模板来帮你快速搭建项目简报的骨架。# 查看所有可用模板 spine template list # 查看某个模板的详细信息例如 SaaS 营销网站 spine template show saas-marketing # 使用模板初始化一个简报文件 spine init --template saas-marketing执行init后你会在当前目录得到一个brief.md文件。这个文件不是空壳它已经根据你选择的模板预填充了结构化的章节和提示性问题。例如saas-marketing模板会预设关于核心转化目标、SEO 策略、性能预算如 Largest Contentful Paint 2.5s等问题。你的任务就是像一个产品经理或技术负责人一样填充这些问题的答案。注意事项不要被模板限制。brief.md是一个 Markdown 文件你可以任意增删改。编译器的解析器足够智能能从非结构化的文本中提取关键信息。但遵循模板的结构能让你获得更精确、冲突更少的编译结果。3.3 第二步编译上下文当你有了brief.md和一个初步的代码仓库甚至可以是一个空文件夹或只有package.json的仓库就可以进行首次编译了。这是最核心的一步。# 最基本编译仅使用简报和当前仓库 spine compile --brief ./brief.md --repo . # 更完整的编译加入模板和设计令牌 spine compile --brief ./brief.md --repo . --template saas-marketing --tokens ./tokens/global.json命令参数详解--brief指定简报文件路径。--repo指定要分析的代码仓库根目录。--template可选指定一个模板。它会为编译过程贡献额外的规则比如特定项目类型应有的路由、组件和 QA 项。--tokens可选指定设计令牌 JSON 文件路径。这是连接设计与开发的桥梁。编译完成后你会得到什么执行成功后你的项目目录下会新增一个.project-spine/文件夹和几个根目录文件。关键产出包括.project-spine/spine.json核心的机器可读上下文模型。建议将其加入.gitignore因为它可以从其他文件重新生成。.project-spine/export-manifest.json用于漂移检测的哈希清单。必须加入版本控制。AGENTS.md/CLAUDE.md/.github/copilot-instructions.md分别针对不同 AI 助手的指令文件。它们内容同源但格式适配。.project-spine/exports/目录下的一系列 Markdown 文件如scaffold-plan.md脚手架计划、qa-guardrails.md质量检查清单、sprint-1-backlog.md第一个冲刺待办列表等。这些是给人类看的、可直接用于指导工作的文档。3.4 第三步集成 AI 助手技能Project Spine 不仅生成静态文件还贴心地为流行的 AI 编码助手Claude Code、Codex CLI、Cursor准备了“技能包”。这些技能本质上是教导你的 AI 助手如何与 Project Spine 协作的指令集。# 进入项目目录 cd /path/to/project-spine # 安装技能到 Claude Code ./skills/install.sh # 同时安装到 Codex CLI ./skills/install.sh --codex # 干跑模式预览将要安装的技能而不实际操作 ./skills/install.sh --dry-run安装后当你在 AI 助手的聊天框中输入类似“我们有一个新客户项目”或“我觉得AGENTS.md过时了”这样的短语时对应的技能就会被触发。助手会引导你使用spine init、spine compile或spine drift check等命令来建立或更新项目上下文。这形成了一个非常流畅的闭环用自然语言启动项目用工具生成结构化上下文再用这个上下文赋能 AI 助手进行高质量输出。3.5 第四步日常维护与漂移检查项目是动态发展的。需求会变代码会增删设计会调整。你需要确保spine.json及其衍生物与项目现状同步。# 检查是否有任何漂移用于本地开发提醒 spine drift check # 在 CI 流水线中使用如果发现任何漂移则使构建失败 spine drift check --fail-on any # 如果发现漂移查看具体差异 spine drift diff # 更新上下文以反映最新状态重新编译 spine compile --brief ./brief.md --repo . --template saas-marketing最佳实践建议将spine drift check --fail-on any作为 CI 流水线中的一个必要检查步骤。这能像代码 lint 检查一样强制团队在修改需求或设计后主动更新项目上下文防止 AI 助手基于过时的信息做出错误决策。4. 深度解析模板系统与设计令牌集成4.1 模板不仅仅是文件脚手架Project Spine 内置的六个模板SaaS 营销网站、应用仪表盘、设计系统、文档门户、API 服务、Monorepo是其“有主见”的集中体现。每个模板都是一个完整的、针对特定项目类型的“领域知识包”。以app-dashboard应用仪表盘模板为例它不仅仅帮你生成一个关于仪表盘的brief.md草稿。当你使用--template app-dashboard进行编译时它会向最终的spine.json注入一系列高度相关的规则规则类别具体贡献实际价值路由规则自动包含如/dashboard、/dashboard/analytics、/settings等标准路由。并标记哪些路由需要身份验证requiresAuth: true哪些需要特定角色权限allowedRoles: [“admin”]。AI 助手在生成路由相关代码时会天然考虑权限控制避免生成不安全的公开路由。组件蓝图预定义PermissionGate、DataTable、AppShell、SidebarNav等仪表盘典型组件的接口规范和预期行为。指导 AI 生成符合项目架构的、可复用的组件而不是一次性的、风格迥异的代码。QA 护栏加入针对个人身份信息PII数据处理的检查项例如“所有用户数据列表接口必须默认脱敏”、“日志中不得记录完整信用卡号”。将安全合规要求转化为具体的、可检查的开发任务降低审计风险。UX/非功能性需求设定仪表盘类应用的性能指标如“主要数据表首次渲染应 1s”、“过滤操作响应应 200ms”。为性能优化提供明确、可衡量的目标。选择与定制启动时选对模板至关重要。但模板并非枷锁。所有模板贡献的规则在spine.json中都被标记为kind: “template”。你完全可以在后续的brief.md中覆盖或细化这些规则。编译器会处理这些冲突并在warnings.json中给出提示。4.2 设计令牌连接设计与开发的自动化管道对于现代前端项目设计系统与代码的脱节是一个老大难问题。设计师在 Figma 中更新了主色开发需要手动同步到tailwind.config.js和各个 CSS 变量文件中极易出错。Project Spine 的--tokens参数旨在解决这个问题。它支持两种主流的设计令牌格式DTCG 标准格式这是 W3C 社区小组制定的跨工具标准。Tokens Studio 插件格式这是 Figma 中非常流行的设计令牌管理插件。操作流程设计师在 Figma 中使用 Tokens Studio 插件定义和维护颜色、间距、字体、阴影等设计令牌。通过插件导出tokens.json文件。开发者运行spine compile --tokens ./tokens.json。Project Spine 会解析这个 JSON 文件并将其转换为代码中的约束规则例如“品牌主色是#0066ff错误色是#dc2626”。spine.json中的设计规则明确哪些颜色可以用于背景哪些用于文本间距的阶梯 scale 是什么。潜在的qa-guardrails.md检查项如“禁止使用硬编码颜色值必须使用设计令牌变量”。更高级的用法对于 Figma Enterprise 用户Project Spine 甚至计划提供spine tokens pull命令直接从 Figma VariablesFigma 的原生变量功能拉取令牌实现真正的单向同步管道确保设计即真理。5. 实战场景与经验心得5.1 场景一快速启动一个绿色字段项目假设你要为一个创业公司快速搭建一个产品官网SaaS 营销站。初始化spine init --template saas-marketing。这会生成一个结构化的brief.md引导你思考核心价值主张、目标用户、关键页面和转化点。填充简报花 30 分钟与创始人或产品经理一起填写brief.md。明确写出“首要目标是获取试用注册”、“需要集成博客系统”、“首页需满足 Core Web Vitals 所有绿标”等具体需求。创建代码库mkdir new-saas-site cd new-saas-site git init。然后快速用你喜欢的脚手架如create-next-app初始化一个基础项目。编译上下文spine compile --brief ../brief.md --repo . --template saas-marketing。此时你还没有任何设计令牌所以先省略--tokens。即刻获得指导打开生成的scaffold-plan.md你会看到一个清晰的路由清单如/,/pricing,/blog,/contact和对应的组件建议。打开sprint-1-backlog.md你已经有了一个带着初步验收标准的待办事项列表可以直接导入到 Jira 或 Linear。而AGENTS.md则已经准备好可以让你打开 Claude Code直接说“基于我们的项目上下文开始实现首页英雄区块”。心得这个流程将通常需要数小时甚至一天的项目启动、需求对齐和文档编写工作压缩到了一个小时以内并且产出的不是孤立的文档而是一个活的、可执行的上下文系统。5.2 场景二为遗留项目注入 AI 协作能力你加入了一个已有半年历史的 React 项目代码量不小但没有任何 AI 辅助配置。团队对使用 Copilot 持怀疑态度因为它经常“胡编乱造”。项目分析spine inspect --repo .。这个命令不需要brief.md它会单纯分析现有代码库生成一个repo-profile.json和一份初步的架构报告。你可以先看看它对你的技术栈、代码结构的理解是否准确。逆向工程简报基于spine inspect的输出和你对业务的理解反向编写一个brief.md。描述这个项目是做什么的核心业务逻辑是什么现有的架构约定即使不成文有哪些。编译与试运行spine compile --brief ./brief.md --repo .。由于没有使用模板编译器将完全基于你的简报和代码仓库来生成规则。重点审查warnings.json看编译器是否发现了代码与简报描述冲突的地方。渐进式采纳不要一次性要求团队全部采用。可以先将生成的CLAUDE.md放在仓库根目录并告诉团队成员“我们在尝试用这个文件来约束 Claude Code让它更懂我们的项目。大家试用一下看看它生成的代码是否更靠谱了。” 通过实际效果来获得支持。引入漂移检查在团队初步认可后将spine drift check加入 CI。当有人修改了核心业务逻辑但忘了更新brief.md时CI 会失败并提示这能逐渐培养团队维护上下文的习惯。心得对于遗留项目Project Spine 的价值在于“发现”和“显式化”那些隐藏的、口口相传的项目知识并将其转化为机器可读的规范。这不仅能提升 AI 助手的效率本身也是一次宝贵的项目知识梳理和沉淀。5.3 场景三在设计系统团队中作为唯一事实来源你负责维护一个公司的 React 组件库设计系统。设计和开发之间的同步一直是痛点。建立设计令牌流与设计师约定所有设计变量必须通过 Figma Tokens Studio 插件管理并定期导出tokens.json到代码仓库的指定位置。创建设计系统专属上下文spine init --template design-system创建一个针对组件库的简报强调文档完整性、版本兼容性、测试覆盖率等。编译与同步spine compile --brief ./brief.md --repo . --tokens ./tokens.json --template design-system。利用输出component-plan.md会帮你规划原子组件Button、Input和复合组件Modal、Dropdown的依赖关系。qa-guardrails.md会包含针对设计系统的特殊检查项如“所有组件必须提供 Storybook story”、“所有导出的 Token 必须有 JSDoc 注释”。设计令牌会被转化为具体的规则如“color.brand.primary应用于所有主要操作按钮”。自动化在 CI 中设置每当tokens.json文件更新由设计师提交或通过自动化脚本拉取就自动运行spine compile并提交更新的上下文文件。确保任何设计变更都能立即反映在开发约束中。心得在这里Project Spine 扮演了设计系统“守门员”和“同步中枢”的角色。它确保了设计意图不折不扣地传递到代码层面并且通过机器可读的规则让 AI 助手在生成使用设计系统的业务代码时也能严格遵守设计规范。6. 常见问题与故障排查在实际使用和与社区交流中我总结了一些常见问题和解决方法。6.1 编译过程报错或警告问题现象可能原因解决方案运行spine compile时报“Cannot find module”或语法错误。Node.js 版本过低或项目依赖损坏。确保 Node.js ≥ 20。尝试在 Project Spine 项目根目录运行npm install和npm run build重新构建。warnings.json中出现大量“Conflict detected”。简报 (brief.md)、模板 (--template) 或仓库分析结果之间存在规则冲突。这是正常现象说明编译器发现了需要你决策的矛盾点。逐一查看冲突详情修改brief.md以明确你的选择。例如如果模板建议用 RESTful API但你的简报写了“使用 GraphQL”你需要明确采用哪一个。生成的AGENTS.md文件内容看起来过于泛泛或不符合项目情况。brief.md内容过于简略或仓库 (--repo) 路径指向错误如空文件夹。丰富你的brief.md提供更多具体的业务逻辑、技术约束和用户故事细节。确保--repo指向一个真实的、有代码的项目目录这样 Repo Analyzer 才能提取出有价值的技术上下文。--tokens参数指定的 JSON 文件无法被解析。设计令牌文件格式不符合 DTCG 或 Tokens Studio 的预期结构。使用 Tokens Studio 插件导出的文件通常最可靠。也可以参考 Project Spine 文档中的示例格式手动调整你的 JSON 文件结构。6.2 与 AI 助手集成不生效问题现象可能原因解决方案安装了技能但在 Claude Code 中提及“新项目”时没有触发。技能安装路径不正确或 Claude Code 未正确加载技能。运行./skills/install.sh --dry-run查看技能将被安装到的确切路径。确认 Claude Code 的技能目录配置指向该路径。有时需要重启 Claude Code 应用。AI 助手读取了CLAUDE.md但生成的代码仍然不符合项目规范。CLAUDE.md中的指令可能不够具体或 AI 助手的上下文窗口未包含全部关键信息。检查生成的CLAUDE.md文件。你可能需要手动编辑它加入更具体的、针对你项目的“禁忌”例如“本项目绝对不使用any类型”“所有 API 调用必须使用useSWR钩子”。确保CLAUDE.md位于项目根目录并且被 AI 助手正确索引。Cursor 似乎没有使用AGENTS.md。Cursor 对项目级配置文件的加载机制可能与 Claude Code 不同。查阅 Cursor 的官方文档了解其项目上下文配置的最佳实践。有时需要将AGENTS.md中的关键信息复制到 Cursor 特定的配置文件如.cursor/rules中。Project Spine 生成的AGENTS.md是一个很好的起点但可能需要根据具体工具做适配。6.3 性能与规模化问题问题现象可能原因解决方案在一个非常大的 Monorepo 上运行spine compile速度很慢。Repo Analyzer 在递归扫描大量文件特别是node_modules。确保你的--repo路径指向的是需要分析的应用或包目录而不是整个庞大的 Monorepo 根目录。未来版本可能会提供--ignore模式来排除目录。spine drift check在 CI 中偶尔误报。可能是生成文件中包含时间戳或非确定性内容尽管 Project Spine 极力避免。检查export-manifest.json的完整性。确保在 CI 环境中编译和检查步骤使用相同版本的 Project Spine 和 Node.js。如果问题持续可以考虑在spine drift check之前先运行一次spine export来确保导出文件是最新的。团队多人协作时spine.json和生成的 Markdown 文件频繁产生合并冲突。多人同时修改brief.md并编译导致生成的衍生文件冲突。黄金法则只将brief.md和export-manifest.json纳入版本控制。将.project-spine/spine.json和所有生成的 Markdown 文件AGENTS.md,CLAUDE.md等加入.gitignore。在 CI 流水线或预提交钩子中设置一个步骤来自动运行spine compile和spine export保证每个人本地和部署环境得到的衍生文件都是一致且最新的。6.4 高级技巧与自定义创建自定义模板内置模板不满足需求你可以创建自己的模板。研究templates/目录下的结构本质上它是一个包含manifest.json和若干贡献规则文件的文件夹。你可以复制一个现有模板并修改然后通过spine template add /path/to/your-template来注册它。只生成部分文件如果你只想更新AGENTS.md和CLAUDE.md而不想触发完整的编译可能很耗时可以使用spine export --targets agents,claude。这个命令会基于现有的spine.json重新生成指定的导出文件非常高效。解释规则来源对spine.json中的某条规则有疑问使用spine explain rule-id命令它可以告诉你这条规则是从简报的哪一行、仓库的哪个文件或者哪个模板的哪条贡献中来的。将 Spine 集成到现有工作流不要把它当成一个独立的工具。考虑将它集成到你的需求管理如 Jira Issue 转brief.md、设计交接Figma Webhook 触发spine tokens pull和代码审查PR 中自动运行spine drift check流程中使其成为交付流水线中无声但关键的一环。Project Spine 目前仍处于 alpha 阶段这意味着它正在快速进化API 和功能可能发生变化。但它的核心思想——将模糊的项目意图编译成确定性的、可版本化的、机器友好的上下文——已经非常清晰和有力。它不是在替代思考而是在放大思考的价值不是在自动化创意而是在为创意提供坚实、一致的实施基础。对于任何严肃对待软件交付质量和团队效能的开发者或团队来说它都值得深入尝试和关注。