Meteor 仓库 AI 协作上下文体系：CLAUDE.md 与 Skills 机制深度解读

• 后端
• 前端
• 开发工具
• 移动开发

导读

Meteor（JavaScript 全栈应用平台）在其仓库根目录维护了一套面向 AI 编码助手（Claude Code 等）的结构化上下文文档体系，核心入口即 CLAUDE.md。本文以该文件为骨架，结合 AGENTS.md 与.github/skills/目录下的全部 10 个技能文档，剖析这套"根上下文 + 按需加载技能（Skill）"的 AI 文档分层架构：读者将掌握 Meteor 仓库如何通过技能表引导 Agent 定位构建系统、包开发、测试、Changelog 生成等任务，以及如何通过符号链接在本地安装全部技能。

CLAUDE.md 在 Meteor 仓库中的定位

CLAUDE.md 全文仅两个部分，却是整个 AI 上下文体系的"桥头堡"：它以一行指令强制 Agent 在开始任何任务前先读取根上下文 AGENTS.md，随后提供两张关键表格——技能索引表与 Claude Code 安装指引。

这一设计的背景记录在 ai-context 技能文档 中：Claude Code 并不原生加载AGENTS.md，因此需要CLAUDE.md作为桥接文件，把 Claude Code 接入与其它 Agent 相同的上下文系统。整个文件层级为：

AGENTS.md # 根上下文，每次交互都加载 CLAUDE.md # Claude Code 专属入口（加载 AGENTS.md） .github/skills/<topic>/SKILL.md # 按需加载的详细上下文 packages/<name>/AGENTS.md # 包级上下文 <any-folder>/AGENTS.md # 目录级上下文

根上下文 AGENTS.md：Agent 的"最小上下文预算"

AGENTS.md 遵循"根文件保持精简以节省 token"的原则，仅保留四类信息：

• 项目一句话描述：Full-stack JavaScript platform for modern web and mobile applications；
• 核心命令清单（从源码运行、创建应用、自测、包测试、单元/E2E/原生测试）；
• 顶层目录结构（packages/、tools/、npm-packages/、scripts/）；
• 关键入口表与技能索引表。

其中关键入口表值得重点记忆：

AGENTS.md 还提供了 Meteor 领域包的快速导航（认证、数据库、构建、Web、响应式五类），以及一条重要约定：docs/与guide/是公开文档站点而非 Agent 上下文，v3-docs/才是 Meteor 3.x 文档所在。

Skills 技能表：10 个按需加载的上下文模块

CLAUDE.md 与 AGENTS.md 共用同一张技能索引表，每个技能对应.github/skills/<topic>/SKILL.md，按任务触发条件加载：

下文逐一解读各技能的核心技术内容。

codebase：Isobuild 构建管线与目录导航

该技能勾勒了 Meteor 的完整构建链路：CLI（tools/cli/main.js）解析命令 → 项目上下文解析依赖 → Isobuild（tools/isobuild/）中的 bundler/compiler/linker 分别负责编排、编译与模块包装 → 产出star.json与程序 → runners（run-app/run-mongo/run-hmr）驱动运行 → DDP Server ↔ Minimongo ↔ UI 构成实时应用。

它还给出了四个构建目标（web.browser、web.browser.legacy、web.cordova、server）、meteor create --<template>支持的模板清单（react、vue、svelte、angular、blaze、typescript、tailwind、solid、apollo 等），以及排障要点（包找不到时检查package.js名称并meteor reset；构建插件不生效时检查archMatching与文件扩展名）。

conventions：包清单与代码模式规范

该技能定义了 Meteor 包的目录规范（package.js+ 实现文件 +*-tests.js）与package.js的完整结构：Package.describe、Package.onUse（含api.versionsFrom、api.use、api.mainModule、api.export）、Package.onTest、Npm.depends。同时提供四个高频模式：

• CLI 命令注册：在tools/cli/commands.js中通过main.registerCommand({ name, options, catalogRefresh })注册；
• WebApp 中间件：区分WebApp.rawConnectHandlers（认证前）与WebApp.connectHandlers（认证后，req.userId可用）；
• 构建插件：Package.registerBuildPlugin+Plugin.registerCompiler+ 继承CachingCompiler实现getCacheKey/compileOneFile；
• tools-core 集成：logProgress、checkNpmDependencyExists、getMeteorAppConfig、spawnProcess等工具函数。

testing：从 TinyTest 到 Playwright 的四层测试栈

该技能完整收录了 Meteor 的测试命令矩阵：

# CLI 自测 ./meteor self-test # 全部 CLI 测试 ./meteor self-test "test name" --retries 0 # 指定测试、开发时跳过重试 # 包测试（TinyTest，浏览器 UI 在 localhost:3000） ./meteor test-packages mongo TINYTEST_FILTER="collection" ./meteor test-packages # 无头终端输出（Puppeteer） ./packages/test-in-console/run.sh "mongo" # E2E（Jest + Playwright） npm run test:e2e -- -t="React" # 原生移动端冒烟（Maestro） npm run test:native:android

测试助手包 packages/test-helpers 提供waitUntil/simplePoll（异步等待）、clickElement/simulateEvent/canonicalizeHtml（DOM/UI）、makeTestConnection/captureConnectionMessages（连接捕获）与SeededRandom、try_all_permutations等工具；tinytest 则提供Tinytest.add/Tinytest.addAsync同步与异步用例 API。E2E 测试位于 tools/e2e-tests/，覆盖 react/vue/svelte/solid/blaze/typescript/babel/coffeescript/monorepo 等应用骨架。

