尧图网站建设 
后端前端数据分析数据可视化【免费下载链接】growthbookOpen Source Feature Flags, Experimentation, and Product Analytics项目地址https://gitcode.com/gh_mirrors/gr/growthbook点击查看免费下载本篇技术文章基于 GrowthBook 仓库中的 .agents/guides/README.md 展开。该目录是 GrowthBook 为所有编码代理coding agent设计的规范指南之家canonical home采用工具无关tool-neutral的组织方式根目录与各包中的 AGENTS.md、CLAUDE.md 等提供商配置只负责挂载指针真正的规则细节统一沉淀在.agents/guides/下。读完本文你将了解这套指南的目录架构、各份指南的核心规则包边界、权限系统、UI 文案规范、数据获取与 API 模式等以及它们如何通过 ESLint 与 CI 命令从文档变成可执行的约束。1. 设计原则指南与提供商配置分离.agents/guides/README.md 开宗明义地给出两条组织原则该目录是所有编码代理共享的详细仓库指南的规范归属地指南内容必须保持工具无关——提供商特定的配置如 AGENTS.md、CLAUDE.md只应包含附加相关指南所需的元数据或指针而不应复制规则正文。这一设计的收益很直接规则只有一份事实来源single source of truth任何代理工具接入时都只需指向同一份指南规则更新不需要多处同步。仓库根目录的 AGENTS.md 即为各代理的总入口提供构建、开发与代码质量命令而更细粒度的领域规则则按主题拆分到指南目录中。指南目录的完整清单如下相对路径均以仓库根目录为起点指南文件覆盖内容project-overview.mdMonorepo 架构与包职责划分development-guidelines.md全项目编码约定与校验命令package-boundaries.md被强制执行的导入与依赖限制permissions.md权限与商业特性commercial feature模式ui-copy-style.md所有面向用户文案的大小写与措辞规则docs.mdMintlify MDX frontmatter 规则frontend/react-patterns.mdReact 组件与 UI 组件选型模式frontend/data-fetching.mdSWR 数据获取与变更mutation模式backend/api-patterns.md内部 API 与外部 REST API 的构建模式backend/model-patterns.md数据模型BaseModel模式backend/legacy-model-migration-patterns.md旧模型迁移模式backend/warehouse-column-casing.md数仓列大小写规则flag-family-authority.mdFlag 家族的权限权威判定模型revisions-architecture.md修订revision引擎架构2. Monorepo 架构与包职责project-overview.mdproject-overview.md 描述了 GrowthBook 的工程骨架这是所有后续指南的上下文前提仓库由pnpm workspaces管理见 pnpm-workspace.yaml仅声明packages/*一个 glob必须使用pnpm禁止 npm 或 yarn各包的定位与开发端口包职责关键事实packages/front-endNext.js 应用完整 UI开发时运行于 http://localhost:3000React 函数组件路径别名/packages/back-endExpress API 服务运行于 http://localhost:3100MongoDB 为主存储内部导入使用back-end/前缀packages/shared共享 TypeScript 代码类型、工具、校验器、常量禁止 UI 组件或服务端专属代码packages/statsPython 统计引擎gbstatsPython 3.9Poetry 管理依赖使用 pandas/numpy/scipypackages/sdk-jsJS SDKnpm 名growthbook/growthbook与内部包完全隔离packages/sdk-reactReact SDKnpm 名growthbook/growthbook-react与内部包完全隔离指南还特别标注了企业版代码的位置packages/front-end/enterprise/、packages/back-end/src/enterprise/、packages/shared/src/enterprise/并明确通常不接受外部对 enterprise 目录的贡献。值得注意的是 back-end 提供两套独立的 API这一架构在 backend/api-patterns.md 中有完整展开供 GrowthBook 前端使用的内部 APIsrc/controllers/src/routers/以及供客户集成的外部 REST APIsrc/api/挂载在/api/v1/前缀下。3. 开发约定从注释纪律到质量命令development-guidelines.mddevelopment-guidelines.md 是全项目通用的编码约定几个要点测试策略不要求为前端组件或后端 router/controller/model 写测试但关键工具/辅助函数必须有测试。注释纪律附正反例// ❌ BAD — 叙述显而易见的内容、过度解释 // GET /configs/:id/references — features, constants, and configs that // reference this config via const:key. Scoped to the project globals. router.get(/:id/references, ...) // ✅ GOOD — 只保留代码无法传达的非显然约束 // Spans both collections: configs and constants share the const: namespace. router.get(/:id/references, ...)类型安全规则严格类型禁用any类型未知时用unknown来自不可信来源的数据请求体、JSON.parse先按unknown处理通常用 zod 校验未使用变量尽量避免必须保留时以下划线_前缀生产代码避免console.logESLint 会警告后端可从util/logger导入替代。Zod 校验范式指南给出的标准写法import { z } from zod; const mySchema z.object({ name: z.string(), count: z.number().int().positive(), }); type MyType z.infertypeof mySchema;类型定义位置共享类型放在packages/shared/types/*.d.ts只用.d.ts文件做纯类型定义有 Zod schema 时以 schema 为唯一事实来源并infer类型不要重复手写 interface。环境变量后端统一定义在 secrets.ts前端定义在 init.ts 与 env.ts其他任何文件都不得直接引用process.env。代码质量命令与 AGENTS.md 中的命令表一致pnpm pretty # 格式化写入 pnpm pretty:check # 仅校验格式 pnpm lint # ESLint 自动修复 pnpm lint:ci # 仅校验 lint node scripts/check-docs-frontmatter.mjs # 校验文档 frontmatter引用含 : 的 YAML 值 pnpm type-check # 全包类型检查 pnpm ci # CI 执行的完整校验链指南最后列出九条关键原则其中最具项目特色的是遵守包边界、前端使用设计系统组件不直接引 Radix UI、新增模型默认使用 BaseModel、权限检查必须走permissionsUtil、高级功能必须用hasCommercialFeature()判定。4. 包边界ESLint 强制执行的导入矩阵package-boundaries.mdpackage-boundaries.md 定义了一套由 ESLint 强制的包间导入限制这是 monorepo 隔离性的核心保障包允许导入禁止front-endshared、自身、sdk-js、sdk-reactback-end禁止直接导入 Radix UI 组件须用/ui/设计系统包装器back-endshared、自身、sdk-jsfront-end、sdk-react禁止直接导入node-fetch用back-end/src/util/http.util的fetchshared自身、sdk-jsback-end、front-end、sdk-reactpackages/shared/src/validators/*中禁止对 Zod schema 使用.default()改用 BaseModel 配置的defaultValuessdk-js / sdk-react仅自身React 可依赖 JS反之不行任何内部包零第三方依赖必须自包含以便 npm 发行指南还给出两条前端专属禁令不要用import { Button } from radix-ui/themes而要用import { Button } from /ui/Button涉及 Avatar、Badge、Button、Callout、Checkbox、DataList、DropdownMenu、Link、RadioCards、RadioGroup、Select、Switch、Table、Tabs 等组件不要直接使用window.history.pushState/replaceState而应使用next/router的router.push(url, undefined, { shallow: true })。5. 权限系统三层作用域 商业特性双闸门permissions.mdpermissions.md 是体量最大的一份指南描述 GrowthBook 的三层权限体系Global / Project-scoped / Environment-scoped并强调权限与商业特性是两道独立的闸门——两者都通过才放行。5.1 权限作用域划分全局权限组织级manageTeam、manageBilling、manageApiKeys、organizationSettings、viewAuditLog、createPresentations、createDimensions、manageNamespaces、manageCustomRoles、manageCustomFields、manageDecisionCriteria项目作用域权限可授予全部或特定项目readData、addComments三类 Flag 实体Features/Configs/Constants各自的edit*Drafts、review*、bypassApproval*targetFeatures通过 Targeting 项目把 Feature Flag 投放到另一个项目在被添加的项目上检查、Saved Group 全家桶editSavedGroupDrafts、reviewSavedGroups、publishSavedGroups等、createMetrics、createAnalyses、createSegments、manageFactTables、manageFactMetrics、createDatasources、editDatasourceSettings、runQueries等环境作用域权限进一步限制到项目内特定环境各 Flag 实体的create*、publish*、revert*线上写入、delete*归档是环境作用域的删除已归档的 Flag 则不是传NO_ENVIRONMENT_BINDING、runExperiments、manageEnvironments、manageSDKConnections、manageSDKWebhooks。5.2 前端usePermissionsUtil() 与条件渲染前端主要使用 usePermissions.ts 所在目录下的usePermissionsUtilhook按三层作用域分别检查import usePermissionsUtil from /hooks/usePermissionsUtil; function MyComponent() { const permissionsUtil usePermissionsUtil(); // 全局权限检查 if (!permissionsUtil.canManageTeam()) return NoAccess /; // 项目作用域检查 if (!permissionsUtil.canCreateFeature({ project: prj_123 })) return NoAccess /; // 环境作用域检查 if (!permissionsUtil.canPublishFeature(feature, [production])) return NoAccess /; return MyContent /; }指南列出的常用检查方法覆盖了 FeaturecanCreateFeature/canEditFeatureDrafts/canReviewFeatureDrafts/canPublishFeature/canRevertFeature、ExperimentcanCreateExperiment/canUpdateExperiment/canRunExperiment、MetriccanCreateMetric/canUpdateMetric/canDeleteMetric、ProjectcanReadSingleProjectResource/canReadMultiProjectResource/canManageSomeProjects等族系简单全局检查则可用usePermissions()直接读布尔字段如permissions.manageTeam。5.3 后端context.permissions 与草稿 vs 发布的权威划分后端从请求上下文取权限getContextFromReq(req)指南用一个完整示例阐明了最关键的一条纪律——编辑 草稿 发布写线上状态的 handler 必须用发布级权限门控const context getContextFromReq(req); const feature await getFeatureById(context, id); if (!feature) return res.status(404).json({ error: Feature not found }); // updateFeature 写的是 LIVE 状态所以按变更触及的环境做 publish 级检查 // 只有止步于 revision 的写入才允许用 canEditFeatureDrafts if ( !context.permissions.canPublishFeature( feature, Array.from(getEnabledEnvironments(feature, environmentIds)), ) ) { context.permissions.throwPermissionError(); }指南的注释块还解释了两个易错点实验的环境集合必须用getExperimentAffectedEnvs解析草稿实验在任何地方都不在线只做 live 检查会在启动时漏过延迟动作定时发布、定时状态变更必须以暂存该动作的用户身份重建上下文再执行检查而不是以 job 身份执行。模型层则通过重写canRead/canCreate/canUpdate/canDelete保护方法接入this.context.permissions。5.4 商业特性闸门与角色解析商业特性独立于权限用户可能有权限但组织套餐不含该特性。前端用useUser()的hasCommercialFeature(advanced-permissions)判定配合PremiumTooltip commercialFeature...包装展示升级提示后端用orgHasPremiumFeature(context.org, archetypes)并在不满足时抛PlanDoesNotAllowError。指南列出的常见商业特性包括advanced-permissions、teams、audit-logging、archetypes、templates、sso、encrypt-features-endpoint、ai-suggestions等其常量定义位于 license-consts.ts。权限解析顺序为用户的全局角色 → 项目级角色覆盖 → 团队角色最终用OR并集逻辑合并环境限制只作用于环境作用域权限。默认角色表noaccess、readonly、collaborator、visualEditor、engineer、analyst、experimenter、admin。指南给出的五条最佳实践值得特别注意尽早检查权限在产生任何落盘副作用之前而不是先建 revision 再检查使用具体权限方法而非裸布尔字段不存在 edit 动词——创作门控在canEditFeatureDrafts落地门控在canPublishFeature权限原子定义见revisionPermissions.ts角色从不直接命名原子组织授予的是把三类 Flag 实体打包的策略POLICY传入变更实际触及的环境——不要图省事传全部组织环境会要求变更本不需要的权限无环境变更基础 Config、Constant 基础值、删除已归档 Flag传NO_ENVIRONMENT_BINDING空数组会跳过环境检查切勿误传权限与商业特性两道闸门都要处理不要硬编码角色判断user.role ! admin这类写法被明确列为反例。权限相关代码位置常量在 permissions.constants.ts工具函数与权限类在同目录后端解析在 organization.util.ts。此外flag-family-authority.md 对同一体系做了更深的权威模型论述每次权限判定都由四个名词决定——Verb动词/原子、Scope项目、Footprint环境足迹、Basis判定基准状态任一选错都会产生读起来正确、逻辑上错误的检查REVISION_PERMISSIONS[model][action]是动词到权限、作用域类映射的唯一存放点不得重新推导。6. 用户文案规范双层大小写规则与名词表ui-copy-style.mdui-copy-style.md 统一约束所有面向用户的字符串——前端 UI 文案与后端 API 错误信息——规则相同仅载体不同。核心是双层大小写Heading元素用Title Case如 Data Source Settings其余一律sentence case字段标签、按钮、占位符、提示文本仅首词大写Save、Regenerate all命名资源永远 Title Case即使在句中也保持原样。名词表glossary是单一事实来源节选术语备注GrowthBook产品名不得写作 GrowthbookVisual Editor产品特性Data Source命名资源句内也 Title CaseFact Metric非指该资源时 metric 小写Feature Flag用户文案中用全称不用 Feature/Flag 简称Saved Group、SDK Connection命名资源Experiment Template完整复合词是命名资源裸 template 仍是普通名词Project、Constant、Config指 GrowthBook 资源时 Title Case指其他产品的 projectBigQuery/GCP、普通配置对象、config.yml文件时小写技术标识符experiment key、API key、token在行文中保持小写。指南给出的正反例非常具体API error: Feature key must be unique within the Project ✅ sentence case 命名资源 API error: Feature Key Must Be Unique ❌ 不是标题 API error: could not find data source ❌ 未大写开头且 Data Source 应为 Title Case API error: This Saved Group is in use ✅修改文案时若引入了新的第一级资源有独立侧栏入口/模型/顶层页面应在同一变更中更新该名词表。7. 文档 frontmatter 规则docs.mddocs.md 只讲一条硬规则但它是 CI 强制项MDX frontmatter 是 YAML冒号后跟空格: 会被解析为嵌套映射因此标题中的冒号必须给值加引号# 非法 title: AI Mode: Generate A/B Test Variations With AI # 正确 title: AI Mode: Generate A/B Test Variations With AI同样的规则适用于description、sidebarTitle等任意标量而https://example.com这类 URL 因冒号后无空格可以不加引号。CI 通过 scripts/check-docs-frontmatter.mjs 在 Docs workflow 中强制执行这一校验。8. 前端模式React 组件选型与 SWR 数据获取8.1 组件结构与 UI 组件优先级frontend/react-patterns.mdreact-patterns.md 要求使用 TypeScript 函数组件、props 用显式类型、复杂函数写显式返回类型。更核心的是UI 组件选型优先级设计系统/ui/首选Button、Badge、Checkbox、Select、Tabs、Table、Callout、DropdownMenu、Tooltip、Popover 等 20 余个组件全部禁止直接引 Radix UIRadix Themes次选仅当/ui/没有等价物时用Flex、Box、Grid、Text、Heading等布局原语既有领域组件packages/front-end/components/新建组件最后手段若模式通用可复用应先提议新增/ui/组件含.stories.tsx而不是内联一次性组件。尺寸系统有一条硬性约束所有/ui/尺寸属性使用同一衬衫尺码阶梯定义在 sizes.tssm/md/lg/xl映射 Radix 的1/2/3/4禁用 Radix 数字或sizemedium这类写法组件只声明自己支持的子集Sizesm | md通过radixSize()在 Radix 透传点做一次映射——组件缺少某档位时会通过类型系统在编译期暴露指南明确这是守护机制在工作不要 cast。指南同时给出 Bootstrap → 设计系统的迁移对照表如btn btn-primary→Button、badge bg-*→Badge、d-flex→Flex、row/col-*→Grid原则是小改动可以保留旧 Bootstrap 但不得新增重构时顺带迁移。8.2 数据获取useApi() 与 apiCall()frontend/data-fetching.mddata-fetching.md 规定 GrowthBook 前端统一用 SWR封装为 useApi.ts 的useApi()做读取、apiCall()做变更所有请求自动作用域到当前组织。基本用法与选项import useApi from /hooks/useApi; const { data, error, mutate } useApi{ items: ItemInterface[] }(/items); // 选项 useApiResponse(path, { shouldRun: () boolean, // 条件执行如 ID 就绪后才拉取 autoRevalidate: true, // 默认 truefocus/reconnect 时重新校验 orgScoped: true, // 默认 true缓存键带 orgId 前缀 });变更操作用useAuth()的apiCall()变更后调用mutate()刷新缓存全局性数据metrics/features/segments变更后用useDefinitions()的mutateDefinitions()。指南覆盖的错误处理模式包括try-catch state、Modal组件自动展示submit抛出的错误、以及useApi返回中直接检查error。此外还给出乐观更新先mutate(newData, false)再请求、失败回滚与多缓存并发刷新Promise.all([mutateFeatures(), mutateExperiments()])的完整示例。组织上下文方面所有请求自动携带Authorization: Bearer token与X-Organization: orgId头缓存键以orgId::前缀切换组织自动使全部缓存失效。9. 后端模式双 API 架构与 Spec 驱动的外部 REST API9.1 内部 APIcontroller/router 模式api-patterns.md 明确后端两套 API 的定位差异维度内部 API外部 REST API位置src/controllers/、src/routers/src/api/认证Session cookieAPI KeyAuthorization: Bearer key模式Controllers wrapControllerApiModel createApiRequestHandler受众GrowthBook Web 应用客户集成文档内部OpenAPI specURL 前缀/api/*/api/v1/*内部 API 的 controller 是命名导出的 HTTP handler用wrapController()包一层自动错误处理新 controller/router 必须放在src/routers/目录下不再往src/app.ts里加——那是旧做法且模型文件只导出函数与方法、不导出模型类本身。9.2 外部 REST APIZod spec 驱动的自动生成对由 BaseModel 支撑的端点指南要求使用apiConfig spec模式从 Zod 定义自动生成标准 CRUD 端点、OpenAPI 文档与路由。四步流程在src/api/specs/*.spec.ts写 OpenAPI specsatisfies OpenApiModelSpec必须带export default供生成脚本动态发现export const myResourceApiSpec { modelSingular: myResource, modelPlural: myResources, pathBase: /my-resources, apiInterface: apiMyResourceValidator, schemas: { createBody: apiCreateMyResourceBody, updateBody: apiUpdateMyResourceBody }, includeDefaultCrud: true, // 生成 get / create / list / update / delete } satisfies OpenApiModelSpec;在模型的MakeModelClass调用中接入apiConfig: { modelKey, openApiSpec }自动生成GET/POST/PUT/DELETE /api/v1/my-resources[...]把模型类加入 api.router.ts 中的API_MODELS数组完成路由注册必须实现toApiInterface——把内部文档映射为 API 响应形状否则内部模型的任何改动都会立刻泄漏到 API 契约中。进阶机制包括用overrideParametersInstanceTypetypeof BaseClass[handleApiGet][0]重写标准 handler类型自动与 validator 保持同步用crudValidatorOverrides为 delete/list 追加 query 参数类型会自动传导到req.query自定义端点把文档元数据spec与运行时逻辑defineCustomApiHandler的reqHandler分离顶层 API 模型用namedSchema包装使其以$ref形式出现在 OpenAPI 的components/schemas/。OpenAPI spec 由 generate-openapi.ts 从 Zod validator 生成修改校验器或端点后需重新生成并提交pnpm --filter back-end generate-openapiownerEmail 解析每个带 owner 的外部 API 响应都必须同时暴露解析后的ownerEmail。默认handleApi*实现已内置该包装一旦重写这些方法或编写非 BaseModel 端点就要在最终 API 形状上调用 services/owner.ts 的resolveOwnerEmail单文档/resolveOwnerEmails列表批量查库——不要塞进同步的toApiInterface里。调度与 Ramp 的计划级门控指南末尾一节简单调度规则schedule简写与多步 ramp 调度共用同一引擎整套 ramp 家族schedule-feature-flag、ramp-schedules、safe-rollout同属 Pro 套餐且只门控新建调度——已低于 Pro 的组织仍可编辑/暂停/取消既有调度以便收尾eject-target与DELETE等清理动作刻意不做审批门控。10. 其他指南与落地方式除上述主指南外目录中还包含两份架构级深潜文档revisions-architecture.md描述 Config/Constant/Saved Group 的通用修订引擎与 Feature Flag 专属引擎的对照落地顺序相反通用引擎先 claim 后写 liveFeature 引擎SINGLE 发布先写 live 后 claim并说明崩溃后的恢复路径recoverStrandedMerge等规则集中在landAuthority.ts、reviewCycle.ts、casLoop.tsbackend/legacy-model-migration-patterns.md 与 backend/warehouse-column-casing.md分别约束旧模型向新模式的迁移写法与数仓列名大小写处理。11. 小结指南如何从文档变成约束GrowthBook 的 Agent 指南体系有几个可复用的工程实践单一事实来源 指针式挂载规则正文只存在于.agents/guides/各提供商配置AGENTS.md / CLAUDE.md只保留指针避免多处漂移文档规则与机器校验一一对应包边界由 ESLint 强制、frontmatter 由check-docs-frontmatter.mjs在 CI 强制、类型与格式由pnpm type-check/pnpm lint:ci/pnpm pretty:check覆盖pnpm ci一条命令复现全部校验正反例并置每份指南都给出BAD/GOOD对照注释、权限检查时机、文案大小写让规则可被逐行核对而非停留在抽象描述权限与套餐是双闸门permissionsUtil与hasCommercialFeature/orgHasPremiumFeature的组合模式贯穿前后端避免了有权限但套餐不允许这类半通过状态。对参与该仓库开发或接入编码代理的工程师来说正确的阅读顺序是先 AGENTS.md 掌握命令与架构再按本次变更涉及的层读取对应指南——动 UI 读 react-patterns.md 与 ui-copy-style.md动权限读 permissions.md 与 flag-family-authority.md动 API 读 api-patterns.md动docs/读 docs.md——最后用pnpm ci验证一切。赞分享后端前端数据分析数据可视化【免费下载链接】growthbookOpen Source Feature Flags, Experimentation, and Product Analytics项目地址https://gitcode.com/gh_mirrors/gr/growthbook点击查看免费下载相关推荐open-agents CLAUDE.md为 AI 编码 Agent 建立可执行的工程规范的实践剖析open agents CLAUDE.md为 AI 编码 Agent 建立可执行的工程规范的实践剖析 Open Agents 仓库根目录的 CLAUDE.md人工智能AI Agent代码智能体Agent 工作流Agent 沙箱工具调用后端前端Foam AGENTS.md 深度解读如何为 AI 编码代理编写一套可执行的仓库协作规范Foam AGENTS.md 深度解读如何为 AI 编码代理编写一套可执行的仓库协作规范 Foam一个面向 VSCode 的个人知识管理与共享系统的仓库根知识管理知识库开发工具MCP 服务Feast 仓库 AI Agent 开发指南环境搭建、命令体系、Agent Skills 与代码规范Feast 仓库 AI Agent 开发指南环境搭建、命令体系、Agent Skills 与代码规范 本文以 Feast 仓库根目录的 AGENTS.md hMLOps后端数据工程上一篇Lance 对象存储配置完全指南S3 / Azure / GCS / OSS / TOS / COS / GooseFS 的 storage_options 详解下一篇Android Studio中文界面汉化完整指南3步快速打造中文开发环境创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 GrowthBook Agent 指南体系：.agents/guides 如何为编码代理建立可执行的仓库规范
后端前端数据分析数据可视化【免费下载链接】growthbookOpen Source Feature Flags, Experimentation, and Product Analytics项目地址https://gitcode.com/gh_mirrors/gr/growthbook点击查看免费下载本篇技术文章基于 GrowthBook 仓库中的 .agents/guides/README.md 展开。该目录是 GrowthBook 为所有编码代理coding agent设计的规范指南之家canonical home采用工具无关tool-neutral的组织方式根目录与各包中的 AGENTS.md、CLAUDE.md 等提供商配置只负责挂载指针真正的规则细节统一沉淀在.agents/guides/下。读完本文你将了解这套指南的目录架构、各份指南的核心规则包边界、权限系统、UI 文案规范、数据获取与 API 模式等以及它们如何通过 ESLint 与 CI 命令从文档变成可执行的约束。1. 设计原则指南与提供商配置分离.agents/guides/README.md 开宗明义地给出两条组织原则该目录是所有编码代理共享的详细仓库指南的规范归属地指南内容必须保持工具无关——提供商特定的配置如 AGENTS.md、CLAUDE.md只应包含附加相关指南所需的元数据或指针而不应复制规则正文。这一设计的收益很直接规则只有一份事实来源single source of truth任何代理工具接入时都只需指向同一份指南规则更新不需要多处同步。仓库根目录的 AGENTS.md 即为各代理的总入口提供构建、开发与代码质量命令而更细粒度的领域规则则按主题拆分到指南目录中。指南目录的完整清单如下相对路径均以仓库根目录为起点指南文件覆盖内容project-overview.mdMonorepo 架构与包职责划分development-guidelines.md全项目编码约定与校验命令package-boundaries.md被强制执行的导入与依赖限制permissions.md权限与商业特性commercial feature模式ui-copy-style.md所有面向用户文案的大小写与措辞规则docs.mdMintlify MDX frontmatter 规则frontend/react-patterns.mdReact 组件与 UI 组件选型模式frontend/data-fetching.mdSWR 数据获取与变更mutation模式backend/api-patterns.md内部 API 与外部 REST API 的构建模式backend/model-patterns.md数据模型BaseModel模式backend/legacy-model-migration-patterns.md旧模型迁移模式backend/warehouse-column-casing.md数仓列大小写规则flag-family-authority.mdFlag 家族的权限权威判定模型revisions-architecture.md修订revision引擎架构2. Monorepo 架构与包职责project-overview.mdproject-overview.md 描述了 GrowthBook 的工程骨架这是所有后续指南的上下文前提仓库由pnpm workspaces管理见 pnpm-workspace.yaml仅声明packages/*一个 glob必须使用pnpm禁止 npm 或 yarn各包的定位与开发端口包职责关键事实packages/front-endNext.js 应用完整 UI开发时运行于 http://localhost:3000React 函数组件路径别名/packages/back-endExpress API 服务运行于 http://localhost:3100MongoDB 为主存储内部导入使用back-end/前缀packages/shared共享 TypeScript 代码类型、工具、校验器、常量禁止 UI 组件或服务端专属代码packages/statsPython 统计引擎gbstatsPython 3.9Poetry 管理依赖使用 pandas/numpy/scipypackages/sdk-jsJS SDKnpm 名growthbook/growthbook与内部包完全隔离packages/sdk-reactReact SDKnpm 名growthbook/growthbook-react与内部包完全隔离指南还特别标注了企业版代码的位置packages/front-end/enterprise/、packages/back-end/src/enterprise/、packages/shared/src/enterprise/并明确通常不接受外部对 enterprise 目录的贡献。值得注意的是 back-end 提供两套独立的 API这一架构在 backend/api-patterns.md 中有完整展开供 GrowthBook 前端使用的内部 APIsrc/controllers/src/routers/以及供客户集成的外部 REST APIsrc/api/挂载在/api/v1/前缀下。3. 开发约定从注释纪律到质量命令development-guidelines.mddevelopment-guidelines.md 是全项目通用的编码约定几个要点测试策略不要求为前端组件或后端 router/controller/model 写测试但关键工具/辅助函数必须有测试。注释纪律附正反例// ❌ BAD — 叙述显而易见的内容、过度解释 // GET /configs/:id/references — features, constants, and configs that // reference this config via const:key. Scoped to the project globals. router.get(/:id/references, ...) // ✅ GOOD — 只保留代码无法传达的非显然约束 // Spans both collections: configs and constants share the const: namespace. router.get(/:id/references, ...)类型安全规则严格类型禁用any类型未知时用unknown来自不可信来源的数据请求体、JSON.parse先按unknown处理通常用 zod 校验未使用变量尽量避免必须保留时以下划线_前缀生产代码避免console.logESLint 会警告后端可从util/logger导入替代。Zod 校验范式指南给出的标准写法import { z } from zod; const mySchema z.object({ name: z.string(), count: z.number().int().positive(), }); type MyType z.infertypeof mySchema;类型定义位置共享类型放在packages/shared/types/*.d.ts只用.d.ts文件做纯类型定义有 Zod schema 时以 schema 为唯一事实来源并infer类型不要重复手写 interface。环境变量后端统一定义在 secrets.ts前端定义在 init.ts 与 env.ts其他任何文件都不得直接引用process.env。代码质量命令与 AGENTS.md 中的命令表一致pnpm pretty # 格式化写入 pnpm pretty:check # 仅校验格式 pnpm lint # ESLint 自动修复 pnpm lint:ci # 仅校验 lint node scripts/check-docs-frontmatter.mjs # 校验文档 frontmatter引用含 : 的 YAML 值 pnpm type-check # 全包类型检查 pnpm ci # CI 执行的完整校验链指南最后列出九条关键原则其中最具项目特色的是遵守包边界、前端使用设计系统组件不直接引 Radix UI、新增模型默认使用 BaseModel、权限检查必须走permissionsUtil、高级功能必须用hasCommercialFeature()判定。4. 包边界ESLint 强制执行的导入矩阵package-boundaries.mdpackage-boundaries.md 定义了一套由 ESLint 强制的包间导入限制这是 monorepo 隔离性的核心保障包允许导入禁止front-endshared、自身、sdk-js、sdk-reactback-end禁止直接导入 Radix UI 组件须用/ui/设计系统包装器back-endshared、自身、sdk-jsfront-end、sdk-react禁止直接导入node-fetch用back-end/src/util/http.util的fetchshared自身、sdk-jsback-end、front-end、sdk-reactpackages/shared/src/validators/*中禁止对 Zod schema 使用.default()改用 BaseModel 配置的defaultValuessdk-js / sdk-react仅自身React 可依赖 JS反之不行任何内部包零第三方依赖必须自包含以便 npm 发行指南还给出两条前端专属禁令不要用import { Button } from radix-ui/themes而要用import { Button } from /ui/Button涉及 Avatar、Badge、Button、Callout、Checkbox、DataList、DropdownMenu、Link、RadioCards、RadioGroup、Select、Switch、Table、Tabs 等组件不要直接使用window.history.pushState/replaceState而应使用next/router的router.push(url, undefined, { shallow: true })。5. 权限系统三层作用域 商业特性双闸门permissions.mdpermissions.md 是体量最大的一份指南描述 GrowthBook 的三层权限体系Global / Project-scoped / Environment-scoped并强调权限与商业特性是两道独立的闸门——两者都通过才放行。5.1 权限作用域划分全局权限组织级manageTeam、manageBilling、manageApiKeys、organizationSettings、viewAuditLog、createPresentations、createDimensions、manageNamespaces、manageCustomRoles、manageCustomFields、manageDecisionCriteria项目作用域权限可授予全部或特定项目readData、addComments三类 Flag 实体Features/Configs/Constants各自的edit*Drafts、review*、bypassApproval*targetFeatures通过 Targeting 项目把 Feature Flag 投放到另一个项目在被添加的项目上检查、Saved Group 全家桶editSavedGroupDrafts、reviewSavedGroups、publishSavedGroups等、createMetrics、createAnalyses、createSegments、manageFactTables、manageFactMetrics、createDatasources、editDatasourceSettings、runQueries等环境作用域权限进一步限制到项目内特定环境各 Flag 实体的create*、publish*、revert*线上写入、delete*归档是环境作用域的删除已归档的 Flag 则不是传NO_ENVIRONMENT_BINDING、runExperiments、manageEnvironments、manageSDKConnections、manageSDKWebhooks。5.2 前端usePermissionsUtil() 与条件渲染前端主要使用 usePermissions.ts 所在目录下的usePermissionsUtilhook按三层作用域分别检查import usePermissionsUtil from /hooks/usePermissionsUtil; function MyComponent() { const permissionsUtil usePermissionsUtil(); // 全局权限检查 if (!permissionsUtil.canManageTeam()) return NoAccess /; // 项目作用域检查 if (!permissionsUtil.canCreateFeature({ project: prj_123 })) return NoAccess /; // 环境作用域检查 if (!permissionsUtil.canPublishFeature(feature, [production])) return NoAccess /; return MyContent /; }指南列出的常用检查方法覆盖了 FeaturecanCreateFeature/canEditFeatureDrafts/canReviewFeatureDrafts/canPublishFeature/canRevertFeature、ExperimentcanCreateExperiment/canUpdateExperiment/canRunExperiment、MetriccanCreateMetric/canUpdateMetric/canDeleteMetric、ProjectcanReadSingleProjectResource/canReadMultiProjectResource/canManageSomeProjects等族系简单全局检查则可用usePermissions()直接读布尔字段如permissions.manageTeam。5.3 后端context.permissions 与草稿 vs 发布的权威划分后端从请求上下文取权限getContextFromReq(req)指南用一个完整示例阐明了最关键的一条纪律——编辑 草稿 发布写线上状态的 handler 必须用发布级权限门控const context getContextFromReq(req); const feature await getFeatureById(context, id); if (!feature) return res.status(404).json({ error: Feature not found }); // updateFeature 写的是 LIVE 状态所以按变更触及的环境做 publish 级检查 // 只有止步于 revision 的写入才允许用 canEditFeatureDrafts if ( !context.permissions.canPublishFeature( feature, Array.from(getEnabledEnvironments(feature, environmentIds)), ) ) { context.permissions.throwPermissionError(); }指南的注释块还解释了两个易错点实验的环境集合必须用getExperimentAffectedEnvs解析草稿实验在任何地方都不在线只做 live 检查会在启动时漏过延迟动作定时发布、定时状态变更必须以暂存该动作的用户身份重建上下文再执行检查而不是以 job 身份执行。模型层则通过重写canRead/canCreate/canUpdate/canDelete保护方法接入this.context.permissions。5.4 商业特性闸门与角色解析商业特性独立于权限用户可能有权限但组织套餐不含该特性。前端用useUser()的hasCommercialFeature(advanced-permissions)判定配合PremiumTooltip commercialFeature...包装展示升级提示后端用orgHasPremiumFeature(context.org, archetypes)并在不满足时抛PlanDoesNotAllowError。指南列出的常见商业特性包括advanced-permissions、teams、audit-logging、archetypes、templates、sso、encrypt-features-endpoint、ai-suggestions等其常量定义位于 license-consts.ts。权限解析顺序为用户的全局角色 → 项目级角色覆盖 → 团队角色最终用OR并集逻辑合并环境限制只作用于环境作用域权限。默认角色表noaccess、readonly、collaborator、visualEditor、engineer、analyst、experimenter、admin。指南给出的五条最佳实践值得特别注意尽早检查权限在产生任何落盘副作用之前而不是先建 revision 再检查使用具体权限方法而非裸布尔字段不存在 edit 动词——创作门控在canEditFeatureDrafts落地门控在canPublishFeature权限原子定义见revisionPermissions.ts角色从不直接命名原子组织授予的是把三类 Flag 实体打包的策略POLICY传入变更实际触及的环境——不要图省事传全部组织环境会要求变更本不需要的权限无环境变更基础 Config、Constant 基础值、删除已归档 Flag传NO_ENVIRONMENT_BINDING空数组会跳过环境检查切勿误传权限与商业特性两道闸门都要处理不要硬编码角色判断user.role ! admin这类写法被明确列为反例。权限相关代码位置常量在 permissions.constants.ts工具函数与权限类在同目录后端解析在 organization.util.ts。此外flag-family-authority.md 对同一体系做了更深的权威模型论述每次权限判定都由四个名词决定——Verb动词/原子、Scope项目、Footprint环境足迹、Basis判定基准状态任一选错都会产生读起来正确、逻辑上错误的检查REVISION_PERMISSIONS[model][action]是动词到权限、作用域类映射的唯一存放点不得重新推导。6. 用户文案规范双层大小写规则与名词表ui-copy-style.mdui-copy-style.md 统一约束所有面向用户的字符串——前端 UI 文案与后端 API 错误信息——规则相同仅载体不同。核心是双层大小写Heading元素用Title Case如 Data Source Settings其余一律sentence case字段标签、按钮、占位符、提示文本仅首词大写Save、Regenerate all命名资源永远 Title Case即使在句中也保持原样。名词表glossary是单一事实来源节选术语备注GrowthBook产品名不得写作 GrowthbookVisual Editor产品特性Data Source命名资源句内也 Title CaseFact Metric非指该资源时 metric 小写Feature Flag用户文案中用全称不用 Feature/Flag 简称Saved Group、SDK Connection命名资源Experiment Template完整复合词是命名资源裸 template 仍是普通名词Project、Constant、Config指 GrowthBook 资源时 Title Case指其他产品的 projectBigQuery/GCP、普通配置对象、config.yml文件时小写技术标识符experiment key、API key、token在行文中保持小写。指南给出的正反例非常具体API error: Feature key must be unique within the Project ✅ sentence case 命名资源 API error: Feature Key Must Be Unique ❌ 不是标题 API error: could not find data source ❌ 未大写开头且 Data Source 应为 Title Case API error: This Saved Group is in use ✅修改文案时若引入了新的第一级资源有独立侧栏入口/模型/顶层页面应在同一变更中更新该名词表。7. 文档 frontmatter 规则docs.mddocs.md 只讲一条硬规则但它是 CI 强制项MDX frontmatter 是 YAML冒号后跟空格: 会被解析为嵌套映射因此标题中的冒号必须给值加引号# 非法 title: AI Mode: Generate A/B Test Variations With AI # 正确 title: AI Mode: Generate A/B Test Variations With AI同样的规则适用于description、sidebarTitle等任意标量而https://example.com这类 URL 因冒号后无空格可以不加引号。CI 通过 scripts/check-docs-frontmatter.mjs 在 Docs workflow 中强制执行这一校验。8. 前端模式React 组件选型与 SWR 数据获取8.1 组件结构与 UI 组件优先级frontend/react-patterns.mdreact-patterns.md 要求使用 TypeScript 函数组件、props 用显式类型、复杂函数写显式返回类型。更核心的是UI 组件选型优先级设计系统/ui/首选Button、Badge、Checkbox、Select、Tabs、Table、Callout、DropdownMenu、Tooltip、Popover 等 20 余个组件全部禁止直接引 Radix UIRadix Themes次选仅当/ui/没有等价物时用Flex、Box、Grid、Text、Heading等布局原语既有领域组件packages/front-end/components/新建组件最后手段若模式通用可复用应先提议新增/ui/组件含.stories.tsx而不是内联一次性组件。尺寸系统有一条硬性约束所有/ui/尺寸属性使用同一衬衫尺码阶梯定义在 sizes.tssm/md/lg/xl映射 Radix 的1/2/3/4禁用 Radix 数字或sizemedium这类写法组件只声明自己支持的子集Sizesm | md通过radixSize()在 Radix 透传点做一次映射——组件缺少某档位时会通过类型系统在编译期暴露指南明确这是守护机制在工作不要 cast。指南同时给出 Bootstrap → 设计系统的迁移对照表如btn btn-primary→Button、badge bg-*→Badge、d-flex→Flex、row/col-*→Grid原则是小改动可以保留旧 Bootstrap 但不得新增重构时顺带迁移。8.2 数据获取useApi() 与 apiCall()frontend/data-fetching.mddata-fetching.md 规定 GrowthBook 前端统一用 SWR封装为 useApi.ts 的useApi()做读取、apiCall()做变更所有请求自动作用域到当前组织。基本用法与选项import useApi from /hooks/useApi; const { data, error, mutate } useApi{ items: ItemInterface[] }(/items); // 选项 useApiResponse(path, { shouldRun: () boolean, // 条件执行如 ID 就绪后才拉取 autoRevalidate: true, // 默认 truefocus/reconnect 时重新校验 orgScoped: true, // 默认 true缓存键带 orgId 前缀 });变更操作用useAuth()的apiCall()变更后调用mutate()刷新缓存全局性数据metrics/features/segments变更后用useDefinitions()的mutateDefinitions()。指南覆盖的错误处理模式包括try-catch state、Modal组件自动展示submit抛出的错误、以及useApi返回中直接检查error。此外还给出乐观更新先mutate(newData, false)再请求、失败回滚与多缓存并发刷新Promise.all([mutateFeatures(), mutateExperiments()])的完整示例。组织上下文方面所有请求自动携带Authorization: Bearer token与X-Organization: orgId头缓存键以orgId::前缀切换组织自动使全部缓存失效。9. 后端模式双 API 架构与 Spec 驱动的外部 REST API9.1 内部 APIcontroller/router 模式api-patterns.md 明确后端两套 API 的定位差异维度内部 API外部 REST API位置src/controllers/、src/routers/src/api/认证Session cookieAPI KeyAuthorization: Bearer key模式Controllers wrapControllerApiModel createApiRequestHandler受众GrowthBook Web 应用客户集成文档内部OpenAPI specURL 前缀/api/*/api/v1/*内部 API 的 controller 是命名导出的 HTTP handler用wrapController()包一层自动错误处理新 controller/router 必须放在src/routers/目录下不再往src/app.ts里加——那是旧做法且模型文件只导出函数与方法、不导出模型类本身。9.2 外部 REST APIZod spec 驱动的自动生成对由 BaseModel 支撑的端点指南要求使用apiConfig spec模式从 Zod 定义自动生成标准 CRUD 端点、OpenAPI 文档与路由。四步流程在src/api/specs/*.spec.ts写 OpenAPI specsatisfies OpenApiModelSpec必须带export default供生成脚本动态发现export const myResourceApiSpec { modelSingular: myResource, modelPlural: myResources, pathBase: /my-resources, apiInterface: apiMyResourceValidator, schemas: { createBody: apiCreateMyResourceBody, updateBody: apiUpdateMyResourceBody }, includeDefaultCrud: true, // 生成 get / create / list / update / delete } satisfies OpenApiModelSpec;在模型的MakeModelClass调用中接入apiConfig: { modelKey, openApiSpec }自动生成GET/POST/PUT/DELETE /api/v1/my-resources[...]把模型类加入 api.router.ts 中的API_MODELS数组完成路由注册必须实现toApiInterface——把内部文档映射为 API 响应形状否则内部模型的任何改动都会立刻泄漏到 API 契约中。进阶机制包括用overrideParametersInstanceTypetypeof BaseClass[handleApiGet][0]重写标准 handler类型自动与 validator 保持同步用crudValidatorOverrides为 delete/list 追加 query 参数类型会自动传导到req.query自定义端点把文档元数据spec与运行时逻辑defineCustomApiHandler的reqHandler分离顶层 API 模型用namedSchema包装使其以$ref形式出现在 OpenAPI 的components/schemas/。OpenAPI spec 由 generate-openapi.ts 从 Zod validator 生成修改校验器或端点后需重新生成并提交pnpm --filter back-end generate-openapiownerEmail 解析每个带 owner 的外部 API 响应都必须同时暴露解析后的ownerEmail。默认handleApi*实现已内置该包装一旦重写这些方法或编写非 BaseModel 端点就要在最终 API 形状上调用 services/owner.ts 的resolveOwnerEmail单文档/resolveOwnerEmails列表批量查库——不要塞进同步的toApiInterface里。调度与 Ramp 的计划级门控指南末尾一节简单调度规则schedule简写与多步 ramp 调度共用同一引擎整套 ramp 家族schedule-feature-flag、ramp-schedules、safe-rollout同属 Pro 套餐且只门控新建调度——已低于 Pro 的组织仍可编辑/暂停/取消既有调度以便收尾eject-target与DELETE等清理动作刻意不做审批门控。10. 其他指南与落地方式除上述主指南外目录中还包含两份架构级深潜文档revisions-architecture.md描述 Config/Constant/Saved Group 的通用修订引擎与 Feature Flag 专属引擎的对照落地顺序相反通用引擎先 claim 后写 liveFeature 引擎SINGLE 发布先写 live 后 claim并说明崩溃后的恢复路径recoverStrandedMerge等规则集中在landAuthority.ts、reviewCycle.ts、casLoop.tsbackend/legacy-model-migration-patterns.md 与 backend/warehouse-column-casing.md分别约束旧模型向新模式的迁移写法与数仓列名大小写处理。11. 小结指南如何从文档变成约束GrowthBook 的 Agent 指南体系有几个可复用的工程实践单一事实来源 指针式挂载规则正文只存在于.agents/guides/各提供商配置AGENTS.md / CLAUDE.md只保留指针避免多处漂移文档规则与机器校验一一对应包边界由 ESLint 强制、frontmatter 由check-docs-frontmatter.mjs在 CI 强制、类型与格式由pnpm type-check/pnpm lint:ci/pnpm pretty:check覆盖pnpm ci一条命令复现全部校验正反例并置每份指南都给出BAD/GOOD对照注释、权限检查时机、文案大小写让规则可被逐行核对而非停留在抽象描述权限与套餐是双闸门permissionsUtil与hasCommercialFeature/orgHasPremiumFeature的组合模式贯穿前后端避免了有权限但套餐不允许这类半通过状态。对参与该仓库开发或接入编码代理的工程师来说正确的阅读顺序是先 AGENTS.md 掌握命令与架构再按本次变更涉及的层读取对应指南——动 UI 读 react-patterns.md 与 ui-copy-style.md动权限读 permissions.md 与 flag-family-authority.md动 API 读 api-patterns.md动docs/读 docs.md——最后用pnpm ci验证一切。赞分享后端前端数据分析数据可视化【免费下载链接】growthbookOpen Source Feature Flags, Experimentation, and Product Analytics项目地址https://gitcode.com/gh_mirrors/gr/growthbook点击查看免费下载相关推荐open-agents CLAUDE.md为 AI 编码 Agent 建立可执行的工程规范的实践剖析open agents CLAUDE.md为 AI 编码 Agent 建立可执行的工程规范的实践剖析 Open Agents 仓库根目录的 CLAUDE.md人工智能AI Agent代码智能体Agent 工作流Agent 沙箱工具调用后端前端Foam AGENTS.md 深度解读如何为 AI 编码代理编写一套可执行的仓库协作规范Foam AGENTS.md 深度解读如何为 AI 编码代理编写一套可执行的仓库协作规范 Foam一个面向 VSCode 的个人知识管理与共享系统的仓库根知识管理知识库开发工具MCP 服务Feast 仓库 AI Agent 开发指南环境搭建、命令体系、Agent Skills 与代码规范Feast 仓库 AI Agent 开发指南环境搭建、命令体系、Agent Skills 与代码规范 本文以 Feast 仓库根目录的 AGENTS.md hMLOps后端数据工程上一篇Lance 对象存储配置完全指南S3 / Azure / GCS / OSS / TOS / COS / GooseFS 的 storage_options 详解下一篇Android Studio中文界面汉化完整指南3步快速打造中文开发环境创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考