tldraw 的 AGENTS.mdAI Agent 如何在这个 Monorepo 中安全、高效地写代码【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldrawtldraw 仓库根目录的 AGENTS.md 是一份面向 AI 编码智能体Claude、Cursor 及通用 Agent的工程协作规范它把「用哪个包管理器、跑哪条命令、改哪个包、测试放在哪、依赖如何声明」等关键决策全部固化成明确规则。读完本文你可以完整理解这份规范背后的 monorepo 工程约束并能把同样的方法论移植到自己的多包仓库中让 AI Agent或新加入的人类开发者在大型代码库里少走弯路、少犯错误。一、核心规则八条不可逾越的底线AGENTS.md 开篇即列出核心规则Core rules这是整份文档的总纲只用yarn不用npm。仓库基于 Yarn workspaces Yarn 4 构建。这一点可以从根 package.json 中得到印证packageManager: yarn4.17.1且workspaces字段声明了packages/*、apps/*、apps/vscode/*、apps/dotcom/*、internal/*、templates/*六个工作区范围。命令默认从仓库根目录执行除非某条命令明确要求在某个 workspace 内运行。永远不要裸跑tsc统一使用根目录的yarn typecheck。原因是仓库的类型检查并非简单的全量编译internal/scripts/typecheck.ts 会收集所有 workspace 的tsconfig.json并按拓扑顺序先叶子包、后依赖方分阶段执行tsc --build——源码中的注释解释了这样做的原因全新 checkout 时一次性把所有工程传给单次--build调用会导致 tsc 无法解析部分 workspace 包导入因此必须先按拓扑顺序构建packages/下的包来产出声明文件。优先做定点检查避免不必要的仓库级测试或 e2e 运行。变更范围收敛改动只限于当前请求与受影响的包不顺手重构无关代码。尊重 worktree 中已有的用户改动未被明确要求时不回滚。优先修改既有文件而非新建文件未要求时不新增文档。标题、标签与文档文字使用 sentence case句首大写。此外仓库还通过 CLAUDE.md 让 Claude 直接引用这份规范该文件内容即AGENTS.md体现了「单一事实来源 兼容性指针」的做法。二、仓库总览先知道代码住在哪里AGENTS.md 用两个清单给出了仓库地图。理解这张地图是所有后续规则的前提。核心 SDK 包packages/包职责packages/editor基础的无限画布编辑器不含任何默认形状、工具或 UIpackages/tldraw完整 SDK含默认 UI、形状、工具与交互packages/store响应式客户端数据库、持久化与迁移packages/tlschema形状、绑定与记录类型的定义和校验器packages/state响应式信号库signalspackages/sync/packages/sync-core多人协作同步packages/utils/packages/validate共享工具与校验辅助packages/assets图标、字体、翻译等打包资源应用与示例apps/ 与 templates/apps/examples— SDK 示例与演示示例开发的主战场示例位于apps/examples/src/examples/目录采用小写 kebab-case 命名apps/docs— tldraw.dev 文档站内容在apps/docs/content/apps/dotcom— tldraw.com 应用及 Cloudflare workersapps/vscode— VS Code 扩展templates/— 各受支持框架的起步模板。三、环境准备Node 版本与 Corepack规范要求 Node22.12.0并在安装依赖前启用 Corepack。这与根 package.json 中的engines: { node: 22.12.0 }一致。标准安装流程为npm i -g corepack yarnCorepack 会按packageManager字段自动使用仓库锁定的 Yarn 4.17.1避免团队内 Yarn 版本漂移。值得注意的是.yarnrc.yml中还有npmMinimalAgeGate: 7d依赖最小年龄门限与enableScripts: false见第七节供应链部分等安全相关配置。四、常用命令速查开发、构建、测试与代码质量以下命令均继承自 AGENTS.md并可与根 package.json 的scripts字段一一对应。开发命令作用yarn dev启动 examples 应用运行在 localhost:5420yarn dev-app启动 tldraw.com 客户端通过 process-compose 拉起 apps/dotcom/process-compose.yaml 定义的一组进程yarn dev-docs启动文档站yarn dev-vscode启动 VS Code 扩展开发yarn dev-template template name运行指定模板脚本见 internal/scripts/dev-template.shyarn dev的底层实现是lazy run dev --filterapps/examples --filterpackages/tldraw ...lazyrepo 工具关键点在于它连带执行各包的predev步骤。例如 packages/tldraw/package.json 中定义了predev: node ./scripts/copy-css-files.mjs用于生成tldraw.css等构建产物。AGENTS.md 特别警告如果直接运行 workspace 级命令如yarn workspace examples.tldraw.com devpredev会被跳过导致tldraw/tldraw.css这类导入无法解析。另一条实操细节全新的 git worktree 没有node_modules必须先yarn install。构建yarn build— 增量构建所有有变更的包对应lazy build增量策略由根目录 lazy.config.ts 驱动yarn build-package— 仅构建 SDK 包--filter packages/*yarn build-app— 构建 tldraw.com 客户端yarn build-docs— 构建文档站。测试yarn testworkspace 内— watch 模式运行该 workspace 的测试yarn test run— 只跑一次yarn test run --grep pattern— 只跑匹配的用例yarn vitest— 全仓库测试速度慢非必要不用。根 vitest.config.ts 会把apps与packages下所有vitest.config.ts聚合为 projects因此这一命令等价于跑遍所有 workspaceyarn e2e— examples 应用的 e2e 测试lazy e2e --filterapps/examplesyarn e2e-dotcom— tldraw.com 的 e2e 测试。代码质量yarn lint— lint 当前包或 workspace实现见 internal/scripts/lint.ts底层是 oxlint oxfmtyarn lint-current— 只 lint 变更过的文件yarn typecheck— 类型检查所有包并刷新资源先执行yarn refresh-assetsyarn format/yarn format-current— 格式化全仓库 / 仅变更文件yarn api-check— 校验公开 API 报告API extractor 报告即各包的api-report.api.md。五、验证工作流按改动范围选检查粒度AGENTS.md 给出了一套「改动范围 → 验证手段」的映射这正是前文「优先定点检查」规则的可操作化单个包的小改动先跑该 workspace 的测试例如cd packages/tldraw yarn test run --grep SelectTool影响共享类型、迁移、编辑器行为或跨包契约的改动从仓库根运行yarn typecheck公开 API 变更运行yarn api-check并把有意的 API 报告更新一并提交资源assets变更运行yarn refresh-assets或yarn typecheck保证生成产物是最新的文档变更仅在改动影响生成内容、MDX 行为或站点结构时才跑定点 docs 检查或 docs 构建e2e 行为变更运行最小相关的 e2e 套件且只在行为被有意修改时才更新快照。六、架构要点改代码前必须理解的五个约定这一节是 AGENTS.md 中最有源码深度的部分它告诉 Agent 如何按仓库既有模式扩展功能而不是打补丁。响应式状态状态由tldraw/state的信号系统Atom、Computed及相关原语管理。编辑器状态是可观察且带依赖追踪的——规范明确要求不要绕过既有的响应式模式。形状Shapes形状行为集中在ShapeUtil类中几何、渲染、手柄handles、交互与 SVG/导出行为都由 shape util 定义。添加自定义形状应遵循既有的 ShapeUtil 模式而不是做一次性的编辑器补丁。工具Tools工具是StateNode状态机。复杂工具通过子状态child states处理指针、键盘、tick 与切换行为规范要求交互逻辑要靠近拥有它的工具状态避免把逻辑散落到全局。绑定Bindings形状间关系使用 binding 记录 BindingUtil类表达。箭头等连接类形状应通过绑定工具类更新端点而不是临时性地直接改形状属性。管理器Managers最具体的一条架构约定编辑器子系统位于packages/editor/src/lib/editor/managers/是由Editor拥有并负责销毁的类。当前实际存在的管理器包括 ClickManager、HistoryManager、InputsManager、SnapManager、SpatialIndexManager、ThemeManager、TickManager 等。AGENTS.md 对管理器的清理teardown给出了精确规则需要订阅事件或持有资源的管理器应继承EditorManager并注册清理函数使其在dispose()时运行订阅编辑器总线事件用addEditorEvent(event, fn)其余一切store 副作用、reactions、DOM 监听器、子资源用register(fn)定时器/帧循环优先用editor.timers编辑器级别的清理用editor.disposables无 teardown 需求的管理器不要继承EditorManager。这与源码完全对应。packages/editor/src/lib/editor/managers/EditorManager.ts 的类注释写明了设计动机统一的拆除契约保证「设置者即拆除者」的对称生命周期防止清理被遗忘——注释中引用了严格模式下相机 bug#8892作为反面案例。实现上register(dispose)把清理函数存入SetaddEditorEvent内部就是editor.on(event, fn)加上自动注册的editor.off反注册dispose()时依次执行全部清理函数并清空集合。若需要有序拆除例如先暂停循环再取消它文档注释指引覆盖dispose()并在最后调用super.dispose()范例是TickManager。存储与 SchemaStore 的改动必须尊重迁移、校验器与 schema 版本化。涉及 schema 的变更通常需要同步更新packages/tlschema并补充针对性的迁移测试。七、依赖管理两条防止「本地能跑、他人崩溃」的规则AGENTS.md 在 Dependencies 小节给出了两条极有实操价值的规则均能在仓库中找到对应证据。1. 每个被导入的包必须声明在自己的 workspacepackage.json中Yarn 的node-moduleslinker 会把一切 hoist 到仓库根因此未声明的导入在本仓库依然能解析——但在 pnpm 或 Yarn PnP 的消费者环境就会失败。仓库用自研 oxlint 规则tldraw/no-undeclared-dependencies在packages/*全局强制执行internal/scripts/oxlint/tldraw-plugin.mjs 中的规则实现会定位文件所属包检查每条import/export ... from/ 动态import()/require的导入方是否已在 owner 的package.json声明中未声明即报「Yarns hoisted node_modules resolves it anyway, but package managers with strict isolation (pnpm, Yarn PnP) cant」。另外新增 workspace 依赖还必须在对应包的tsconfig.json中补一条references可用yarn check-packages --fix修复实现见 internal/scripts/check-packages.ts。2. 依赖安装/构建脚本默认关闭白名单放行.yarnrc.yml 中enableScripts: false关闭了第三方依赖的安装/构建脚本直接堵住了供应链中postinstall任意执行代码的主路径。确实需要构建的包native/napi 模块、二进制下载器在根 package.json 的dependenciesMeta中以built: true白名单放行例如esbuild、sharp、better-sqlite3、swc/core。反过来workerd被显式设为built: false——package.json 中的注释解释了原因其 postinstall 会执行原生二进制做自检在缺少 GLIBC 2.35 的 CI 镜像如构建文档站的环境上会失败而跳过该脚本并不影响 wrangler 在开发者机器上的正常工作。AGENTS.md 提醒Yarn 对未列入白名单的脚本是静默跳过的所以漏加白名单不会在安装时报错而会表现为运行期或构建期失败。八、在哪里工作改动落点决策表AGENTS.md 用「Where to work」小节明确了每类改动应落在哪个包核心编辑器原语、几何、管理器、无 UI 行为 →packages/editor默认形状、默认工具、UI、以及需要完整 SDK 的集成测试 →packages/tldraw可运行的 SDK 示例 →apps/examples文档文章与 release notes →apps/docs/contenttldraw.com 前端行为 →apps/dotcom/clientCloudflare worker →apps/dotcom/*-worker起步项目变更 →templates/。九、测试规范测试写在哪、怎么写单元测试与源码同目录命名*.test.ts集成测试通常放在 packages/tldraw/src/test/其中包含SelectTool.test.ts、HandTool.test.ts、ScribbleManager.test.ts等E2E 测试位于apps/examples/e2e/与apps/dotcom/client/e2e/涉及默认形状/工具/绑定/UI 的测试放packages/tldraw不应依赖默认形状与 UI 的核心编辑器行为放packages/editor断言时优先整体对象比较——相比逐字段断言它能给出更清晰的失败信息详细测试模式参见 skills/write-unit-tests/ 与 skills/write-e2e-tests/。十、Skills 系统把 Agent 能力沉淀为仓库资产AGENTS.md 专设 Skills 一节描述了仓库中一套「Agent 技能即文件」的机制规范的技能存放在skills/目录结构为skill-name/SKILL.mdYAML frontmatter 至少包含name与description例如 skills/pr/SKILL.md 的 frontmatter 声明了何时触发该技能.agents/skills、.claude/skills、.cursor/skills均为指向../skills的符号链接分别兼容通用 Agent、Claude 与 Cursor——已实际核验三者确实存在且指向同一目录。这保证了以skills/为唯一事实来源不为不同 Agent 复制技能内容只加兼容性指针可复用脚本、参考资料与资产放在对应技能目录内创建或重构技能前先阅读 skills/skill-creator/。当前skills/下的工作流类技能包括pr、issue、take、commit-changes、clean-copy、write-docs、write-example、write-release-notes等。文档与示例方面规范要求示例目录用小写 kebab-case、示例 README frontmatter 驱动示例站点、标题与描述保持 sentence case且 API 或用户可见行为变化时必须同步更新文档或示例。十一、代码与写作规范TS、React、生成文件、注释与文风TypeScript 与 API 设计跟随文件内既有风格与抽象使用 workspace 类型与辅助函数而非重复定义公开 API 变更须刻意为之并体现在 API 报告中新 API 避免布尔或语义模糊的位置参数——命名对象或枚举能让调用点更清晰。React 与 UI跟随所在 app/package 的既有组件模式用户可见文字保持简洁、sentence case能用聚焦的组件改动解决的不做大范围 UI 重写。生成文件不要手改生成的资源、API 报告或 schema——除非仓库本就期望直接编辑该文件生成产物需要变更时运行负责它的生成命令。注释哲学注释要「说出代码说不出的话」AGENTS.md 的 Comments 小节提出了一个可执行的检验标准好的注释命名的是失败模式failure mode而不是机制。具体规则包括作用域限定于你新写的代码与你正在改的行——修 bug 时不要顺手清扫存量注释否则会把小改动埋进大 diff发现值得清理的注释时提出来或放到独立 PR不重复代码getToolbar()上方写/** Get the toolbar */、不旁白代码editor.deleteShapes()上方写// Delete the shapes、不加章节横幅、不罗列调用点、不写只复述签名的param/returns共享理由只在共享处说明一次不复制到兄弟调用点注释应比它解释的代码短跨文件的叙述应放进文档README.md、SPEC.md、apps/docs/content/代码里只留短指针永远保留非显然的不变量、issue 编号与来源、不该盲调的常量、图示、以及代码不可破坏的枚举案例密度差异packages/*中public表面的文档注释会成为 API 参考那里的密度是预期之内的apps/*与templates/*保持稀疏。写作风格Markdown 标题、UI 标签、文档/PR/issue 标题一律 sentence case专有名词与缩写正常大写如PostgreSQL、WebSocket、NodeShapeUtil语言直接具体提交、PR 描述、issue、文档与 release notes 中不得包含 AI 署名。十二、Git 与 PR 约定被要求提交时保持 commit 聚焦PR 标题使用语义化格式type(scope): description绝不把 AI 工具加为 co-authorGitHub 工作流参见 skills/pr/ 与 skills/issue/仓库内容标准参见 skills/write-pr/ 与 skills/write-issue/。小结AGENTS.md 的价值不仅在于它约束了「在这个仓库里怎么用 AI」更在于它示范了一套可迁移的实践把包管理器、命令入口、验证粒度、架构模式、依赖安全、测试位置、注释哲学与写作风格全部显性化为机器与人都能执行的规则并用符号链接与单一事实来源支撑多 Agent 生态兼容。对维护 monorepo 的团队而言这份文档本身就是「让 AI Agent 可靠地参与大型仓库开发」的一份工程参考。【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考