Bytebase 领域文档体系CONTEXT.md 术语表与 ADR 如何约束代码 Agent 的协作方式【免费下载链接】bytebaseDatabase governance built for humans and agents — controlling changes and access across every major database.项目地址: https://gitcode.com/GitHub_Trending/by/bytebaseBytebase 仓库为参与开发的编码 Agent 建立了一套明确的“领域文档消费规则”以仓库根目录的 CONTEXT.md 作为统一领域语言以 docs/adr/ 下的架构决策记录ADR作为不可静默推翻的设计约束。本文基于 docs/agents/domain.md 展开结合仓库中真实的术语表条目与 ADR 实例讲清这套 single-context 领域文档布局的构成、Agent 探索代码库前必须执行的阅读流程、术语使用纪律以及如何显式地标出与既有 ADR 的冲突——读完你可以在自己的代码库中复刻同一套“术语表 ADR”机制让 AI 协作不产生语言漂移和架构回退。单上下文Single-Context领域文档布局docs/agents/domain.md 明确规定本仓库采用single-context领域文档布局即领域语言与架构决策集中在仓库顶层的两个固定位置而不是分散到各个子模块/ ├── CONTEXT.md ├── docs/adr/ │ ├── 0001-event-sourced-orders.md │ └── 0002-postgres-for-write-model.md └── src/文档中给出的这棵目录树是示意布局对照当前仓库的实际结构可以确认该布局已被严格落实仓库根目录存在 CONTEXT.md首段即定义领域定位“Bytebase is a governed database development workspace. It turns proposed database work into reviewable plans and staged execution across managed database resources.”仓库根目录的 docs/adr/ 目录当前收录了四份按序号命名的 ADR0001-per-concept-type-metadata.md0002-support-workspace-and-project-instances.md0003-collect-state-metrics-on-every-replica.md0004-sample-project-instance-lifecycle.md“single-context” 的含义是不存在按模块拆分的多份领域文档Agent 只需要记住一个入口根目录CONTEXT.md和一个目录docs/adr/即可覆盖全部领域语言与设计约束。这与分散式文档每个子目录各放一份 README/说明形成对比目的是保证领域词汇全局一致、可被机器稳定消费。探索代码前必读以及“静默继续”规则原文档要求 Agent 在探索代码库之前先完成两项阅读CONTEXT.md仓库根目录——项目领域语言docs/adr/——读取与你即将工作的领域相关的 ADR。这条要求在仓库根目录的 AGENTS.md 中被作为“Read before working”清单的第一条正式引用Before exploring domain behavior, read domain guidance.也就是说docs/agents/domain.md本身是 Agent 的“领域文档使用手册”而它指向的真正内容资产是CONTEXT.md与docs/adr/。原文档还包含一条容易被忽略的纪律性规定如果这些文件不存在静默继续proceed silently。不要指出文件缺失也不要在开工前建议创建它们。领域文档由/domain-modelingskill经由/grill-with-docs和/improve-codebase-architecture触达在术语或决策真正被解决时惰性创建。这条规则把“写文档”从前置任务变成了结果产物术语是被使用出来的ADR 是被决策出来的而不是被预先模板化的。使用术语表的受控词汇Glossary VocabularyCONTEXT.md 的 “Language” 部分是 Bytebase 的领域术语表其条目格式高度结构化由术语 定义 _Avoid_禁用同义词清单三要素组成。原文档的要求是当你的输出issue 标题、重构提案、假设、测试名提及某个领域概念时必须使用CONTEXT.md中定义的术语不得漂移到术语表明确规避的同义词上。从当前仓库的术语表看它精确覆盖了 Bytebase 的核心领域对象例如术语定义要点摘自 CONTEXT.md被规避的同义词Workspace顶层协作边界包含项目、数据库连接、环境、用户和策略Project, organizationProject某个应用/团队数据库的治理边界拥有数据库成员、issue 工作流、审批、标签与 rollout 限制Workspace, repository, environmentInstance已注册的数据库服务器/集群/服务连接注册为 workspace instance 或 project instance 二选一且作用域不可变Database, environmentWorkspace Instance由 workspace 直接治理的实例其数据库可分属不同项目Project instance, unassigned instanceProject Instance被且仅被一个项目拥有的实例其中所有数据库都属于该项目Workspace instance, shared instancePlan项目内可审查的数据库工作提案描述执行前“要做什么、对哪些目标做”Rollout, issue, migrationRollout计划的执行体组织为阶段stage与任务task追踪各目标环境的进度Plan, issue, releaseTask / Task Run任务是可执行单元Task Run 是“一次执行尝试”的记录讨论执行日志与状态迁移时用 Task RunPlan spec / TaskRelease用于跨目标协调部署的数据库变更输入包是变更工件而非审批记录或执行本身Plan, rollout, issueChangelog迁移执行后的历史记录是“变更已执行”的证据而非变更提案本身Change request, releaseComposite TypePostgreSQL 系独立命名行类型CREATE TYPE x AS (...)与 enum、domain、range、Oracle object type、SQL Server table/alias type 各自是独立概念UDT, user-defined type, custom type这套词汇表的价值在协作场景中非常直接例如术语表把 “Database Change”而非裸词 “change”、“Rollout”而非 “release” 或 “issue”严格区分开Agent 在写 issue 标题或测试名时就不会再产出与仓库既有代码命名不一致的措辞。原文档还给出了一条判断规则如果你需要表达的概念不在术语表里这本身是一个信号——要么你在发明项目并不使用的语言应重新考虑措辞要么存在真实的词汇缺口记录下来交给/domain-modeling处理。这形成了一个闭环术语表既是约束也是被动的完备性检查器。显式标出与 ADR 的冲突原文档的最后一节规定了冲突处理纪律如果你的输出与某个既有 ADR 矛盾必须显式标出而不是静默覆盖并给出了引用格式Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…用当前仓库中真实存在的 ADR 来理解这条规则0001-per-concept-type-metadata.md 决策采用“按概念的窄元数据消息”而非统一的UserDefinedTypeMetadata。其核心论证是元数据以 protojson 持久化在 JSONB 中快照、changelog、release反序列化时带DiscardUnknown字段名与消息形状一旦发布即被永久冻结任何重命名都会静默孤立历史数据且无报错。因此 Agent 若提出“把各类型元数据统一成一个带kind判别字段的结构体”就是在挑战这份 ADR必须以上面的格式显式引用 ADR-0001 并给出重开理由而不能直接在方案中“顺手统一”。0002-support-workspace-and-project-instances.md 规定了实例的两种互斥作用域workspace instance / project instance作用域在创建时选定、v1 内不可变并给出了完整的 v1 资源命名对照表如 project instance 的数据库路径为projects/{project}/instances/{instance}/databases/{database}。这解释了CONTEXT.md中 Instance 术语为什么强调“its scope does not change”——术语表与 ADR 在此互相印证。0003-collect-state-metrics-on-every-replica.md 是一个极短但完整的决策样本每个副本都从/metrics同步计算并服务安装级状态指标用少量副本间的重复计算换取免 leader 选举、免故障切换空窗且明确“只有当指标级 benchmark 证明必要时才加缓存”。0004-sample-project-instance-lifecycle.md 则展示了 ADR 如何约束一个具体子系统Sample Project Instance 作为聚合体的生命周期、单次终身权益one lifetime entitlement、基于created_at/expires_at/deleted_at推导的状态机、三分钟生命周期窗口与FOR UPDATE SKIP LOCKED的清理竞争模型并链接到运维文档 docs/operations/sample-project-instance.md。“显式标冲突”这条规则的实际效果是ADR 成为 Agent 输出的一种可校验约束——任何方案若与docs/adr/内既有决策相悖冲突会浮到文档/PR 表面供人裁决而不是被静默执行。领域文档与代码、测试的对应关系从源码结构看领域文档中的术语与决策可以一一对应到代码与测试资产这也正是术语表要求“输出使用受控词汇”的落点——词汇、文档、代码三层命名保持一致Sample Project Instance术语定义在 CONTEXT.md决策在 docs/adr/0004-sample-project-instance-lifecycle.md持久化实现与测试可见于 backend/store/sample_instance.go 与 backend/store/sample_instance_test.go服务层有 backend/api/v1/sample_project_instance_test.go对应文件名以仓库实际为准store 层路径已确认。测试命名沿用领域术语而非随意同义词。Workspace Instance / Project Instance 双作用域ADR-0002 的资源命名表直接对应backend/api/v1中InstanceService的扩展端点相关行为测试见 backend/store/instance_project_test.go 与 backend/api/v1/instance_service_test.go。Composite Type 等元数据概念ADR-0001 所述“每概念一个消息、protojson 入 JSONB”的约定与根目录 AGENTS.md 中 “Metadata JSONB usesprotojson.Marshal” 的编码约定一致元数据转换的测试规约则由 backend/plugin/schema/AGENTS.md 进一步约束。这种“术语表条目 ↔ ADR ↔ 代码/测试”的三层对应是 single-context 布局能运转的关键Agent 读到术语就知道去哪里找决策读到 ADR 就知道去哪些测试验证。Agent 侧的实践规则清单综合 docs/agents/domain.md 原文与上述仓库证据可以把它压缩为一份可直接执行的检查清单探索前先读根目录 CONTEXT.md再读与待工作领域相关的 docs/adr/ 条目两者缺失时静默继续不提议创建。命名时issue 标题、重构提案、假设、测试名一律使用术语表词汇避开_Avoid_清单中的同义词遇到术语表未覆盖的概念先自查是否在发明语言确属缺口再记录给/domain-modeling。决策时输出与既有 ADR 矛盾时按 “Contradicts ADR-XXXX (主题) — but worth reopening because…” 格式显式引用绝不静默覆盖。不预写领域文档是决策与术语被解决后的惰性产物不在开工前批量创建空壳文件。此外docs/agents/目录下的其余文档如 issue-tracker.md、triage-labels.md、frontend-ux.md、exploratory-qa.md分别约束 issue 操作、分诊标签、前端 UX 契约与探索式 QA与领域文档一起构成 Bytebase 的 Agent 指令体系而根目录 AGENTS.md 声明 “AGENTS.mdfiles are the instruction source of truth;CLAUDE.mdfiles import them”保证同一套规则在不同 Agent 工具间单一来源。小结Bytebase 的领域文档机制本质上是一份面向 Agent 的“上下文消费协议”single-context 布局根目录CONTEXT.mddocs/adr/让领域语言与设计约束集中且可预测术语表以 “定义 _Avoid_” 结构压制同义词漂移并以“缺失即信号”的规则保持词汇完备性ADR 冲突必须显式引用而非静默推翻。三者叠加使得人类与 AI 的产出在同一套语言与同一组不可回退的决策上对齐——这也是该仓库能够同时服务人类开发者与编码 Agent 的工程文档基础。【免费下载链接】bytebaseDatabase governance built for humans and agents — controlling changes and access across every major database.项目地址: https://gitcode.com/GitHub_Trending/by/bytebase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Bytebase 领域文档体系：CONTEXT.md 术语表与 ADR 如何约束代码 Agent 的协作方式
Bytebase 领域文档体系CONTEXT.md 术语表与 ADR 如何约束代码 Agent 的协作方式【免费下载链接】bytebaseDatabase governance built for humans and agents — controlling changes and access across every major database.项目地址: https://gitcode.com/GitHub_Trending/by/bytebaseBytebase 仓库为参与开发的编码 Agent 建立了一套明确的“领域文档消费规则”以仓库根目录的 CONTEXT.md 作为统一领域语言以 docs/adr/ 下的架构决策记录ADR作为不可静默推翻的设计约束。本文基于 docs/agents/domain.md 展开结合仓库中真实的术语表条目与 ADR 实例讲清这套 single-context 领域文档布局的构成、Agent 探索代码库前必须执行的阅读流程、术语使用纪律以及如何显式地标出与既有 ADR 的冲突——读完你可以在自己的代码库中复刻同一套“术语表 ADR”机制让 AI 协作不产生语言漂移和架构回退。单上下文Single-Context领域文档布局docs/agents/domain.md 明确规定本仓库采用single-context领域文档布局即领域语言与架构决策集中在仓库顶层的两个固定位置而不是分散到各个子模块/ ├── CONTEXT.md ├── docs/adr/ │ ├── 0001-event-sourced-orders.md │ └── 0002-postgres-for-write-model.md └── src/文档中给出的这棵目录树是示意布局对照当前仓库的实际结构可以确认该布局已被严格落实仓库根目录存在 CONTEXT.md首段即定义领域定位“Bytebase is a governed database development workspace. It turns proposed database work into reviewable plans and staged execution across managed database resources.”仓库根目录的 docs/adr/ 目录当前收录了四份按序号命名的 ADR0001-per-concept-type-metadata.md0002-support-workspace-and-project-instances.md0003-collect-state-metrics-on-every-replica.md0004-sample-project-instance-lifecycle.md“single-context” 的含义是不存在按模块拆分的多份领域文档Agent 只需要记住一个入口根目录CONTEXT.md和一个目录docs/adr/即可覆盖全部领域语言与设计约束。这与分散式文档每个子目录各放一份 README/说明形成对比目的是保证领域词汇全局一致、可被机器稳定消费。探索代码前必读以及“静默继续”规则原文档要求 Agent 在探索代码库之前先完成两项阅读CONTEXT.md仓库根目录——项目领域语言docs/adr/——读取与你即将工作的领域相关的 ADR。这条要求在仓库根目录的 AGENTS.md 中被作为“Read before working”清单的第一条正式引用Before exploring domain behavior, read domain guidance.也就是说docs/agents/domain.md本身是 Agent 的“领域文档使用手册”而它指向的真正内容资产是CONTEXT.md与docs/adr/。原文档还包含一条容易被忽略的纪律性规定如果这些文件不存在静默继续proceed silently。不要指出文件缺失也不要在开工前建议创建它们。领域文档由/domain-modelingskill经由/grill-with-docs和/improve-codebase-architecture触达在术语或决策真正被解决时惰性创建。这条规则把“写文档”从前置任务变成了结果产物术语是被使用出来的ADR 是被决策出来的而不是被预先模板化的。使用术语表的受控词汇Glossary VocabularyCONTEXT.md 的 “Language” 部分是 Bytebase 的领域术语表其条目格式高度结构化由术语 定义 _Avoid_禁用同义词清单三要素组成。原文档的要求是当你的输出issue 标题、重构提案、假设、测试名提及某个领域概念时必须使用CONTEXT.md中定义的术语不得漂移到术语表明确规避的同义词上。从当前仓库的术语表看它精确覆盖了 Bytebase 的核心领域对象例如术语定义要点摘自 CONTEXT.md被规避的同义词Workspace顶层协作边界包含项目、数据库连接、环境、用户和策略Project, organizationProject某个应用/团队数据库的治理边界拥有数据库成员、issue 工作流、审批、标签与 rollout 限制Workspace, repository, environmentInstance已注册的数据库服务器/集群/服务连接注册为 workspace instance 或 project instance 二选一且作用域不可变Database, environmentWorkspace Instance由 workspace 直接治理的实例其数据库可分属不同项目Project instance, unassigned instanceProject Instance被且仅被一个项目拥有的实例其中所有数据库都属于该项目Workspace instance, shared instancePlan项目内可审查的数据库工作提案描述执行前“要做什么、对哪些目标做”Rollout, issue, migrationRollout计划的执行体组织为阶段stage与任务task追踪各目标环境的进度Plan, issue, releaseTask / Task Run任务是可执行单元Task Run 是“一次执行尝试”的记录讨论执行日志与状态迁移时用 Task RunPlan spec / TaskRelease用于跨目标协调部署的数据库变更输入包是变更工件而非审批记录或执行本身Plan, rollout, issueChangelog迁移执行后的历史记录是“变更已执行”的证据而非变更提案本身Change request, releaseComposite TypePostgreSQL 系独立命名行类型CREATE TYPE x AS (...)与 enum、domain、range、Oracle object type、SQL Server table/alias type 各自是独立概念UDT, user-defined type, custom type这套词汇表的价值在协作场景中非常直接例如术语表把 “Database Change”而非裸词 “change”、“Rollout”而非 “release” 或 “issue”严格区分开Agent 在写 issue 标题或测试名时就不会再产出与仓库既有代码命名不一致的措辞。原文档还给出了一条判断规则如果你需要表达的概念不在术语表里这本身是一个信号——要么你在发明项目并不使用的语言应重新考虑措辞要么存在真实的词汇缺口记录下来交给/domain-modeling处理。这形成了一个闭环术语表既是约束也是被动的完备性检查器。显式标出与 ADR 的冲突原文档的最后一节规定了冲突处理纪律如果你的输出与某个既有 ADR 矛盾必须显式标出而不是静默覆盖并给出了引用格式Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…用当前仓库中真实存在的 ADR 来理解这条规则0001-per-concept-type-metadata.md 决策采用“按概念的窄元数据消息”而非统一的UserDefinedTypeMetadata。其核心论证是元数据以 protojson 持久化在 JSONB 中快照、changelog、release反序列化时带DiscardUnknown字段名与消息形状一旦发布即被永久冻结任何重命名都会静默孤立历史数据且无报错。因此 Agent 若提出“把各类型元数据统一成一个带kind判别字段的结构体”就是在挑战这份 ADR必须以上面的格式显式引用 ADR-0001 并给出重开理由而不能直接在方案中“顺手统一”。0002-support-workspace-and-project-instances.md 规定了实例的两种互斥作用域workspace instance / project instance作用域在创建时选定、v1 内不可变并给出了完整的 v1 资源命名对照表如 project instance 的数据库路径为projects/{project}/instances/{instance}/databases/{database}。这解释了CONTEXT.md中 Instance 术语为什么强调“its scope does not change”——术语表与 ADR 在此互相印证。0003-collect-state-metrics-on-every-replica.md 是一个极短但完整的决策样本每个副本都从/metrics同步计算并服务安装级状态指标用少量副本间的重复计算换取免 leader 选举、免故障切换空窗且明确“只有当指标级 benchmark 证明必要时才加缓存”。0004-sample-project-instance-lifecycle.md 则展示了 ADR 如何约束一个具体子系统Sample Project Instance 作为聚合体的生命周期、单次终身权益one lifetime entitlement、基于created_at/expires_at/deleted_at推导的状态机、三分钟生命周期窗口与FOR UPDATE SKIP LOCKED的清理竞争模型并链接到运维文档 docs/operations/sample-project-instance.md。“显式标冲突”这条规则的实际效果是ADR 成为 Agent 输出的一种可校验约束——任何方案若与docs/adr/内既有决策相悖冲突会浮到文档/PR 表面供人裁决而不是被静默执行。领域文档与代码、测试的对应关系从源码结构看领域文档中的术语与决策可以一一对应到代码与测试资产这也正是术语表要求“输出使用受控词汇”的落点——词汇、文档、代码三层命名保持一致Sample Project Instance术语定义在 CONTEXT.md决策在 docs/adr/0004-sample-project-instance-lifecycle.md持久化实现与测试可见于 backend/store/sample_instance.go 与 backend/store/sample_instance_test.go服务层有 backend/api/v1/sample_project_instance_test.go对应文件名以仓库实际为准store 层路径已确认。测试命名沿用领域术语而非随意同义词。Workspace Instance / Project Instance 双作用域ADR-0002 的资源命名表直接对应backend/api/v1中InstanceService的扩展端点相关行为测试见 backend/store/instance_project_test.go 与 backend/api/v1/instance_service_test.go。Composite Type 等元数据概念ADR-0001 所述“每概念一个消息、protojson 入 JSONB”的约定与根目录 AGENTS.md 中 “Metadata JSONB usesprotojson.Marshal” 的编码约定一致元数据转换的测试规约则由 backend/plugin/schema/AGENTS.md 进一步约束。这种“术语表条目 ↔ ADR ↔ 代码/测试”的三层对应是 single-context 布局能运转的关键Agent 读到术语就知道去哪里找决策读到 ADR 就知道去哪些测试验证。Agent 侧的实践规则清单综合 docs/agents/domain.md 原文与上述仓库证据可以把它压缩为一份可直接执行的检查清单探索前先读根目录 CONTEXT.md再读与待工作领域相关的 docs/adr/ 条目两者缺失时静默继续不提议创建。命名时issue 标题、重构提案、假设、测试名一律使用术语表词汇避开_Avoid_清单中的同义词遇到术语表未覆盖的概念先自查是否在发明语言确属缺口再记录给/domain-modeling。决策时输出与既有 ADR 矛盾时按 “Contradicts ADR-XXXX (主题) — but worth reopening because…” 格式显式引用绝不静默覆盖。不预写领域文档是决策与术语被解决后的惰性产物不在开工前批量创建空壳文件。此外docs/agents/目录下的其余文档如 issue-tracker.md、triage-labels.md、frontend-ux.md、exploratory-qa.md分别约束 issue 操作、分诊标签、前端 UX 契约与探索式 QA与领域文档一起构成 Bytebase 的 Agent 指令体系而根目录 AGENTS.md 声明 “AGENTS.mdfiles are the instruction source of truth;CLAUDE.mdfiles import them”保证同一套规则在不同 Agent 工具间单一来源。小结Bytebase 的领域文档机制本质上是一份面向 Agent 的“上下文消费协议”single-context 布局根目录CONTEXT.mddocs/adr/让领域语言与设计约束集中且可预测术语表以 “定义 _Avoid_” 结构压制同义词漂移并以“缺失即信号”的规则保持词汇完备性ADR 冲突必须显式引用而非静默推翻。三者叠加使得人类与 AI 的产出在同一套语言与同一组不可回退的决策上对齐——这也是该仓库能够同时服务人类开发者与编码 Agent 的工程文档基础。【免费下载链接】bytebaseDatabase governance built for humans and agents — controlling changes and access across every major database.项目地址: https://gitcode.com/GitHub_Trending/by/bytebase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考