用COMMENT ON给AI Agent写数据库指南

很多时候给AI Agent喂DDL，它能看懂字段名和类型，但根本不知道哪个字段是坑，哪个视图才是权威数据源，结果就是一本正经地写出错误的SQL。其实解决办法很简单：直接在PostgreSQL里用COMMENT ON写注释，把业务逻辑直接打在数据库里。

在公司推行AI Agent实操的时候我发现，与其在Prompt里写几千字的数据库字典，不如直接在DB层做约定。推荐一套高效的标注习惯，用特定的Tag来引导AI：

• @ai：给Agent的指令或背景知识（比如：这个字段已弃用，别用它）。
• @policy：记录业务规则（虽然不强制执行，但能让AI知道逻辑）。
• @example：给视图附带一个可执行的查询示例。

这里有几个关键的踩坑点，写错了AI识别不到：
1. Tag必须写在行首，写在行中间会被当成普通文本。
2. @ai 和 @policy 每一行只能有一个Tag，多条指令就换行写。
3. 冒号必须用英文半角:，用了全角：会导致解析失效且没报错，非常坑。

举几个实战例子，直接把“陷阱”告诉AI：

-- 明确告诉AI不要使用某个冗余字段
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.';

这种做法最爽的地方在于，当你使用支持MCP协议的工具（比如Kozou）时，Agent在搜索Schema时会自动检索这些COMMENT内容。这意味着你给AI写的笔记，直接变成了它定位数据的“索引”。

这种把元数据管理交给DB本身的方案，比维护一份随时会过时的外部文档要靠谱得多。