从 AGENTS.md 读懂 CapAI Agent 协作开发规范与 Monorepo 工程实践【免费下载链接】CapOpen source Loom alternative. Beautiful, shareable screen recordings.项目地址: https://gitcode.com/GitHub_Trending/cap1/CapCapREADME.md 中定位为 Open source Loom alternative. Beautiful, shareable screen recordings.是一个横跨桌面端、Web、CLI、移动端与录制核心的多语言仓库。本文以仓库根目录的 AGENTS.md 为骨架系统讲解这份面向 AI Agent 与贡献者的《仓库开发规范》从零容忍的代码形状约束Rust clippy / Biome、生成文件红线到 Turborepo 的构建、测试、提交与 Effect API 工程实践。读完后你将理解在 Cap 这样的多语言 monorepo 中如何一次写对代码、如何做最小且安全的改动、如何安全地修改数据库 schema以及为什么仓库要求 Agent 在动手前先读这份规范。一、AGENTS.md 是什么仓库的第一读者约定AGENTS.md 是 Cap 仓库面向 AI Agent以及所有以研究→修改→验证方式工作的贡献者的顶层指南全文围绕一个核心主张CI 中每一条可避免的失败都意味着 Agent 没有先读本文档。它把开发流程拆解为几个阶段写代码前Pre-Generation Invariants零容忍规则 各语言的一次写对清单改完代码后Post-edit checks按触碰文件类型执行的最快验证工程上下文Project Structure、Build/Test/Develop、Coding Style、Testing、Commits PRs行为准则Agent-Specific Practices、Deep Investigation Default、Effect Usage。仓库根目录的 CLAUDE.md 只有一句话ReadAGENTS.mdfor repository instructions.可见 AGENTS.md 是唯一的规范权威来源。二、Pre-Generation Invariants写代码前的三条零容忍红线AGENTS.md 明确定义了三条零容忍规则违反即被 CI 拒绝1. 默认不写代码注释只在解决复杂问题后补充注释的唯一合法用途是捕获非显然的上下文修复为什么长这样、绕过了哪个上游/平台 bug、经过调研后选择的非显然不变量或取舍、解释该决策的 PR/issue 链接。以下情况一律禁止复述代码在做什么、重复类型信息逐字解释参数名的 JSDocTODO: refactor、this should be cleaner 类随笔描述正在做的这次修改的注释。规则要求When in doubt, prefer better naming/types over a comment.拿不准时优先用更好的命名与类型而不是注释。该规则适用于仓库内所有语言Rust、TS、JS、Python、shell、SQL、TOML 等。一个正面的例子是 apps/web/app/api/currency/route.ts 中关于Cache-Control: private, no-store的注释——它解释了响应随访问者 IP 变化绝不能落入共享 CDN 缓存这一非显然的原因正是规范鼓励的注释类型。2. 绝不手工编辑生成文件以下文件由工具链生成、必须保持提交状态CI typecheck 与全新 clone 依赖它们只能通过重新生成来变更生成文件重新生成方式**/tauri.ts如 apps/desktop/src/utils/tauri.ts仅 debug 桌面运行时重新生成apps/desktop/src-tauri/gen/**Tauri CLI 生成packages/ui-solid/src/auto-imports.d.tsunplugin-auto-import 生成packages/database/migrations/下的 Drizzle SQLbun run db:generate数据库 schema 变更的标准流程是修改 schema →bun run db:generate→连同生成的 SQL、snapshot 与 journal 一起提交。注意 apps/desktop/src/utils/queries.ts 是手写文件而非生成文件可直接正常编辑biome.json 的files.includes中也对它做了豁免排除。3. 绝不额外启动开发服务器bun run dev、bun run dev:web、bun run dev:desktop以及 Docker 服务都假设已在运行。AGENTS.md 与 Agent-Specific Practices 反复强调不要启动多余服务器需要哪个用哪个如bun run dev:web或bun run dev:desktop。三、Rust写出 clippy-clean 的正确形状Cap 的 Rust 工作区通过 Cargo.toml 的[workspace.lints]把以下 lint 全部设为denyCI 以cargo clippy -D warnings强制执行。AGENTS.md 给出了别这么写 → 该这么写的对照表❌ 不要写✅ 改为Lintdbg!(x)tracing::debug!(?x)或直接删除dbg_macrolet _ async_fn();async_fn().await;或tokio::spawn(async_fn());let_underscore_future对Duration/Instant做a - ba.saturating_sub(b)unchecked_time_subtractionCargo.toml 中实际登记的 lint 名为unchecked_duration_subtraction两者指向同一类问题if a { if b { … } }if a b { … }collapsible_ifx.clone()当x: Copyxclone_on_copyiter.map(\|x\| foo(x))iter.map(foo)redundant_closurefn f(v: VecT)/fn f(s: String)fn f(v: [T])/fn f(s: str)ptr_argv.len() 0/v.len() 0v.is_empty()/!v.is_empty()len_zerolet _ unit_returning();unit_returning();let_unit_valueopt.unwrap_or_else(\|\| 42)默认值廉价时opt.unwrap_or(42)unnecessary_lazy_evaluationsfor i in 0..v.len() { v[i] … }for item in v { … }或.iter().enumerate()needless_range_loopvalue.min(max).max(min)value.clamp(min, max)manual_clamp此外工作区对全部 Rust 代码启用unused_must_use deny每个Result、Option和#[must_use]值都必须显式处理?、.unwrap()、.ok()等。对返回值是Result而你有意丢弃的调用let _ tx.send(msg);是被允许的正确逃生通道但对返回()的调用let _ …则会触发let_unit_value。从实际代码看规范确实被严格执行例如 apps/cli/src/main.rs 中对 Linux 下 Mesallvmpipe_thread_count的环境变量设置与 Windows 下SetProcessDpiAwareness的调用都使用了显式处理方式。四、TypeScript / JavaScriptBiome 强制的一次写对仓库根目录的 biome.json 定义了 TS/JS 的硬性规范AGENTS.md 明确禁止在局部覆盖缩进用 tabindentStyle: tab不是两空格也不是四空格新文件与编辑都必须遵守字符串一律双引号quoteStyle: double写foo而不是fooorganizeImports: onimport 由工具自动排序分组不要手工排序也不要遗留未使用的 import推荐 lint 规则集开启唯一例外是关闭suspicious.noShadowRestrictedNames其余规则未使用变量、noExplicitAny、死代码等全部生效a11y 规则差异apps/desktop/**下关闭 a11y 规则其余位置apps/web、packages/ui等强制启用——biome.json 的overrides中可确认这一差异CSS 例外**/*.css关闭noUnknownAtRules、noUnknownTypeSelector、noDescendingSpecificity。TypeScript 严格性避免any优先unknown 类型收窄或复用cap/utils、cap/web-domain、生成的 binding 等现有共享类型不无理由引入ts-expect-error/ts-ignore优先修复类型本身。五、Post-edit checks改完必须跑的最窄最快检查AGENTS.md 的核心主张是优先做有范围的快速检查而不是默认跑全仓慢速门禁触碰了任何Rust文件 → 跑cargo fmt --all和cargo check -p crate只有显式要求、准备 CI/PR 终验或改动范围跨多个 crate 时才加--all-targets、--workspace或cargo clippy -p crate --all-targets -- -D warnings触碰了TS / JS / JSON / CSS / MD文件 → 先对触碰文件跑最窄的格式化/检查例如bun run biome check --write files只有显式要求或改动跨共享类型/包时才跑全量bun run format、bun run lint、bun run typecheck触碰了DB schema→ 在依赖它之前先跑bun run db:generate。若窄范围检查失败必须在源码中修复违规而不是用#[allow(...)]、// biome-ignore或any抑制——除非得到显式批准。六、项目结构与模块划分AGENTS.md 描述的是一个 Turborepo monorepoturbo.json 与 package.json 可印证apps/desktopTauri v2 SolidStart 桌面端Rust 侧为cap-desktopcrate见 apps/desktop/src-tauri/Cargo.toml依赖大量 Tauri 插件与cap-*录制/渲染 crateGPUI 分支位于 apps/desktop-gpuiapps/webNext.js Web 端API 路由位于 apps/web/app/apiapps/cliRust CLIapps/cli/src/main.rs基于 clap 解析支持补全生成packages/*共享库如databaseDrizzle MySQL见 packages/database/package.json、ui、ui-solid、utils、web-*crates/*Rust 媒体/录制/渲染/摄像头 cratescripts/*、infra/、packages/local-docker/工具脚本与本地服务。七、构建、测试与开发命令全解安装与初始化bun install # 安装依赖Bun 1.4.0见 package.json 的 packageManager 字段 bun run env-setup # 生成 .env 环境配置调用 scripts/env-cli.js bun run cap-setup # 后续初始化调用 scripts/setup.js开发bun run dev # web desktop 同时开发会自动 docker:up 并在退出时 docker:stop bun run dev:desktop # 仅桌面端 bun run dev:web # 仅 Web cd apps/web bun run dev从 package.json 的dev脚本可见开发时会先用docker:up拉起本地 MySQL/MinIO再用 Turbo 以--env-modeloose方式并行跑子包。此外还有dev:extensionWeb Chrome 扩展、dev:mobile/dev:mobile:physicalExpo 移动端等变体。构建bun run build # Turbo 全仓构建顶层 build 任务见 turbo.json bun run tauri:build # 桌面发布构建走 apps/desktop 的 build:tauri使用 tauri.prod.conf.json桌面构建链路较长build:sidecar编译 sidecar 二进制→build:gpuirelease 版 GPUI→preparescript --release→verify-gpui-release-inputs→tauri build见 apps/desktop/package.json。数据库bun run db:generate # Drizzle Kit 生成迁移 SQL/snapshot/journal bun run db:push # 推送 schema 到 MySQL bun run db:studio # 打开 Drizzle Studio 可视化数据库配置见 packages/database/drizzle.config.ts方言为 MySQLcasing: snake_case输出到./migrations并要求DATABASE_URL必须以mysql://开头。生成物示例见 packages/database/migrations/0000_brown_sunfire.sqlaccounts、comments、s3_buckets、users、videos 等表。注意turbo.json中dev任务dependsOn: [db:push]即开发时 schema 会自动推送但规范仍要求改 schema 时先db:generate再提交生成物。Docker 与质量检查bun run docker:up | docker:stop | docker:clean # 本地 MySQL/MinIO bun run lint # biome lint bun run format # biome check --write bun run typecheck # next typegen tsc -b cargo build -p crate / cargo test -p crate # 按 crate 构建/测试 Rust八、编码风格与命名约定AGENTS.md 明确了命名规则TS/JS/JSON/CSStab 缩进 双引号Biome 强制biome.json 印证不许配置逐文件覆盖Rustrustfmt默认风格 上文 clippy deny 清单文件 kebab-case如user-menu.tsxReact/Solid 组件 PascalCasehooks 用useX前缀Rust 模块 snake_casecrate kebab-case运行环境基线Node 20、Bun 1.4.0、Rust 1.88、DockerMySQL/MinIO与 package.json 的enginesnode 20, bun 1.4.0一致。九、测试约定TS/JS使用 Vitest测试文件命名为*.test.ts(x)并放在源码附近例如 apps/desktop 下的*.test.js、apps/web/tests的 unit/e2e 目录Rustcargo test按 crate 运行测试放在src或tests如 apps/desktop/src-tauri/tests、各 crates/*/tests 目录原则逻辑部分偏好单元测试流程部分用轻量冒烟测试暂不设严格覆盖率门槛。十、提交与 PR 规范Conventional Commits风格feat:、fix:、chore:、improve:、refactor:、docs:如fix: hide watermark for pro users绝不添加Co-authored-by或其他署名 trailer无论来自 Cursor 还是任何 Agent只以用户身份提交PR 要求清晰的描述、关联 issue、UI 改动附截图/GIF、包含 env/迁移说明保持范围聚焦行为变化时同步更新文档。十一、Deep Investigation Default深入调查默认值当被要求检查、审查、优化、加固或修复某个问题时AGENTS.md 要求不要停在表面的局部修改而是先追溯完整路径再做一轮爆炸半径blast-radius复查找出真正的根因而不只是症状追溯调用方、副作用、异步/运行时行为、生成产物、缓存、导出、旧数据与平台特有路径review diff 时对比新旧行为明确区分已验证与仅推测在宣布完成前预判后续 reviewer 或用户可能提出的问题尽可能验证真实可见的用户结果而不只是编译/lint 通过。最终原则是优先最小的正确修复但前提是确认这个窄修复没有漏掉相关后果。十二、Effect 用法Web 端 API 的工程范式AGENTS.md 用一整节规定apps/web的 Effect 架构仓库源码完全印证了这套模式apps/web/app/api/*的 Next.js API 路由基于effect/platform的HttpApi构建器。典型实例是 apps/web/app/api/currency/route.ts先用Schema.Struct定义请求参数GetCurrencyParams再用HttpApi.make(CapCurrencyApi)HttpApiGroup.make(root)HttpApiEndpoint.get(...)声明端点最后通过HttpApiBuilder.apiHttpApiBuilder.group实现 handler——文档要求复制现有 class/group/endpoint 模式而不是临时手写 handler。后端服务在Effect.gen块内获取如Videos、S3Buckets通过Layer.provide/HttpApiBuilder.group注入并把领域错误翻译成HttpApiError变体。effectful API 转成 Next.js handler 用apiToHandler(ApiLive)来自 apps/web/lib/server.ts导出返回的handler——不要在路由文件里调用runPromise。apiToHandler内部会拼装 span 命名、HttpAuthMiddlewareLive、CORS、Cookie 密码附件等中间件。currency路由的结尾正是const handler apiToHandler(ApiLive); export const GET handler;。服务端运行 effect 用EffectRuntime.runPromiseapps/web/lib/server.ts 导出的runPromise内部走ManagedRuntime并先provide(CookiePasswordAttachmentLive)通常配合provideOptionalAuth使用让 cookie 与每请求上下文自动附加。客户端使用useEffectQuery/useEffectMutation来自 apps/web/lib/EffectRuntime.ts内部封装ManagedRuntime与 tracing组件中不应直接调用EffectRuntime.run*。结语Cap 的 AGENTS.md 是一份罕见的、把给 AI Agent 看的规范当作一等公民的仓库文档它把 CI 门禁前移为写码时的形状约束把审查后移为爆炸半径复查并给出了一套可执行的最小验证流程。对贡献者而言遵循这份文档意味着Rust 代码天然通过 clippy deny 清单、TS 代码天然满足 Biome 规则、数据库改动始终带迁移文件、Web API 始终走统一的 Effect 范式。对希望了解 Cap 工程结构的人来说这份文档则是进入仓库的最佳地图——从 package.json 的脚本矩阵、Cargo.toml 的工作区 lints、biome.json 的格式化策略到 apps/web/app/api/currency/route.ts 的 API 范式每一条规范都能在源码中找到落地证据。【免费下载链接】CapOpen source Loom alternative. Beautiful, shareable screen recordings.项目地址: https://gitcode.com/GitHub_Trending/cap1/Cap创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 从 AGENTS.md 读懂 Cap：AI Agent 协作开发规范与 Monorepo 工程实践
从 AGENTS.md 读懂 CapAI Agent 协作开发规范与 Monorepo 工程实践【免费下载链接】CapOpen source Loom alternative. Beautiful, shareable screen recordings.项目地址: https://gitcode.com/GitHub_Trending/cap1/CapCapREADME.md 中定位为 Open source Loom alternative. Beautiful, shareable screen recordings.是一个横跨桌面端、Web、CLI、移动端与录制核心的多语言仓库。本文以仓库根目录的 AGENTS.md 为骨架系统讲解这份面向 AI Agent 与贡献者的《仓库开发规范》从零容忍的代码形状约束Rust clippy / Biome、生成文件红线到 Turborepo 的构建、测试、提交与 Effect API 工程实践。读完后你将理解在 Cap 这样的多语言 monorepo 中如何一次写对代码、如何做最小且安全的改动、如何安全地修改数据库 schema以及为什么仓库要求 Agent 在动手前先读这份规范。一、AGENTS.md 是什么仓库的第一读者约定AGENTS.md 是 Cap 仓库面向 AI Agent以及所有以研究→修改→验证方式工作的贡献者的顶层指南全文围绕一个核心主张CI 中每一条可避免的失败都意味着 Agent 没有先读本文档。它把开发流程拆解为几个阶段写代码前Pre-Generation Invariants零容忍规则 各语言的一次写对清单改完代码后Post-edit checks按触碰文件类型执行的最快验证工程上下文Project Structure、Build/Test/Develop、Coding Style、Testing、Commits PRs行为准则Agent-Specific Practices、Deep Investigation Default、Effect Usage。仓库根目录的 CLAUDE.md 只有一句话ReadAGENTS.mdfor repository instructions.可见 AGENTS.md 是唯一的规范权威来源。二、Pre-Generation Invariants写代码前的三条零容忍红线AGENTS.md 明确定义了三条零容忍规则违反即被 CI 拒绝1. 默认不写代码注释只在解决复杂问题后补充注释的唯一合法用途是捕获非显然的上下文修复为什么长这样、绕过了哪个上游/平台 bug、经过调研后选择的非显然不变量或取舍、解释该决策的 PR/issue 链接。以下情况一律禁止复述代码在做什么、重复类型信息逐字解释参数名的 JSDocTODO: refactor、this should be cleaner 类随笔描述正在做的这次修改的注释。规则要求When in doubt, prefer better naming/types over a comment.拿不准时优先用更好的命名与类型而不是注释。该规则适用于仓库内所有语言Rust、TS、JS、Python、shell、SQL、TOML 等。一个正面的例子是 apps/web/app/api/currency/route.ts 中关于Cache-Control: private, no-store的注释——它解释了响应随访问者 IP 变化绝不能落入共享 CDN 缓存这一非显然的原因正是规范鼓励的注释类型。2. 绝不手工编辑生成文件以下文件由工具链生成、必须保持提交状态CI typecheck 与全新 clone 依赖它们只能通过重新生成来变更生成文件重新生成方式**/tauri.ts如 apps/desktop/src/utils/tauri.ts仅 debug 桌面运行时重新生成apps/desktop/src-tauri/gen/**Tauri CLI 生成packages/ui-solid/src/auto-imports.d.tsunplugin-auto-import 生成packages/database/migrations/下的 Drizzle SQLbun run db:generate数据库 schema 变更的标准流程是修改 schema →bun run db:generate→连同生成的 SQL、snapshot 与 journal 一起提交。注意 apps/desktop/src/utils/queries.ts 是手写文件而非生成文件可直接正常编辑biome.json 的files.includes中也对它做了豁免排除。3. 绝不额外启动开发服务器bun run dev、bun run dev:web、bun run dev:desktop以及 Docker 服务都假设已在运行。AGENTS.md 与 Agent-Specific Practices 反复强调不要启动多余服务器需要哪个用哪个如bun run dev:web或bun run dev:desktop。三、Rust写出 clippy-clean 的正确形状Cap 的 Rust 工作区通过 Cargo.toml 的[workspace.lints]把以下 lint 全部设为denyCI 以cargo clippy -D warnings强制执行。AGENTS.md 给出了别这么写 → 该这么写的对照表❌ 不要写✅ 改为Lintdbg!(x)tracing::debug!(?x)或直接删除dbg_macrolet _ async_fn();async_fn().await;或tokio::spawn(async_fn());let_underscore_future对Duration/Instant做a - ba.saturating_sub(b)unchecked_time_subtractionCargo.toml 中实际登记的 lint 名为unchecked_duration_subtraction两者指向同一类问题if a { if b { … } }if a b { … }collapsible_ifx.clone()当x: Copyxclone_on_copyiter.map(\|x\| foo(x))iter.map(foo)redundant_closurefn f(v: VecT)/fn f(s: String)fn f(v: [T])/fn f(s: str)ptr_argv.len() 0/v.len() 0v.is_empty()/!v.is_empty()len_zerolet _ unit_returning();unit_returning();let_unit_valueopt.unwrap_or_else(\|\| 42)默认值廉价时opt.unwrap_or(42)unnecessary_lazy_evaluationsfor i in 0..v.len() { v[i] … }for item in v { … }或.iter().enumerate()needless_range_loopvalue.min(max).max(min)value.clamp(min, max)manual_clamp此外工作区对全部 Rust 代码启用unused_must_use deny每个Result、Option和#[must_use]值都必须显式处理?、.unwrap()、.ok()等。对返回值是Result而你有意丢弃的调用let _ tx.send(msg);是被允许的正确逃生通道但对返回()的调用let _ …则会触发let_unit_value。从实际代码看规范确实被严格执行例如 apps/cli/src/main.rs 中对 Linux 下 Mesallvmpipe_thread_count的环境变量设置与 Windows 下SetProcessDpiAwareness的调用都使用了显式处理方式。四、TypeScript / JavaScriptBiome 强制的一次写对仓库根目录的 biome.json 定义了 TS/JS 的硬性规范AGENTS.md 明确禁止在局部覆盖缩进用 tabindentStyle: tab不是两空格也不是四空格新文件与编辑都必须遵守字符串一律双引号quoteStyle: double写foo而不是fooorganizeImports: onimport 由工具自动排序分组不要手工排序也不要遗留未使用的 import推荐 lint 规则集开启唯一例外是关闭suspicious.noShadowRestrictedNames其余规则未使用变量、noExplicitAny、死代码等全部生效a11y 规则差异apps/desktop/**下关闭 a11y 规则其余位置apps/web、packages/ui等强制启用——biome.json 的overrides中可确认这一差异CSS 例外**/*.css关闭noUnknownAtRules、noUnknownTypeSelector、noDescendingSpecificity。TypeScript 严格性避免any优先unknown 类型收窄或复用cap/utils、cap/web-domain、生成的 binding 等现有共享类型不无理由引入ts-expect-error/ts-ignore优先修复类型本身。五、Post-edit checks改完必须跑的最窄最快检查AGENTS.md 的核心主张是优先做有范围的快速检查而不是默认跑全仓慢速门禁触碰了任何Rust文件 → 跑cargo fmt --all和cargo check -p crate只有显式要求、准备 CI/PR 终验或改动范围跨多个 crate 时才加--all-targets、--workspace或cargo clippy -p crate --all-targets -- -D warnings触碰了TS / JS / JSON / CSS / MD文件 → 先对触碰文件跑最窄的格式化/检查例如bun run biome check --write files只有显式要求或改动跨共享类型/包时才跑全量bun run format、bun run lint、bun run typecheck触碰了DB schema→ 在依赖它之前先跑bun run db:generate。若窄范围检查失败必须在源码中修复违规而不是用#[allow(...)]、// biome-ignore或any抑制——除非得到显式批准。六、项目结构与模块划分AGENTS.md 描述的是一个 Turborepo monorepoturbo.json 与 package.json 可印证apps/desktopTauri v2 SolidStart 桌面端Rust 侧为cap-desktopcrate见 apps/desktop/src-tauri/Cargo.toml依赖大量 Tauri 插件与cap-*录制/渲染 crateGPUI 分支位于 apps/desktop-gpuiapps/webNext.js Web 端API 路由位于 apps/web/app/apiapps/cliRust CLIapps/cli/src/main.rs基于 clap 解析支持补全生成packages/*共享库如databaseDrizzle MySQL见 packages/database/package.json、ui、ui-solid、utils、web-*crates/*Rust 媒体/录制/渲染/摄像头 cratescripts/*、infra/、packages/local-docker/工具脚本与本地服务。七、构建、测试与开发命令全解安装与初始化bun install # 安装依赖Bun 1.4.0见 package.json 的 packageManager 字段 bun run env-setup # 生成 .env 环境配置调用 scripts/env-cli.js bun run cap-setup # 后续初始化调用 scripts/setup.js开发bun run dev # web desktop 同时开发会自动 docker:up 并在退出时 docker:stop bun run dev:desktop # 仅桌面端 bun run dev:web # 仅 Web cd apps/web bun run dev从 package.json 的dev脚本可见开发时会先用docker:up拉起本地 MySQL/MinIO再用 Turbo 以--env-modeloose方式并行跑子包。此外还有dev:extensionWeb Chrome 扩展、dev:mobile/dev:mobile:physicalExpo 移动端等变体。构建bun run build # Turbo 全仓构建顶层 build 任务见 turbo.json bun run tauri:build # 桌面发布构建走 apps/desktop 的 build:tauri使用 tauri.prod.conf.json桌面构建链路较长build:sidecar编译 sidecar 二进制→build:gpuirelease 版 GPUI→preparescript --release→verify-gpui-release-inputs→tauri build见 apps/desktop/package.json。数据库bun run db:generate # Drizzle Kit 生成迁移 SQL/snapshot/journal bun run db:push # 推送 schema 到 MySQL bun run db:studio # 打开 Drizzle Studio 可视化数据库配置见 packages/database/drizzle.config.ts方言为 MySQLcasing: snake_case输出到./migrations并要求DATABASE_URL必须以mysql://开头。生成物示例见 packages/database/migrations/0000_brown_sunfire.sqlaccounts、comments、s3_buckets、users、videos 等表。注意turbo.json中dev任务dependsOn: [db:push]即开发时 schema 会自动推送但规范仍要求改 schema 时先db:generate再提交生成物。Docker 与质量检查bun run docker:up | docker:stop | docker:clean # 本地 MySQL/MinIO bun run lint # biome lint bun run format # biome check --write bun run typecheck # next typegen tsc -b cargo build -p crate / cargo test -p crate # 按 crate 构建/测试 Rust八、编码风格与命名约定AGENTS.md 明确了命名规则TS/JS/JSON/CSStab 缩进 双引号Biome 强制biome.json 印证不许配置逐文件覆盖Rustrustfmt默认风格 上文 clippy deny 清单文件 kebab-case如user-menu.tsxReact/Solid 组件 PascalCasehooks 用useX前缀Rust 模块 snake_casecrate kebab-case运行环境基线Node 20、Bun 1.4.0、Rust 1.88、DockerMySQL/MinIO与 package.json 的enginesnode 20, bun 1.4.0一致。九、测试约定TS/JS使用 Vitest测试文件命名为*.test.ts(x)并放在源码附近例如 apps/desktop 下的*.test.js、apps/web/tests的 unit/e2e 目录Rustcargo test按 crate 运行测试放在src或tests如 apps/desktop/src-tauri/tests、各 crates/*/tests 目录原则逻辑部分偏好单元测试流程部分用轻量冒烟测试暂不设严格覆盖率门槛。十、提交与 PR 规范Conventional Commits风格feat:、fix:、chore:、improve:、refactor:、docs:如fix: hide watermark for pro users绝不添加Co-authored-by或其他署名 trailer无论来自 Cursor 还是任何 Agent只以用户身份提交PR 要求清晰的描述、关联 issue、UI 改动附截图/GIF、包含 env/迁移说明保持范围聚焦行为变化时同步更新文档。十一、Deep Investigation Default深入调查默认值当被要求检查、审查、优化、加固或修复某个问题时AGENTS.md 要求不要停在表面的局部修改而是先追溯完整路径再做一轮爆炸半径blast-radius复查找出真正的根因而不只是症状追溯调用方、副作用、异步/运行时行为、生成产物、缓存、导出、旧数据与平台特有路径review diff 时对比新旧行为明确区分已验证与仅推测在宣布完成前预判后续 reviewer 或用户可能提出的问题尽可能验证真实可见的用户结果而不只是编译/lint 通过。最终原则是优先最小的正确修复但前提是确认这个窄修复没有漏掉相关后果。十二、Effect 用法Web 端 API 的工程范式AGENTS.md 用一整节规定apps/web的 Effect 架构仓库源码完全印证了这套模式apps/web/app/api/*的 Next.js API 路由基于effect/platform的HttpApi构建器。典型实例是 apps/web/app/api/currency/route.ts先用Schema.Struct定义请求参数GetCurrencyParams再用HttpApi.make(CapCurrencyApi)HttpApiGroup.make(root)HttpApiEndpoint.get(...)声明端点最后通过HttpApiBuilder.apiHttpApiBuilder.group实现 handler——文档要求复制现有 class/group/endpoint 模式而不是临时手写 handler。后端服务在Effect.gen块内获取如Videos、S3Buckets通过Layer.provide/HttpApiBuilder.group注入并把领域错误翻译成HttpApiError变体。effectful API 转成 Next.js handler 用apiToHandler(ApiLive)来自 apps/web/lib/server.ts导出返回的handler——不要在路由文件里调用runPromise。apiToHandler内部会拼装 span 命名、HttpAuthMiddlewareLive、CORS、Cookie 密码附件等中间件。currency路由的结尾正是const handler apiToHandler(ApiLive); export const GET handler;。服务端运行 effect 用EffectRuntime.runPromiseapps/web/lib/server.ts 导出的runPromise内部走ManagedRuntime并先provide(CookiePasswordAttachmentLive)通常配合provideOptionalAuth使用让 cookie 与每请求上下文自动附加。客户端使用useEffectQuery/useEffectMutation来自 apps/web/lib/EffectRuntime.ts内部封装ManagedRuntime与 tracing组件中不应直接调用EffectRuntime.run*。结语Cap 的 AGENTS.md 是一份罕见的、把给 AI Agent 看的规范当作一等公民的仓库文档它把 CI 门禁前移为写码时的形状约束把审查后移为爆炸半径复查并给出了一套可执行的最小验证流程。对贡献者而言遵循这份文档意味着Rust 代码天然通过 clippy deny 清单、TS 代码天然满足 Biome 规则、数据库改动始终带迁移文件、Web API 始终走统一的 Effect 范式。对希望了解 Cap 工程结构的人来说这份文档则是进入仓库的最佳地图——从 package.json 的脚本矩阵、Cargo.toml 的工作区 lints、biome.json 的格式化策略到 apps/web/app/api/currency/route.ts 的 API 范式每一条规范都能在源码中找到落地证据。【免费下载链接】CapOpen source Loom alternative. Beautiful, shareable screen recordings.项目地址: https://gitcode.com/GitHub_Trending/cap1/Cap创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考