Opik Architect Agent 深度解析AI 架构师如何驱动 Opik 的 API、Schema 与跨组件设计决策【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llmcomet-llmOpik仓库在.agents/agents/目录下维护了一套面向 AI Agent 的专职角色定义其中 architect.md 是“软件架构师”角色的完整规格书它定义了 Agent 的触发条件、五大核心职责、Opik 系统分层架构、五步设计流程、标准化的设计文档输出模板与五条设计原则。本文以该文档为主体逐节展开其机制并对照仓库中的前端依赖、后端配置、技能文档与迁移脚本验证文档中每一处架构断言在源码层面的实际落点帮助读者理解“用 Agent 化方式做架构设计”在大型 monorepo 中的完整工程实践。一、architect.md 在 Agent 体系中的位置Opik 的 Agent 基础设施集中在 .agents/ 目录从源码结构看可划分为四个层次子目录职责典型内容agents/专职角色定义本文主角architect.md、planner.md、code-reviewer.md、test-runner.md、meta-auditor.mdcommands/可执行工作流命令create-pr.md、work-on-github-issue.md、investigate-e2e-failure.md等skills/领域知识与模式库opik-backend、opik-frontend、python-sdk、typescript-sdk 等 18 个技能索引见 skills/README.mdrules/全局部署规则agents.mdc 定义了按路径到领域技能的路由表architect 与同级 planner、code-reviewer 是同一套“角色卡片”格式YAML frontmatter 声明元数据正文注入系统提示词。这种设计的核心思想是把架构决策所需的领域知识系统拓扑、分层约定、迁移策略固化为 Agent 可读的规格使每次设计输出风格一致、可追溯。二、角色定义与触发条件文档第 145 行是 YAML frontmatterarchitect.md关键字段及其含义如下name: architect description: | Use this agent when the user needs system design, API design, database schema changes, or architectural decisions. model: sonnet color: magenta tools: [Read, Grep, Glob]model: sonnet指定由 Sonnet 级模型驱动与同级 planner.md 一致而 code-reviewer.md 使用model: inherit继承父模型。tools: [Read, Grep, Glob]architect 只有只读工具——能读文件、正则搜索、按 glob 匹配文件但没有Bash等执行工具。这与其“设计而非施工”的定位严格对应架构师只负责探索现状与输出方案不直接修改代码。对比 code-reviewer 的工具列表[Read, Grep, Glob, Bash]后者需要执行git diff获取变更上下文才被授予了命令执行能力。color: magentaAgent 在宿主环境中的展示颜色planner 为 blue、code-reviewer 为 cyan形成视觉区分。四个触发场景description字段内嵌了四个 few-shot 示例architect.md用example/commentary标签给出“用户话语 → 触发判断”的映射触发场景用户示例话语架构师介入点新系统设计“How should I design the new metrics aggregation system?”系统架构设计数据库变更“I need to add a new table for experiment comparisons”Schema 与集成设计API 设计“What should the API look like for the new prompt versioning feature?”契约设计横切关注点“How should we handle authentication across the SDKs?”跨组件一致性方案这四个例子恰好覆盖了后文“核心职责”中最高频的三类设计对象系统、数据模型、API 契约以及一类跨边界问题横切关注点。示例中的领域名词metrics aggregation、experiment comparisons、prompt versioning都直接取材于 Opik 的真实功能域使触发判断贴合本仓库语境而非泛泛的通用描述。三、Opik 系统架构文档断言与仓库证据文档中段architect.md用 ASCII 图刻画了 Opik 的整体拓扑这是 architect Agent 做一切设计判断的“世界观”前提┌─────────────────────────────────────────────────────────────┐ │ Frontend (React) │ │ TanStack Query/Router • Zustand • shadcn/ui │ │ localhost:5174 (dev) • localhost:5173 (BE-only) │ └─────────────────────────────────────────────────────────────┘ │ REST API ▼ ┌─────────────────────────────────────────────────────────────┐ │ Backend (Java/Dropwizard) │ │ Resources → Services → DAOs │ │ localhost:8080 │ └─────────────────────────────────────────────────────────────┘ │ ┌───────────────────┼───────────────────┐ ▼ ▼ ▼ ┌─────────┐ ┌──────────┐ ┌─────────┐ │ MySQL │ │ClickHouse│ │ Redis │ │ (config,│ │ (traces, │ │ (cache) │ │ metadata)│ │ spans) │ │ │ └─────────┘ └──────────┘ └──────────┘ ┌─────────────────────────────────────────────────────────────┐ │ SDKs │ │ Python (opik) │ TypeScript (opik) │ │ Async batching → REST API │ └─────────────────────────────────────────────────────────────┘图中每一处技术断言都能在仓库中找到对应证据前端栈。apps/opik-frontend/package.json 的依赖清单确认了tanstack/react-query ^5.45.0、tanstack/react-router ^1.36.3、zustand ^4.5.2shadcn/ui 的底座 Radix 组件族radix-ui/react-dialog、radix-ui/react-tooltip等数十个包同样在依赖中列明。开发端口方面apps/opik-frontend/vite.config.ts 的注释明确写着VITE_DEV_PORT: Frontend dev server port (default: 5174)、VITE_BACKEND_PORT: Backend server port for proxy target (default: 8080)——与图中 “localhost:5174 (dev) / localhost:8080” 完全吻合。后端分层。Resources → Services → DAOs的分层规则被 .agents/skills/opik-backend/SKILL.md 强化为“Layered: Resource → Service → DAO (never skip layers)”并规定了单复数命名法Resource/URL/表名用复数TracesResource、/v1/private/traces、tracesDAO/Service 用单数TraceDAO、TraceService。architect 做 API 与 Schema 设计时“一致性”原则的实际抓手就是这套约定。双数据库 缓存拓扑。apps/opik-backend/config.yml 是 Dropwizard 主配置其中database段默认jdbc:mysql://localhost:3306/opik状态库/元数据databaseAnalytics段默认localhost:8123的 ClickHouse分析库与图中 “MySQL(config, metadata) ClickHouse(traces, spans)” 的分工一一对应该 skill 文档进一步解释了分工动机MySQL 承载“transactional”事务数据ClickHouse 承载“append-only”分析数据。配置中还存在databaseAnalyticsMigrations等迁移专用连接段说明双库拓扑在迁移路径上也有独立配置面。SDK 写入路径。图中 “Async batching → REST API” 描述的是 SDK 通过异步批量上报接入后端 REST 接口的方式对应的 SDK 实现分别位于 sdks/python 与 sdks/typescript。四、五步设计流程从需求到迁移策略文档的 “Design Process”architect.md把架构工作拆成五个有序步骤。以下逐节展开原文检查项并补充仓库中对应的实操支撑。Step 1: Requirements Analysis需求分析原文检查项What problem are we solving?Who are the users? What are their workflows?What are the constraints (performance, compatibility, timeline)?Whats explicitly out of scope?对 Opik 这类追踪 LLM 应用的平台而言“constraints” 一项尤其关键traces/spans 的写入是 append-only 高吞吐场景任何新表设计都要回答“在 ClickHouse 上如何落地”。配套的 opik-backend/migrations.md 定义了 MySQL/ClickHouse 的 Liquibase 迁移格式query-performance 技能则要求“在合并前验证 ClickHouse 查询的真实代价”把性能约束从口号变成了可执行检查。Step 2: Codebase Exploration代码库探索原文检查项Find similar features and understand their patternsIdentify affected components and blast radiusNote any technical debt or constraintsarchitect 的Grep/Glob只读工具正是为这一步配备的。探索时可直接引用各领域的 skill 文档作为“模式地图”后端看 opik-backend、前端看 opik-frontend、SDK 分别看 python-sdk 与 typescript-sdk。“blast radius”影响面的评估依据则是 .agents/rules/agents.mdc 中的领域路由表——它规定了apps/opik-backend/**、apps/opik-frontend/**、sdks/python/**等路径到技能的映射帮助设计者圈定变更波及的组件边界。Step 3: Solution Design方案设计原文检查项Data modelentities, relationships, storageAPI contractsendpoints, request/response shapesComponent interactionssequence diagramsError handling and edge casesOpik 后端对这三类产出都有硬性格式约束architect 设计时应当直接引用而非自创数据模型SQL 只能以 text block 声明一次可变值走:placeholder .bind(...)可变片段走 StringTemplate 的if(x)…endif——opik-backend/SKILL.md 的 “SQL Query Construction” 一节给出了完整的正反例且 code-reviewer.md 会在评审阶段对违反该规则的新增查询标记为 Critical。API 契约仓库提供了 OpenAPI 生成链路 scripts/generate_openapi.sh文档站的 apps/opik-documentation/documentation/fern/openapi/ 与 redoc 页面均基于生成物渲染设计端点形状时需考虑其与 SDK 代码生成的兼容性。skill 文档还特别指出列表型查询参数应一开始就用复数命名如exclude_category_names因为“先单数后补复数”会在同一端点上留下两个冗余参数——这正是“向后兼容”在 API 设计层面的具体体现。错误处理后端统一使用 Jakarta 异常BadRequestException/NotFoundException/ConflictException/InternalServerErrorException错误响应类只用既定的io.dropwizard.jersey.errors.ErrorMessage或com.comet.opik.api.error.ErrorMessage禁止新建错误消息类。Step 4: Trade-off Analysis权衡分析原文要求回答存在哪些备选方案各自的优劣为什么选这个而不选其他这一步的产出直接落到输出模板的 “Trade-offs Considered” 表格见下节强制架构师把“拒绝的方案”也写下来——从 planner.md 的 Risk 表Likelihood/Impact/Mitigation可以看出Opik 的 Agent 体系普遍偏好“决策可审计”的结构化输出。Step 5: Migration Strategy迁移策略原文检查项Can we deploy incrementally?Whats the rollback plan?Are there backwards compatibility concerns?Opik 仓库把迁移做成了独立的工程资产architect 设计迁移方案时应与之对齐apps/opik-backend/data-migrations/ 目录下存放按版本与按主题组织的数据迁移脚本例如 traces-local-v2-cutover 就是一次带 README 说明、14 个 SQL 加 9 个 shell 脚本的完整切流迁移包——“增量部署 可回滚”不是空话而是仓库中可查证的实践范式。仓库根部的 scripts/check_backend_migration_conflicts.sh 用于检测后端迁移冲突apps/opik-backend/run_db_migrations.sh 与 scripts/check_clickhouse_migrations_cluster.sh 分别处理双库的迁移执行与集群一致性校验。设计新 Schema 时把“是否会被这些脚本正确识别与执行”纳入检查清单就是把迁移策略落地为可验证项。五、设计文档输出格式九段式模板文档 “Output Format” 一节architect.md规定了 architect 产出的设计文档必须包含的完整骨架。该模板全文如下原样保留方括号内为填写说明## Problem Statement [What were solving and why] ## Proposed Solution [High-level approach in 2-3 sentences] ## Data Model [Schema changes, new entities, relationships] ## API Design [Endpoints, methods, request/response examples] ## Component Changes | Component | Changes | |-----------|---------| | Backend | [What changes] | | Frontend | [What changes] | | SDKs | [What changes] | ## Trade-offs Considered | Option | Pros | Cons | Verdict | |--------|------|------|---------| | A | ... | ... | Chosen | | B | ... | ... | Rejected | ## Migration Strategy [How to deploy safely] ## Open Questions - [ ] [Things needing clarification]九个章节的设计意图可以对照 Opik 的组件结构理解Problem Statement对应 Step 1 的需求分析结论要求先回答“为什么做”Proposed Solution限定 2-3 句话的高层方案防止方案叙述喧宾夺主Data Model与API Design分别承接 MySQL/ClickHouse 侧与 REST 侧的变更二者在 Opik 双库拓扑中必须分开陈述——同一个业务对象往往在两个存储里形态不同如 traces 的元数据在 MySQL、事件在 ClickHouseComponent Changes表格固定为 Backend / Frontend / SDKs 三行与架构图中的三层交付面一一对应确保任何跨层需求都不会漏掉某一侧的改动清单Trade-offs Considered表格强制包含Verdict列且示例中明写Chosen/Rejected把权衡分析收敛为可复核的决策记录Migration Strategy与Open Questions收尾后者用 checkbox 列表登记未决问题避免“隐含假设”混入已决方案。这套模板与 planner.md 的 “Implementation Plan” 模板Overview / Requirements / Affected Components / Phases / Testing Strategy / Risks / Definition of Done形成上下游关系architect 解决“设计什么、为什么这样设计”planner 接手把已定方案拆成“改哪些文件、分几个 Phase、每步如何验证”——两者都是只读工具集Read/Grep/Glob分工完全由输出模板界定。六、五条设计原则及其仓库落点文档末尾architect.md给出五条原则每条都能找到仓库内的具体执行机制原则原文表述仓库中的落地证据Consistency一致性Follow existing patterns unless theres strong reason not toopik-backend skill 的单复数命名法、Lombok 约定、StringTemplate 规则AGENTS.md 要求“Use existing module formatters/conventions and keep edits scoped”Simplicity简洁性Prefer simple solutions over clever ones错误响应类“Never create new error message classes”——复用两个既有类而非为场景造新类Incremental增量交付Design for incremental delivery when possibledata-migrations/下按主题组织的切流迁移包如 traces-local-v2-cutover支持分阶段部署Backwards compatible向后兼容Dont break existing clients without migration pathAPI 查询参数“从一开始就用复数命名”的约定以及迁移策略作为设计文档的必备章节Observable可观测Include logging, metrics, error handlingskill 文档规定日志值必须用单引号包裹log.info(Created user: {}, userId)、禁止记录 PII/密钥metrics-instrumentation 技能提供 OpenTelemetry 指标 Grafana 仪表盘的标准接法值得注意的是这五条原则不是孤立的价值观声明一致性有命名规范兜底增量与兼容有迁移资产兜底可观测有日志与指标规范兜底。architect Agent 在设计评审中引用某条原则时可以顺藤摸到可检查的规则而不是停留在“原则上应该……”。七、只读设计者architect 与整个 Agent 流水线的协作把 agents.mdc 的 “Task Approach” 一节连起来看Opik 期望的任务流是复杂功能先 Plan、Bug 先写复现测试、跨组件任务跨领域协同。architect 在其中承担的是设计决策的产出者角色其特征可以概括为三点输入面只读三件套Read/Grep/Glob 系统架构世界观ASCII 拓扑图 领域 skill 文档保证探索代码库时不产生副作用输出面九段式设计文档其中 Data Model / API Design / Migration Strategy 三段与仓库既有的工程资产Liquibase 迁移、OpenAPI 生成、切流迁移包直接对接边界面不实施无写工具、不评审那是 code-reviewer.md 的职责、不排期那是 planner.md 的职责。对开发者而言理解这份 Agent 定义的实际收益是双重的其一它本身就是 Opik 系统架构的一份可执行文档——拓扑图、分层规则、数据库分工全部经过仓库证据校验可作为新人上手或 Agent 二次开发的架构说明书其二它示范了 monorepo 中“把架构知识从人脑转移到 Agent 规格”的方法frontmatter 管触发与权限正文管流程与模板配套的 skills 目录管领域细则rules 目录管路由——四层文件各司其职共同支撑起可复现的设计决策过程。参考文件本文主体.agents/agents/architect.md同级 Agentplanner.md、code-reviewer.md技能索引与后端模式.agents/skills/README.md、opik-backend/SKILL.md领域路由规则.agents/rules/agents.mdc架构证据apps/opik-frontend/package.json、apps/opik-frontend/vite.config.ts、apps/opik-backend/config.yml迁移资产scripts/check_backend_migration_conflicts.sh、apps/opik-backend/data-migrations/traces-local-v2-cutover/README.md仓库总览AGENTS.md【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Opik Architect Agent 深度解析：AI 架构师如何驱动 Opik 的 API、Schema 与跨组件设计决策
Opik Architect Agent 深度解析AI 架构师如何驱动 Opik 的 API、Schema 与跨组件设计决策【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llmcomet-llmOpik仓库在.agents/agents/目录下维护了一套面向 AI Agent 的专职角色定义其中 architect.md 是“软件架构师”角色的完整规格书它定义了 Agent 的触发条件、五大核心职责、Opik 系统分层架构、五步设计流程、标准化的设计文档输出模板与五条设计原则。本文以该文档为主体逐节展开其机制并对照仓库中的前端依赖、后端配置、技能文档与迁移脚本验证文档中每一处架构断言在源码层面的实际落点帮助读者理解“用 Agent 化方式做架构设计”在大型 monorepo 中的完整工程实践。一、architect.md 在 Agent 体系中的位置Opik 的 Agent 基础设施集中在 .agents/ 目录从源码结构看可划分为四个层次子目录职责典型内容agents/专职角色定义本文主角architect.md、planner.md、code-reviewer.md、test-runner.md、meta-auditor.mdcommands/可执行工作流命令create-pr.md、work-on-github-issue.md、investigate-e2e-failure.md等skills/领域知识与模式库opik-backend、opik-frontend、python-sdk、typescript-sdk 等 18 个技能索引见 skills/README.mdrules/全局部署规则agents.mdc 定义了按路径到领域技能的路由表architect 与同级 planner、code-reviewer 是同一套“角色卡片”格式YAML frontmatter 声明元数据正文注入系统提示词。这种设计的核心思想是把架构决策所需的领域知识系统拓扑、分层约定、迁移策略固化为 Agent 可读的规格使每次设计输出风格一致、可追溯。二、角色定义与触发条件文档第 145 行是 YAML frontmatterarchitect.md关键字段及其含义如下name: architect description: | Use this agent when the user needs system design, API design, database schema changes, or architectural decisions. model: sonnet color: magenta tools: [Read, Grep, Glob]model: sonnet指定由 Sonnet 级模型驱动与同级 planner.md 一致而 code-reviewer.md 使用model: inherit继承父模型。tools: [Read, Grep, Glob]architect 只有只读工具——能读文件、正则搜索、按 glob 匹配文件但没有Bash等执行工具。这与其“设计而非施工”的定位严格对应架构师只负责探索现状与输出方案不直接修改代码。对比 code-reviewer 的工具列表[Read, Grep, Glob, Bash]后者需要执行git diff获取变更上下文才被授予了命令执行能力。color: magentaAgent 在宿主环境中的展示颜色planner 为 blue、code-reviewer 为 cyan形成视觉区分。四个触发场景description字段内嵌了四个 few-shot 示例architect.md用example/commentary标签给出“用户话语 → 触发判断”的映射触发场景用户示例话语架构师介入点新系统设计“How should I design the new metrics aggregation system?”系统架构设计数据库变更“I need to add a new table for experiment comparisons”Schema 与集成设计API 设计“What should the API look like for the new prompt versioning feature?”契约设计横切关注点“How should we handle authentication across the SDKs?”跨组件一致性方案这四个例子恰好覆盖了后文“核心职责”中最高频的三类设计对象系统、数据模型、API 契约以及一类跨边界问题横切关注点。示例中的领域名词metrics aggregation、experiment comparisons、prompt versioning都直接取材于 Opik 的真实功能域使触发判断贴合本仓库语境而非泛泛的通用描述。三、Opik 系统架构文档断言与仓库证据文档中段architect.md用 ASCII 图刻画了 Opik 的整体拓扑这是 architect Agent 做一切设计判断的“世界观”前提┌─────────────────────────────────────────────────────────────┐ │ Frontend (React) │ │ TanStack Query/Router • Zustand • shadcn/ui │ │ localhost:5174 (dev) • localhost:5173 (BE-only) │ └─────────────────────────────────────────────────────────────┘ │ REST API ▼ ┌─────────────────────────────────────────────────────────────┐ │ Backend (Java/Dropwizard) │ │ Resources → Services → DAOs │ │ localhost:8080 │ └─────────────────────────────────────────────────────────────┘ │ ┌───────────────────┼───────────────────┐ ▼ ▼ ▼ ┌─────────┐ ┌──────────┐ ┌─────────┐ │ MySQL │ │ClickHouse│ │ Redis │ │ (config,│ │ (traces, │ │ (cache) │ │ metadata)│ │ spans) │ │ │ └─────────┘ └──────────┘ └──────────┘ ┌─────────────────────────────────────────────────────────────┐ │ SDKs │ │ Python (opik) │ TypeScript (opik) │ │ Async batching → REST API │ └─────────────────────────────────────────────────────────────┘图中每一处技术断言都能在仓库中找到对应证据前端栈。apps/opik-frontend/package.json 的依赖清单确认了tanstack/react-query ^5.45.0、tanstack/react-router ^1.36.3、zustand ^4.5.2shadcn/ui 的底座 Radix 组件族radix-ui/react-dialog、radix-ui/react-tooltip等数十个包同样在依赖中列明。开发端口方面apps/opik-frontend/vite.config.ts 的注释明确写着VITE_DEV_PORT: Frontend dev server port (default: 5174)、VITE_BACKEND_PORT: Backend server port for proxy target (default: 8080)——与图中 “localhost:5174 (dev) / localhost:8080” 完全吻合。后端分层。Resources → Services → DAOs的分层规则被 .agents/skills/opik-backend/SKILL.md 强化为“Layered: Resource → Service → DAO (never skip layers)”并规定了单复数命名法Resource/URL/表名用复数TracesResource、/v1/private/traces、tracesDAO/Service 用单数TraceDAO、TraceService。architect 做 API 与 Schema 设计时“一致性”原则的实际抓手就是这套约定。双数据库 缓存拓扑。apps/opik-backend/config.yml 是 Dropwizard 主配置其中database段默认jdbc:mysql://localhost:3306/opik状态库/元数据databaseAnalytics段默认localhost:8123的 ClickHouse分析库与图中 “MySQL(config, metadata) ClickHouse(traces, spans)” 的分工一一对应该 skill 文档进一步解释了分工动机MySQL 承载“transactional”事务数据ClickHouse 承载“append-only”分析数据。配置中还存在databaseAnalyticsMigrations等迁移专用连接段说明双库拓扑在迁移路径上也有独立配置面。SDK 写入路径。图中 “Async batching → REST API” 描述的是 SDK 通过异步批量上报接入后端 REST 接口的方式对应的 SDK 实现分别位于 sdks/python 与 sdks/typescript。四、五步设计流程从需求到迁移策略文档的 “Design Process”architect.md把架构工作拆成五个有序步骤。以下逐节展开原文检查项并补充仓库中对应的实操支撑。Step 1: Requirements Analysis需求分析原文检查项What problem are we solving?Who are the users? What are their workflows?What are the constraints (performance, compatibility, timeline)?Whats explicitly out of scope?对 Opik 这类追踪 LLM 应用的平台而言“constraints” 一项尤其关键traces/spans 的写入是 append-only 高吞吐场景任何新表设计都要回答“在 ClickHouse 上如何落地”。配套的 opik-backend/migrations.md 定义了 MySQL/ClickHouse 的 Liquibase 迁移格式query-performance 技能则要求“在合并前验证 ClickHouse 查询的真实代价”把性能约束从口号变成了可执行检查。Step 2: Codebase Exploration代码库探索原文检查项Find similar features and understand their patternsIdentify affected components and blast radiusNote any technical debt or constraintsarchitect 的Grep/Glob只读工具正是为这一步配备的。探索时可直接引用各领域的 skill 文档作为“模式地图”后端看 opik-backend、前端看 opik-frontend、SDK 分别看 python-sdk 与 typescript-sdk。“blast radius”影响面的评估依据则是 .agents/rules/agents.mdc 中的领域路由表——它规定了apps/opik-backend/**、apps/opik-frontend/**、sdks/python/**等路径到技能的映射帮助设计者圈定变更波及的组件边界。Step 3: Solution Design方案设计原文检查项Data modelentities, relationships, storageAPI contractsendpoints, request/response shapesComponent interactionssequence diagramsError handling and edge casesOpik 后端对这三类产出都有硬性格式约束architect 设计时应当直接引用而非自创数据模型SQL 只能以 text block 声明一次可变值走:placeholder .bind(...)可变片段走 StringTemplate 的if(x)…endif——opik-backend/SKILL.md 的 “SQL Query Construction” 一节给出了完整的正反例且 code-reviewer.md 会在评审阶段对违反该规则的新增查询标记为 Critical。API 契约仓库提供了 OpenAPI 生成链路 scripts/generate_openapi.sh文档站的 apps/opik-documentation/documentation/fern/openapi/ 与 redoc 页面均基于生成物渲染设计端点形状时需考虑其与 SDK 代码生成的兼容性。skill 文档还特别指出列表型查询参数应一开始就用复数命名如exclude_category_names因为“先单数后补复数”会在同一端点上留下两个冗余参数——这正是“向后兼容”在 API 设计层面的具体体现。错误处理后端统一使用 Jakarta 异常BadRequestException/NotFoundException/ConflictException/InternalServerErrorException错误响应类只用既定的io.dropwizard.jersey.errors.ErrorMessage或com.comet.opik.api.error.ErrorMessage禁止新建错误消息类。Step 4: Trade-off Analysis权衡分析原文要求回答存在哪些备选方案各自的优劣为什么选这个而不选其他这一步的产出直接落到输出模板的 “Trade-offs Considered” 表格见下节强制架构师把“拒绝的方案”也写下来——从 planner.md 的 Risk 表Likelihood/Impact/Mitigation可以看出Opik 的 Agent 体系普遍偏好“决策可审计”的结构化输出。Step 5: Migration Strategy迁移策略原文检查项Can we deploy incrementally?Whats the rollback plan?Are there backwards compatibility concerns?Opik 仓库把迁移做成了独立的工程资产architect 设计迁移方案时应与之对齐apps/opik-backend/data-migrations/ 目录下存放按版本与按主题组织的数据迁移脚本例如 traces-local-v2-cutover 就是一次带 README 说明、14 个 SQL 加 9 个 shell 脚本的完整切流迁移包——“增量部署 可回滚”不是空话而是仓库中可查证的实践范式。仓库根部的 scripts/check_backend_migration_conflicts.sh 用于检测后端迁移冲突apps/opik-backend/run_db_migrations.sh 与 scripts/check_clickhouse_migrations_cluster.sh 分别处理双库的迁移执行与集群一致性校验。设计新 Schema 时把“是否会被这些脚本正确识别与执行”纳入检查清单就是把迁移策略落地为可验证项。五、设计文档输出格式九段式模板文档 “Output Format” 一节architect.md规定了 architect 产出的设计文档必须包含的完整骨架。该模板全文如下原样保留方括号内为填写说明## Problem Statement [What were solving and why] ## Proposed Solution [High-level approach in 2-3 sentences] ## Data Model [Schema changes, new entities, relationships] ## API Design [Endpoints, methods, request/response examples] ## Component Changes | Component | Changes | |-----------|---------| | Backend | [What changes] | | Frontend | [What changes] | | SDKs | [What changes] | ## Trade-offs Considered | Option | Pros | Cons | Verdict | |--------|------|------|---------| | A | ... | ... | Chosen | | B | ... | ... | Rejected | ## Migration Strategy [How to deploy safely] ## Open Questions - [ ] [Things needing clarification]九个章节的设计意图可以对照 Opik 的组件结构理解Problem Statement对应 Step 1 的需求分析结论要求先回答“为什么做”Proposed Solution限定 2-3 句话的高层方案防止方案叙述喧宾夺主Data Model与API Design分别承接 MySQL/ClickHouse 侧与 REST 侧的变更二者在 Opik 双库拓扑中必须分开陈述——同一个业务对象往往在两个存储里形态不同如 traces 的元数据在 MySQL、事件在 ClickHouseComponent Changes表格固定为 Backend / Frontend / SDKs 三行与架构图中的三层交付面一一对应确保任何跨层需求都不会漏掉某一侧的改动清单Trade-offs Considered表格强制包含Verdict列且示例中明写Chosen/Rejected把权衡分析收敛为可复核的决策记录Migration Strategy与Open Questions收尾后者用 checkbox 列表登记未决问题避免“隐含假设”混入已决方案。这套模板与 planner.md 的 “Implementation Plan” 模板Overview / Requirements / Affected Components / Phases / Testing Strategy / Risks / Definition of Done形成上下游关系architect 解决“设计什么、为什么这样设计”planner 接手把已定方案拆成“改哪些文件、分几个 Phase、每步如何验证”——两者都是只读工具集Read/Grep/Glob分工完全由输出模板界定。六、五条设计原则及其仓库落点文档末尾architect.md给出五条原则每条都能找到仓库内的具体执行机制原则原文表述仓库中的落地证据Consistency一致性Follow existing patterns unless theres strong reason not toopik-backend skill 的单复数命名法、Lombok 约定、StringTemplate 规则AGENTS.md 要求“Use existing module formatters/conventions and keep edits scoped”Simplicity简洁性Prefer simple solutions over clever ones错误响应类“Never create new error message classes”——复用两个既有类而非为场景造新类Incremental增量交付Design for incremental delivery when possibledata-migrations/下按主题组织的切流迁移包如 traces-local-v2-cutover支持分阶段部署Backwards compatible向后兼容Dont break existing clients without migration pathAPI 查询参数“从一开始就用复数命名”的约定以及迁移策略作为设计文档的必备章节Observable可观测Include logging, metrics, error handlingskill 文档规定日志值必须用单引号包裹log.info(Created user: {}, userId)、禁止记录 PII/密钥metrics-instrumentation 技能提供 OpenTelemetry 指标 Grafana 仪表盘的标准接法值得注意的是这五条原则不是孤立的价值观声明一致性有命名规范兜底增量与兼容有迁移资产兜底可观测有日志与指标规范兜底。architect Agent 在设计评审中引用某条原则时可以顺藤摸到可检查的规则而不是停留在“原则上应该……”。七、只读设计者architect 与整个 Agent 流水线的协作把 agents.mdc 的 “Task Approach” 一节连起来看Opik 期望的任务流是复杂功能先 Plan、Bug 先写复现测试、跨组件任务跨领域协同。architect 在其中承担的是设计决策的产出者角色其特征可以概括为三点输入面只读三件套Read/Grep/Glob 系统架构世界观ASCII 拓扑图 领域 skill 文档保证探索代码库时不产生副作用输出面九段式设计文档其中 Data Model / API Design / Migration Strategy 三段与仓库既有的工程资产Liquibase 迁移、OpenAPI 生成、切流迁移包直接对接边界面不实施无写工具、不评审那是 code-reviewer.md 的职责、不排期那是 planner.md 的职责。对开发者而言理解这份 Agent 定义的实际收益是双重的其一它本身就是 Opik 系统架构的一份可执行文档——拓扑图、分层规则、数据库分工全部经过仓库证据校验可作为新人上手或 Agent 二次开发的架构说明书其二它示范了 monorepo 中“把架构知识从人脑转移到 Agent 规格”的方法frontmatter 管触发与权限正文管流程与模板配套的 skills 目录管领域细则rules 目录管路由——四层文件各司其职共同支撑起可复现的设计决策过程。参考文件本文主体.agents/agents/architect.md同级 Agentplanner.md、code-reviewer.md技能索引与后端模式.agents/skills/README.md、opik-backend/SKILL.md领域路由规则.agents/rules/agents.mdc架构证据apps/opik-frontend/package.json、apps/opik-frontend/vite.config.ts、apps/opik-backend/config.yml迁移资产scripts/check_backend_migration_conflicts.sh、apps/opik-backend/data-migrations/traces-local-v2-cutover/README.md仓库总览AGENTS.md【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考