open-seo 仓库的 Agent 协作指南工程原则、审阅规则与安全边界【免费下载链接】open-seoOpen source alternative to Semrush and Ahrefs项目地址: https://gitcode.com/GitHub_Trending/op/open-seo本篇文章基于开源仓库 AGENTS.mdAgent guidance展开面向所有在本仓库内工作的 AI 编码 AgentClaude Code、Codex 等与维护者梳理本仓库对 Agent 协作的工程约束、审阅流程与安全边界。读完你可以掌握如何按本仓库的工程原则组织代码与数据、遇到小摩擦时如何记录 papercuts、审阅结论何时该沉淀为长期规则以及哪些文件变更必须经过维护者明确批准。一、AGENTS.md 在仓库中的角色AGENTS.md 是本仓库给 AI Agent 的第一份指令它定义了 Agent 在本仓库内写代码、提交审阅、维护工具链时应遵守的约定。与它功能相似、但面向不同 Agent 产品的是 CLAUDE.md为 Claude Code 提供相同原则并额外补充了测试规范。两个文件的存在说明这类 Agent 指令文件是仓库协作控制面review control plane的一部分其变更本身也需要受控。AGENTS.md 的结构非常精简由三部分组成Engineering principles—— 写代码时的工程原则Log papercuts—— 遇到仓库小摩擦时的记录约定Preserve review learnings—— 审阅结论如何沉淀为长期规则。这种先给原则、再给过程约定、最后给变更边界的结构也是值得其他 AI 辅助开发仓库借鉴的模板。二、工程原则简单、扁平、少抽象AGENTS.md 的第一部分定义了 8 条工程原则核心思想可以概括为在正确的地方做正确的事偏爱简单、可读、扁平的代码尽量减少间接层minimal indirection。间接层增加认知负担只有在真正防止有意义漂移meaningful drift时才抽象避免投机性speculative或一次性使用的抽象层。创建新 helper 或抽象之前先搜索现有实现和已安装的库。这条与仓库实际的依赖管理一致例如项目大量依赖 zod 做运行时校验、TanStack 系列做路由/查询/表单而不是自研。保持产品数据规范化、关系显式化。不要在 JSON 或文本里编码关系型数据来逃避 join。新增应用后端功能时默认采用分层结构TanStack server function → service → repository。这一条在仓库中可以直接印证看 src/serverFunctions/projects.ts 的写法createServerFn只负责请求入口与权限检查真正的业务逻辑委托给ProjectService如ProjectService.createProject、ProjectService.updateProject而数据访问在 repository 层。schema 变更、查询和变更操作必须同时兼容 SQLite 和 Postgres。这也是为什么仓库同时维护了 drizzleSQLite/D1与 drizzle-pgPostgres两套迁移目录并存在 schema-parity.test.ts 这类测试来保证两套 schema 的一致性。使用惯用 TypeScript用 Zod 校验不可信数据并在信任边界trust boundaries收窄运行时值。信任边界的典型例子所有外部输入在进入 handler 前都先过 validator。优先使用项目已有的 helper 和库而不是手写实现。对服务端状态、路由和表单提交优先使用 TanStack Query、Router 和 Form 的惯用模式。源码印证server function → service → repository以项目管理的 server function 为例src/serverFunctions/projects.ts 展示了一个典型的四步模式export const createProject createServerFn({ method: POST }) .middleware(requireAuthenticatedContext) // 1. 认证中间件 .validator(createProjectSchema) // 2. Zod 校验信任边界 .handler(async ({ data, context }) { // 3. 权限检查 requireOrgPermission(context, { project: [create] }); return ProjectService.createProject(context.organizationId, data); // 4. 委托给 service });这里清晰地体现了三条原则中间件负责上下文解析、validator 负责信任边界的 Zod 校验、handler 不直接触碰数据库而是委托 service。数据校验的细节沉淀在 src/types/schemas/projects.ts例如createProjectSchema对项目名做了.trim().min(1).max(120)的限制并有一个有趣的约束——languageCode必须伴随locationCodehasLocationForLanguagerefine否则报错 A language requires a location.。这个语言必须伴随地点的配对校验正是在信任边界收窄运行时值的实例。源码印证双数据库兼容兼容 SQLite 与 Postgres不只是口头约定。仓库根目录同时存在 drizzle.config.tsD1/SQLite与 drizzle-pg.config.tsPostgrespackage.json 中db:generate脚本同时生成两套迁移db:generate: npm run db:generate:d1 npm run db:generate:pg, db:generate:d1: drizzle-kit generate, db:generate:pg: drizzle-kit generate --config drizzle-pg.config.ts而 src/db/schema-parity.test.ts 这类测试用于防止两套 schema 在演进中产生漂移。这意味着任何 Agent 提交的 schema 变更都必须同时考虑两种方言的写法。三、Log papercuts把小摩擦记下来AGENTS.md 要求 Agent 在遇到小的、不阻塞的仓库摩擦时——例如重试的工具调用、令人困惑的搭建步骤、不稳定的命令、过期的缓存、误导性的报错、不明显的坑——当场使用papercutsskill 并追加到.agents/PAPERCUTS.md然后继续当前任务。这条约定有几个关键边界只在当下记录in the moment不允许在会话结束后回头挖掘整段会话的 papercuts也不允许在用户没有明确要求时发起大规模清理。区分 papercuts 与真 bug真实的 bug 和已跟踪的工作不算 papercuts敏感数据绝不能记录sensitive data must never be logged。本仓库当前工作区中尚未存在.agents/PAPERCUTS.md这正是设计意图——该文件由遇到摩擦的 Agent 在需要时创建而不是预置的空模板。这种做法的价值在于把踩坑经验从 Agent 的一次性会话中沉淀为仓库的持久记忆让后续的 Agent 无需重新踩同样的坑。四、Preserve review learnings审阅结论的沉淀与边界第三部分针对代码审阅当一次 merge-ready或其它审阅验证了某个发现后只有在以下条件同时满足时才使用maintain-greptile-rules将其提升为长期规则该发现暴露的是反复出现或高风险的仓库不变量recurring or high-risk repository invariant现有的.greptile/上下文和自动化检查尚未覆盖这一不变量。同时明确禁止把一次性 bug 或个人偏好提升为永久审阅规则。这防止了规则库被低价值规则污染。审阅控制面review control plane与变更边界AGENTS.md 明确指出以下文件属于审阅控制面对它们的任何变更都必须得到维护者的显式审阅.greptile/**AGENTS.mdCLAUDE.md.agents/skills/**.github/**控制面文件会直接影响谁来审、审什么、怎么审因此是高风险区域。仓库还要求CODEOWNERS请求对这些文件的审阅在仓库设置允许的情况下开启 GitHub 对 code-owner 批准的要求require code-owner approval仓库专属规则放在.greptile/维护者应配置或保留一个最小化的、由组织强制执行的 Greptile 基线baseline覆盖外部贡献、密钥、认证、计费、CI 和规则篡改rule-tampering风险Agent 如果发现基线缺失或未经验证必须上报且未经用户明确授权不得修改 dashboard 或组织规则。这条边界背后的安全考量外部贡献者的代码提交、密钥泄露、认证/计费逻辑被篡改、CI 被注入、或者审阅规则本身被悄悄修改都是高风险的供应链攻击面。把谁可以改审阅规则这个元问题单独拎出来管控是 AGENTS.md 中最重要的安全设计。与 CLAUDE.md 的关系CLAUDE.md 是给 Claude Code 的镜像指令工程原则部分与 AGENTS.md 完全一致但额外增加了Testing一节约定测试规范例如不为测试而测试、测试要覆盖可能真实发生的核心行为或难以发现的边界情况、在公共入口测试行为、静态导入被测模块vi.mock会被提升因此禁止无理由的await import()与vi.resetModules()、测试中不得重新声明生产类、一个测试对应一个不变量、不 mock ORM 构建链等。这解释了为什么仓库的测试文件如 src/db/schema-parity.test.ts普遍轻量且聚焦行为而非实现细节。五、对 Agent 与维护者的实践清单综合 AGENTS.md 的全部内容可以在本仓库工作的 Agent 和负责审阅的维护者各总结一份实践清单。Agent 应该做写扁平、可读的代码先搜索已有实现再新建 helper新增后端功能走server function → service → repository分层在信任边界用 Zod 校验保持 schema 对 SQLite/Postgres 双兼容遇到小摩擦当场用papercutsskill 记录到.agents/PAPERCUTS.md并继续当前任务审阅发现满足反复出现或高风险 现有检查未覆盖时才用maintain-greptile-rules沉淀规则。Agent 不应该做不创建投机性或一次性抽象层不在 JSON/文本中编码关系数据来逃避 join不把一次性 bug 或个人偏好提升为永久审阅规则不未经授权修改 dashboard 或组织规则发现基线缺失只上报、不擅动不记录敏感数据到 papercuts。维护者应该做对.greptile/**、AGENTS.md、CLAUDE.md、.agents/skills/**、.github/**的变更保持显式审阅配置 CODEOWNERS 并要求 code-owner 批准将仓库专属规则存放在.greptile/保留组织级最小 Greptile 基线以覆盖外部贡献、密钥、认证、计费、CI 与规则篡改风险在仓库实际演进过程中验证基线是否存在且可信。六、总结AGENTS.md 是一份给 Agent 的工程宪法它的价值不在于篇幅而在于把三件事讲清楚了怎么写出符合仓库风格的代码扁平化、少抽象、分层明确、双数据库兼容、信任边界校验、过程性经验如何沉淀papercuts 即记即用规则提炼谨慎克制、审阅控制面如何防守控制面文件变更需显式审阅组织级基线不可被 Agent 私自改动。对于任何想要深度参与 open-seo 开发的 Agent 或维护者这份文件都是理解仓库协作契约的起点——配合 CLAUDE.md 的测试规范和 CONTRIBUTING.md 的贡献流程可以快速对齐仓库的开发预期。【免费下载链接】open-seoOpen source alternative to Semrush and Ahrefs项目地址: https://gitcode.com/GitHub_Trending/op/open-seo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考