packages：按领域索引的核心包地图

该技能按领域列出 Meteor 包生态：认证与账号（accounts-base、accounts-password、accounts-2fa、accounts-passwordless及多个社交登录包）、数据层（mongo、minimongo、ddp-server、ddp-client、ejson）、构建编译（babel-compiler、typescript、modules、rspack）、测试（tinytest、test-helpers、test-in-console）、以及需要生产环境移除的autopublish/insecure开发包。

modern-tools：tools-core 工具函数与 Rspack 集成

这是内容最丰富的技能之一，覆盖 packages/tools-core 的六大模块：

• 日志（lib/log.js）：logProgress/logSuccess/logError/logInfo，尊重METEOR_DISABLE_COLORS；
• npm 管理（lib/npm.js）：getNodeBinaryPath、checkNpmDependencyExists、checkNpmDependencyVersion、installNpmDependency、getNpmCommand/getNpxCommand，以及 yarn/monorepo 检测；
• 进程管理（lib/process.js）：spawnProcess（支持env/cwd/onStdout/onExit等选项）、stopProcess（SIGTERM/SIGKILL 回退）、waitForPort；
• Meteor 配置（lib/meteor.js）：getMeteorAppDir/getMeteorAppConfig/getMeteorAppEntrypoints，以及一整套命令模式判定函数（isMeteorAppRun/isMeteorAppBuild/isMeteorAppTest等）与项目类型探测（isMeteorBlazeProject/isMeteorTypescriptProject等）；
• 全局状态（lib/global-state.js）：跨文件变更期间保持持久状态；
• git 管理（lib/git.js）：isGitRepository、ensureGitignoreExists、addGitignoreEntries。

同时介绍了 packages/rspack 的现代打包集成：四个构建上下文目录（_build、build-assets、build-chunks、.rsdoctor），关键依赖@rspack/core、@meteorjs/rspack、swc-loader，以及与 tools-core 的协作方式（入口点获取、命令模式感知、进程与 npm 工具）。

e2e-coverage、changelog、version-bump、docs-gap：发布与文档治理类技能

• e2e-coverage 规范了 dev/modern-tools/rspack/E2E_COVERAGE.md 的维护：报告须按"测试生命周期 → 应用 → 骨架 → npm 包兼容性 → 功能覆盖矩阵"五段结构组织，并明确何时触发更新（新增应用、骨架、npm 兼容测试或自定义断言）。
• changelog 定义发布 Changelog 的唯一数据源位于v3-docs/docs/generators/changelog/versions/，命名规则为MAJOR.MINOR.PATCH.md（无v前缀），并要求按固定顺序包含 Highlights / Breaking Changes / Migration Steps / Bumped Packages 等小节（空节用N/A），大版本用meteor update --release <VERSION>作为迁移第一步。
• version-bump 对应X.Y.Z-rcN.M版本模式（语义版本 + 发布候选号 + 包级修订号，见 conventions）。
• docs-gap 负责在发布后检查是否存在面向用户的文档缺口。

Claude Code 的 Skill 安装机制

CLAUDE.md 的最后一部分给出了可复制的安装脚本。其原理是：Claude Code 从.claude/skills/目录发现技能，而 Meteor 仓库的技能源位于.github/skills/；由于.claude/skills/已被 gitignore，每位贡献者需要在每次检出后执行一次符号链接安装：

for skill in .github/skills/*/; do name=$(basename "$skill") mkdir -p ".claude/skills/$name" ln -sf "../../../.github/skills/$name/SKILL.md" ".claude/skills/$name/SKILL.md" done

该命令遍历.github/skills/下每个主题目录，为SKILL.md建立指向仓库源的软链接，使 Claude Code 能发现并加载技能，同时保证技能文件单一来源、随仓库演进自动更新。这也是"技能只读加载、文档以仓库为唯一事实源"这一原则的落地实现。

技能文档的撰写与维护规范

ai-context 总结了这套体系自身的维护规则，可作为任何仓库建设 AI 上下文的参考：

• Token 预算：根文件保持精简，细节下沉到技能；
• 按需加载：技能仅在任务相关时读取；
• 触发式描述：SKILL.md 的 frontmatterdescription应写成触发条件（什么任务应加载它）；
• 零重复：信息若已在其他技能中存在，引用而非复制；
• 活文档：模式变化时及时更新，过时文档比没有更糟；
• 维护触发器：Agent 反复询问某主题 → 新建技能；Agent 反复出错 → 精炼对应技能；技能过大 → 拆分。

小结

CLAUDE.md 虽短，却是 Meteor 仓库 AI 协作体系的关键枢纽：它以一句"先读 AGENTS.md"建立上下文入口，以技能索引表将 Agent 的探索成本从"通读全库"降为"按任务加载"，再以符号链接脚本完成 Claude Code 侧的技能安装。这套"根上下文精简 + 技能按需加载 + 文档单一来源"的模式，使 100+ 核心包的 Meteor 代码库对 AI 编码助手保持可导航、可检索、可维护，也为其他大型开源仓库提供了可复制的 AI 文档治理范式。

• 后端
• 前端
• 开发工具
• 移动开发