Supabase文档对AI代理友好吗？我们不知道，所以我们测试了一下
内容提要
Supabase团队使用AI代理测试文档，发现RLS指南存在漏洞：代理默认授予匿名用户全部写权限，且测试缺失。通过调整结构，将关键指令放在代码旁，修复了问题。结论是文档需兼顾代理与人类，清晰结构是关键，并计划持续扩展测试。
延伸解读
文档结构对AI代理的影响
测试发现，AI代理不会从头到尾阅读文档，而是选择性提取与任务相关的内容。即使指南中包含了正确的测试指导，如果放在页面不显眼的位置，代理也可能忽略。将关键指令放在用户实际会复制的代码旁边，能显著提高代理执行正确操作的概率。这表明，文档设计需要考虑到代理的阅读习惯，而不仅仅是人类读者。
安全默认值的重要性
初始测试中，代理按照指南操作后，竟然授予了匿名用户对所有表的写权限，包括公开的天气仪表盘。这暴露了文档在安全默认值上的缺失。通过添加显式的撤销默认权限步骤，并强调按需添加策略，问题得到解决。这提醒开发者，在涉及安全配置的文档中，必须明确说明默认权限的风险，并提供清晰的修复步骤。
文档测试的持续改进
Supabase团队将文档测试纳入常规流程，使用开源框架supabase/evals定期运行代理任务，并根据结果迭代文档。他们强调，测试清单不能从文档自身生成，而应基于领域知识和外部标准，以避免循环验证。这种持续测试的方法有助于发现文档中的漏洞，并确保文档对代理和人类都保持有效。
Q&A
Supabase团队为什么决定测试他们的文档对AI代理的友好程度？
因为数据显示人们不再阅读文档，而是让编码代理（如Claude Code或Cursor）来执行任务。代理可能无法像人类一样发现文档中的错误或遗漏，因此团队想通过测试来找出文档中的摩擦点，并改进文档，使其对代理和人类都更有效。
Supabase团队是如何测试文档的？
他们创建了一个评估（eval），运行代理执行一系列任务，然后由程序化评判员根据清单对结果进行评分。清单不是从指南本身编写的，而是基于正确RLS要求的整体视图，由主题专家、内部培训、其他文档页面和外部来源构建。
在测试RLS指南时，代理最初犯了什么严重错误？
代理默认授予匿名用户（anon）对所有表的全部写权限（插入、更新、删除、截断），包括公开的天气仪表板，这应该是只读的。这会导致数据暴露风险。
Supabase团队如何修复代理授予匿名用户写权限的问题？
他们在文档中添加了程序性步骤，指导用户撤销所有默认授权，并有意识地添加策略。同时，在代码旁边放置了具体的代码片段，以增强代理正确执行操作的可能性。
为什么添加测试指南后评估仍然失败？
因为代理不会从头到尾阅读页面，而是只提取与任务相关的内容。如果正确的指导放在页面的错误位置，可能会被完全跳过。
最终是什么结构上的改变让评估通过了？
将测试示例移到用户（或代理）复制策略代码时自然阅读到的位置，即紧挨着代码。这样关键指导就出现在阅读流程中，代理不会错过。
Supabase团队从这次测试中得到了哪些关于编写文档的启示？
代理会选择性阅读，关键指令应放在代码旁边；为代理和人类写作存在张力，但清晰的结构、明确的章节和明显的路标对两者都有益；文档测试需要成为常规习惯，而不是一次性修复。
Supabase团队计划如何继续改进文档的代理友好性？
他们计划将RLS场景从内部回归套件升级到公共的supabase/evals基准测试中，并扩展到其他最受欢迎的指南，以便编码代理使用Supabase时能遵循推荐的方法。
