别再往 Prompt 里塞数据库字典了，试试用 COMMENT ON 给 AI Agent 写指南
order_amount 是 numeric 类型，但它绝不可能知道这个字段在 2023 年之后就被弃用了，或者某个视图才是计算 GMV 的唯一权威来源。结果就是 Agent 经常一本正经地写出逻辑错误但语法完美的 SQL。我最近在团队内部推行一套方案：放弃在 Prompt 里维护几千字的“数据库字典”，直接把业务逻辑通过 PostgreSQL 的 COMMENT ON 语句打在数据库元数据里。
这种做法的核心逻辑是：让数据库本身成为 AI 的“操作手册”。当你使用支持 MCP（Model Context Protocol）协议的工具（比如 Kozou）时，Agent 在检索 Schema 阶段会自动拉取这些 COMMENT 内容。这意味着你写在数据库里的注释，直接变成了 Agent 定位数据的实时索引，且永远与版本同步。
为了让 AI 能够精准解析这些注释，我建议建立一套标准化的 Tag 标注习惯，而不是随缘写注释。推荐使用以下三类标签：
1. @ai：专门给 Agent 的指令或避坑指南。例如明确告知某个字段已弃用，或者在多个相似字段中指定首选。
2. @policy：记录业务逻辑规则。虽然这些规则在数据库层面不强制执行，但能让 AI 在生成 WHERE 子句时知道过滤条件。
3. @example：为复杂的视图或表提供一个可执行的查询示例，让 AI 通过 Few-Shot 快速模仿。
但在实操过程中，有三个非常隐蔽的坑点，如果没处理好，AI 可能会直接忽略你的指令：
首先，Tag 必须写在行首。如果你把 @ai 写在描述文字的中间，很多解析器会将其视作普通文本，导致指令失效。
其次，单行只能承载一个 Tag。如果你需要告诉 AI 两个不同的要点，必须换行写，不能在同一行堆叠多个 @ai。
最坑的一点是标点符号：冒号必须使用英文半角 :。我之前在测试时误用了中文全角 ：，结果 Agent 完全没反应，而且数据库执行时没有任何报错，排查起来非常浪费时间。
这里分享两个实战场景的写法：
场景一：处理冗余字段。假设 orders 表里有一个 amount_total 字段，但由于历史原因它不准，必须通过 order_items 求和。你可以这样写：COMMENT ON COLUMN orders.amount_total IS 'DEPRECATED denormalized order total.
@ai: Do NOT use this column for calculations; use order_items sum instead.';
场景二：指明权威数据源。当数据库里有多个状态视图时，明确告诉 AI 谁才是“真理”：COMMENT ON VIEW active_subscriptions IS 'Current active subscriptions.
@ai: This is the authoritative source for subscription status.';
对比传统的“外部文档 → 复制到 Prompt → AI 读取”链路，这种将元数据管理交还给 DB 的方案效率极高。它解决了文档同步滞后的问题，让数据库 Schema 变成了具备自解释能力的知识库，真正实现了“数据与逻辑共存”。
