1. 项目概述为软件交付构建缺失的“上下文层”如果你和我一样在过去一年里深度使用过 Claude Code、Cursor 或者 GitHub Copilot那你一定经历过这种时刻你新建了一个项目或者接手了一个老项目满怀期待地打开 AI 助手结果它要么给你一堆不着边际的建议要么就干脆沉默不语。你不得不花上几十分钟甚至几个小时手动在项目里创建AGENTS.md、CLAUDE.md或者.github/copilot-instructions.md试图告诉 AI 助手这个项目是干什么的、用什么技术栈、有什么代码规范。更糟心的是项目一旦开始迭代这些文件很快就过时了变成了没人维护的“僵尸文档”。这就是Project Spine要解决的核心痛点。它不是一个 AI 代码生成器而是一个“上下文编译器”。你可以把它理解为一个专门为软件项目打造的“翻译官”和“档案管理员”。它的工作流程非常直观你把项目的原始材料——比如一份客户需求简报brief.md、项目的代码仓库repo/以及可选的、来自 Figma 的设计系统规范design.md或tokens.json——交给它。Project Spine 会像编译器处理源代码一样对这些原材料进行解析、分析和整合最终输出一个机器可读、版本可控的“项目操作层”。这个操作层包含了 AI 智能体Agent能直接理解的指令、项目的架构摘要、UX 设计规则、脚手架决策、QA 质量护栏甚至是一个可以直接用于 Sprint 规划的产品待办列表。所有这一切都在一次编译中完成并且所有产出物都直接存放在你的代码仓库里与你的代码一起接受版本管理。这从根本上解决了 AI 配置文件的“碎片化”和“易漂移”问题。简单来说Project Spine 的目标是让项目的“意图”和“上下文”变得像代码一样确定、可版本化和可协作。2. 核心设计理念与架构解析2.1 为什么是“编译器”而不是“生成器”市面上已经有很多工具可以基于模板生成项目脚手架或者用 LLM 来写文档。Project Spine 的独特之处在于它的“编译器”思维。这不仅仅是语义上的区别而是贯穿其整个架构的设计哲学。一个典型的代码编译器比如 TypeScript 的tsc工作流程是输入源代码 - 解析成抽象语法树AST- 进行类型检查、转换等操作 - 输出目标代码如 JavaScript。在这个过程中AST 是一个中间表示它忠实地反映了源代码的结构和语义。Project Spine 采用了类似的思路输入解析它将非结构化的自然语言简报brief.md解析成一个结构化的 JSON 对象brief.normalized.json。同时它会扫描你的代码仓库分析出技术栈、文件结构、编码约定等生成一份仓库档案repo-profile.json。中间表示这些解析后的信息连同可选的模板规则和设计令牌会被送入一个规则编译器。这个编译器的核心任务是进行规则的合并、去重和冲突检测。例如你的简报里说“使用 React”而仓库里检测到的是 Vue编译器就会在warnings.json中标记这个冲突。最终所有经过验证和整合的规则会形成一个权威的、机器可读的spine.json文件。你可以把它看作是项目的“上下文 AST”。目标输出最后一系列导出器会读取这个spine.json根据不同的目标格式如给 Claude Code 的CLAUDE.md给 Copilot 的copilot-instructions.md给人看的architecture-summary.md等生成最终的文件。这种设计带来了几个关键优势确定性只要输入简报、代码、设计不变输出就是完全一致的。这避免了基于 LLM 生成内容时的随机性。可追溯性spine.json中的每一条规则都带有source指针比如brief.md#section0/item3或repo-profile#framework。这意味着任何一条出现在最终 Agent 指令里的规则你都能追溯到它最初来自哪里是基于客户需求、代码现状还是某个模板的推荐。可组合性你可以混合使用多个输入源。一个来自saas-marketing模板的默认规则可以被你brief.md中的具体需求所覆盖而repo-profile.json中检测到的现有库又会进一步修正实现细节。2.2 项目结构深度剖析理解 Project Spine 的代码结构有助于我们看清它是如何实现上述理念的。它的源码组织得非常清晰模块化程度很高src/ analyzer/ # 仓库分析器这是项目的“侦探”。它通过扫描 package.json、配置文件、目录结构、导入语句等推断出项目的技术栈框架、UI库、测试工具、代码风格是否使用 TypeScript、ESLint/Prettier配置、以及项目类型是应用、库还是文档站点。 brief/ # 简报解析器负责解析 Markdown 格式的客户简报。它不仅仅做简单的文本提取还能识别出结构化的章节如“目标”、“功能需求”、“非功能需求”并将其转换为带有语义标签的 JSON 数据模型。 compiler/ # 规则编译器这是整个系统的“大脑”。它接收来自分析器、简报解析器和模板的所有输入执行关键的合并、冲突解决和优先级排序逻辑最终生成权威的 spine.json 和 warnings.json。 exporters/ # 导出器一系列独立的模块每个负责生成一种特定的输出文件。例如claude-exporter.ts 专门生成 CLAUDE.mdcopilot-exporter.ts 生成 copilot-instructions.md。它们共享 spine.json 作为唯一数据源。 design/ # 设计系统解析器处理来自 Figma Variables 或 Tokens Studio 的设计令牌Design TokensJSON 文件将其转换为项目内部使用的设计规则表示。 drift/ # 漂移检测这是 Project Spine 的“守门员”。它通过对比当前仓库状态与上次编译时生成的哈希清单export-manifest.json来检测任何可能导致上下文失效的变更比如简报被修改、代码库技术栈迁移或者有人手动篡改了生成的 AGENTS.md。 templates/ # 模板系统管理内置的六个项目模板如 saas-marketing, app-dashboard。每个模板不仅仅是一份简报草稿更是一套完整的、可贡献的规则集合包括推荐的路由、组件、QA 检查项等。 skills/ # 独立目录Agent 技能包这是一套可安装到 Claude Code、Codex CLI 等 AI 助手环境中的技能脚本。它们教会 AI 助手如何与 Project Spine 交互例如如何初始化一个新项目、如何检查上下文漂移。这种架构分离了关注点使得每个模块都可以独立测试和演进。例如如果你想支持一种新的简报格式比如 YAML你只需要修改brief/目录下的解析器而不会影响编译器或导出器的逻辑。2.3 内置模板不仅仅是脚手架Project Spine 自带的六个模板是其开箱即用价值的重要体现。它们不是简单的“Hello World”项目生成器而是凝聚了特定领域最佳实践的规则包。以app-dashboard认证仪表盘模板为例当你使用它时Project Spine 不仅仅会给你一个包含登录页面的项目骨架。它会在生成的上下文中注入以下规则路由守卫自动标记哪些路由需要认证/dashboard/*哪些是公开的/login,/register。组件约定推荐使用名为PermissionGate的组件进行权限检查DataTable组件用于展示列表数据并建议一个AppShell布局组件来保持 UI 一致性。安全与合规加入关于 PII个人身份信息数据擦除的 QA 检查项提醒在日志和错误信息中避免泄露用户敏感数据。Agent 指令告诉 AI 助手在生成与用户数据相关的代码时必须考虑权限层级和数据隔离。这些规则会被无缝地整合到你项目的spine.json中。如果你的简报里指定了不同的权限模型比如基于角色的访问控制 RBAC编译器会智能地合并这些规则并在有冲突时给出警告。这相当于让一个经验丰富的架构师在项目启动之初就为你预先配置好了大量上下文和约束条件。3. 从零开始实战完整工作流演练让我们通过一个完整的例子来看看如何在实际项目中应用 Project Spine。假设我们要启动一个名为 “TaskFlow” 的 SaaS 任务管理应用。3.1 第一步初始化与简报撰写首先全局安装 Project SpineAlpha 版本npm install -g project-spinenext进入你的项目目录可以是一个空目录也可以是一个已有仓库我们使用saas-marketing模板来快速生成一份简报草稿因为它包含了营销站点常见的页面和需求。spine init --template saas-marketing --output ./brief.md这个命令会在当前目录生成一个brief.md文件。打开它你会发现它已经是一个结构清晰的 Markdown 文档包含了项目概述、目标用户、核心功能、技术偏好、非功能需求等章节的引导性问题和占位符。实操心得不要被模板限制。spine init生成的简报是一个强大的起点但你必须根据实际项目情况对其进行深度定制。花时间仔细填写每一个部分特别是“核心功能”和“非功能需求”如性能、SEO、可访问性。这份简报的质量直接决定了最终生成上下文的准确性和实用性。把它当作你和客户或产品经理以及未来 AI 协作伙伴之间的一份“契约”。接下来我们编辑brief.md填充 TaskFlow 项目的具体内容。例如在“核心功能”部分我们可能会写## 核心功能 1. **用户认证与授权** * 邮箱/密码注册与登录。 * OAuth 2.0 集成Google GitHub。 * 基于团队的权限系统所有者、管理员、成员。 2. **任务管理** * 创建、编辑、删除任务标题、描述、截止日期、优先级。 * 看板视图待处理、进行中、已完成。 * 支持任务分配、评论和附件。 3. **团队协作** * 创建和管理团队。 * 邀请成员加入团队。 * 团队内任务可见性与权限控制。在“技术偏好”部分我们可以指定## 技术偏好 * **前端框架**: React 18 (使用 Vite) * **语言**: TypeScript (严格模式) * **样式**: Tailwind CSS * **状态管理**: Zustand * **后端/API**: 本项目仅关注前端部分API 假设已由另一团队使用 Node.js (Express) 提供。 * **UI 库**: 使用 shadcn/ui 组件库作为基础。 * **代码质量**: 必须配置 ESLint (Airbnb 配置扩展) 和 Prettier。提交前使用 Husky 进行钩子检查。3.2 第二步编译上下文简报准备就绪后就可以进行第一次编译了。即使我们还没有写一行代码也可以先基于简报和模板生成初始的上下文文件。spine compile --brief ./brief.md --repo . --template saas-marketing这个命令会执行以下操作解析brief.md。分析当前目录--repo .——虽然现在几乎是空的但分析器会检测到我们可能有的任何配置文件比如如果已经初始化了package.json。加载saas-marketing模板的规则。运行规则编译器合并所有输入解决冲突生成spine.json和一系列导出文件。编译完成后查看项目根目录你会发现新生成了AGENTS.md和CLAUDE.md以及一个.project-spine/目录。这个目录是 Project Spine 的工作区里面包含了所有中间文件和生成的产物。现在让我们看看CLAUDE.md里有什么。它可能包含类似这样的指令# TaskFlow - 项目上下文 (Claude Code) ## 项目概览 这是一个名为 TaskFlow 的 SaaS 任务管理应用前端项目。核心功能包括团队任务管理、看板视图和用户协作。 ## 技术栈与约定 * **框架**: React 18 with TypeScript (strict)。 * **构建工具**: Vite。 * **样式**: Tailwind CSS。使用 apply 提取重复工具类。 * **组件库**: 以 shadcn/ui 为基础。自定义组件应放在 src/components/ui 下。 * **状态管理**: Zustand。Store 应放在 src/stores/ 目录下。 * **路由**: 使用 React Router DOM。路由定义见 src/routes/。 * **代码风格**: 遵循 Airbnb ESLint 配置。Pre-commit 钩子已通过 Husky 配置。 ## 当前重点与下一步 当前 Sprint 1 的目标是搭建核心身份验证流程和团队管理的基础 UI。优先实现以下路由和组件...这份文件已经是一个可以直接喂给 Claude Code 的、高度情境化的指令集。AI 助手现在清楚地知道要构建什么、用什么技术、以及当前的开发重点。3.3 第三步集成现有代码与设计系统假设我们的前端团队已经搭建了基础框架并且设计团队通过 Figma 提供了完整的设计令牌。我们可以将这些信息整合进来。首先确保你的代码仓库已经初始化并有了基本结构。然后从 Figma 或 Tokens Studio 导出一份设计令牌 JSON 文件例如tokens.json。再次运行编译命令这次加入设计令牌spine compile --brief ./brief.md --repo . --tokens ./tokens.json这次spine.json会额外包含来自设计令牌的规则例如颜色系统、字体缩放、间距尺度等。生成的CLAUDE.md和copilot-instructions.md中也会加入相应的 UX 规则比如## UX 与设计规则 * **颜色**: 主要品牌色是 --primary-600 (#3b82f6)。错误状态使用 --error-500 (#ef4444)。 * **字体**: 主要字体族为 Inter。标题使用 font-weight: 600。 * **间距**: 使用 4px 基准单位。组件内边距通常为 16px (4u)。 * **阴影**: 卡片使用 shadow-md模态框使用 shadow-xl。现在当你在 IDE 中让 Copilot 生成一个按钮组件时它有很大概率会直接使用正确的品牌色和间距而不是随意猜测。3.4 第四步应对变更与漂移检测项目开发过程中需求会变代码会演进。这是上下文最容易“漂移”的时候。Project Spine 的drift命令是你的安全网。当你修改了brief.md或者添加了一个新的 UI 库后运行spine drift check这个命令会对比当前仓库状态与上次编译时保存的哈希值。如果它检测到简报、代码库或设计令牌发生了实质性变更它会输出一份报告指出哪些输入源发生了变化以及哪些生成的导出文件可能已经过时。例如输出可能是⚠️ Drift detected! - Input changed: brief.md (hash mismatch) - Affected exports: AGENTS.md, CLAUDE.md, scaffold-plan.md, sprint-1-backlog.md - Suggestion: Run spine compile to regenerate context.你还可以使用spine drift diff来查看具体是简报的哪一部分被修改了。为了在 CI/CD 流水线中自动捕获问题你可以使用--fail-on参数spine drift check --fail-on any # 或者只在意简报和代码的变更不关心导出文件是否被手动编辑 spine drift check --fail-on input如果检测到漂移命令会以非零退出码结束从而使 CI 流水线失败。这确保了团队的上下文文件永远不会在不知不觉中失效。4. 核心功能模块深度解析4.1 简报解析器从自然语言到结构化数据brief.md是 Project Spine 最重要的输入之一。它的解析器设计得非常灵活支持混合使用自由文本和结构化 Frontmatter。一个高效的简报通常包含以下部分Frontmatter (YAML)用于机器可读的元数据。--- project: TaskFlow version: 0.1.0 priority: high stack: [react, typescript, tailwindcss, node] ---Markdown 章节用于人类可读的详细描述。## 目标与愿景## 用户画像## 核心功能(解析器会尝试识别编号列表中的功能点)## 技术偏好(会提取关键词如 “React”, “TypeScript”, “Tailwind”)## 非功能需求(会识别 “性能”, “SEO”, “a11y” 等)解析器会使用一系列启发式规则和正则表达式来提取信息。例如在“技术偏好”部分提到 “我们使用 React 和 TypeScript”它会被标记为{ framework: react, language: typescript }。更明确的结构化列表会被更精确地解析。注意事项简报的清晰度至关重要。避免使用模糊的语言。与其写“应用应该很快”不如写“首页的 Largest Contentful Paint (LCP) 应小于 2.5 秒”。后者能被解析器识别并转化为具体的性能规则注入到qa-guardrails.md中。4.2 仓库分析器读懂你的代码仓库分析器 (src/analyzer/) 是 Project Spine 的“眼睛”。它通过静态分析来理解项目的现状主要手段包括文件系统扫描识别package.json、tsconfig.json、vite.config.ts、dockerfile等配置文件。依赖分析读取package.json中的dependencies和devDependencies确定框架、库、工具链。代码结构推断通过查看src/目录下的文件组织方式如是否存在components/、pages/、utils/文件夹来推断项目架构和约定。源码窥探抽样读取一些源代码文件检查是否使用了特定的语法如 React 的 JSX、特定的 Hook如useState或特定的导入模式。分析器生成repo-profile.json其中包含诸如{ framework: react, packageManager: npm, hasTesting: true, conventions: { componentsDir: src/components } }这样的信息。这些信息在规则编译阶段具有很高的优先级因为它们代表了项目的现状。如果简报说“用 Vue”但仓库里全是 React 组件编译器会相信分析器的结果并在warnings.json中提示简报与现状不符。4.3 规则编译器冲突解决与优先级仲裁这是 Project Spine 最核心、也最复杂的部分 (src/compiler/)。它接收来自多个源的规则简报规则(brief.normalized.json)仓库规则(repo-profile.json)模板规则(如saas-marketing)设计规则(tokens.json)这些规则可能会冲突。编译器的仲裁策略通常是仓库现状优先检测到的代码库事实如使用的框架具有最高优先级因为它反映了实际状态。简报意图次之客户或产品明确指定的需求如“必须使用 PostgreSQL”优先级很高。模板建议作为默认值模板提供的是一般性最佳实践当没有更高优先级规则时使用。设计令牌作为具体约束颜色、字体等设计规则是具体的实现约束。编译器会生成两个关键文件spine.json包含所有最终裁决后的规则每条规则都带有source和priority元数据。warnings.json记录所有被覆盖的规则、检测到的冲突以及缺失的推荐信息例如简报要求“高测试覆盖率”但仓库中没有测试框架。4.4 导出器生成可用的工件导出器 (src/exporters/) 是“最后一公里”负责将机器可读的spine.json转换为人与 AI 都可用的文件。每个导出器都是独立的、单一职责的模块。claude-exporter.ts生成CLAUDE.md。它采用一种简洁的、指令式的风格适合 Claude Code 这种对话式 AI。它大量使用import语句来引用.project-spine/exports/下的其他详细文件如architecture-summary.md保持主文件精简。copilot-exporter.ts生成.github/copilot-instructions.md。GitHub Copilot 的指令文件需要更自包含、更示例化。这个导出器会将关键的代码风格、组件使用范例直接内联。scaffold-exporter.ts生成scaffold-plan.md。这是一个面向开发者的行动计划列出了建议创建的路由、组件及其优先级甚至包含一个sprint-1-backlog.md的链接。qa-exporter.ts生成qa-guardrails.md。这是一个可操作的检查清单包含功能、性能、安全、可访问性等方面的验收标准DoD。所有导出器都遵循一个原则即使没有 AI生成的文件也对人类开发者有直接价值。architecture-summary.md可以帮助新成员快速上手rationale.md可以用来对齐客户和团队对项目目标的理解。5. 高级用法与集成策略5.1 与 AI 智能体深度集成技能包Project Spine 的skills/目录提供了一套预制的“技能包”可以将它的能力直接嵌入到 Claude Code、Codex CLI 或 Cursor 等 AI 编码助手中。安装技能包后当你在 AI 助手的聊天框中输入诸如“我们有一个新客户项目要启动”或“我觉得我们的AGENTS.md过时了”之类的短语时AI 助手会主动触发相应的技能。例如“项目启动”技能会引导你一步步使用spine init和spine compile。“上下文漂移检查”技能会帮你运行spine drift check并解释结果。这些技能的本质是带有 YAML 前端元数据的 Markdown 文件描述了技能的触发词、所需参数和执行步骤。它们极大地降低了使用 Project Spine 的门槛使其从命令行工具变成了 AI 开发工作流中的一个自然环节。5.2 设计令牌工作流对于拥有成熟设计系统的团队Project Spine 的设计令牌集成功能非常强大。它支持两种主流格式DTCG (Design Tokens Community Group) 格式一种新兴的、工具无关的标准格式。Tokens Studio 插件格式许多 Figma 设计团队使用的流行工具。你可以通过spine compile --tokens ./tokens.json直接导入。对于 Figma Enterprise 团队甚至可以使用spine tokens pull命令在配置了 API 令牌后直接从 Figma Variables 拉取令牌。导入后设计令牌中的颜色、字体、间距、阴影等会被转换为 CSS 自定义属性或 Tailwind 配置的建议规则并加入到项目的上下文中。这确保了从设计到代码的“单一事实来源”AI 生成的代码在样式上能与设计稿高度一致。5.3 在 CI/CD 流水线中强制执行上下文同步为了确保团队协作中上下文永不漂移可以将 Project Spine 集成到你的 CI/CD 流程中。一个简单的 GitHub Actions 工作流示例name: Check Context Drift on: [push, pull_request] jobs: spine-drift-check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 20 - name: Install Project Spine run: npm install -g project-spinenext - name: Check for Context Drift run: spine drift check --fail-on any # 如果任何输入简报、代码、设计或输出文件发生漂移此步骤会失败这个工作流会在每次推送或拉取请求时运行如果检测到上下文漂移比如有人更新了需求但没重新编译上下文CI 会失败阻止合并。这强制团队养成更新上下文文件的习惯。更进一步你可以在流水线中加入自动编译步骤在brief.md被修改后自动重新生成上下文文件并提交回仓库- name: Auto-compile Context on Brief Change if: contains(github.event.head_commit.message, update brief.md) run: | spine compile --brief ./brief.md --repo . git config user.name github-actions git config user.email actionsgithub.com git add .project-spine/ AGENTS.md CLAUDE.md git commit -m chore: regenerate project context [skip ci] git push5.4 创建自定义模板虽然内置模板覆盖了常见场景但每个团队都有自己的独特约定和最佳实践。Project Spine 允许你创建和使用自定义模板。一个自定义模板本质上是一个包含以下内容的目录template.json定义模板的元数据名称、描述、标签。brief.md该类型项目的简报模板。contributes/目录包含一系列.json文件定义了该模板要贡献的规则例如routes.json推荐的路由结构。components.json推荐的组件列表及其用途。qa-rules.json特定的质量检查项。agent-rules.json针对该类型项目的 AI 指令。你可以将自定义模板放在本地目录然后通过spine compile --template /path/to/your/template来使用。对于公司内部可以将其发布到私有的 npm 仓库或 Git 子模块中实现在全公司范围内统一项目启动规范。6. 常见问题、故障排查与最佳实践6.1 编译过程常见问题问题运行spine compile时报错 “Cannot find module ‘xxx’”。排查这通常是项目本地依赖未安装导致的。仓库分析器会读取package.json如果node_modules不存在或依赖未安装它可能无法准确检测技术栈。解决在运行spine compile前先执行npm install或yarn install安装项目依赖。问题生成的CLAUDE.md文件内容过于泛泛没有结合我的项目细节。排查检查你的brief.md文件是否填写得足够具体。模糊的简报会导致模糊的输出。同时检查warnings.json文件看是否有大量“信息缺失”的警告。解决细化你的简报。使用具体的功能描述、明确的技术选型和非功能指标。参考内置模板的brief.md结构来组织你的内容。问题spine drift check总是报告我的AGENTS.md文件有漂移即使我没改过。排查很可能你或你的 AI 助手直接编辑了AGENTS.md文件。Project Spine 将这些导出文件视为“编译产物”任何手动修改都会被标记为漂移。解决不要直接编辑AGENTS.md、CLAUDE.md等导出文件。正确的做法是更新源文件brief.md、代码或tokens.json然后重新运行spine compile。如果你有特殊的、无法通过源文件表达的 AI 指令可以考虑将其作为“自定义规则”以插件形式集成或者与团队协商是否将其加入项目模板。6.2 与现有项目集成策略场景我有一个大型的、正在开发中的单体仓库如何引入 Project Spine策略采用渐进式方法。仅简报首先只为项目创建一个高层次的brief.md描述项目的整体目标、核心模块和未来方向。运行spine compile --brief ./brief.md --repo .。这能生成一个架构摘要和初步的 Agent 指令帮助新成员理解项目全景。分模块细化不要试图一次性为整个庞大代码库生成完美上下文。选择其中一个正在活跃开发的模块例如“用户通知中心”为这个模块编写更详细的子简报并针对这个模块的代码目录进行分析。逐步为各个模块建立更精细的上下文。利用inspect命令对于已有项目spine inspect --repo .命令非常有用。它只运行仓库分析器生成repo-profile.json和一份分析报告让你了解 Project Spine 是如何看待你现有代码的而无需提供简报。场景我们团队使用 Monorepo有多个应用和共享包。策略使用monorepo内置模板是一个很好的起点。但你需要为每个独立的子项目app或package分别创建brief.md并运行编译。可以在每个子项目的根目录下放置其专属的brief.md和.project-spine目录。在根目录的简报中可以描述整个 Monorepo 的治理结构、构建工具约定和共享依赖。6.3 性能与规模化考量问题我的仓库很大spine compile会不会很慢现状Project Spine 的仓库分析器目前主要进行轻量级的静态分析读取配置文件抽样少量文件。对于绝大多数项目 10万行代码编译通常在几秒到几十秒内完成。优化如果遇到性能问题可以通过.spineignore文件类似于.gitignore来排除不需要分析的大型目录如dist/,build/,node_modules/, 庞大的第三方库目录等。未来根据官方路线图更深入、更耗时的代码分析如完整的 AST 解析可能会被放在可选的“深度分析”模式中或者通过增量分析来优化。6.4 安全与隐私顾虑Project Spine 会读取我的代码并上传到云端吗设计原则Project Spine 严格遵循“默认安全”原则。所有处理都在本地进行。它不会将你的代码、简报或设计令牌发送到任何远程服务器。spine.json和所有导出文件都只保存在你的本地仓库中。唯一的网络请求可能发生在使用spine tokens pull从 Figma API 拉取令牌时但这需要你显式配置 API 密钥。顾虑生成的AGENTS.md等文件包含了项目敏感信息能提交到 Git 吗建议这需要根据项目敏感程度判断。AGENTS.md和CLAUDE.md通常包含的是技术栈、架构模式和开发规范这些信息一般可以公开。但是如果你的简报 (brief.md) 包含了客户机密信息、内部业务逻辑或未公开的产品路线图那么你需要谨慎处理。方案内容脱敏在brief.md中避免写入绝对机密信息。用功能描述代替具体的业务数据。.gitignore可以将.project-spine/目录加入.gitignore只将AGENTS.md和CLAUDE.md这类对团队协作有用的输出文件纳入版本控制。缺点是失去了上下文的版本追溯能力。私有仓库对于敏感项目确保整个代码仓库是私有的。6.5 最佳实践总结简报即合约投入时间撰写清晰、具体、无歧义的brief.md。它是所有后续工作的基石。早用常用在项目启动的第一天就使用spine init和spine compile。在每次迭代或需求变更时首先更新简报然后重新编译上下文。将漂移检查纳入 CI使用spine drift check --fail-on input在 CI 流水线中强制保持上下文同步防止团队信息不一致。自定义你的模板根据你团队的技术栈和业务领域创建自己的项目模板。这能确保所有新项目都遵循统一的高标准起点。导出文件是编译产物像对待dist/目录下的代码一样对待AGENTS.md。不要手动编辑它而是通过更新源文件并重新编译来管理变更。与设计系统联动如果可能将 Figma 设计令牌集成进来。这能建立从设计到代码的“真理之源”极大提升 UI 开发的一致性和 AI 生成代码的准确性。善用inspect命令在接手遗留项目时先用spine inspect来快速理解其技术栈和结构这比盲目阅读代码要高效得多。Project Spine 所代表的“上下文工程”理念正在成为现代软件工程特别是人机协同编程时代的一项基础设施。它解决的远不止是给 AI 写指令的问题更是如何将项目的“为什么”和“是什么”清晰、持久、可操作地固化下来让团队中的每一个人——无论是人类开发者还是 AI 智能体——都能在统一的、最新的上下文环境中高效工作。